@mailwoman/api 7.2.0 → 7.2.1

package/app.ts

@@ -0,0 +1,126 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The native Mailwoman Hono app: CORS + a request-body-size guard + the strict-validation error
+ *   envelope + the `/v1` routes + the emitted OpenAPI document. Engine-agnostic — the `mailwoman`
+ *   CLI wires the real parse/geocode/resolve stack (phase 4b); tests inject fixtures.
+ */
+
+import { OpenAPIHono } from "@hono/zod-openapi"
+import { apiError, attachOpenAPIDocs, type OpenAPIDocInfo } from "@mailwoman/api-kit"
+import packageJson from "@mailwoman/api/package.json" with { type: "json" }
+import { bodyLimit } from "hono/body-limit"
+import { cors } from "hono/cors"
+
+import type { MailwomanAPIEngine } from "./engine.ts"
+import { DEFAULT_BATCH_MAX, registerMailwomanAPIRoutes } from "./routes.ts"
+
+/** 2 MiB — carried from the express server's `express.json({ limit: "2mb" })` (`mailwoman/server/index.ts`). */
+const DEFAULT_BODY_LIMIT_BYTES = 2 * 1024 * 1024
+
+/** Options for {@link createMailwomanAPI}. */
+export interface MailwomanAPIOptions {
+	/**
+	 * Emit permissive CORS headers (`Access-Control-Allow-Origin: *`) on every response and answer preflight `OPTIONS`
+	 * with `204`. Default `true` — browser-embedded clients (the demo, a map widget) need it: a cross-origin XHR
+	 * (including the `POST` preflight) is blocked without it (#1017). Set `false` when a reverse proxy already owns the
+	 * CORS headers.
+	 */
+	cors?: boolean
+
+	/** Max request body size in bytes, enforced ahead of every `/v1/*` handler. Default 2 MiB. */
+	bodyLimitBytes?: number
+
+	/** Max `addresses` rows accepted by `POST /v1/batch`. Default 500 (see `routes.ts`'s `DEFAULT_BATCH_MAX`). */
+	batchMax?: number
+}
+
+/**
+ * Short, single-line summary of a zod validation failure for the envelope's `detail` field — not the full `ZodError`,
+ * which is multi-line and carries internal path/code detail not meant for a wire response.
+ */
+function summarizeValidationError(error: { issues: Array<{ path: PropertyKey[]; message: string }> }): string {
+	return error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ")
+}
+
+/**
+ * The document info stamped into the emitted OpenAPI document. Exported (not inlined) so the `mailwoman openapi`
+ * command can call `emitOpenAPIDocuments` with the SAME info the mounted `/openapi.json` route (below, via
+ * {@link attachOpenAPIDocs}) uses — one source of truth, no risk of the two drifting.
+ */
+export const MAILWOMAN_API_DOC_INFO: OpenAPIDocInfo = {
+	title: packageJson.name,
+	version: packageJson.version,
+	description: packageJson.description,
+	license: { name: "AGPL-3.0-only OR LicenseRef-Commercial", identifier: "AGPL-3.0-only" },
+	contact: { name: "Sister Software", url: "https://mailwoman.sister.software" },
+	servers: [
+		{
+			url: "http://{host}:{port}",
+			variables: { host: { default: "127.0.0.1" }, port: { default: "3000" } },
+		},
+	],
+	security: [],
+	tags: [
+		{ name: "parsing", description: "Free-text address parsing." },
+		{ name: "geocoding", description: "Address-to-coordinate resolution." },
+		{ name: "resolving", description: "Gazetteer resolution over an already-decoded address tree." },
+		{ name: "formatting", description: "Component-dict rendering — the inverse of parsing." },
+		{ name: "meta", description: "Health, metrics, and deploy-time operations." },
+	],
+}
+
+/** Build the native Mailwoman app around an injected {@link MailwomanAPIEngine}. */
+export function createMailwomanAPI(engine: MailwomanAPIEngine, options: MailwomanAPIOptions = {}): OpenAPIHono {
+	const app = new OpenAPIHono({
+		// This surface is ours (no vendor contract to preserve): every declared body/query schema is
+		// validator-enforced, and a failure maps through the shared api-kit envelope — never the raw zod
+		// `{success, error}` shape. Individual routes (routes.ts) override this per-call to answer their OWN
+		// friendly business message (e.g. "address is required"); this is the fallback for the rest (currently
+		// just `/v1/format`).
+		defaultHook: (result, c) => {
+			if (!result.success) {
+				return apiError(c, 400, "invalid request body", summarizeValidationError(result.error))
+			}
+
+			return undefined
+		},
+	})
+
+	// Browser-embedded clients need CORS or their cross-origin XHR (including the mutating `/v1/*` preflight) is
+	// blocked before it completes (#1017). GET+POST, unlike the read-only drop-ins (photon, nominatim).
+	if (options.cors !== false) {
+		app.use(cors({ origin: "*", allowMethods: ["GET", "POST", "OPTIONS"], allowHeaders: ["*"], maxAge: 86400 }))
+	}
+
+	// Safety net: an engine fault answers the native envelope, never a crash. `detail` carries the raw message —
+	// this surface is ours to design, so (unlike the vendor-constrained drop-in envelopes) we can be helpful.
+	app.onError((error, c) => {
+		// A malformed request body is a client-side syntax error, not a server fault — Hono's zod-openapi
+		// validator throws before a route's own hook ever sees the body, so it lands here instead of the
+		// per-route 400s in routes.ts. Answer 400, not the 500 net (which stays reserved for engine faults).
+		if (error instanceof Error && error.message.includes("Malformed JSON")) {
+			return apiError(c, 400, "invalid request body", "malformed JSON")
+		}
+
+		return apiError(c, 500, "internal error", error instanceof Error ? error.message : String(error))
+	})
+
+	// Ahead of the handlers (which buffer the body into memory) so an oversized POST is rejected before that
+	// buffering happens, not after — mirrors the libpostal precedent.
+	app.use(
+		"/v1/*",
+		bodyLimit({
+			maxSize: options.bodyLimitBytes ?? DEFAULT_BODY_LIMIT_BYTES,
+			onError: (c) => apiError(c, 413, "request body too large"),
+		})
+	)
+
+	registerMailwomanAPIRoutes(app, engine, { batchMax: options.batchMax ?? DEFAULT_BATCH_MAX })
+
+	attachOpenAPIDocs(app, MAILWOMAN_API_DOC_INFO)
+
+	return app
+}

