@mailwoman/api 9.0.0 → 9.2.0

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@mailwoman/api",
-  "version": "9.0.0",
+  "version": "9.2.0",
   "description": "The native Mailwoman HTTP API — engine-agnostic /v1 surface (parse, geocode, batch, resolve, format) with health, metrics, and an emitted OpenAPI document.",
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "repository": {
     "type": "git",
     "url": "https://github.com/sister-software/mailwoman.git",
-    "directory": "api"
+    "directory": "packages/api"
   },
   "files": [
     "out/**/*.js",
@@ -21,14 +21,22 @@
     "!*.test.ts",
     "!*.test.tsx",
     "!**/*.test.ts",
-    "!**/*.test.tsx"
+    "!**/*.test.tsx",
+    "!test/**"
   ],
   "type": "module",
+  "imports": {
+    "#package.json": "./package.json"
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {
       "types": "./out/index.d.ts",
       "default": "./out/index.js"
+    },
+    "./schema": {
+      "types": "./out/schema.d.ts",
+      "default": "./out/schema.js"
     }
   },
   "publishConfig": {
@@ -38,15 +46,22 @@
       ".": {
         "types": "./out/index.d.ts",
         "default": "./out/index.js"
+      },
+      "./schema": {
+        "types": "./out/schema.d.ts",
+        "default": "./out/schema.js"
       }
+    },
+    "imports": {
+      "#package.json": "./package.json"
     }
   },
   "dependencies": {
     "@hono/zod-openapi": "^1.5.1",
-    "@mailwoman/api-kit": "9.0.0",
-    "@mailwoman/core": "9.0.0",
-    "@mailwoman/formatter": "9.0.0",
-    "hono": "^4.12.32",
+    "@mailwoman/api-kit": "9.2.0",
+    "@mailwoman/core": "9.2.0",
+    "@mailwoman/formatter": "9.2.0",
+    "hono": "^4.13.0",
     "zod": "^4.4.3"
   }
 }

package/routes.ts

@@ -20,7 +20,7 @@
  */
 
 import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi"
-import { apiError, metricsSnapshot, recordTimed } from "@mailwoman/api-kit"
+import { geocoderUnavailableError, metricsSnapshot, recordTimed } from "@mailwoman/api-kit"
 import type { AddressTree } from "@mailwoman/core/decoder"
 import type { ComponentTag } from "@mailwoman/core/types"
 import { canonicalKey, type ComponentDict, formatAddress, type FormatAddressOptions } from "@mailwoman/formatter"
@@ -39,6 +39,7 @@ import {
 	ParseRequestSchema,
 	ResolveRequestSchema,
 	ResolveResponseSchema,
+	type GeocodeOutcome,
 } from "./schema.ts"
 
 /**
@@ -50,15 +51,6 @@ export const DEFAULT_BATCH_MAX = 500
 
 const startedAt = Date.now()
 
-/**
- * `detail` text for every 503 "engine method absent" response (`/v1/geocode`, `/v1/batch`, `/v1/resolve`, `/v1/reload`)
- * — the express-era remediation carried forward: a stranger hitting a 503 must see the exact fix, not just "not
- * available". Matches `mailwoman/api-engine.ts`'s `buildPreflightMessage()` boot-time banner in spirit (same two
- * missing pieces — the packages, and the gazetteer data), condensed to one line for a JSON error body.
- */
-const GEOCODER_UNAVAILABLE_DETAIL =
-	"install @mailwoman/neural + @mailwoman/resolver-wof-sqlite and provide gazetteer data (MAILWOMAN_WOF_DB / MAILWOMAN_CANDIDATE_DB)"
-
 /**
  * Options for {@link registerMailwomanAPIRoutes}.
  */
@@ -261,15 +253,16 @@ function toComponentDict(components: Record<string, string | string[]>): Compone
 /**
  * Register the native `/v1` routes + `/health` + `/metrics` against an injected engine.
  */
