metaobjects 0.9.0__py3-none-any.whl

metaobjects/registry.py

@@ -0,0 +1,210 @@
+"""The type registry: (type, subType) -> TypeDefinition. Populated by providers."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+from .errors import ErrorCode, ParseError
+from .shared.base_types import SUBTYPE_BASE
+
+
+@dataclass(frozen=True)
+class AttrSchema:
+    name: str
+    # An attr subtype name, e.g. "string", "boolean", "stringArray".
+    # Optional: a None value_type declares the attr as "known but untyped",
+    # which the YAML coercion guard skips. Used for polymorphic attrs like
+    # @default whose value type follows the OWNING field's subtype.
+    value_type: str | None
+    required: bool = False
+    allowed_values: tuple[str, ...] | None = None
+    default: object | None = None
+    # True for an array-valued attr (a list of the scalar value_type) — the
+    # single orthogonal array axis that replaced the retired "stringarray"
+    # subtype, mirroring Java's StringAttribute + @isArray. The loader coerces an
+    # array-flagged attr through the array string-attr coercion (bare-string →
+    # one-element list).
+    is_array: bool = False
+
+
+@dataclass(frozen=True)
+class ChildRule:
+    child_type: str
+    child_sub_type: str  # "*" wildcard matches any subtype
+
+
+# factory(type, sub_type, name) -> a node instance
+NodeFactory = Callable[[str, str, str], object]
+
+
+@dataclass
+class TypeDefinition:
+    type: str
+    sub_type: str
+    factory: NodeFactory
+    attrs: list[AttrSchema] = field(default_factory=list)
+    child_rules: list[ChildRule] = field(default_factory=list)
+
+    @property
+    def key(self) -> tuple[str, str]:
+        return (self.type, self.sub_type)
+
+
+class TypeRegistry:
+    def __init__(self) -> None:
+        self._defs: dict[tuple[str, str], TypeDefinition] = {}
+        self._common_attrs: list[AttrSchema] = []
+        # Per-type designated default subType (queried by the YAML desugar to
+        # resolve a bare `metadata:` / `object:` key to e.g. `metadata.root` /
+        # `object.entity`). Mirrors TypeRegistry._defaultSubTypes in TS.
+        self._default_sub_types: dict[str, str] = {}
+        # ADR-0023 Decision 2 — sealed state. Once sealed, every mutating
+        # registration method raises ERR_REGISTRY_SEALED. Python composes from an
+        # explicit immutable provider set (compose_registry(core_providers)), so
+        # sealing here is the guard + negative test (no polluted singleton to
+        # pivot off). The library seals after the metamodel bootstrap; a
+        # downstream app composes its own (unsealed) registry.
+        self._sealed = False
+
+    def seal(self) -> None:
+        """Seal the registry: every subsequent mutating registration raises
+        ERR_REGISTRY_SEALED. Idempotent. Reads are unaffected."""
+        self._sealed = True
+
+    def is_sealed(self) -> bool:
+        """Whether this registry has been sealed (ADR-0023)."""
+        return self._sealed
+
+    def _check_not_sealed(self, operation: str) -> None:
+        if self._sealed:
+            raise ParseError(
+                f"TypeRegistry is sealed (ADR-0023): {operation} is not permitted after "
+                "metamodel bootstrap. Made-up metamodel attributes/types are structurally "
+                "disallowed — a new metamodel attribute requires a registered provider + "
+                "human agreement. Downstream apps that need extra vocabulary must compose "
+                "their own (unsealed) registry.",
+                ErrorCode.ERR_REGISTRY_SEALED,
+            )
+
+    def register(self, definition: TypeDefinition) -> None:
+        self._check_not_sealed(f'register("{definition.key}")')
+        # Store a per-registry COPY of the definition's mutable lists. Providers
+        # hold their TypeDefinition objects as long-lived singletons (re-used across
+        # every compose_registry call); a later provider's extend() does
+        # definition.attrs.append(...). Without copying here, that append would mutate
+        # the provider's SHARED list and accumulate duplicates across composes. Copying
+        # makes extend() scoped to the registry being composed. The factory is shared
+        # (a type's identity belongs to whoever registered it — see extend()).
+        self._defs[definition.key] = TypeDefinition(
+            type=definition.type,
+            sub_type=definition.sub_type,
+            factory=definition.factory,
+            attrs=list(definition.attrs),
+            child_rules=list(definition.child_rules),
+        )
+
+    def find(self, type_: str, sub_type: str) -> TypeDefinition | None:
+        return self._defs.get((type_, sub_type))
+
+    def has_type(self, type_: str) -> bool:
+        return any(t == type_ for (t, _s) in self._defs)
+
+    def set_default_sub_type(self, type_: str, sub_type: str) -> None:
+        """Designate the default subType for a bare `type` YAML key (ADR-0006 Rule 1).
+
+        Mirrors TypeRegistry.setDefaultSubType in TS. Used by the YAML desugar
+        when resolving sugared `metadata:` / `object:` keys.
+        """
+        self._check_not_sealed(f'set_default_sub_type("{type_}")')
+        self._default_sub_types[type_] = sub_type
+
+    def default_sub_type_of(self, type_: str) -> str | None:
+        """Return the designated default subType for *type_*, or None if none.
+
+        Mirrors TypeRegistry.defaultSubTypeOf in TS.
+        """
+        return self._default_sub_types.get(type_)
+
+    def register_common_attrs(self, attrs: list[AttrSchema]) -> None:
+        """Register attrs accepted on every metatype. First-wins dedupe by name.
+
+        Conflict with per-type attrs is detected at validation time, not here.
+        """
+        self._check_not_sealed("register_common_attrs")
+        for attr in attrs:
+            if any(existing.name == attr.name for existing in self._common_attrs):
+                continue  # first registration wins
+            self._common_attrs.append(attr)
+
+    def get_common_attrs(self) -> list[AttrSchema]:
+        """Return a defensive copy of the registered common attrs."""
+        return list(self._common_attrs)
+
+    def attrs_of(self, type_: str, sub_type: str) -> list[AttrSchema]:
+        """The declared attribute schemas for a (type, subType), or [] if unregistered.
+        Mirrors the TS registry's attrsOf()."""
+        definition = self.find(type_, sub_type)
+        return list(definition.attrs) if definition is not None else []
+
+    def attr_schema(self, type_: str, sub_type: str, attr_name: str) -> AttrSchema | None:
+        """Look up a per-type attr schema by name, then fall back to common attrs."""
+        for attr in self.attrs_of(type_, sub_type):
+            if attr.name == attr_name:
+                return attr
+        for attr in self._common_attrs:
+            if attr.name == attr_name:
+                return attr
+        return None
+
+    def extend(
+        self,
+        type_: str,
+        sub_type: str,
+        *,
+        attributes: list[AttrSchema] | None = None,
+        child_rules: list[ChildRule] | None = None,
+    ) -> None:
+        """Additively enrich an already-registered ``(type_, sub_type)``.
+
+        Append attributes and/or child rules to the existing TypeDefinition.
+        Does NOT touch the factory — a type's identity belongs to whoever
+        registered it. Used by providers to extend types another provider
+        defined (mirrors the TS ``TypeRegistry.extend`` and C#
+        ``TypeRegistry.Extend``).
+
+        :raises ParseError: ``ERR_UNKNOWN_SUBTYPE`` if ``(type_, sub_type)``
+            is not registered.
+        :raises ParseError: ``ERR_PROVIDER_ATTR_CONFLICT`` if an attribute
+            name already exists on the type (own-only check — common-attr
+            collisions are still surfaced separately at validation time).
+
+        Note: providers calling ``extend`` MUST declare a dependency on the
+        provider that originally registered the ``(type_, sub_type)`` so
+        ``compose_registry``'s topological ordering puts the registering
+        provider before the extending one.
+        """
+        self._check_not_sealed(f'extend("{type_}.{sub_type}")')
+        definition = self.find(type_, sub_type)
+        if definition is None:
+            raise ParseError(
+                f'TypeRegistry.extend: no registered type "{type_}.{sub_type}" to extend',
+                ErrorCode.ERR_UNKNOWN_SUBTYPE,
+            )
+
+        for attr in attributes or []:
+            if attr.value_type == SUBTYPE_BASE:
+                raise ValueError(
+                    f'TypeRegistry.extend: attr "{attr.name}" being added to '
+                    f'"{type_}.{sub_type}" declares value_type "{SUBTYPE_BASE}", '
+                    f"which is not valid for attrs. Use None for a polymorphic/untyped attr."
+                )
+            if any(existing.name == attr.name for existing in definition.attrs):
+                raise ParseError(
+                    f'TypeRegistry.extend: attribute "{attr.name}" is already declared '
+                    f'on "{type_}.{sub_type}"',
+                    ErrorCode.ERR_PROVIDER_ATTR_CONFLICT,
+                )
+            definition.attrs.append(attr)
+
+        for rule in child_rules or []:
+            definition.child_rules.append(rule)

