@metaobjectsdev/render 0.8.1 → 0.9.0

package/dist/recover/types.js

@@ -1,124 +0,0 @@
-// FR-010 recover engine — types & model (Tier-2 idiomatic TS port).
-//
-// Cross-port REFERENCE is the Java engine
-// (server/java/render/.../recover/). This file ports the Java records/enums to
-// idiomatic TS: enums become string-union `as const` objects (values match the
-// corpus / Java enum names exactly), records become readonly interfaces +
-// factory functions, and the mutable RecoveryReport is a class.
-/** Output format the dirty text claims to be. Corpus schema.json uses "JSON"/"XML". */
-export const Format = {
-    JSON: "JSON",
-    XML: "XML",
-};
-/** The coercion target kinds the engine understands. OBJECT = nested RecoverSchema. */
-export const FieldKind = {
-    STRING: "STRING",
-    INT: "INT",
-    LONG: "LONG",
-    DOUBLE: "DOUBLE",
-    BOOLEAN: "BOOLEAN",
-    ENUM: "ENUM",
-    OBJECT: "OBJECT",
-};
-/**
- * FROZEN cross-port per-field recovery classification. Do not reorder or add
- * without an ADR. These string values are SERIALIZED in the conformance corpus.
- */
-export const FieldRecovery = {
-    RECOVERED: "RECOVERED",
-    // DEFAULTED is reserved (a future @default-backed value); the engine does not emit it yet.
-    DEFAULTED: "DEFAULTED",
-    LOST_OPTIONAL: "LOST_OPTIONAL",
-    LOST_REQUIRED: "LOST_REQUIRED",
-    MALFORMED: "MALFORMED",
-};
-/**
- * STRICT: case-sensitive, minimal repair. NORMAL: case-insensitive keys/tags
- * (default). LOOSE: maximal repair (currently identical to NORMAL — reserved).
- */
-export const Tolerance = {
-    STRICT: "STRICT",
-    NORMAL: "NORMAL",
-    LOOSE: "LOOSE",
-};
-export function scalar(name, kind, required) {
-    return { name, kind, required, array: false, enumValues: null, enumAlias: null, min: null, max: null, nested: null };
-}
-export function enumField(name, required, values, aliases) {
-    return {
-        name,
-        kind: FieldKind.ENUM,
-        required,
-        array: false,
-        enumValues: values == null ? null : [...values],
-        enumAlias: aliases == null ? {} : { ...aliases },
-        min: null,
-        max: null,
-        nested: null,
-    };
-}
-export function range(name, kind, required, min, max) {
-    return { name, kind, required, array: false, enumValues: null, enumAlias: null, min, max, nested: null };
-}
-export function object(name, required, array, nested) {
-    return { name, kind: FieldKind.OBJECT, required, array, enumValues: null, enumAlias: null, min: null, max: null, nested };
-}
-export function recoverSchema(format, rootName, fields) {
-    return { format, rootName, fields: fields == null ? [] : [...fields] };
-}
-export function defaults() {
-    return { tolerance: Tolerance.NORMAL, aliases: {}, normalizers: {}, onField: null };
-}
-/** Normalize a partial / undefined options bag into a complete RecoverOptions. */
-export function normalizeOptions(opts) {
-    if (opts == null)
-        return defaults();
-    return {
-        tolerance: opts.tolerance ?? Tolerance.NORMAL,
-        aliases: opts.aliases == null ? {} : { ...opts.aliases },
-        normalizers: opts.normalizers == null ? {} : { ...opts.normalizers },
-        onField: opts.onField ?? null,
-    };
-}
-/** Mutable accumulator of per-field recovery classification, the degenerate-response flag, and coercion notes. */
-export class RecoveryReport {
-    // Insertion-ordered (Map preserves insertion order, mirroring Java LinkedHashMap).
-    _states = new Map();
-    _coercions = [];
-    _empty = false;
-    set(fieldPath, state) {
-        this._states.set(fieldPath, state);
-    }
-    addCoercion(c) {
-        this._coercions.push(c);
-    }
-    markEmpty() {
-        this._empty = true;
-    }
-    isEmpty() {
-        return this._empty;
-    }
-    states() {
-        return new Map(this._states);
-    }
-    coercions() {
-        return [...this._coercions];
-    }
-    lostRequired() {
-        return this.byState(FieldRecovery.LOST_REQUIRED);
-    }
-    malformed() {
-        return this.byState(FieldRecovery.MALFORMED);
-    }
-    hasLostRequired() {
-        return this.lostRequired().length > 0;
-    }
-    byState(s) {
-        const out = [];
-        for (const [k, v] of this._states)
-            if (v === s)
-                out.push(k);
-        return out;
-    }
-}
-//# sourceMappingURL=types.js.map