-export function registerMailwomanAPIRoutes(
+export function registerMailwomanAPIRoutes<T extends Partial<GeocodeOutcome> = GeocodeOutcome>(
 	app: OpenAPIHono,
-	engine: MailwomanAPIEngine,
+	engine: MailwomanAPIEngine<T>,
 	options: RegisterMailwomanAPIRoutesOptions = {}
 ): void {
 	const batchMax = options.batchMax ?? DEFAULT_BATCH_MAX
 
 	app.openapi(parseGetRoute, async (c) => {
 		if (!engine.parse) return c.json({ error: "parse not implemented" }, 501)
+
 		const address = c.req.query("address")?.trim()
 
 		if (!address) return c.json({ error: "address is required" }, 400)
@@ -284,11 +277,17 @@ export function registerMailwomanAPIRoutes(
 	app.openapi(
 		parsePostRoute,
 		async (c) => {
-			if (!engine.parse) return c.json({ error: "parse not implemented" }, 501)
+			if (!engine.parse) {
+				return c.json({ error: "parse not implemented" }, 501)
+			}
+
 			const { address, debug, input_mode } = c.req.valid("json")
 			const trimmed = address.trim()
 
-			if (!trimmed) return c.json({ error: "address is required" }, 400)
+			if (!trimmed) {
+				return c.json({ error: "address is required" }, 400)
+			}
+
 			const outcome = await engine.parse(trimmed, { debug: debug ?? false, inputMode: input_mode })
 
 			return c.json(outcome, 200)
@@ -303,29 +302,33 @@ export function registerMailwomanAPIRoutes(
 	app.openapi(
 		geocodeRoute,
 		async (c) => {
-			if (!engine.geocode) return apiError(c, 503, "geocoder not available", GEOCODER_UNAVAILABLE_DETAIL)
+			if (!engine.geocode) {
+				return geocoderUnavailableError(c)
+			}
+
 			const { address, input_mode } = c.req.valid("json")
 			const trimmed = address.trim()
 
 			if (!trimmed) return c.json({ error: "address is required" }, 400)
 			const t0 = performance.now()
 
-			try {
-				const outcome = await engine.geocode(trimmed, { inputMode: input_mode })
-				recordTimed(performance.now() - t0, String(outcome["resolution_tier"] ?? "admin"))
-
-				// `GeocodeOutcome` (the engine contract) is a deliberate `Record<string, unknown>` passthrough —
-				// `GeocodeOutcomeSchema` is now a REAL typed shape (doc-accuracy only, per its own docstring), so a
-				// local cast at this wire boundary is needed, matching the established idiom below (`/v1/resolve`'s
-				// `tree as unknown as AddressTree`) for "documented wire shape looser than the domain type".
-				return c.json(outcome as unknown as z.infer<typeof GeocodeOutcomeSchema>, 200)
-			} catch (error) {
-				recordTimed(performance.now() - t0, "error")
-				throw error
-			}
+			return engine
+				.geocode(trimmed, { inputMode: input_mode })
+				.then((outcome) => {
+					recordTimed(performance.now() - t0, String(outcome.resolution_tier ?? "admin"))
+
+					return c.json(outcome as unknown as GeocodeOutcome, 200)
+				})
+				.catch((error) => {
+					recordTimed(performance.now() - t0, "error")
+
+					throw error
+				})
 		},
 		(result, c) => {
-			if (!result.success) return c.json({ error: "address is required" }, 400)
+			if (!result.success) {
+				return c.json({ error: "address is required" }, 400)
+			}
 
 			return undefined
 		}
@@ -342,7 +345,9 @@ export function registerMailwomanAPIRoutes(
 				return c.json({ error: `batch too large: ${addresses.length} > ${batchMax}` }, 413)
 			}
 
-			if (!engine.batch) return apiError(c, 503, "geocoder not available", GEOCODER_UNAVAILABLE_DETAIL)
+			if (!engine.batch) {
+				return geocoderUnavailableError(c)
+			}
 
 			// Whole-call latency, recorded under the "batch" tier. Per-row tier metrics are the ENGINE's
 			// responsibility (phase 4b) — this app only times the call as a unit.
@@ -375,11 +380,14 @@ export function registerMailwomanAPIRoutes(
 		// street node's stamped resolution tier per call — the wired engine must carry that over, and
 		// must trim batch rows the same way (the route passes raw input through).
 		async (c) => {
-			if (!engine.resolveTree) return apiError(c, 503, "resolver not available", GEOCODER_UNAVAILABLE_DETAIL)
+			// `resolver`, not `geocoder` — the missing method is `engine.resolveTree`, and the 503's `error`
+			// value is what a caller branches on.
+			if (!engine.resolveTree) {
+				return geocoderUnavailableError(c, "resolver")
+			}
+
 			const { tree, opts } = c.req.valid("json")
-			// The wire schema keeps `tree` loose (`{ roots: unknown[] }`, forward-compat) — a local cast at the
-			// boundary onto the engine's `AddressTree` contract, matching the established idiom (api-kit's
-			// `openapi.ts`, the drop-ins' response casts) for "documented wire shape looser than the domain type".
+
 			const outcome = await engine.resolveTree(tree as unknown as AddressTree, opts ?? {})
 
 			return c.json(outcome, 200)
@@ -392,7 +400,10 @@ export function registerMailwomanAPIRoutes(
 	)
 
 	app.openapi(reloadRoute, async (c) => {
-		if (!engine.reload) return apiError(c, 503, "geocoder not available", GEOCODER_UNAVAILABLE_DETAIL)
+		if (!engine.reload) {
+			return geocoderUnavailableError(c)
+		}
+
 		const outcome = await engine.reload()
 
 		return c.json(outcome, 200)

package/schema.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.
  *
@@ -98,6 +98,9 @@ const GeocodeHierarchyEntrySchema = z
 		lat: z.number().optional(),
 		lon: z.number().optional(),
 		placeID: z.string().optional(),
+		// #1731 tri-state lineage provenance: true = the winner's ancestor chain vouches for this entry, false =
+		// resolved independently OUTSIDE the winner's lineage, absent = unverifiable. Absence is not false.
+		in_winner_lineage: z.boolean().optional(),
 	})
 	.openapi("GeocodeHierarchyEntry")
 
@@ -116,6 +119,80 @@ const GeocodeCandidateSchema = z
 	})
 	.openapi("GeocodeCandidate")
 
+/**
+ * The `ComponentTag` union at this engine-agnostic boundary, named once so every schema that speaks about a tag speaks
+ * about the SAME list. Two hand-copied enums would agree on the day they were written and diverge on the day a tag is
+ * added — the shape of defect `feedback-parity-needs-shared-function-not-shared-constants` describes.
+ */
+const ComponentTagSchema = z.enum([
+	"country",
+	"region",
+	"locality",
+	"dependent_locality",
+	"postcode",
+	"subregion",
+	"house_number",
+	"street",
+	"street_prefix",
+	"street_prefix_particle",
+	"street_suffix",
+	"intersection_a",
+	"intersection_b",
+	"unit",
+	"venue",
+	"attention",
+	"po_box",
+	"cedex",
+	"prefecture",
+	"municipality",
+	"district",
+	"block",
+	"sub_block",
+	"building_number",
+	"building_name",
+])
+
+/**
+ * Canonical parsed-component map carried by `GeocodeResult.components`. Spelled out at this engine-agnostic API
+ * boundary for the same reason the result schema is hand-modeled; the compile-time drift pin in
+ * `mailwoman/test/api-schema-drift.test.ts` catches any mismatch with the real `ComponentTag`-keyed result type.
+ */
+const GeocodeComponentsSchema = z.partialRecord(ComponentTagSchema, z.string())
+
+/**
+ * One `GeocodeOutcome.intent_markers` entry — an advisory the ROAD_TO_V9 §4 intent vocabulary raised about the QUERY.
+ * Mirrors `QueryIntentMarker` (`core/pipeline/types.ts`).
+ *
+ * `evidence` is deliberately open (`z.record`): each `code` carries its own measurement — a dominance margin, a pair of
+ * interpretations, a taxonomy id — and flattening those into one closed shape would either lose the numbers or invent
+ * fields that do not apply. `code` is the discriminator a client branches on.
+ */
+const QueryIntentMarkerSchema = z
+	.object({
+		// Spelled out rather than `z.string()` so `mailwoman/test/api-schema-drift.test.ts`'s schema-too-wide direction
+		// keeps biting: a new `QueryKind` that never reaches this list is a documented contract that has quietly stopped
+		// describing the real one.
+		kind: z.enum([
+			"postcode_only",
+			"locality_only",
+			"structured_address",
+			"intersection",
+			"po_box",
+			"landmark",
+			"poi_query",
+			"vague",
+			"bare_toponym",
+			"route_pair",
+			"near_me",
+			"poi_category",
+		]),
+		code: z.enum(["declared_ambiguity", "declared_fork", "focus_point_required", "poi_category"]),
+		mechanism: z.string(),
+		message: z.string(),
+		evidence: z.record(z.string(), z.unknown()).optional(),
+	})
+	.openapi("QueryIntentMarker")
+
 /**
  * `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
@@ -126,34 +203,93 @@ const GeocodeCandidateSchema = z
  * `@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.
  */
-export const GeocodeOutcomeSchema = z
-	.object({
-		input: z.string(),
-		lat: z.number().nullable(),
-		lon: z.number().nullable(),
-		resolution_tier: z.enum(["address_point", "interpolated", "street", "admin"]),
-		uncertainty_m: z.number().nullable(),
-		locality: z.string().nullable(),
-		region: z.string().nullable(),
-		postcode: z.string().nullable(),
-		house_number: z.string().nullable(),
-		street: z.string().nullable(),
-		// The parsed venue span (#1041 posture; surfaced 2026-08-01 for the hierarchy-evidence campaign R1).
-		venue: z.string().nullable(),
-		// The parsed dependent-locality span (parse view; `hierarchy` is the resolved view).
-		dependent_locality: z.string().nullable(),
-		// The parsed unit / sub-venue span (parse view) — "Terminal 5", "Suite 300".
-		unit: z.string().nullable(),
-		countryCode: z.string().nullable(),
-		hierarchy: z.array(GeocodeHierarchyEntrySchema),
-		candidates: z.array(GeocodeCandidateSchema),
-		// #42: the country the postcode-country coherence pass scoped the walk to, or null. Non-null ONLY when it
-		// OVERRODE the request's country prior — so a caller who asked for US and got an FR answer can see which
-		// evidence bought the change instead of reading it as a bug.
-		postcode_country_scope: z.string().nullable(),
-	})
-	.loose()
-	.openapi("GeocodeOutcome")
+export const GeocodeOutcomeLikeSchema = z.object({
+	input: z.string(),
+	components: GeocodeComponentsSchema,
+	lat: z.number().nullable(),
+	lon: z.number().nullable(),
+	resolution_tier: z.enum(["address_point", "interpolated", "street", "admin", "venue", "plus_code"]),
+	// The fork→entity probe's answer (#1585) — present only on the `venue` tier; see geocode-core's
+	// GeocodeResult.entity.
+	entity: z
+		.object({
+			name: z.string(),
+			categoryID: z.string().nullable(),
+			confidence: z.number(),
+			country: z.string(),
+		})
+		.optional(),
+	uncertainty_m: z.number().nullable(),
+	locality: z.string().nullable(),
+	region: z.string().nullable(),
+	postcode: z.string().nullable(),
+	house_number: z.string().nullable(),
+	street: z.string().nullable(),
+	// The parsed venue span (#1041 posture; surfaced 2026-08-01 for the hierarchy-evidence campaign R1).
+	venue: z.string().nullable(),
+	// The parsed dependent-locality span (parse view; `hierarchy` is the resolved view).
+	dependent_locality: z.string().nullable(),
+	// The parsed unit / sub-venue span (parse view) — "Terminal 5", "Suite 300".
+	unit: z.string().nullable(),
+	countryCode: z.string().nullable(),
+	hierarchy: z.array(GeocodeHierarchyEntrySchema),
+	candidates: z.array(GeocodeCandidateSchema),
+	// The register row's OWN scope tags when the address_point tier answered and its shard carries
+	// them (normalized locality key + postcode of the ROOFTOP) — see geocode-core's GeocodeResult.rooftop.
+	rooftop: z
+		.object({
+			localityNorm: z.string().optional(),
+			postcode: z.string().optional(),
+		})
+		.optional(),
+	// #42: the country the postcode-country coherence pass scoped the walk to, or null. Non-null ONLY when it
+	// OVERRODE the request's country prior — so a caller who asked for US and got an FR answer can see which
+	// evidence bought the change instead of reading it as a bug.
+	postcode_country_scope: z.string().nullable(),
+	// ROAD_TO_V9 §4: query-intent advisories. Always present; empty means the vocabulary looked and had nothing to
+	// say. Advisory ONLY — no marker changed which answer won, and a client is free to ignore the array entirely.
+	intent_markers: z.array(QueryIntentMarkerSchema),
+	// #1717 stage 1: flag-only admin-coherence verdicts — did the winning candidate's resolved ancestry confirm,
+	// contradict, or fail to speak to the PARSED region/country qualifiers? Nothing ranks or gates on these; present
+	// whenever a winner resolved (both members always populated — `unstated` is the explicit no-qualifier claim),
+	// absent when nothing resolved to check against. See mailwoman's `admin-coherence.ts` for the verdict contract.
+	admin_coherence: z
+		.object({
+			region: z.enum(["confirmed", "contradicted", "unstated", "unverifiable"]),
+			country: z.enum(["confirmed", "contradicted", "unstated", "unverifiable"]),
+		})
+		.optional(),
+	// #1755: spans the flat `components` map could not represent. `components` holds one value per tag, so a second
+	// `locality` span ceases to exist there — and without this line `region: null` means both "the input named no
+	// region" and "it named one and we deleted it". Absent when nothing was dropped; never an empty array on the wire,
+	// because the common case is nothing dropped and a client should not have to read a field to learn that.
+	dropped_components: z
+		.array(
+			z.object({
+				tag: ComponentTagSchema,
+				value: z.string(),
+				// The value that held the slot, so a reader sees which of the two survived without re-deriving it.
+				kept: z.string(),
+			})
+		)
+		.optional(),
+})
+
+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
+ * 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 tripwire that
+ * catches this shape drifting from the real `GeocodeResult` interface.
+ */
+export const GeocodeOutcomeSchema = GeocodeOutcomeLikeSchema.loose().openapi("GeocodeOutcome")
+
+export type GeocodeOutcome = z.infer<typeof GeocodeOutcomeSchema>
 
 /**
  * `POST /v1/batch` request body.