metaobjects/registry_manifest.py

@@ -0,0 +1,223 @@
+"""SP-G Registry Conformance — the Python registry-manifest emitter.
+
+Walks an assembled core ``TypeRegistry`` and serializes the LOGICAL metamodel
+vocabulary as a canonical, fully-sorted, byte-stable JSON manifest. This is the
+single-source contract the other four ports (TS / C# / Java / Kotlin) must
+byte-match — a structural gate against the SP-C class of silent vocabulary
+drift (a port's registry diverging — wrong attr names, missing subtypes,
+different required-ness — with every behavioral corpus still green).
+
+The IN/OUT boundary (the v1 logical subset emittable byte-identically by all
+five ports) is documented in ``fixtures/registry-conformance/README.md``. In
+short: ``type.subType`` + ``attrs[{name, valueType, required}]`` + ``commonAttrs``
++ ``defaultSubTypes``. EXCLUDED from v1 (per-port-physical or
+not-universally-tracked-on-the-registry): factories/native bindings;
+``AttrSchema.default`` and ``allowed_values`` (Java's attr model carries
+neither); ``inheritsFrom``; ``child_rules``.
+
+The TS emitter (``server/typescript/packages/metadata/src/registry-manifest.ts``,
+``emitRegistryManifest``) is the reference implementation; the canonical bytes
+live in ``fixtures/registry-conformance/expected-registry.json``.
+"""
+from __future__ import annotations
+
+import json
+from enum import Enum
+
+from .documentation.doc_constants import DOC_ATTR_DESCRIPTION
+from .meta.core.attr.attr_constants import (
+    ATTR_SUBTYPE_STRING,
+    ATTR_SUBTYPE_STRINGARRAY,
+)
+from .meta.presentation.view.view_constants import VIEW_SUBTYPE_CURRENCY
+from .registry import AttrSchema, TypeRegistry
+from .shared.base_types import SUBTYPE_BASE, TYPE_METADATA, TYPE_VIEW
+from .shared.structural import KEY_IS_ARRAY
+
+# Wave 3b — the in/out boundary is an EXPLICIT CLASSIFICATION (a reason category
+# per carve-out), not a bare name-match. The negative branch of a name-list
+# silently meant "logical"; now ``classify_per_type_attr`` returns either an
+# ``ExclusionReason`` (carved out, with a documented category) or ``INCLUDED``
+# (logical cross-port vocabulary). Inclusion-by-classification is sound because
+# ADR-0023 seals the agreed-vocabulary registry. The axis is
+# cross-port-CONTRACT vs port-PRIVATE-mechanism (NOT abstract-vs-physical — the
+# physical-DB attrs column/dbColumnType/db.indexed/precision/scale/maxLength/
+# unique ARE logical here, the agreed persistence vocabulary). See
+# fixtures/registry-conformance/README.md.
+
+
+class ExclusionReason(str, Enum):
+    """Reason a per-type attr/row is carved out of the agreed vocabulary."""
+
+    #: Sentinel: NOT excluded — logical cross-port vocabulary.
+    INCLUDED = "included"
+    #: Native type-binding / factory (incl. ADR-0001 ``object``, ADR-0005 ``objectAdapter``).
+    NATIVE_BINDING = "native-binding"
+    #: Bare structural / OO-shape keyword (isArray/isAbstract/extends/implements/isInterface).
+    STRUCTURAL_KEYWORD = "structural-keyword"
+    #: A commonAttr (``description``) re-registered per-type — belongs in commonAttrs.
+    COMMON_ATTR_DUP = "common-attr-dup"
+    #: The ``metadata.base`` per-port inheritance anchor (deferred inheritsFrom facet).
+    INHERITANCE_ANCHOR = "inheritance-anchor"
+    #: TS-web-presentation-only facet (the generic ``view.*`` controls).
+    PRESENTATION_ONLY = "presentation-only"
+
+
+_ATTR_NAME_IS_ABSTRACT = "isAbstract"
+_ATTR_NAME_EXTENDS = "extends"
+_ATTR_NAME_IMPLEMENTS = "implements"
+_ATTR_NAME_IS_INTERFACE = "isInterface"
+# ADR-0001 class-FQN type binding + ADR-0005 hybrid value-access seam.
+_ATTR_NAME_OBJECT = "object"
+_ATTR_NAME_OBJECT_ADAPTER = "objectAdapter"
+
+# Per-type attr names carved out of the agreed vocabulary, each mapped to its
+# PORT_PRIVATE reason. An attr NOT in this map is logical (INCLUDED) by the
+# ADR-0023 sealed-vocabulary contract. ``description`` is carved out ONLY
+# per-type — it stays in the commonAttrs block.
+_EXCLUDED_PER_TYPE_ATTRS: dict[str, ExclusionReason] = {
+    KEY_IS_ARRAY: ExclusionReason.STRUCTURAL_KEYWORD,
+    _ATTR_NAME_IS_ABSTRACT: ExclusionReason.STRUCTURAL_KEYWORD,
+    _ATTR_NAME_EXTENDS: ExclusionReason.STRUCTURAL_KEYWORD,
+    _ATTR_NAME_IMPLEMENTS: ExclusionReason.STRUCTURAL_KEYWORD,
+    _ATTR_NAME_IS_INTERFACE: ExclusionReason.STRUCTURAL_KEYWORD,
+    _ATTR_NAME_OBJECT: ExclusionReason.NATIVE_BINDING,
+    _ATTR_NAME_OBJECT_ADAPTER: ExclusionReason.NATIVE_BINDING,
+    DOC_ATTR_DESCRIPTION: ExclusionReason.COMMON_ATTR_DUP,
+}
+
+
+def classify_per_type_attr(name: str) -> ExclusionReason:
+    """Classify a per-type attr: an ``ExclusionReason`` (carved out) or
+    ``ExclusionReason.INCLUDED`` (logical). Total — no silent default."""
+    return _EXCLUDED_PER_TYPE_ATTRS.get(name, ExclusionReason.INCLUDED)
+
+
+def classify_type_subtype(type_name: str, sub_type: str) -> ExclusionReason:
+    """Classify a ``(type, subType)`` row: the metadata.base inheritance anchor
+    (C-5) / the generic ``view.*`` presentation controls (B-2) / INCLUDED."""
+    if type_name == TYPE_METADATA and sub_type == SUBTYPE_BASE:
+        return ExclusionReason.INHERITANCE_ANCHOR  # C-5 — Java's internal inheritance anchor
+    if type_name == TYPE_VIEW and sub_type not in (SUBTYPE_BASE, VIEW_SUBTYPE_CURRENCY):
+        return ExclusionReason.PRESENTATION_ONLY  # B-2 — TS-web-presentation generic view controls
+    return ExclusionReason.INCLUDED
+
+
+def _is_excluded_type_subtype(type_name: str, sub_type: str) -> bool:
+    """True if a ``(type, subType)`` row is carved out of the manifest (any reason)."""
+    return classify_type_subtype(type_name, sub_type) is not ExclusionReason.INCLUDED
+
+
+def _to_manifest_attr(attr: AttrSchema) -> dict[str, object]:
+    """Normalize one AttrSchema to the manifest's logical attr shape.
+
+    Emits ``{name, valueType, isArray, required}`` — decomposing array-ness into
+    a scalar ``valueType`` + an orthogonal ``isArray`` flag (``allowed_values`` /
+    ``default`` are intentionally dropped, deferred per the v1 boundary).
+    ``value_type`` is ``None`` for polymorphic/untyped attrs (e.g. ``@default``);
+    the manifest renders that as an explicit JSON ``null``. A legacy
+    ``stringarray`` value_type token is decomposed to
+    ``{valueType: "string", isArray: true}`` so no ``stringarray`` token reaches
+    the manifest.
+    """
+    is_legacy_string_array = attr.value_type == ATTR_SUBTYPE_STRINGARRAY
+    is_array = attr.is_array or is_legacy_string_array
+    value_type = ATTR_SUBTYPE_STRING if is_legacy_string_array else attr.value_type
+    # Fixed key order: name, valueType, isArray, required.
+    return {
+        "name": attr.name,
+        "valueType": value_type,
+        "isArray": is_array,
+        "required": attr.required,
+    }
+
+
+def _sorted_attrs(attrs: list[AttrSchema]) -> list[dict[str, object]]:
+    """Sort attrs by name (ascending, ASCII codepoint compare)."""
+    return [_to_manifest_attr(a) for a in sorted(attrs, key=lambda a: a.name)]
+
+
+def _sorted_per_type_attrs(attrs: list[AttrSchema]) -> list[dict[str, object]]:
+    """As ``_sorted_attrs``, but keeping only attrs the explicit classification
+    marks ``INCLUDED`` (logical cross-port vocabulary). A carved-out attr
+    (structural keyword, native binding, per-type ``description`` dup) is dropped
+    for a documented reason, never a silent name-match. Applied ONLY to per-type
+    attrs — ``description`` stays in the commonAttrs block."""
+    return _sorted_attrs(
+        [a for a in attrs if classify_per_type_attr(a.name) is ExclusionReason.INCLUDED]
+    )
+
+
+def build_registry_manifest(registry: TypeRegistry) -> dict[str, object]:
+    """Build the canonical registry-manifest object from an assembled registry.
+
+    The registry must already be composed (e.g.
+    ``compose_registry([core_provider, doc_provider])``) so all providers — core
+    types, the DB-domain attrs Python keeps on its field defs, and the common
+    doc attrs — have run.
+
+    All collections are sorted explicitly (not relying on dict insertion order)
+    so the serialization is byte-stable and port-independent.
+    """
+    types: list[dict[str, object]] = []
+    # Iterate every registered (type, subType). Sorting is applied after the
+    # walk, so dict iteration order is irrelevant.
+    for definition in registry._defs.values():  # noqa: SLF001 (no public iterator)
+        if _is_excluded_type_subtype(definition.type, definition.sub_type):
+            continue  # metadata.base anchor (C-5) / generic view.* controls (B-2)
+        types.append(
+            {
+                "type": definition.type,
+                "subType": definition.sub_type,
+                "attrs": _sorted_per_type_attrs(definition.attrs),
+            }
+        )
+    types.sort(key=lambda t: f"{t['type']}.{t['subType']}")
+
+    common_attrs = _sorted_attrs(registry.get_common_attrs())
+
+    # defaultSubTypes: probe each registered type name; emit with sorted keys.
+    type_names = sorted({t["type"] for t in types})  # type: ignore[misc]
+    default_sub_types: dict[str, str] = {}
+    for type_name in type_names:
+        default_sub = registry.default_sub_type_of(type_name)  # type: ignore[arg-type]
+        if default_sub is not None:
+            default_sub_types[type_name] = default_sub
+
+    # Fixed top-level key order: types, commonAttrs, defaultSubTypes.
+    return {
+        "types": types,
+        "commonAttrs": common_attrs,
+        "defaultSubTypes": default_sub_types,
+    }
+
+
+def emit_registry_manifest(registry: TypeRegistry) -> str:
+    """Emit the canonical registry manifest as a byte-stable JSON string.
+
+    Serialization contract — every port MUST match this exactly:
+     - 2-space indentation.
+     - Object keys in a fixed order (``types`` / ``commonAttrs`` /
+       ``defaultSubTypes``; each type ``type`` / ``subType`` / ``attrs``; each
+       attr ``name`` / ``valueType`` / ``isArray`` / ``required``).
+     - All arrays sorted: ``types`` by ``"type.subType"``; each ``attrs`` by
+       name; ``commonAttrs`` by name; ``defaultSubTypes`` keys sorted.
+     - ``valueType: null`` literal for polymorphic/untyped attrs.
+     - A single trailing newline.
+
+    ``json.dumps(indent=2, separators=(",", ": "))`` reproduces JS
+    ``JSON.stringify(obj, null, 2)`` byte-for-byte for ASCII content: no
+    trailing whitespace on container lines, ``": "`` after keys, ``,`` line
+    separators. ``ensure_ascii=False`` keeps any non-ASCII verbatim (there is
+    none in the core vocabulary, but it matches the JS contract).
+    """
+    manifest = build_registry_manifest(registry)
+    return (
+        json.dumps(
+            manifest,
+            indent=2,
+            ensure_ascii=False,
+            separators=(",", ": "),
+        )
+        + "\n"
+    )