package/engine.ts

@@ -0,0 +1,47 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The native-surface engine contract. Engine-agnostic like the drop-ins: the `mailwoman` CLI
+ *   wires the real parse/geocode/resolve stack (phase 4b); tests inject fixtures. `format` is the
+ *   exception — it's wired in-package from `@mailwoman/formatter` (the surface exists to expose it).
+ */
+
+import type { AddressTree } from "@mailwoman/core"
+
+/** One parsed component in reading order (a `ComponentTag` + the covered text). */
+export interface ParseComponent {
+	tag: string
+	value: string
+}
+
+/** One parse outcome: ordered components + the full decoded tree (the same language `/v1/resolve` speaks). */
+export interface ParseOutcome {
+	input: string
+	components: ParseComponent[]
+	tree: AddressTree
+	debug?: string
+}
+
+/** A geocode outcome — the engine returns the geocode-core `GeocodeResult` shape verbatim (passthrough). */
+export type GeocodeOutcome = Record<string, unknown>
+
+/** A batch row: a GeocodeOutcome, or an `{ input, error }` slot (per-row isolation). */
+export type BatchRow = GeocodeOutcome | { input: string; error: string }
+
+export interface ResolveTreeOutcome {
+	tree: AddressTree
+}
+
+/** The `/health` data block the engine contributes (model card, data-root inventory). */
+export type HealthData = Record<string, unknown>
+
+export interface MailwomanAPIEngine {
+	parse?(address: string, opts: { debug: boolean }): Promise<ParseOutcome>
+	geocode?(address: string): Promise<GeocodeOutcome>
+	batch?(addresses: string[]): Promise<{ results: BatchRow[] }>
+	resolveTree?(tree: AddressTree, opts: Record<string, unknown>): Promise<ResolveTreeOutcome>
+	reload?(): Promise<{ reloaded: boolean; versions: unknown }>
+	health?(): HealthData
+}