package/dist/recover/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/recover/types.ts"],"names":[],"mappings":"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"}

package/src/recover/KNOWN_GAPS.md

@@ -1,35 +0,0 @@
-# FR-010 TypeScript recover engine — known gaps & intentional cross-port divergences
-
-Scope: the tolerant `recover` pipeline (`src/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#, beyond Java/Kotlin)
-
-- **Nested-object recover is implemented.** A `FieldSpec` with a non-null `nested` schema
-  (built via the `object(...)` factory) is descended into and its sub-fields classified. The
-  Java/Kotlin ports defer this (their codegen emits a scalar-STRING placeholder). The C# port
-  also carries the OBJECT branch, so TS and C# agree. This is **dormant** under both the
-  conformance corpus (no nested fixture; the runner's schema parser never sets `nested`) and the
-  FR-010 codegen (Phase 3 emits the scalar placeholder for cross-port parity), so it changes no
-  shared-corpus result. If a future shared fixture adds a nested case, Java/Kotlin catch up.
-
-## Intentional, documented divergence (NOT a bug)
-
-The cross-port contract pins *classification + canonical value* (numbers within ±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); TS uses `Number(...)` + `Number.isFinite`,
-  which rejects them → **MALFORMED** (same accepted divergence the C# port records). The
-  load-bearing behavior — finite-only acceptance, `NaN`/`±Infinity` → MALFORMED — is identical.
-
-- **JS-only radix-prefixed literals are GUARDED for parity.** `Number("0x10")` is `16` in JS, but
-  Java/C# reject `0x..`/`0b..`/`0o..` → MALFORMED. `parseFiniteNumber` rejects these prefixes
-  explicitly so TS matches Java/C# (→ MALFORMED) rather than over-accepting. (Not a divergence —
-  noted here because the guard exists precisely to prevent one.)
-
-## Bounded deferral (parity with all ports)
-
-- Array-of-enum is not specialized (a scalar array recovers via `asStringList`).
-- `asInt`/`asLong` both return `number | null` (JS has one number type) and truncate toward zero.

package/src/recover/coerce.ts

@@ -1,141 +0,0 @@
-// Stage 7: canonicalize a raw scalar string per its FieldSpec. Returns the MALFORMED
-// sentinel when present-but-uncoercible. Mirrors Java Coerce.
-//
-// Tier-2 divergence (documented, parity with the C# port's KNOWN_GAPS): JS has one
-// number type. INT/LONG both truncate toward zero via Math.trunc and return `number`.
-// Coercion uses Number(...) + Number.isFinite, NOT Java's Double.parseDouble — so JS
-// does NOT accept Java's numeric suffixes ("42d"/"42f") or hex-float literals. The
-// load-bearing contract (finite-only acceptance; NaN/±Infinity → MALFORMED; numeric
-// classification) is identical across ports.
-
-import { FieldKind, Tolerance } from "./types.js";
-import type { FieldSpec, RecoverOptions, RecoveryReport } from "./types.js";
-
-/** Sentinel: the value was present but could not be coerced to the declared kind/vocabulary. */
-export const MALFORMED: unique symbol = Symbol("recover.coerce.MALFORMED");
-
-export function coerceValue(
-  raw: string | null,
-  spec: FieldSpec,
-  opts: RecoverOptions,
-  fieldPath: string,
-  report: RecoveryReport,
-): unknown | typeof MALFORMED {
-  if (raw == null) return MALFORMED;
-
-  if (opts.onField != null) {
-    const hooked = opts.onField(fieldPath, raw, spec);
-    if (hooked != null) {
-      report.addCoercion({ fieldPath, from: raw, to: stringify(hooked), kind: "onField" });
-      return hooked;
-    }
-  }
-
-  // Per-field runtime normalizer (bounded 20% surface). Keyed by field path, then simple name.
-  const norm = opts.normalizers[fieldPath] ?? opts.normalizers[spec.name];
-  if (norm != null) {
-    const normalized = norm(raw);
-    if (normalized != null) {
-      report.addCoercion({ fieldPath, from: raw, to: stringify(normalized), kind: "normalizer" });
-      return normalized;
-    }
-  }
-
-  const ci = opts.tolerance !== Tolerance.STRICT;
-  switch (spec.kind) {
-    case FieldKind.ENUM:
-      return coerceEnum(raw, spec, opts, fieldPath, report, ci);
-    case FieldKind.INT:
-    case FieldKind.LONG:
-      return coerceInt(raw, spec, fieldPath, report);
-    case FieldKind.DOUBLE:
-      return coerceDouble(raw, spec, fieldPath, report);
-    case FieldKind.BOOLEAN:
-      return coerceBool(raw, ci);
-    default:
-      return raw;
-  }
-}
-
-function coerceEnum(
-  raw: string,
-  spec: FieldSpec,
-  opts: RecoverOptions,
-  path: string,
-  report: RecoveryReport,
-  ci: boolean,
-): unknown | typeof MALFORMED {
-  if (spec.enumValues != null) {
-    for (const v of spec.enumValues) {
-      if (v === raw) return v;
-      if (ci && v.toLowerCase() === raw.toLowerCase()) {
-        report.addCoercion({ fieldPath: path, from: raw, to: v, kind: "case" });
-        return v;
-      }
-    }
-  }
-  const schemaTarget = spec.enumAlias == null ? undefined : spec.enumAlias[raw];
-  const runtimeTarget = opts.aliases[raw];
-  if (runtimeTarget != null) {
-    const kind = schemaTarget != null && schemaTarget !== runtimeTarget ? "runtime-alias-override" : "alias";
-    report.addCoercion({ fieldPath: path, from: raw, to: runtimeTarget, kind });
-    return runtimeTarget;
-  }
-  if (schemaTarget != null) {
-    report.addCoercion({ fieldPath: path, from: raw, to: schemaTarget, kind: "alias" });
-    return schemaTarget;
-  }
-  return MALFORMED;
-}
-
-function coerceInt(raw: string, spec: FieldSpec, path: string, report: RecoveryReport): unknown | typeof MALFORMED {
-  const n = parseFiniteNumber(raw);
-  if (n === null) return MALFORMED;
-  return clamp(Math.trunc(n), spec, path, report);
-}
-
-function coerceDouble(raw: string, spec: FieldSpec, path: string, report: RecoveryReport): unknown | typeof MALFORMED {
-  const n = parseFiniteNumber(raw);
-  if (n === null) return MALFORMED;
-  return clamp(n, spec, path, report);
-}
-
-/** Parse a trimmed numeric string; null if empty, non-numeric, or non-finite (NaN/±Infinity). */
-function parseFiniteNumber(raw: string): number | null {
-  const t = raw.trim();
-  if (t.length === 0) return null;
-  // Reject JS-only radix-prefixed literals (0x.., 0b.., 0o..) that Number() would
-  // accept but Java/C# numeric parsing rejects → MALFORMED. Keeps cross-port parity.
-  if (/^[+-]?0[xXbBoO]/.test(t)) return null;
-  const n = Number(t); // Number("") === 0, hence the empty guard above
-  return Number.isFinite(n) ? n : null;
-}
-
-function clamp(n: number, spec: FieldSpec, path: string, report: RecoveryReport): number {
-  let c = n;
-  if (spec.min != null && c < spec.min) c = spec.min;
-  if (spec.max != null && c > spec.max) c = spec.max;
-  if (c !== n) report.addCoercion({ fieldPath: path, from: stringify(n), to: stringify(c), kind: "clamp" });
-  return c;
-}
-
-function coerceBool(raw: string, ci: boolean): boolean | typeof MALFORMED {
-  const t = ci ? raw.trim().toLowerCase() : raw.trim();
-  switch (t) {
-    case "true":
-    case "yes":
-    case "1":
-      return true;
-    case "false":
-    case "no":
-    case "0":
-      return false;
-    default:
-      return MALFORMED;
-  }
-}
-
-/** Canonical string form (locale-independent), mirroring Java String.valueOf for the corpus. */
-function stringify(v: unknown): string {
-  return String(v);
-}

package/src/recover/recover.ts

@@ -1,146 +0,0 @@
-// Public entry point. Runs the staged pipeline; NEVER throws. Mirrors Java Recover.
-
-import {
-  Format,
-  FieldKind,
-  FieldRecovery,
-  Tolerance,
-  normalizeOptions,
-} from "./types.js";
-import type { FieldSpec, RecoverOptions, RecoverOutcome, RecoverSchema } from "./types.js";
-import { RecoveryReport } from "./types.js";
-import { strip } from "./strip.js";
-import { locateJson, locateXml } from "./locate.js";
-import { readJson, TRUNCATED } from "./json-forgiving-reader.js";
-import { readXml } from "./xml-forgiving-reader.js";
-import { coerceValue, MALFORMED } from "./coerce.js";
-
-/** The forgiving entry point: recover dirty `text` against `schema`. Never throws. */
-export function recover(
-  text: string | null | undefined,
-  schema: RecoverSchema,
-  opts?: Partial<RecoverOptions> | null,
-): RecoverOutcome {
-  const o = normalizeOptions(opts);
-  const report = new RecoveryReport();
-  const data: Record<string, unknown> = {};
-
-  const stripped = strip(text);
-  const ci = o.tolerance !== Tolerance.STRICT;
-
-  const span =
-    schema.format === Format.JSON ? locateJson(stripped) : locateXml(stripped, schema.rootName, ci);
-
-  let raw: Record<string, unknown>;
-  if (span == null) {
-    raw = {};
-  } else if (schema.format === Format.JSON) {
-    raw = readJson(span);
-  } else {
-    raw = readXml(span, ci);
-  }
-
-  if (isEmptyRecord(raw) && (stripped.length === 0 || span == null)) {
-    report.markEmpty();
-  }
-
-  extract(schema.fields, raw, "", data, report, o, ci);
-  return { data, report };
-}
-
-function extract(
-  fields: readonly FieldSpec[],
-  raw: Record<string, unknown>,
-  prefix: string,
-  data: Record<string, unknown>,
-  report: RecoveryReport,
-  o: RecoverOptions,
-  ci: boolean,
-): void {
-  for (const f of fields) {
-    const path = prefix.length === 0 ? f.name : `${prefix}.${f.name}`;
-    const present = lookup(raw, f.name, ci);
-    if (present === undefined) {
-      report.set(path, f.required ? FieldRecovery.LOST_REQUIRED : FieldRecovery.LOST_OPTIONAL);
-      continue;
-    }
-    if (present === TRUNCATED) {
-      // present-but-garbled (empty/cut-off value)
-      report.set(path, FieldRecovery.MALFORMED);
-      continue;
-    }
-    if (f.array) {
-      // An array field: a single non-list value is treated as a one-element array
-      // (e.g. a single repeated-XML tag). Each element is coerced/recursed independently.
-      const elements: unknown[] = Array.isArray(present) ? present : [present];
-      const out: unknown[] = [];
-      let anyMalformed = false;
-      for (let idx = 0; idx < elements.length; idx++) {
-        const v = extractValue(f, elements[idx], `${path}[${idx}]`, report, o, ci);
-        if (v === MALFORMED) anyMalformed = true;
-        else out.push(v);
-      }
-      // Cross-port contract: a MALFORMED array still places its successfully-coerced
-      // elements into data (partial recovery), UNLIKE a MALFORMED scalar which is absent.
-      data[f.name] = out;
-      report.set(path, anyMalformed ? FieldRecovery.MALFORMED : FieldRecovery.RECOVERED);
-      continue;
-    }
-    if (Array.isArray(present)) {
-      // a list where a singular value was expected
-      report.set(path, FieldRecovery.MALFORMED);
-      continue;
-    }
-    const v = extractValue(f, present, path, report, o, ci);
-    if (v === MALFORMED) {
-      report.set(path, FieldRecovery.MALFORMED);
-    } else {
-      data[f.name] = v;
-      report.set(path, FieldRecovery.RECOVERED);
-    }
-  }
-}
-
-/** Coerce one (non-array) element: nested-object recursion or scalar coercion. Returns MALFORMED on failure. */
-function extractValue(
-  f: FieldSpec,
-  present: unknown,
-  path: string,
-  report: RecoveryReport,
-  o: RecoverOptions,
-  ci: boolean,
-): unknown | typeof MALFORMED {
-  if (f.kind === FieldKind.OBJECT) {
-    if (f.nested != null && isPlainObject(present)) {
-      const nestedData: Record<string, unknown> = {};
-      extract(f.nested.fields, present as Record<string, unknown>, path, nestedData, report, o, ci);
-      return nestedData;
-    }
-    return MALFORMED; // object expected but scalar/non-map present
-  }
-  const rawStr = typeof present === "string" ? present : stringifyScalar(present);
-  return coerceValue(rawStr, f, o, path, report);
-}
-
-/** Case-folding lookup honoring tolerance. Returns `undefined` for absent (mirrors Java null). */
-function lookup(raw: Record<string, unknown>, name: string, ci: boolean): unknown {
-  if (Object.prototype.hasOwnProperty.call(raw, name)) return raw[name];
-  if (ci) {
-    const lower = name.toLowerCase();
-    for (const k of Object.keys(raw)) if (k.toLowerCase() === lower) return raw[k];
-  }
-  return undefined;
-}
-
-function isPlainObject(o: unknown): boolean {
-  return typeof o === "object" && o !== null && !Array.isArray(o);
-}
-
-function isEmptyRecord(o: Record<string, unknown>): boolean {
-  return Object.keys(o).length === 0;
-}
-
-/** Mirror Java String.valueOf for non-string forgiving-reader scalars. */
-function stringifyScalar(v: unknown): string {
-  return String(v);
-}

package/src/recover/types.ts

@@ -1,217 +0,0 @@
-// FR-010 recover engine — types & model (Tier-2 idiomatic TS port).
-//
-// Cross-port REFERENCE is the Java engine
-// (server/java/render/.../recover/). This file ports the Java records/enums to
-// idiomatic TS: enums become string-union `as const` objects (values match the
-// corpus / Java enum names exactly), records become readonly interfaces +
-// factory functions, and the mutable RecoveryReport is a class.
-
-/** Output format the dirty text claims to be. Corpus schema.json uses "JSON"/"XML". */
-export const Format = {
-  JSON: "JSON",
-  XML: "XML",
-} as const;
-export type Format = (typeof Format)[keyof typeof Format];
-
-/** The coercion target kinds the engine understands. OBJECT = nested RecoverSchema. */
-export const FieldKind = {
-  STRING: "STRING",
-  INT: "INT",
-  LONG: "LONG",
-  DOUBLE: "DOUBLE",
-  BOOLEAN: "BOOLEAN",
-  ENUM: "ENUM",
-  OBJECT: "OBJECT",
-} as const;
-export type FieldKind = (typeof FieldKind)[keyof typeof FieldKind];
-
-/**
- * FROZEN cross-port per-field recovery classification. Do not reorder or add
- * without an ADR. These string values are SERIALIZED in the conformance corpus.
- */
-export const FieldRecovery = {
-  RECOVERED: "RECOVERED",
-  // DEFAULTED is reserved (a future @default-backed value); the engine does not emit it yet.
-  DEFAULTED: "DEFAULTED",
-  LOST_OPTIONAL: "LOST_OPTIONAL",
-  LOST_REQUIRED: "LOST_REQUIRED",
-  MALFORMED: "MALFORMED",
-} as const;
-export type FieldRecovery = (typeof FieldRecovery)[keyof typeof FieldRecovery];
-
-/**
- * STRICT: case-sensitive, minimal repair. NORMAL: case-insensitive keys/tags
- * (default). LOOSE: maximal repair (currently identical to NORMAL — reserved).
- */
-export const Tolerance = {
-  STRICT: "STRICT",
-  NORMAL: "NORMAL",
-  LOOSE: "LOOSE",
-} as const;
-export type Tolerance = (typeof Tolerance)[keyof typeof Tolerance];
-
-/** A recorded normalization/coercion. kind e.g. "alias", "clamp", "case", "runtime-alias-override". */
-export interface Coercion {
-  readonly fieldPath: string;
-  readonly from: string;
-  readonly to: string;
-  readonly kind: string;
-}
-
-/**
- * One field's recover descriptor. enumValues/enumAlias non-null only for ENUM;
- * min/max non-null only for numeric range constraints; nested non-null only for OBJECT.
- */
-export interface FieldSpec {
-  readonly name: string;
-  readonly kind: FieldKind;
-  readonly required: boolean;
-  readonly array: boolean;
-  readonly enumValues: readonly string[] | null;
-  readonly enumAlias: Readonly<Record<string, string>> | null;
-  readonly min: number | null;
-  readonly max: number | null;
-  readonly nested: RecoverSchema | null;
-}
-
-export function scalar(name: string, kind: FieldKind, required: boolean): FieldSpec {
-  return { name, kind, required, array: false, enumValues: null, enumAlias: null, min: null, max: null, nested: null };
-}
-
-export function enumField(
-  name: string,
-  required: boolean,
-  values: readonly string[] | null,
-  aliases: Readonly<Record<string, string>> | null,
-): FieldSpec {
-  return {
-    name,
-    kind: FieldKind.ENUM,
-    required,
-    array: false,
-    enumValues: values == null ? null : [...values],
-    enumAlias: aliases == null ? {} : { ...aliases },
-    min: null,
-    max: null,
-    nested: null,
-  };
-}
-
-export function range(
-  name: string,
-  kind: FieldKind,
-  required: boolean,
-  min: number | null,
-  max: number | null,
-): FieldSpec {
-  return { name, kind, required, array: false, enumValues: null, enumAlias: null, min, max, nested: null };
-}
-
-export function object(name: string, required: boolean, array: boolean, nested: RecoverSchema | null): FieldSpec {
-  return { name, kind: FieldKind.OBJECT, required, array, enumValues: null, enumAlias: null, min: null, max: null, nested };
-}
-
-/** Top-level recover descriptor. rootName = the XML root tag / logical JSON root name. */
-export interface RecoverSchema {
-  readonly format: Format;
-  readonly rootName: string;
-  readonly fields: readonly FieldSpec[];
-}
-
-export function recoverSchema(format: Format, rootName: string, fields: readonly FieldSpec[] | null): RecoverSchema {
-  return { format, rootName, fields: fields == null ? [] : [...fields] };
-}
-
-/**
- * ctx carries the field path and the FieldSpec; return null to fall through to
- * default coercion. The single bespoke-coercion hook (the bounded "20%").
- */
-export type OnField = (fieldPath: string, rawValue: string, spec: FieldSpec) => unknown | null;
-
-/**
- * Bounded runtime override surface. aliases/normalizers are MERGED with the
- * schema's, runtime winning on key conflict. onField is the single hook.
- */
-export interface RecoverOptions {
-  readonly tolerance: Tolerance;
-  readonly aliases: Readonly<Record<string, string>>;
-  readonly normalizers: Readonly<Record<string, (raw: string) => unknown | null>>;
-  readonly onField: OnField | null;
-}
-
-export function defaults(): RecoverOptions {
-  return { tolerance: Tolerance.NORMAL, aliases: {}, normalizers: {}, onField: null };
-}
-
-/** Normalize a partial / undefined options bag into a complete RecoverOptions. */
-export function normalizeOptions(opts?: Partial<RecoverOptions> | null): RecoverOptions {
-  if (opts == null) return defaults();
-  return {
-    tolerance: opts.tolerance ?? Tolerance.NORMAL,
-    aliases: opts.aliases == null ? {} : { ...opts.aliases },
-    normalizers: opts.normalizers == null ? {} : { ...opts.normalizers },
-    onField: opts.onField ?? null,
-  };
-}
-
-/** Engine return. data is a forgiving record; Phase-2 codegen wraps it into a typed RecoveryResult<T>. */
-export interface RecoverOutcome {
-  readonly data: Record<string, unknown>;
-  readonly report: RecoveryReport;
-}
-
-/** Typed result of a generated recover(...): best-effort value (null where lost/malformed) + report. */
-export interface RecoveryResult<T> {
-  readonly data: T | null;
-  readonly report: RecoveryReport;
-}
-
-/** Mutable accumulator of per-field recovery classification, the degenerate-response flag, and coercion notes. */
-export class RecoveryReport {
-  // Insertion-ordered (Map preserves insertion order, mirroring Java LinkedHashMap).
-  private readonly _states = new Map<string, FieldRecovery>();
-  private readonly _coercions: Coercion[] = [];
-  private _empty = false;
-
-  set(fieldPath: string, state: FieldRecovery): void {
-    this._states.set(fieldPath, state);
-  }
-
-  addCoercion(c: Coercion): void {
-    this._coercions.push(c);
-  }
-
-  markEmpty(): void {
-    this._empty = true;
-  }
-
-  isEmpty(): boolean {
-    return this._empty;
-  }
-
-  states(): ReadonlyMap<string, FieldRecovery> {
-    return new Map(this._states);
-  }
-
-  coercions(): readonly Coercion[] {
-    return [...this._coercions];
-  }
-
-  lostRequired(): string[] {
-    return this.byState(FieldRecovery.LOST_REQUIRED);
-  }
-
-  malformed(): string[] {
-    return this.byState(FieldRecovery.MALFORMED);
-  }
-
-  hasLostRequired(): boolean {
-    return this.lostRequired().length > 0;
-  }
-
-  private byState(s: FieldRecovery): string[] {
-    const out: string[] = [];
-    for (const [k, v] of this._states) if (v === s) out.push(k);
-    return out;
-  }
-}