@mailwoman/api 9.1.0 → 9.3.0

package/out/schema.d.ts

@@ -7,7 +7,7 @@
  *   libpostal), nothing here is a vendor contract — this surface is ours to design, so request
  *   bodies are REQUIRED and validator-enforced (no legacy tolerance to preserve). A `defaultHook`
  *   on the app maps validation failures through the shared `APIErrorSchema` envelope
- *   (`apiError(c, 400, "invalid request body", <zod summary>)`) — the pattern boundary every
+ *   (`errorResponse(c, 400, "invalid request body", <zod summary>)`) — the pattern boundary every
  *   surface holds to: where no legacy contract exists, the validator MAY speak, but only in
  *   our envelope.
  *
@@ -16,10 +16,16 @@
  *   and error alike, from this one file.
  */
 import { z } from "@hono/zod-openapi";
+import type { AddressNode } from "@mailwoman/core/decoder";
 export { APIErrorSchema } from "@mailwoman/api-kit";
 /**
  * `POST /v1/parse` request body.
  */
+/**
+ * One node of the decoded address tree. The decoder's `AddressNode` is a recursive union the OpenAPI generator cannot
+ * derive a schema for on its own, so it is registered as an open object; the shape is documented by the type.
+ */
+export declare const AddressNodeSchema: z.ZodCustom<AddressNode, AddressNode>;
 /**
  * The input register (Decision A / GTM B10): `fragmented` = the map-search register (evidence-bundle channels feed);
  * `formatted` = the validation/record register (channels off). Unset → the engine derives it from the input's shape.
@@ -73,7 +79,8 @@ export declare const ParseOutcomeSchema: z.ZodObject<{
         value: z.ZodString;
     }, z.core.$strip>>;
     tree: z.ZodObject<{
-        roots: z.ZodArray<z.ZodUnknown>;
+        raw: z.ZodString;
+        roots: z.ZodArray<z.ZodCustom<AddressNode, AddressNode>>;
     }, z.core.$loose>;
     debug: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -87,6 +94,307 @@ export declare const GeocodeRequestSchema: z.ZodObject<{
         formatted: "formatted";
     }>>;
 }, z.core.$strip>;
+/**
+ * The derivation behind a geocode answer, present only when the engine was asked to trace — `@mailwoman/evidence`'s
+ * `DerivationProjection` on the wire.
+ */
+export declare const DerivationProjectionSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        designated: "designated";
+        observed: "observed";
+        derived: "derived";
+        inferred: "inferred";
+        unresolved: "unresolved";
+    }>;
+    constraints: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        evidence: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"observation">;
+            source: z.ZodString;
+            vintage: z.ZodNullable<z.ZodString>;
+            value: z.ZodUnknown;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"exclusion">;
+            source: z.ZodString;
+            vintage: z.ZodString;
+            scope: z.ZodObject<{
+                layer: z.ZodString;
+                h3Cell: z.ZodNumber;
+                basis: z.ZodEnum<{
+                    designated: "designated";
+                    surveyed: "surveyed";
+                    source_present: "source_present";
+                }>;
+                fold: z.ZodString;
+            }, z.core.$strip>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"relation">;
+            source: z.ZodString;
+            vintage: z.ZodString;
+            relationship: z.ZodString;
+            assertion: z.ZodEnum<{
+                inferred: "inferred";
+                authoritative: "authoritative";
+            }>;
+            score: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"prior">;
+            source: z.ZodString;
+            label: z.ZodString;
+            weight: z.ZodNumber;
+        }, z.core.$strip>], "kind">;
+        contribution: z.ZodString;
+    }, z.core.$strip>>>;
+    uncertaintyM: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * `POST /v1/geocode` response — a hand-modeled mirror of `GeocodeResult`'s wire shape (`mailwoman/geocode-core.ts`),
+ * `.loose()` so a field the engine adds that this schema doesn't yet know about still rides through undocumented rather
+ * than being stripped or rejected. DOC-ACCURACY ONLY: the route passes `engine.geocode()`'s outcome through verbatim
+ * (`GeocodeOutcome = Record<string, unknown>`, `api/engine.ts`) — nothing here validates a real response, so a
+ * schema/engine mismatch can never reject or mutate a result at runtime. Deliberately carries NO import from
+ * `mailwoman` (the engine-agnosticism boundary — `mailwoman` is the one workspace allowed to depend on
+ * `@mailwoman/api`, never the reverse). `mailwoman/test/api-schema-drift.test.ts` is the compile-time regression check
+ * that catches this shape drifting from the real `GeocodeResult` interface.
+ */
+export declare const GeocodeOutcomeLikeSchema: z.ZodObject<{
+    input: z.ZodString;
+    components: z.ZodRecord<z.ZodEnum<{
+        country: "country";
+        region: "region";
+        locality: "locality";
+        dependent_locality: "dependent_locality";
+        postcode: "postcode";
+        subregion: "subregion";
+        house_number: "house_number";
+        street: "street";
+        street_prefix: "street_prefix";
+        street_prefix_particle: "street_prefix_particle";
+        street_suffix: "street_suffix";
+        intersection_a: "intersection_a";
+        intersection_b: "intersection_b";
+        unit: "unit";
+        venue: "venue";
+        attention: "attention";
+        po_box: "po_box";
+        cedex: "cedex";
+        prefecture: "prefecture";
+        municipality: "municipality";
+        district: "district";
+        block: "block";
+        sub_block: "sub_block";
+        building_number: "building_number";
+        building_name: "building_name";
+        locality_unit: "locality_unit";
+    }> & z.core.$partial, z.ZodString>;
+    lat: z.ZodNullable<z.ZodNumber>;
+    lon: z.ZodNullable<z.ZodNumber>;
+    resolution_tier: z.ZodEnum<{
+        street: "street";
+        venue: "venue";
+        address_point: "address_point";
+        interpolated: "interpolated";
+        admin: "admin";
+        plus_code: "plus_code";
+    }>;
+    epistemic_status: z.ZodEnum<{
+        designated: "designated";
+        observed: "observed";
+        derived: "derived";
+        inferred: "inferred";
+        unresolved: "unresolved";
+    }>;
+    derivation: z.ZodOptional<z.ZodObject<{
+        status: z.ZodEnum<{
+            designated: "designated";
+            observed: "observed";
+            derived: "derived";
+            inferred: "inferred";
+            unresolved: "unresolved";
+        }>;
+        constraints: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            evidence: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"observation">;
+                source: z.ZodString;
+                vintage: z.ZodNullable<z.ZodString>;
+                value: z.ZodUnknown;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"exclusion">;
+                source: z.ZodString;
+                vintage: z.ZodString;
+                scope: z.ZodObject<{
+                    layer: z.ZodString;
+                    h3Cell: z.ZodNumber;
+                    basis: z.ZodEnum<{
+                        designated: "designated";
+                        surveyed: "surveyed";
+                        source_present: "source_present";
+                    }>;
+                    fold: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"relation">;
+                source: z.ZodString;
+                vintage: z.ZodString;
+                relationship: z.ZodString;
+                assertion: z.ZodEnum<{
+                    inferred: "inferred";
+                    authoritative: "authoritative";
+                }>;
+                score: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"prior">;
+                source: z.ZodString;
+                label: z.ZodString;
+                weight: z.ZodNumber;
+            }, z.core.$strip>], "kind">;
+            contribution: z.ZodString;
+        }, z.core.$strip>>>;
+        uncertaintyM: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    entity: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        categoryID: z.ZodNullable<z.ZodString>;
+        confidence: z.ZodNumber;
+        country: z.ZodString;
+    }, z.core.$strip>>;
+    uncertainty_m: z.ZodNullable<z.ZodNumber>;
+    locality: z.ZodNullable<z.ZodString>;
+    region: z.ZodNullable<z.ZodString>;
+    postcode: z.ZodNullable<z.ZodString>;
+    house_number: z.ZodNullable<z.ZodString>;
+    street: z.ZodNullable<z.ZodString>;
+    venue: z.ZodNullable<z.ZodString>;
+    dependent_locality: z.ZodNullable<z.ZodString>;
+    unit: z.ZodNullable<z.ZodString>;
+    countryCode: z.ZodNullable<z.ZodString>;
+    hierarchy: z.ZodArray<z.ZodObject<{
+        tag: z.ZodString;
+        value: z.ZodString;
+        name: z.ZodString;
+        lat: z.ZodOptional<z.ZodNumber>;
+        lon: z.ZodOptional<z.ZodNumber>;
+        placeID: z.ZodOptional<z.ZodString>;
+        in_winner_lineage: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    candidates: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        tag: z.ZodString;
+        lat: z.ZodNumber;
+        lon: z.ZodNumber;
+        countryCode: z.ZodNullable<z.ZodString>;
+        placeID: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    rooftop: z.ZodOptional<z.ZodObject<{
+        localityNorm: z.ZodOptional<z.ZodString>;
+        postcode: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    postcode_country_scope: z.ZodNullable<z.ZodString>;
+    capital_promotion: z.ZodOptional<z.ZodString>;
+    variant_alias_exemption: z.ZodOptional<z.ZodLiteral<true>>;
+    intent_markers: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            intersection: "intersection";
+            po_box: "po_box";
+            postcode_only: "postcode_only";
+            locality_only: "locality_only";
+            structured_address: "structured_address";
+            landmark: "landmark";
+            poi_query: "poi_query";
+            vague: "vague";
+            bare_toponym: "bare_toponym";
+            route_pair: "route_pair";
+            near_me: "near_me";
+            poi_category: "poi_category";
+        }>;
+        code: z.ZodEnum<{
+            poi_category: "poi_category";
+            declared_ambiguity: "declared_ambiguity";
+            declared_fork: "declared_fork";
+            focus_point_required: "focus_point_required";
+            coverage_qualified_absence: "coverage_qualified_absence";
+            authority_designation: "authority_designation";
+        }>;
+        mechanism: z.ZodString;
+        message: z.ZodString;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    admin_coherence: z.ZodOptional<z.ZodObject<{
+        region: z.ZodEnum<{
+            confirmed: "confirmed";
+            contradicted: "contradicted";
+            unstated: "unstated";
+            unverifiable: "unverifiable";
+        }>;
+        country: z.ZodEnum<{
+            confirmed: "confirmed";
+            contradicted: "contradicted";
+            unstated: "unstated";
+            unverifiable: "unverifiable";
+        }>;
+    }, z.core.$strip>>;
+    authoritative: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        status: z.ZodEnum<{
+            matched: "matched";
+            ambiguous: "ambiguous";
+            refused: "refused";
+            transport_error: "transport_error";
+        }>;
+        matches: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            provider_place_id: z.ZodString;
+            object_ids: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            canonical_fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            lat: z.ZodOptional<z.ZodNumber>;
+            lon: z.ZodOptional<z.ZodNumber>;
+            precision: z.ZodOptional<z.ZodString>;
+            match_status: z.ZodEnum<{
+                exact: "exact";
+                approximate: "approximate";
+            }>;
+            provider_score: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
+        attribution: z.ZodOptional<z.ZodString>;
+        license: z.ZodOptional<z.ZodString>;
+        retrieved_at: z.ZodOptional<z.ZodString>;
+        dataset_version: z.ZodOptional<z.ZodString>;
+        error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    dropped_components: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        tag: z.ZodEnum<{
+            country: "country";
+            region: "region";
+            locality: "locality";
+            dependent_locality: "dependent_locality";
+            postcode: "postcode";
+            subregion: "subregion";
+            house_number: "house_number";
+            street: "street";
+            street_prefix: "street_prefix";
+            street_prefix_particle: "street_prefix_particle";
+            street_suffix: "street_suffix";
+            intersection_a: "intersection_a";
+            intersection_b: "intersection_b";
+            unit: "unit";
+            venue: "venue";
+            attention: "attention";
+            po_box: "po_box";
+            cedex: "cedex";
+            prefecture: "prefecture";
+            municipality: "municipality";
+            district: "district";
+            block: "block";
+            sub_block: "sub_block";
+            building_number: "building_number";
+            building_name: "building_name";
+            locality_unit: "locality_unit";
+        }>;
+        value: z.ZodString;
+        kept: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type GeocodeOutcomeLike = z.infer<typeof GeocodeOutcomeLikeSchema>;
 /**
  * `POST /v1/geocode` response — a hand-modeled mirror of `GeocodeResult`'s wire shape (`mailwoman/geocode-core.ts`),
  * `.loose()` so a field the engine adds that this schema doesn't yet know about still rides through undocumented rather
@@ -94,8 +402,8 @@ export declare const GeocodeRequestSchema: z.ZodObject<{
  * (`GeocodeOutcome = Record<string, unknown>`, `api/engine.ts`) — nothing here validates a real response, so a
  * schema/engine mismatch can never reject or mutate a result at runtime. Deliberately carries NO import from
  * `mailwoman` (the engine-agnosticism boundary — `mailwoman` is the one workspace allowed to depend on
- * `@mailwoman/api`, never the reverse). `mailwoman/test/api-schema-drift.test.ts` is the compile-time tripwire that
- * catches this shape drifting from the real `GeocodeResult` interface.
+ * `@mailwoman/api`, never the reverse). `mailwoman/test/api-schema-drift.test.ts` is the compile-time regression check
+ * that catches this shape drifting from the real `GeocodeResult` interface.
  */
 export declare const GeocodeOutcomeSchema: z.ZodObject<{
     input: z.ZodString;
@@ -125,15 +433,80 @@ export declare const GeocodeOutcomeSchema: z.ZodObject<{
         sub_block: "sub_block";
         building_number: "building_number";
         building_name: "building_name";
+        locality_unit: "locality_unit";
     }> & z.core.$partial, z.ZodString>;
     lat: z.ZodNullable<z.ZodNumber>;
     lon: z.ZodNullable<z.ZodNumber>;
     resolution_tier: z.ZodEnum<{
         street: "street";
+        venue: "venue";
         address_point: "address_point";
         interpolated: "interpolated";
         admin: "admin";
+        plus_code: "plus_code";
     }>;
+    epistemic_status: z.ZodEnum<{
+        designated: "designated";
+        observed: "observed";
+        derived: "derived";
+        inferred: "inferred";
+        unresolved: "unresolved";
+    }>;
+    derivation: z.ZodOptional<z.ZodObject<{
+        status: z.ZodEnum<{
+            designated: "designated";
+            observed: "observed";
+            derived: "derived";
+            inferred: "inferred";
+            unresolved: "unresolved";
+        }>;
+        constraints: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            evidence: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"observation">;
+                source: z.ZodString;
+                vintage: z.ZodNullable<z.ZodString>;
+                value: z.ZodUnknown;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"exclusion">;
+                source: z.ZodString;
+                vintage: z.ZodString;
+                scope: z.ZodObject<{
+                    layer: z.ZodString;
+                    h3Cell: z.ZodNumber;
+                    basis: z.ZodEnum<{
+                        designated: "designated";
+                        surveyed: "surveyed";
+                        source_present: "source_present";
+                    }>;
+                    fold: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"relation">;
+                source: z.ZodString;
+                vintage: z.ZodString;
+                relationship: z.ZodString;
+                assertion: z.ZodEnum<{
+                    inferred: "inferred";
+                    authoritative: "authoritative";
+                }>;
+                score: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"prior">;
+                source: z.ZodString;
+                label: z.ZodString;
+                weight: z.ZodNumber;
+            }, z.core.$strip>], "kind">;
+            contribution: z.ZodString;
+        }, z.core.$strip>>>;
+        uncertaintyM: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    entity: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        categoryID: z.ZodNullable<z.ZodString>;
+        confidence: z.ZodNumber;
+        country: z.ZodString;
+    }, z.core.$strip>>;
     uncertainty_m: z.ZodNullable<z.ZodNumber>;
     locality: z.ZodNullable<z.ZodString>;
     region: z.ZodNullable<z.ZodString>;