package/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/api` — the native Mailwoman HTTP API: an engine-agnostic `/v1` surface (parse,
+ *   geocode, batch, resolve, format) alongside health, metrics, and an emitted OpenAPI document.
+ *   Unlike its drop-in siblings (`@mailwoman/nominatim`, `@mailwoman/photon`,
+ *   `@mailwoman/libpostal`), nothing here mimics a third-party API — this is Mailwoman's own wire
+ *   contract, so schemas are strict and validator-enforced rather than tolerant of legacy quirks.
+ *
+ *   Like its siblings, the package is engine-agnostic: routes take a {@link MailwomanAPIEngine}; the
+ *   `mailwoman` CLI wires the real parse/geocode/resolve stack (phase 4b). The Hono app (CORS +
+ *   body-size guard + the strict-validation error envelope + the emitted OpenAPI document) lives in
+ *   `app.ts`; route definitions + handlers (incl. `registerMailwomanAPIRoutes`) in `routes.ts`; the
+ *   engine contract in `engine.ts`; the zod wire schemas in `schema.ts`.
+ */
+
+export * from "./app.ts"
+export * from "./engine.ts"
+export * from "./routes.ts"
+export * from "./schema.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/api",
-  "version": "7.2.0",
+  "version": "7.2.1",
   "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": {
@@ -13,25 +13,39 @@
     "out/**/*.js.map",
     "out/**/*.d.ts",
     "out/**/*.d.ts.map",
-    "README.md"
+    "README.md",
+    "*.ts",
+    "*.tsx",
+    "**/*.ts",
+    "**/*.tsx",
+    "!*.test.ts",
+    "!*.test.tsx",
+    "!**/*.test.ts",
+    "!**/*.test.tsx"
   ],
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "node": "./index.ts",
-      "default": "./out/index.js",
-      "types": "./out/index.d.ts"
+      "types": "./out/index.d.ts",
+      "default": "./out/index.js"
     }
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "exports": {
+      "./package.json": "./package.json",
+      ".": {
+        "types": "./out/index.d.ts",
+        "default": "./out/index.js"
+      }
+    }
   },
   "dependencies": {
     "@hono/zod-openapi": "^1.4.0",
-    "@mailwoman/api-kit": "7.2.0",
-    "@mailwoman/core": "7.2.0",
-    "@mailwoman/formatter": "7.2.0",
+    "@mailwoman/api-kit": "7.2.1",
+    "@mailwoman/core": "7.2.1",
+    "@mailwoman/formatter": "7.2.1",
     "hono": "^4.12.29",
     "zod": "^4.4.3"
   }

package/routes.ts

@@ -0,0 +1,403 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Route definitions + handlers for the native `/v1` surface. The OpenAPI document is emitted from
+ *   these definitions — there is no handwritten spec. Unlike the drop-ins (photon, nominatim,
+ *   libpostal), nothing here mimics a vendor's legacy query-parsing tolerance: request bodies are
+ *   validator-enforced, and a validation failure always answers through the shared api-kit envelope
+ *   (`apiError`), never the raw zod shape. `GET /v1/parse` is the one query-string route, and it
+ *   reads `c.req.query()` directly — a query string has no repeated-value contract worth preserving
+ *   here (contrast the drop-ins' `legacyQuery` adapter), so there's nothing to tolerate.
+ *
+ *   Per-route validation hooks (the 3rd arg to `app.openapi(route, handler, hook)`) override the
+ *   app-level `defaultHook` (wired in `app.ts`) so each route can answer its OWN friendly business
+ *   message — `"address is required"`, `"body must be { addresses: string[] }"`, etc. — matching the
+ *   express `mailwoman/server` precedent this surface carries forward. Routes with no friendly
+ *   carry-forward message (currently just `/v1/format`) fall through to the app-level hook's generic
+ *   `"invalid request body"`.
+ */
+
+import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi"
+import { apiError, 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"
+
+import type { MailwomanAPIEngine } from "./engine.ts"
+import {
+	APIErrorSchema,
+	BatchRequestSchema,
+	BatchResponseSchema,
+	FormatRequestSchema,
+	FormatResponseSchema,
+	GeocodeOutcomeSchema,
+	GeocodeRequestSchema,
+	HealthResponseSchema,
+	ParseOutcomeSchema,
+	ParseRequestSchema,
+	ResolveRequestSchema,
+	ResolveResponseSchema,
+} from "./schema.ts"
+
+/**
+ * Default `POST /v1/batch` row cap when {@link RegisterMailwomanAPIRoutesOptions.batchMax} is omitted. This is the
+ * standalone-engine default, not derived from env — `mailwoman serve` always passes the env-derived value explicitly
+ * (`$public.MAILWOMAN_BATCH_MAX`, default 1000; see `core/env/schema.ts`).
+ */
+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}. */
+export interface RegisterMailwomanAPIRoutesOptions {
+	/** Max `addresses` rows accepted by `POST /v1/batch`. Default {@link DEFAULT_BATCH_MAX}. */
+	batchMax?: number
+}
+
+const errorContent = (description: string) => ({
+	description,
+	content: { "application/json": { schema: APIErrorSchema } },
+})
+
+const parseQueryParams = z.object({
+	address: z.string().optional().openapi({ description: "The address to parse." }),
+	debug: z.string().optional().openapi({ description: '`"true"` to include a diagnostic report.' }),
+})
+
+const parseResponses = {
+	200: {
+		description: "The tokenized input span + ranked solutions.",
+		content: { "application/json": { schema: ParseOutcomeSchema } },
+	},
+	400: errorContent("`address` is required."),
+	501: errorContent("The backing engine method is not wired for this deployment."),
+}
+
+const geocodeResponses = {
+	200: {
+		description: "One geocode result (parse → resolve cascade), passed through from the engine verbatim.",
+		content: { "application/json": { schema: GeocodeOutcomeSchema } },
+	},
+	400: errorContent("`address` is required."),
+	503: errorContent("The geocoding engine is not wired for this deployment (dependencies missing)."),
+}
+
+const batchResponses = {
+	200: {
+		description: "One result per input address, in input order (per-row error isolation).",
+		content: { "application/json": { schema: BatchResponseSchema } },
+	},
+	400: errorContent("Body must be `{ addresses: string[] }`."),
+	413: errorContent("`addresses.length` exceeds the configured batch cap."),
+	503: errorContent("The geocoding engine is not wired for this deployment (dependencies missing)."),
+}
+
+const resolveResponses = {
+	200: {
+		description: "The same tree, decorated in place with gazetteer coordinates + attribution.",
+		content: { "application/json": { schema: ResolveResponseSchema } },
+	},
+	400: errorContent("Body must be `{ tree: AddressTree, opts? }`."),
+	503: errorContent("The resolver is not wired for this deployment (dependencies missing)."),
+}
+
+const reloadResponses = {
+	200: {
+		description: "Versioned data switchover result — the new per-shard version map.",
+		content: {
+			"application/json": { schema: z.looseObject({ reloaded: z.boolean(), versions: z.unknown() }) },
+		},
+	},
+	503: errorContent("The geocoding engine is not wired for this deployment (dependencies missing)."),
+}
+
+const formatResponses = {
+	200: {
+		description: "The rendered address string + the deterministic canonical match key.",
+		content: { "application/json": { schema: FormatResponseSchema } },
+	},
+	400: errorContent("Invalid request body."),
+}
+
+const healthResponses = {
+	200: {
+		description: "Liveness + engine health block. Answers 200 even when the engine is absent or broken.",
+		content: { "application/json": { schema: HealthResponseSchema } },
+	},
+}
+
+const metricsResponses = {
+	200: {
+		description: "The live in-process timing metrics snapshot (latency percentiles + per-tier counts).",
+		content: { "application/json": { schema: z.looseObject({}) } },
+	},
+}
+
+const parseGetRoute = createRoute({
+	method: "get",
+	path: "/v1/parse",
+	operationId: "parseGet",
+	summary: "Parse an address (query string)",
+	tags: ["parsing"],
+	request: { query: parseQueryParams },
+	responses: parseResponses,
+})
+
+const parsePostRoute = createRoute({
+	method: "post",
+	path: "/v1/parse",
+	operationId: "parsePost",
+	summary: "Parse an address (JSON body)",
+	tags: ["parsing"],
+	request: { body: { content: { "application/json": { schema: ParseRequestSchema } }, required: true } },
+	responses: parseResponses,
+})
+
+const geocodeRoute = createRoute({
+	method: "post",
+	path: "/v1/geocode",
+	operationId: "geocode",
+	summary: "Geocode an address to coordinates",
+	tags: ["geocoding"],
+	request: { body: { content: { "application/json": { schema: GeocodeRequestSchema } }, required: true } },
+	responses: geocodeResponses,
+})
+
+const batchRoute = createRoute({
+	method: "post",
+	path: "/v1/batch",
+	operationId: "batch",
+	summary: "Geocode a batch of addresses",
+	tags: ["geocoding"],
+	request: { body: { content: { "application/json": { schema: BatchRequestSchema } }, required: true } },
+	responses: batchResponses,
+})
+
+const resolveRoute = createRoute({
+	method: "post",
+	path: "/v1/resolve",
+	operationId: "resolve",
+	summary: "Resolve an already-decoded address tree against the gazetteer",
+	tags: ["resolving"],
+	request: { body: { content: { "application/json": { schema: ResolveRequestSchema } }, required: true } },
+	responses: resolveResponses,
+})
+
+const reloadRoute = createRoute({
+	method: "post",
+	path: "/v1/reload",
+	operationId: "reload",
+	summary: "Reload versioned data shards (deploy-only; gate at ingress)",
+	tags: ["meta"],
+	responses: reloadResponses,
+})
+
+const formatRoute = createRoute({
+	method: "post",
+	path: "/v1/format",
+	operationId: "format",
+	summary: "Render address components to a string + canonical match key",
+	tags: ["formatting"],
+	request: { body: { content: { "application/json": { schema: FormatRequestSchema } }, required: true } },
+	responses: formatResponses,
+})
+
+const healthRoute = createRoute({
+	method: "get",
+	path: "/health",
+	operationId: "health",
+	summary: "Liveness + engine health",
+	tags: ["meta"],
+	responses: healthResponses,
+})
+
+const metricsRoute = createRoute({
+	method: "get",
+	path: "/metrics",
+	operationId: "metrics",
+	summary: "In-process timing metrics snapshot",
+	tags: ["meta"],
+	responses: metricsResponses,
+})
+
+/**
+ * `components` accepts `string | string[]` per key on the wire (a caller may pass every span a multi-span match
+ * covered); `formatAddress`/`canonicalKey` want a single string per `ComponentTag`. Multi-span values collapse to their
+ * FIRST span here — the formatter template owns joining semantics, not this route.
+ */
+function toComponentDict(components: Record<string, string | string[]>): ComponentDict {
+	const out: ComponentDict = {}
+
+	for (const [key, value] of Object.entries(components)) {
+		const first = Array.isArray(value) ? value[0] : value
+
+		if (first !== undefined) {
+			out[key as ComponentTag] = first
+		}
+	}
+
+	return out
+}
+
+/** Register the native `/v1` routes + `/health` + `/metrics` against an injected engine. */
+export function registerMailwomanAPIRoutes(
+	app: OpenAPIHono,
+	engine: MailwomanAPIEngine,
+	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)
+		const debug = c.req.query("debug") === "true"
+		const outcome = await engine.parse(address, { debug })
+
+		return c.json(outcome, 200)
+	})
+
+	app.openapi(
+		parsePostRoute,
+		async (c) => {
+			if (!engine.parse) return c.json({ error: "parse not implemented" }, 501)
+			const { address, debug } = c.req.valid("json")
+			const trimmed = address.trim()
+
+			if (!trimmed) return c.json({ error: "address is required" }, 400)
+			const outcome = await engine.parse(trimmed, { debug: debug ?? false })
+
+			return c.json(outcome, 200)
+		},
+		(result, c) => {
+			if (!result.success) return c.json({ error: "address is required" }, 400)
+
+			return undefined
+		}
+	)
+
+	app.openapi(
+		geocodeRoute,
+		async (c) => {
+			if (!engine.geocode) return apiError(c, 503, "geocoder not available", GEOCODER_UNAVAILABLE_DETAIL)
+			const { address } = 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)
+				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
+			}
+		},
+		(result, c) => {
+			if (!result.success) return c.json({ error: "address is required" }, 400)
+
+			return undefined
+		}
+	)
+
+	app.openapi(
+		batchRoute,
+		async (c) => {
+			const { addresses } = c.req.valid("json")
+
+			if (addresses.length === 0) return c.json({ results: [] }, 200)
+
+			if (addresses.length > batchMax) {
+				return c.json({ error: `batch too large: ${addresses.length} > ${batchMax}` }, 413)
+			}
+
+			if (!engine.batch) return apiError(c, 503, "geocoder not available", GEOCODER_UNAVAILABLE_DETAIL)
+
+			// 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.
+			const t0 = performance.now()
+
+			try {
+				const outcome = await engine.batch(addresses)
+				recordTimed(performance.now() - t0, "batch")
+
+				// Same wire-vs-domain cast as `/v1/geocode` above — `BatchRow`'s `GeocodeOutcome` half is a
+				// `Record<string, unknown>` passthrough; `BatchResponseSchema` now types its `GeocodeOutcome` union
+				// member as the real shape.
+				return c.json(outcome as unknown as z.infer<typeof BatchResponseSchema>, 200)
+			} catch (error) {
+				recordTimed(performance.now() - t0, "error")
+				throw error
+			}
+		},
+		(result, c) => {
+			if (!result.success) return c.json({ error: "body must be { addresses: string[] }" }, 400)
+
+			return undefined
+		}
+	)
+
+	app.openapi(
+		resolveRoute,
+		// Metrics are the ENGINE's responsibility here (phase 4b): the express predecessor recorded the
+		// 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)
+			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)
+		},
+		(result, c) => {
+			if (!result.success) return c.json({ error: "body must be { tree: AddressTree, opts? }" }, 400)
+
+			return undefined
+		}
+	)
+
+	app.openapi(reloadRoute, async (c) => {
+		if (!engine.reload) return apiError(c, 503, "geocoder not available", GEOCODER_UNAVAILABLE_DETAIL)
+		const outcome = await engine.reload()
+
+		return c.json(outcome, 200)
+	})
+
+	app.openapi(formatRoute, (c) => {
+		const { components, country, options: formatOptions } = c.req.valid("json")
+		const dict = toComponentDict(components)
+		const formatted = formatAddress(dict, country, formatOptions as FormatAddressOptions | undefined)
+
+		return c.json({ formatted, canonicalKey: canonicalKey(dict) }, 200)
+	})
+
+	app.openapi(healthRoute, (c) => {
+		const uptimeSeconds = Math.round((Date.now() - startedAt) / 1000)
+
+		return c.json({ status: "ok", uptime_s: uptimeSeconds, ...engine.health?.() }, 200)
+	})
+
+	app.openapi(metricsRoute, (c) => c.json(metricsSnapshot(), 200))
+}

package/schema.ts

@@ -0,0 +1,181 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Zod wire schemas for the native `/v1` surface. Unlike the drop-ins (photon, nominatim,
+ *   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 (wired in Task 3) maps validation failures through the shared `APIErrorSchema`
+ *   envelope (`apiError(c, 400, "invalid request body", <zod summary>)`) — the documented pattern
+ *   boundary from phase 2: where no legacy contract exists, the validator MAY speak, but only in
+ *   our envelope.
+ *
+ *   `APIErrorSchema` itself is owned by `@mailwoman/api-kit` (plumbing shared by every native
+ *   surface) — it's re-exported here so route modules can import every schema they need, request
+ *   and error alike, from this one file.
+ */
+
+import { z } from "@hono/zod-openapi"
+
+export { APIErrorSchema } from "@mailwoman/api-kit"
+
+/** `POST /v1/parse` request body. */
+export const ParseRequestSchema = z
+	.object({
+		address: z.string(),
+		debug: z.boolean().optional(),
+	})
+	.openapi("ParseRequest")
+
+/** One `ParseOutcome.components` entry — mirrors {@linkcode ParseComponent} (`engine.ts`). */
+export const ParseComponentSchema = z.object({ tag: z.string(), value: z.string() }).openapi("ParseComponent")
+
+/**
+ * `POST /v1/parse` response — mirrors {@linkcode ParseOutcome} (`engine.ts`): the ordered components plus the full
+ * decoded tree. `tree` is the same loose-tree idiom {@link ResolveResponseSchema} uses (`api/schema.ts:134-146`) — the
+ * decoder's `AddressTree` is the engine's contract, not this wire schema's.
+ */
+export const ParseOutcomeSchema = z
+	.object({
+		input: z.string(),
+		components: z.array(ParseComponentSchema),
+		tree: z.looseObject({ roots: z.array(z.unknown()) }),
+		debug: z.string().optional(),
+	})
+	.openapi("ParseOutcome")
+
+/** `POST /v1/geocode` request body. */
+export const GeocodeRequestSchema = z
+	.object({
+		address: z.string(),
+	})
+	.openapi("GeocodeRequest")
+
+/**
+ * One `GeocodeOutcome.hierarchy` entry — locality → country, most specific first. `name` is the resolved gazetteer name
+ * (proper-cased canonical); `value` is the raw parsed span. Mirrors `GeocodeResult["hierarchy"]` entries
+ * (`mailwoman/geocode-core.ts`), hand-modeled — see {@link GeocodeOutcomeSchema} for the no-import rationale.
+ */
+const GeocodeHierarchyEntrySchema = z
+	.object({
+		tag: z.string(),
+		value: z.string(),
+		name: z.string(),
+		lat: z.number().optional(),
+		lon: z.number().optional(),
+		placeID: z.string().optional(),
+	})
+	.openapi("GeocodeHierarchyEntry")
+
+/**
+ * One `GeocodeOutcome.candidates` entry — a ranked alternative place for the query's primary result (the winning place
+ * first, then same-query runner-ups). Mirrors `GeocodeResult["candidates"]` entries.
+ */
+const GeocodeCandidateSchema = z
+	.object({
+		name: z.string(),
+		tag: z.string(),
+		lat: z.number(),
+		lon: z.number(),
+		countryCode: z.string().nullable(),
+		placeID: z.string().optional(),
+	})
+	.openapi("GeocodeCandidate")
+
+/**
+ * `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 = 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(),
+		countryCode: z.string().nullable(),
+		hierarchy: z.array(GeocodeHierarchyEntrySchema),
+		candidates: z.array(GeocodeCandidateSchema),
+	})
+	.loose()
+	.openapi("GeocodeOutcome")
+
+/** `POST /v1/batch` request body. */
+export const BatchRequestSchema = z
+	.object({
+		addresses: z.array(z.string()),
+	})
+	.openapi("BatchRequest")
+
+/** `POST /v1/batch` response — one `GeocodeOutcome`, or an `{ input, error }` slot, per row (per-row isolation). */
+export const BatchResponseSchema = z
+	.object({
+		results: z.array(z.union([GeocodeOutcomeSchema, z.object({ input: z.string(), error: z.string() })])),
+	})
+	.openapi("BatchResponse")
+
+/**
+ * `POST /v1/resolve` request body — an already-decoded `AddressTree` (the parser's output) to resolve against the
+ * gazetteer.
+ */
+export const ResolveRequestSchema = z
+	.object({
+		tree: z.looseObject({ roots: z.array(z.unknown()) }),
+		opts: z.looseObject({}).optional(),
+	})
+	.openapi("ResolveRequest")
+
+/** `POST /v1/resolve` response — the same tree, decorated in place with gazetteer coords + attribution. */
+export const ResolveResponseSchema = z
+	.object({
+		tree: z.looseObject({ roots: z.array(z.unknown()) }),
+	})
+	.openapi("ResolveResponse")
+
+/**
+ * `POST /v1/format` request body. `components` accepts `string | string[]` per key on the wire — a handler-side
+ * concern, not this schema's: `@mailwoman/formatter`'s `ComponentDict` (`format.ts`) is `Partial<Record<ComponentTag,
+ * string>>`, single-string only, so a route handler must join array values before calling
+ * `formatAddress`/`canonicalKey`.
+ */
+export const FormatRequestSchema = z
+	.object({
+		components: z.record(z.string(), z.union([z.string(), z.array(z.string())])),
+		country: z.string(),
+		options: z.looseObject({}).optional(),
+	})
+	.openapi("FormatRequest")
+
+/** `POST /v1/format` response — the rendered string plus the deterministic canonical match key. */
+export const FormatResponseSchema = z
+	.object({
+		formatted: z.string(),
+		canonicalKey: z.string(),
+	})
+	.openapi("FormatResponse")
+
+/**
+ * `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.
+ */
+export const HealthResponseSchema = z
+	.object({
+		status: z.literal("ok"),
+		uptime_s: z.number(),
+	})
+	.loose()
+	.openapi("HealthResponse")