metaobjects/render/__init__.py

@@ -0,0 +1,74 @@
+"""Render-tier engine: the build-time template drift-check ``verify`` (FR-004), the
+FR-010 tolerant ``extract`` parser, and the FR-010 output-format prompt renderer."""
+
+from metaobjects.render.email_document import EmailDocument
+from metaobjects.render.filesystem_provider import FilesystemProvider
+from metaobjects.render.prompt import (
+    PROMPT_OVERRIDES_NONE,
+    OutputFormatSpec,
+    PromptField,
+    PromptOverrides,
+    PromptStyle,
+    no_overrides,
+    prompt_style_from,
+    render_output_format,
+)
+from metaobjects.render.extract import (
+    FieldKind,
+    FieldExtraction,
+    FieldSpec,
+    Format,
+    ExtractOptions,
+    ExtractionOutcome,
+    ExtractSchema,
+    ExtractionReport,
+    ExtractionResult,
+    Tolerance,
+    extract,
+    extract_map,
+)
+from metaobjects.render.verify import (
+    ERR_OUTPUT_TAG_MISSING,
+    ERR_PARTIAL_UNRESOLVED,
+    ERR_REQUIRED_SLOT_UNUSED,
+    ERR_VAR_NOT_ON_PAYLOAD,
+    InMemoryProvider,
+    PayloadField,
+    Provider,
+    VerifyError,
+    verify,
+)
+
+__all__ = [
+    "ERR_OUTPUT_TAG_MISSING",
+    "ERR_PARTIAL_UNRESOLVED",
+    "ERR_REQUIRED_SLOT_UNUSED",
+    "ERR_VAR_NOT_ON_PAYLOAD",
+    "PROMPT_OVERRIDES_NONE",
+    "EmailDocument",
+    "FieldKind",
+    "FieldExtraction",
+    "FieldSpec",
+    "Format",
+    "InMemoryProvider",
+    "OutputFormatSpec",
+    "PayloadField",
+    "PromptField",
+    "PromptOverrides",
+    "PromptStyle",
+    "Provider",
+    "ExtractOptions",
+    "ExtractionOutcome",
+    "ExtractSchema",
+    "ExtractionReport",
+    "ExtractionResult",
+    "FilesystemProvider",
+    "Tolerance",
+    "VerifyError",
+    "no_overrides",
+    "prompt_style_from",
+    "extract",
+    "extract_map",
+    "render_output_format",
+    "verify",
+]