@@ -151,6 +524,7 @@ export declare const GeocodeOutcomeSchema: z.ZodObject<{
         lat: z.ZodOptional<z.ZodNumber>;
         lon: z.ZodOptional<z.ZodNumber>;
         placeID: z.ZodOptional<z.ZodString>;
+        in_winner_lineage: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     candidates: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -160,7 +534,13 @@ export declare const GeocodeOutcomeSchema: z.ZodObject<{
         countryCode: z.ZodNullable<z.ZodString>;
         placeID: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    rooftop: z.ZodOptional<z.ZodObject<{
+        localityNorm: z.ZodOptional<z.ZodString>;
+        postcode: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     postcode_country_scope: z.ZodNullable<z.ZodString>;
+    capital_promotion: z.ZodOptional<z.ZodString>;
+    variant_alias_exemption: z.ZodOptional<z.ZodLiteral<true>>;
     intent_markers: z.ZodArray<z.ZodObject<{
         kind: z.ZodEnum<{
             intersection: "intersection";
@@ -181,12 +561,88 @@ export declare const GeocodeOutcomeSchema: z.ZodObject<{
             declared_ambiguity: "declared_ambiguity";
             declared_fork: "declared_fork";
             focus_point_required: "focus_point_required";
+            coverage_qualified_absence: "coverage_qualified_absence";
+            authority_designation: "authority_designation";
         }>;
         mechanism: z.ZodString;
         message: z.ZodString;
         evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
+    admin_coherence: z.ZodOptional<z.ZodObject<{
+        region: z.ZodEnum<{
+            confirmed: "confirmed";
+            contradicted: "contradicted";
+            unstated: "unstated";
+            unverifiable: "unverifiable";
+        }>;
+        country: z.ZodEnum<{
+            confirmed: "confirmed";
+            contradicted: "contradicted";
+            unstated: "unstated";
+            unverifiable: "unverifiable";
+        }>;
+    }, z.core.$strip>>;
+    authoritative: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        status: z.ZodEnum<{
+            matched: "matched";
+            ambiguous: "ambiguous";
+            refused: "refused";
+            transport_error: "transport_error";
+        }>;
+        matches: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            provider_place_id: z.ZodString;
+            object_ids: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            canonical_fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            lat: z.ZodOptional<z.ZodNumber>;
+            lon: z.ZodOptional<z.ZodNumber>;
+            precision: z.ZodOptional<z.ZodString>;
+            match_status: z.ZodEnum<{
+                exact: "exact";
+                approximate: "approximate";
+            }>;
+            provider_score: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
+        attribution: z.ZodOptional<z.ZodString>;
+        license: z.ZodOptional<z.ZodString>;
+        retrieved_at: z.ZodOptional<z.ZodString>;
+        dataset_version: z.ZodOptional<z.ZodString>;
+        error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    dropped_components: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        tag: z.ZodEnum<{
+            country: "country";
+            region: "region";
+            locality: "locality";
+            dependent_locality: "dependent_locality";
+            postcode: "postcode";
+            subregion: "subregion";
+            house_number: "house_number";
+            street: "street";
+            street_prefix: "street_prefix";
+            street_prefix_particle: "street_prefix_particle";
+            street_suffix: "street_suffix";
+            intersection_a: "intersection_a";
+            intersection_b: "intersection_b";
+            unit: "unit";
+            venue: "venue";
+            attention: "attention";
+            po_box: "po_box";
+            cedex: "cedex";
+            prefecture: "prefecture";
+            municipality: "municipality";
+            district: "district";
+            block: "block";
+            sub_block: "sub_block";
+            building_number: "building_number";
+            building_name: "building_name";
+            locality_unit: "locality_unit";
+        }>;
+        value: z.ZodString;
+        kept: z.ZodString;
+    }, z.core.$strip>>>;
 }, z.core.$loose>;
+export type GeocodeOutcome = z.infer<typeof GeocodeOutcomeSchema>;
 /**
  * `POST /v1/batch` request body.
  */
@@ -229,15 +685,80 @@ export declare const BatchResponseSchema: z.ZodObject<{
             sub_block: "sub_block";
             building_number: "building_number";
             building_name: "building_name";
+            locality_unit: "locality_unit";
         }> & z.core.$partial, z.ZodString>;
         lat: z.ZodNullable<z.ZodNumber>;
         lon: z.ZodNullable<z.ZodNumber>;
         resolution_tier: z.ZodEnum<{
             street: "street";
+            venue: "venue";
             address_point: "address_point";
             interpolated: "interpolated";
             admin: "admin";
+            plus_code: "plus_code";
         }>;
+        epistemic_status: z.ZodEnum<{
+            designated: "designated";
+            observed: "observed";
+            derived: "derived";
+            inferred: "inferred";
+            unresolved: "unresolved";
+        }>;
+        derivation: z.ZodOptional<z.ZodObject<{
+            status: z.ZodEnum<{
+                designated: "designated";
+                observed: "observed";
+                derived: "derived";
+                inferred: "inferred";
+                unresolved: "unresolved";
+            }>;
+            constraints: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                evidence: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"observation">;
+                    source: z.ZodString;
+                    vintage: z.ZodNullable<z.ZodString>;
+                    value: z.ZodUnknown;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"exclusion">;
+                    source: z.ZodString;
+                    vintage: z.ZodString;
+                    scope: z.ZodObject<{
+                        layer: z.ZodString;
+                        h3Cell: z.ZodNumber;
+                        basis: z.ZodEnum<{
+                            designated: "designated";
+                            surveyed: "surveyed";
+                            source_present: "source_present";
+                        }>;
+                        fold: z.ZodString;
+                    }, z.core.$strip>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"relation">;
+                    source: z.ZodString;
+                    vintage: z.ZodString;
+                    relationship: z.ZodString;
+                    assertion: z.ZodEnum<{
+                        inferred: "inferred";
+                        authoritative: "authoritative";
+                    }>;
+                    score: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"prior">;
+                    source: z.ZodString;
+                    label: z.ZodString;
+                    weight: z.ZodNumber;
+                }, z.core.$strip>], "kind">;
+                contribution: z.ZodString;
+            }, z.core.$strip>>>;
+            uncertaintyM: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>;
+        entity: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            categoryID: z.ZodNullable<z.ZodString>;
+            confidence: z.ZodNumber;
+            country: z.ZodString;
+        }, z.core.$strip>>;
         uncertainty_m: z.ZodNullable<z.ZodNumber>;
         locality: z.ZodNullable<z.ZodString>;
         region: z.ZodNullable<z.ZodString>;