metaobjects/render/email_document.py

@@ -0,0 +1,14 @@
+"""A rendered email value type (mirrors the TS/Java/C# ``EmailDocument``)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class EmailDocument:
+    """A rendered email: subject + HTML body + optional plain-text alternative (MIME multipart/alternative)."""
+
+    subject: str
+    html_body: str
+    text_body: str | None = None

metaobjects/render/escapers.py

@@ -0,0 +1,109 @@
+"""Format-keyed escapers for the render engine (FR-004).
+
+Tier-1 invariant: per-format escaping behavior is character-by-character
+identical to TS (``packages/render/src/escapers.ts``), C#
+(``MetaObjects.Render/Escapers.cs``), and Java
+(``server/java/render/.../Escapers.java``).
+
+``{{var}}`` substitutions in a Mustache template are escaped per the
+configured format; ``{{{var}}}`` bypasses escaping (Mustache's
+"triple-stache" raw form is preserved by the renderer).
+"""
+from __future__ import annotations
+
+FORMAT_TEXT = "text"
+FORMAT_HTML = "html"
+FORMAT_XML = "xml"
+FORMAT_CSV = "csv"
+FORMAT_JSON = "json"
+FORMAT_MARKDOWN = "markdown"
+FORMAT_SPREADSHEET = "spreadsheet"
+
+
+def _escape_xml(s: str) -> str:
+    out: list[str] = []
+    for c in s:
+        if c == "&":
+            out.append("&")
+        elif c == "<":
+            out.append("&lt;")
+        elif c == ">":
+            out.append("&gt;")
+        elif c == '"':
+            out.append("&quot;")
+        elif c == "'":
+            out.append("&#39;")
+        else:
+            out.append(c)
+    return "".join(out)
+
+
+def _injection_guard(s: str) -> str:
+    """OWASP CSV/Excel formula-injection guard: prefix a literal apostrophe when
+    the cell starts with an active char (``=``, ``+``, ``-``, ``@``, tab, CR)."""
+    if not s:
+        return s
+    first = s[0]
+    if first in ("=", "+", "-", "@", "\t", "\r"):
+        return "'" + s
+    return s
+
+
+def _escape_csv(s: str) -> str:
+    guarded = _injection_guard(s)
+    needs_quote = any(ch in guarded for ch in (",", '"', "\n", "\r"))
+    if not needs_quote:
+        return guarded
+    return '"' + guarded.replace('"', '""') + '"'
+
+
+def _escape_json(s: str) -> str:
+    """Mirrors JS ``JSON.stringify(s).slice(1, -1)``: escape ``"``, ``\\``, and
+    ASCII control chars; nothing else (no HTML-safety escaping of ``< > &``)."""
+    out: list[str] = []
+    for c in s:
+        if c == '"':
+            out.append('\\"')
+        elif c == "\\":
+            out.append("\\\\")
+        elif c == "\b":
+            out.append("\\b")
+        elif c == "\f":
+            out.append("\\f")
+        elif c == "\n":
+            out.append("\\n")
+        elif c == "\r":
+            out.append("\\r")
+        elif c == "\t":
+            out.append("\\t")
+        elif ord(c) < 0x20:
+            out.append(f"\\u{ord(c):04x}")
+        else:
+            out.append(c)
+    return "".join(out)
+
+
+def _escape_spreadsheet(s: str) -> str:
+    """XML-escape the content first, then guard — the guard's leading quote
+    stays a literal apostrophe (which tells Excel "treat as text"), not
+    ``&#39;``."""
+    return _injection_guard(_escape_xml(s))
+
+
+_REGISTRY = {
+    FORMAT_TEXT: lambda s: s,
+    FORMAT_MARKDOWN: lambda s: s,
+    FORMAT_HTML: _escape_xml,  # HTML uses XML entity set per FR-004 spec
+    FORMAT_XML: _escape_xml,
+    FORMAT_CSV: _escape_csv,
+    FORMAT_SPREADSHEET: _escape_spreadsheet,
+    FORMAT_JSON: _escape_json,
+}
+
+
+def escape(format_: str, value: str) -> str:
+    """Escape *value* per *format_*. Unknown formats raise ``ValueError``."""
+    fn = _REGISTRY.get(format_)
+    if fn is None:
+        raise ValueError(f'unknown render format "{format_}"')
+    return fn(value)

metaobjects/render/extract/__init__.py

@@ -0,0 +1,59 @@
+"""FR-010 tolerant ``extract`` engine (Tier 2).
+
+A forgiving parser that takes dirty LLM output (fenced / preamble / prose-wrapped /
+truncated / trailing-comma JSON, unclosed-tag XML) and extracts 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:`extract`.
+"""
+from __future__ import annotations
+
+from metaobjects.render.extract import extract_map
+from metaobjects.render.extract.coerce import MALFORMED, scalar_coerce
+from metaobjects.render.extract.json_forgiving_reader import (
+    TRUNCATED,
+    JsonForgivingReader,
+)
+from metaobjects.render.extract.normalize import normalize_enum
+from metaobjects.render.extract.extract import extract
+from metaobjects.render.extract.types import (
+    Coercion,
+    FieldKind,
+    FieldExtraction,
+    FieldSpec,
+    Format,
+    Normalizer,
+    OnField,
+    ExtractOptions,
+    ExtractionOutcome,
+    ExtractSchema,
+    ExtractionReport,
+    ExtractionResult,
+    Tolerance,
+)
+from metaobjects.render.extract.xml_forgiving_reader import XmlForgivingReader
+
+__all__ = [
+    "MALFORMED",
+    "TRUNCATED",
+    "Coercion",
+    "FieldKind",
+    "FieldExtraction",
+    "FieldSpec",
+    "Format",
+    "JsonForgivingReader",
+    "Normalizer",
+    "OnField",
+    "ExtractOptions",
+    "ExtractionOutcome",
+    "ExtractSchema",
+    "ExtractionReport",
+    "ExtractionResult",
+    "Tolerance",
+    "XmlForgivingReader",
+    "normalize_enum",
+    "extract",
+    "extract_map",
+    "scalar_coerce",
+]