@@ -255,6 +776,7 @@ export declare const BatchResponseSchema: z.ZodObject<{
             lat: z.ZodOptional<z.ZodNumber>;
             lon: z.ZodOptional<z.ZodNumber>;
             placeID: z.ZodOptional<z.ZodString>;
+            in_winner_lineage: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
         candidates: z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -264,7 +786,13 @@ export declare const BatchResponseSchema: z.ZodObject<{
             countryCode: z.ZodNullable<z.ZodString>;
             placeID: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
+        rooftop: z.ZodOptional<z.ZodObject<{
+            localityNorm: z.ZodOptional<z.ZodString>;
+            postcode: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
         postcode_country_scope: z.ZodNullable<z.ZodString>;
+        capital_promotion: z.ZodOptional<z.ZodString>;
+        variant_alias_exemption: z.ZodOptional<z.ZodLiteral<true>>;
         intent_markers: z.ZodArray<z.ZodObject<{
             kind: z.ZodEnum<{
                 intersection: "intersection";
@@ -285,11 +813,86 @@ export declare const BatchResponseSchema: z.ZodObject<{
                 declared_ambiguity: "declared_ambiguity";
                 declared_fork: "declared_fork";
                 focus_point_required: "focus_point_required";
+                coverage_qualified_absence: "coverage_qualified_absence";
+                authority_designation: "authority_designation";
             }>;
             mechanism: z.ZodString;
             message: z.ZodString;
             evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>;
+        admin_coherence: z.ZodOptional<z.ZodObject<{
+            region: z.ZodEnum<{
+                confirmed: "confirmed";
+                contradicted: "contradicted";
+                unstated: "unstated";
+                unverifiable: "unverifiable";
+            }>;
+            country: z.ZodEnum<{
+                confirmed: "confirmed";
+                contradicted: "contradicted";
+                unstated: "unstated";
+                unverifiable: "unverifiable";
+            }>;
+        }, z.core.$strip>>;
+        authoritative: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodString;
+            status: z.ZodEnum<{
+                matched: "matched";
+                ambiguous: "ambiguous";
+                refused: "refused";
+                transport_error: "transport_error";
+            }>;
+            matches: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                provider_place_id: z.ZodString;
+                object_ids: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                canonical_fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                lat: z.ZodOptional<z.ZodNumber>;
+                lon: z.ZodOptional<z.ZodNumber>;
+                precision: z.ZodOptional<z.ZodString>;
+                match_status: z.ZodEnum<{
+                    exact: "exact";
+                    approximate: "approximate";
+                }>;
+                provider_score: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>>;
+            attribution: z.ZodOptional<z.ZodString>;
+            license: z.ZodOptional<z.ZodString>;
+            retrieved_at: z.ZodOptional<z.ZodString>;
+            dataset_version: z.ZodOptional<z.ZodString>;
+            error: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        dropped_components: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            tag: z.ZodEnum<{
+                country: "country";
+                region: "region";
+                locality: "locality";
+                dependent_locality: "dependent_locality";
+                postcode: "postcode";
+                subregion: "subregion";
+                house_number: "house_number";
+                street: "street";
+                street_prefix: "street_prefix";
+                street_prefix_particle: "street_prefix_particle";
+                street_suffix: "street_suffix";
+                intersection_a: "intersection_a";
+                intersection_b: "intersection_b";
+                unit: "unit";
+                venue: "venue";
+                attention: "attention";
+                po_box: "po_box";
+                cedex: "cedex";
+                prefecture: "prefecture";
+                municipality: "municipality";
+                district: "district";
+                block: "block";
+                sub_block: "sub_block";
+                building_number: "building_number";
+                building_name: "building_name";
+                locality_unit: "locality_unit";
+            }>;
+            value: z.ZodString;
+            kept: z.ZodString;
+        }, z.core.$strip>>>;
     }, z.core.$loose>, z.ZodObject<{
         input: z.ZodString;
         error: z.ZodString;
@@ -301,7 +904,8 @@ export declare const BatchResponseSchema: z.ZodObject<{
  */
 export declare const ResolveRequestSchema: z.ZodObject<{
     tree: z.ZodObject<{
-        roots: z.ZodArray<z.ZodUnknown>;
+        raw: z.ZodString;
+        roots: z.ZodArray<z.ZodCustom<AddressNode, AddressNode>>;
     }, z.core.$loose>;
     opts: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
 }, z.core.$strip>;
@@ -310,7 +914,8 @@ export declare const ResolveRequestSchema: z.ZodObject<{
  */
 export declare const ResolveResponseSchema: z.ZodObject<{
     tree: z.ZodObject<{
-        roots: z.ZodArray<z.ZodUnknown>;
+        raw: z.ZodString;
+        roots: z.ZodArray<z.ZodCustom<AddressNode, AddressNode>>;
     }, z.core.$loose>;
 }, z.core.$strip>;
 /**
@@ -333,9 +938,11 @@ export declare const FormatResponseSchema: z.ZodObject<{
 }, z.core.$strip>;
 /**
  * `GET /health` response — `status`/`uptime_s` are stamped by the ROUTE itself, unconditionally, regardless of engine
- * (`api/routes.ts`'s `healthRoute` handler: `{ status: "ok", uptime_s, ...engine.health?.() }`), so those two are cheap
- * + accurate to pin. Everything else is `HealthData` (`api/engine.ts`) — an engine-defined block (model card, data-root
- * inventory for `mailwoman serve`; something else entirely for another engine) — stays loose.
+ * (`api/routes.ts`'s `healthRoute` handler: `{ status: "ok", uptime_s, ...engine.health?.() }`), so those two are
+ * cheap
+ *
+ * - Accurate to pin. Everything else is `HealthData` (`api/engine.ts`) — an engine-defined block (model card, data-root
+ *   inventory for `mailwoman serve`; something else entirely for another engine) — stays loose.
  */
 export declare const HealthResponseSchema: z.ZodObject<{
     status: z.ZodLiteral<"ok">;