@mailwoman/api 9.2.0 → 9.3.0

package/{app.ts → lib/app.ts}

@@ -9,15 +9,24 @@
  */
 
 import { OpenAPIHono } from "@hono/zod-openapi"
-import { errorResponse, attachOpenAPIDocs, type OpenAPIDocInfo } from "@mailwoman/api-kit"
+import { attachOpenAPIDocs, engineHeaders, errorResponse, type OpenAPIDocInfo } from "@mailwoman/api-kit"
+import { readLocalJSONFile } from "@mailwoman/core/fs/readers"
+import type { EngineStamp } from "@mailwoman/core/license"
+import { resolvePackagePath } from "@mailwoman/core/module/resolvers"
 import { bodyLimit } from "hono/body-limit"
 import { cors } from "hono/cors"
 
-import packageJson from "#package.json" with { type: "json" }
+import type { MailwomanAPIEngine } from "#engine"
+import { DEFAULT_BATCH_MAX, registerMailwomanAPIRoutes } from "#routes"
+import type { GeocodeOutcomeLike } from "#schema"
 
-import type { MailwomanAPIEngine } from "./engine.ts"
-import { DEFAULT_BATCH_MAX, registerMailwomanAPIRoutes } from "./routes.ts"
-import type { GeocodeOutcomeLike } from "./schema.ts"
+/**
+ * This package's own manifest, read at load rather than imported as a module: a JSON import makes `tsc` copy the file
+ * into `out/`, where it becomes the package scope for the compiled tree and breaks every `#` import in it.
+ */
+const packageJson = await readLocalJSONFile<{ name: string; version: string; description: string }>(
+	resolvePackagePath("@mailwoman/api", "package.json")
+)
 
 /**
  * 2 MiB — carried from the express server's `express.json({ limit: "2mb" })` (`mailwoman/server/index.ts`).
@@ -45,6 +54,13 @@ export interface MailwomanAPIOptions {
 	 * Max `addresses` rows accepted by `POST /v1/batch`. Default 500 (see `routes.ts`'s `DEFAULT_BATCH_MAX`).
 	 */
 	batchMax?: number
+
+	/**
+	 * The engine stamp to carry on every response: `engine` in each `/v1` body and the `Server` + `Link: rel="license"`
+	 * headers everywhere. Absent when an embedding application builds the app without the `mailwoman` package; the
+	 * `mailwoman serve` command always passes one.
+	 */
+	engine?: EngineStamp
 }
 
 /**
@@ -110,6 +126,10 @@ export function createMailwomanAPI<T extends Partial<GeocodeOutcomeLike> = Geoco
 		app.use(cors({ origin: "*", allowMethods: ["GET", "POST", "OPTIONS"], allowHeaders: ["*"], maxAge: 86_400 }))
 	}
 
+	if (options.engine) {
+		app.use(engineHeaders(options.engine))
+	}
+
 	// 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) => {
@@ -133,7 +153,10 @@ export function createMailwomanAPI<T extends Partial<GeocodeOutcomeLike> = Geoco
 		})
 	)
 
-	registerMailwomanAPIRoutes(app, engine, { batchMax: options.batchMax ?? DEFAULT_BATCH_MAX })
+	registerMailwomanAPIRoutes(app, engine, {
+		batchMax: options.batchMax ?? DEFAULT_BATCH_MAX,
+		engine: options.engine,
+	})
 
 	attachOpenAPIDocs(app, MAILWOMAN_API_DOC_INFO)
 

package/{engine.ts → lib/engine.ts}

@@ -10,7 +10,7 @@
 
 import type { AddressTree } from "@mailwoman/core"
 
-import type { GeocodeOutcomeLike } from "./schema.ts"
+import type { GeocodeOutcomeLike } from "#schema"
 
 /**
  * One parsed component in reading order (a `ComponentTag` + the covered text).
@@ -71,5 +71,5 @@ export interface MailwomanAPIEngine<T extends Partial<GeocodeOutcomeLike> = Geoc
 	batch?(addresses: string[], opts?: ParseInit): Promise<{ results: BatchResultEntry<T>[] }>
 	resolveTree?(tree: AddressTree, opts: Record<string, unknown>): Promise<ResolveTreeOutcome>
 	reload?(): Promise<{ reloaded: boolean; versions: unknown }>
-	health?(): HealthData
+	health?(): Promise<HealthData>
 }

package/{index.ts → lib/index.ts}

@@ -16,7 +16,7 @@
  *   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"
+export * from "#app"
+export * from "#engine"
+export * from "#routes"
+export * from "#schema"

package/{routes.ts → lib/routes.ts}

@@ -20,12 +20,19 @@
  */
 
 import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi"
-import { geocoderUnavailableError, metricsSnapshot, recordTimed } from "@mailwoman/api-kit"
+import {
+	geocoderUnavailableError,
+	metricsSnapshot,
+	recordTimed,
+	stampedResponseSchema,
+	withEngineStamp,
+} from "@mailwoman/api-kit"
 import type { AddressTree } from "@mailwoman/core/decoder"
+import type { EngineStamp } from "@mailwoman/core/license"
 import type { ComponentTag } from "@mailwoman/core/types"
 import { canonicalKey, type ComponentDict, formatAddress, type FormatAddressOptions } from "@mailwoman/formatter"
 
-import type { MailwomanAPIEngine } from "./engine.ts"
+import type { MailwomanAPIEngine } from "#engine"
 import {
 	APIErrorSchema,
 	BatchRequestSchema,
@@ -40,12 +47,12 @@ import {
 	ResolveRequestSchema,
 	ResolveResponseSchema,
 	type GeocodeOutcome,
-} from "./schema.ts"
+} from "#schema"
 
 /**
  * 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`).
+ * (`$public.MAILWOMAN_BATCH_MAX`, default 1000; see `mailwoman/lib/env/schema.ts`).
  */
 export const DEFAULT_BATCH_MAX = 500
 
@@ -59,6 +66,11 @@ export interface RegisterMailwomanAPIRoutesOptions {
 	 * Max `addresses` rows accepted by `POST /v1/batch`. Default {@link DEFAULT_BATCH_MAX}.
 	 */
 	batchMax?: number
+
+	/**
+	 * The engine stamp attached as `engine` to every `/v1` success body. Absent: no field is added.
+	 */
+	engine?: EngineStamp
 }
 
 const errorContent = (description: string) => ({
@@ -78,7 +90,7 @@ const parseQueryParams = z.object({
 const parseResponses = {
 	200: {
 		description: "The tokenized input span + ranked solutions.",
-		content: { "application/json": { schema: ParseOutcomeSchema } },
+		content: { "application/json": { schema: stampedResponseSchema(ParseOutcomeSchema) } },
 	},
 	400: errorContent("`address` is required."),
 	501: errorContent("The backing engine method is not wired for this deployment."),
@@ -87,7 +99,7 @@ const parseResponses = {
 const geocodeResponses = {
 	200: {
 		description: "One geocode result (parse → resolve cascade), passed through from the engine verbatim.",
-		content: { "application/json": { schema: GeocodeOutcomeSchema } },
+		content: { "application/json": { schema: stampedResponseSchema(GeocodeOutcomeSchema) } },
 	},
 	400: errorContent("`address` is required."),
 	503: errorContent("The geocoding engine is not wired for this deployment (dependencies missing)."),
@@ -96,7 +108,7 @@ const geocodeResponses = {
 const batchResponses = {
 	200: {
 		description: "One result per input address, in input order (per-row error isolation).",
-		content: { "application/json": { schema: BatchResponseSchema } },
+		content: { "application/json": { schema: stampedResponseSchema(BatchResponseSchema) } },
 	},
 	400: errorContent("Body must be `{ addresses: string[] }`."),
 	413: errorContent("`addresses.length` exceeds the configured batch cap."),
@@ -106,7 +118,7 @@ const batchResponses = {
 const resolveResponses = {
 	200: {
 		description: "The same tree, decorated in place with gazetteer coordinates + attribution.",
-		content: { "application/json": { schema: ResolveResponseSchema } },
+		content: { "application/json": { schema: stampedResponseSchema(ResolveResponseSchema) } },
 	},
 	400: errorContent("Body must be `{ tree: AddressTree, opts? }`."),
 	503: errorContent("The resolver is not wired for this deployment (dependencies missing)."),
@@ -114,7 +126,7 @@ const resolveResponses = {
 
 const reloadResponses = {
 	200: {
-		description: "Versioned data switchover result — the new per-shard version map.",
+		description: "Versioned data switchover result — the new per-extract version map.",
 		content: {
 			"application/json": { schema: z.looseObject({ reloaded: z.boolean(), versions: z.unknown() }) },
 		},
@@ -125,7 +137,7 @@ const reloadResponses = {
 const formatResponses = {
 	200: {
 		description: "The rendered address string + the deterministic canonical match key.",
-		content: { "application/json": { schema: FormatResponseSchema } },
+		content: { "application/json": { schema: stampedResponseSchema(FormatResponseSchema) } },
 	},
 	400: errorContent("Invalid request body."),
 }
@@ -198,7 +210,7 @@ const reloadRoute = createRoute({
 	method: "post",
 	path: "/v1/reload",
 	operationId: "reload",
-	summary: "Reload versioned data shards (deploy-only; gate at ingress)",
+	summary: "Reload versioned data extracts (deploy-only; check at ingress)",
 	tags: ["meta"],
 	responses: reloadResponses,
 })
@@ -259,6 +271,7 @@ export function registerMailwomanAPIRoutes<T extends Partial<GeocodeOutcome> = G
 	options: RegisterMailwomanAPIRoutesOptions = {}
 ): void {
 	const batchMax = options.batchMax ?? DEFAULT_BATCH_MAX
+	const stamp = options.engine
 
 	app.openapi(parseGetRoute, async (c) => {
 		if (!engine.parse) return c.json({ error: "parse not implemented" }, 501)
@@ -271,7 +284,7 @@ export function registerMailwomanAPIRoutes<T extends Partial<GeocodeOutcome> = G
 		const inputMode = inputModeRaw === "fragmented" || inputModeRaw === "formatted" ? inputModeRaw : undefined
 		const outcome = await engine.parse(address, { debug, inputMode })
 
-		return c.json(outcome, 200)
+		return c.json(withEngineStamp(outcome, stamp), 200)
 	})
 
 	app.openapi(
@@ -290,7 +303,7 @@ export function registerMailwomanAPIRoutes<T extends Partial<GeocodeOutcome> = G
 
 			const outcome = await engine.parse(trimmed, { debug: debug ?? false, inputMode: input_mode })
 
-			return c.json(outcome, 200)
+			return c.json(withEngineStamp(outcome, stamp), 200)
 		},
 		(result, c) => {
 			if (!result.success) return c.json({ error: "address is required" }, 400)
@@ -317,7 +330,7 @@ export function registerMailwomanAPIRoutes<T extends Partial<GeocodeOutcome> = G
 				.then((outcome) => {
 					recordTimed(performance.now() - t0, String(outcome.resolution_tier ?? "admin"))
 
-					return c.json(outcome as unknown as GeocodeOutcome, 200)
+					return c.json(withEngineStamp(outcome as GeocodeOutcome, stamp), 200)
 				})
 				.catch((error) => {
 					recordTimed(performance.now() - t0, "error")
@@ -339,7 +352,7 @@ export function registerMailwomanAPIRoutes<T extends Partial<GeocodeOutcome> = G
 		async (c) => {
 			const { addresses, input_mode } = c.req.valid("json")
 
-			if (!addresses.length) return c.json({ results: [] }, 200)
+			if (!addresses.length) return c.json(withEngineStamp({ results: [] }, stamp), 200)
 
 			if (addresses.length > batchMax) {
 				return c.json({ error: `batch too large: ${addresses.length} > ${batchMax}` }, 413)
@@ -361,7 +374,7 @@ export function registerMailwomanAPIRoutes<T extends Partial<GeocodeOutcome> = G
 				// 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)
+				return c.json(withEngineStamp(outcome as z.infer<typeof BatchResponseSchema>, stamp), 200)
 			} catch (error) {
 				recordTimed(performance.now() - t0, "error")
 				throw error
@@ -388,9 +401,9 @@ export function registerMailwomanAPIRoutes<T extends Partial<GeocodeOutcome> = G
 
 			const { tree, opts } = c.req.valid("json")
 
-			const outcome = await engine.resolveTree(tree as unknown as AddressTree, opts ?? {})
+			const outcome = await engine.resolveTree(tree as AddressTree, opts ?? {})
 
-			return c.json(outcome, 200)
+			return c.json(withEngineStamp(outcome, stamp), 200)
 		},
 		(result, c) => {
 			if (!result.success) return c.json({ error: "body must be { tree: AddressTree, opts? }" }, 400)
@@ -414,13 +427,13 @@ export function registerMailwomanAPIRoutes<T extends Partial<GeocodeOutcome> = G
 		const dict = toComponentDict(components)
 		const formatted = formatAddress(dict, country, formatOptions as FormatAddressOptions | undefined)
 
-		return c.json({ formatted, canonicalKey: canonicalKey(dict) }, 200)
+		return c.json(withEngineStamp({ formatted, canonicalKey: canonicalKey(dict) }, stamp), 200)
 	})
 
-	app.openapi(healthRoute, (c) => {
+	app.openapi(healthRoute, async (c) => {
 		const uptimeSeconds = Math.round((Date.now() - startedAt) / 1000)
 
-		return c.json({ status: "ok", uptime_s: uptimeSeconds, ...engine.health?.() }, 200)
+		return c.json({ status: "ok", uptime_s: uptimeSeconds, ...(await engine.health?.()) }, 200)
 	})
 
 	app.openapi(metricsRoute, (c) => c.json(metricsSnapshot(), 200))

package/{schema.ts → lib/schema.ts}

@@ -17,12 +17,25 @@
  */
 
 import { z } from "@hono/zod-openapi"
+import type { AddressNode } from "@mailwoman/core/decoder"
+import type { DerivationProjection, Evidence } from "@mailwoman/evidence"
 
 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 const AddressNodeSchema = z.custom<AddressNode>().openapi("AddressNode", {
+	type: "object",
+	additionalProperties: true,
+	description:
+		"A decoded address-tree node: a tag, its span, and its children. See `AddressNode` in `@mailwoman/core/decoder`.",
+})
+
 /**
  * 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.
@@ -70,7 +83,7 @@ export const ParseOutcomeSchema = z
 	.object({
 		input: z.string(),
 		components: z.array(ParseComponentSchema),
-		tree: z.looseObject({ roots: z.array(z.unknown()) }),
+		tree: z.looseObject({ raw: z.string(), roots: z.array(AddressNodeSchema) }),
 		debug: z.string().optional(),
 	})
 	.openapi("ParseOutcome")
@@ -150,6 +163,7 @@ const ComponentTagSchema = z.enum([
 	"sub_block",
 	"building_number",
 	"building_name",
+	"locality_unit",
 ])
 
 /**
@@ -186,13 +200,80 @@ const QueryIntentMarkerSchema = z
 			"near_me",
 			"poi_category",
 		]),
-		code: z.enum(["declared_ambiguity", "declared_fork", "focus_point_required", "poi_category"]),
+		code: z.enum([
+			"declared_ambiguity",
+			"declared_fork",
+			"focus_point_required",
+			"poi_category",
+			"coverage_qualified_absence",
+			"authority_designation",
+		]),
 		mechanism: z.string(),
 		message: z.string(),
 		evidence: z.record(z.string(), z.unknown()).optional(),
 	})
 	.openapi("QueryIntentMarker")
 
+/**
+ * One authoritative-provider match on the wire (#1901) — hoisted so the outcome schema below stays inside the
+ * call-nesting bound. Field-for-field mirror of `mailwoman/authoritative.ts`'s `AuthoritativeAssertionMatch`.
+ */
+const AuthoritativeMatchSchema = z.object({
+	provider_place_id: z.string(),
+	object_ids: z.record(z.string(), z.string()).optional(),
+	canonical_fields: z.record(z.string(), z.string()).optional(),
+	lat: z.number().optional(),
+	lon: z.number().optional(),
+	precision: z.string().optional(),
+	match_status: z.enum(["exact", "approximate"]),
+	provider_score: z.number().optional(),
+})
+
+const EpistemicStatusSchema = z.enum(["designated", "observed", "derived", "inferred", "unresolved"])
+
+const CoverageBasisSchema = z.enum(["designated", "surveyed", "source_present"])
+
+/**
+ * `@mailwoman/evidence`'s `Evidence` union, spelled for the wire. The `EvidencePin` below fails to compile the moment
+ * either side gains, loses or retypes a field.
+ */
+const EvidenceSchema = z.discriminatedUnion("kind", [
+	z.object({ kind: z.literal("observation"), source: z.string(), vintage: z.string().nullable(), value: z.unknown() }),
+	z.object({
+		kind: z.literal("exclusion"),
+		source: z.string(),
+		vintage: z.string(),
+		scope: z.object({ layer: z.string(), h3Cell: z.number(), basis: CoverageBasisSchema, fold: z.string() }),
+	}),
+	z.object({
+		kind: z.literal("relation"),
+		source: z.string(),
+		vintage: z.string(),
+		relationship: z.string(),
+		assertion: z.enum(["authoritative", "inferred"]),
+		score: z.number().optional(),
+	}),
+	z.object({ kind: z.literal("prior"), source: z.string(), label: z.string(), weight: z.number() }),
+])
+
+/**
+ * The derivation behind a geocode answer, present only when the engine was asked to trace — `@mailwoman/evidence`'s
+ * `DerivationProjection` on the wire.
+ */
+export const DerivationProjectionSchema = z.object({
+	status: EpistemicStatusSchema,
+	constraints: z.array(z.object({ label: z.string(), evidence: EvidenceSchema, contribution: z.string() })).readonly(),
+	uncertaintyM: z.number().nullable(),
+})
+
+// Both directions: the schema's inferred type is exactly the evidence package's, or this does not compile.
+type Mutual<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false
+const evidencePin: Mutual<z.infer<typeof EvidenceSchema>, Evidence> = true
+const derivationPin: Mutual<z.infer<typeof DerivationProjectionSchema>, DerivationProjection> = true
+
+void evidencePin
+void derivationPin
+
 /**
  * `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
@@ -200,8 +281,8 @@ const QueryIntentMarkerSchema = z
  * (`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 const GeocodeOutcomeLikeSchema = z.object({
 	input: z.string(),
@@ -209,6 +290,12 @@ export const GeocodeOutcomeLikeSchema = z.object({
 	lat: z.number().nullable(),
 	lon: z.number().nullable(),
 	resolution_tier: z.enum(["address_point", "interpolated", "street", "admin", "venue", "plus_code"]),
+	// What the evidence permits a consumer to claim about the coordinate, orthogonal to how it was produced; see
+	// `@mailwoman/evidence`'s `EpistemicStatus`.
+	epistemic_status: z.enum(["designated", "observed", "derived", "inferred", "unresolved"]),
+	// The derivation behind the answer, present only when the engine was asked to trace. `DerivationProjectionSchema` is
+	// pinned to `@mailwoman/evidence`'s types below, so the wire contract and the evidence union cannot drift apart.
+	derivation: DerivationProjectionSchema.optional(),
 	// The fork→entity probe's answer (#1585) — present only on the `venue` tier; see geocode-core's
 	// GeocodeResult.entity.
 	entity: z
@@ -234,7 +321,7 @@ export const GeocodeOutcomeLikeSchema = z.object({
 	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
+	// The register row's OWN scope tags when the address_point tier answered and its extract carries
 	// them (normalized locality key + postcode of the ROOFTOP) — see geocode-core's GeocodeResult.rooftop.
 	rooftop: z
 		.object({
@@ -246,11 +333,17 @@ export const GeocodeOutcomeLikeSchema = z.object({
 	// 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(),
+	// #1880: the capital promotion's firing receipt — the promoted candidate's country, present only when the
+	// promotion changed some node's leading candidate. Advisory, same posture as postcode_country_scope.
+	capital_promotion: z.string().optional(),
+	// #1893: the variant-alias exemption's firing receipt — present (true) only when the winning candidate reached
+	// the top because the exemption spared it the cross-country alias penalty. Advisory, same posture again.
+	variant_alias_exemption: z.literal(true).optional(),
 	// 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
+	// contradict, or fail to speak to the PARSED region/country qualifiers? Nothing ranks or filters 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
@@ -259,6 +352,23 @@ export const GeocodeOutcomeLikeSchema = z.object({
 			country: z.enum(["confirmed", "contradicted", "unstated", "unverifiable"]),
 		})
 		.optional(),
+	// #1901: a configured authoritative provider's answer, carried BESIDE the open result — every value inside is
+	// the PROVIDER'S assertion, hand-modeled here to match `mailwoman/authoritative.ts`'s wire shape (the
+	// engine-agnosticism boundary forbids importing it). Absent when no provider is configured; `refused` is the
+	// provider declining (distinct from a parse failure or a gazetteer miss); `transport_error` is the provider
+	// being unreachable, reported rather than silently dropped. An `ambiguous` status carries EVERY candidate.
+	authoritative: z
+		.object({
+			provider: z.string(),
+			status: z.enum(["matched", "ambiguous", "refused", "transport_error"]),
+			matches: z.array(AuthoritativeMatchSchema).optional(),
+			attribution: z.string().optional(),
+			license: z.string().optional(),
+			retrieved_at: z.string().optional(),
+			dataset_version: z.string().optional(),
+			error: z.string().optional(),
+		})
+		.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,
@@ -284,8 +394,8 @@ export type GeocodeOutcomeLike = z.infer<typeof GeocodeOutcomeLikeSchema>
  * (`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 const GeocodeOutcomeSchema = GeocodeOutcomeLikeSchema.loose().openapi("GeocodeOutcome")
 
@@ -331,7 +441,7 @@ export const BatchResponseSchema = z
  */
 export const ResolveRequestSchema = z
 	.object({
-		tree: z.looseObject({ roots: z.array(z.unknown()) }),
+		tree: z.looseObject({ raw: z.string(), roots: z.array(AddressNodeSchema) }),
 		opts: z.looseObject({}).optional(),
 	})
 	.openapi("ResolveRequest")
@@ -341,7 +451,7 @@ export const ResolveRequestSchema = z
  */
 export const ResolveResponseSchema = z
 	.object({
-		tree: z.looseObject({ roots: z.array(z.unknown()) }),
+		tree: z.looseObject({ raw: z.string(), roots: z.array(AddressNodeSchema) }),
 	})
 	.openapi("ResolveResponse")
 
@@ -377,9 +487,11 @@ export const FormatResponseSchema = z
 
 /**
  * `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 const HealthResponseSchema = z
 	.object({

package/out/app.d.ts

@@ -9,8 +9,9 @@
  */
 import { OpenAPIHono } from "@hono/zod-openapi";
 import { type OpenAPIDocInfo } from "@mailwoman/api-kit";
-import type { MailwomanAPIEngine } from "./engine.ts";
-import type { GeocodeOutcomeLike } from "./schema.ts";
+import type { EngineStamp } from "@mailwoman/core/license";
+import type { MailwomanAPIEngine } from "#engine";
+import type { GeocodeOutcomeLike } from "#schema";
 /**
  * Options for {@link createMailwomanAPI}.
  */
@@ -30,6 +31,12 @@ export interface MailwomanAPIOptions {
      * Max `addresses` rows accepted by `POST /v1/batch`. Default 500 (see `routes.ts`'s `DEFAULT_BATCH_MAX`).
      */
     batchMax?: number;
+    /**
+     * The engine stamp to carry on every response: `engine` in each `/v1` body and the `Server` + `Link: rel="license"`
+     * headers everywhere. Absent when an embedding application builds the app without the `mailwoman` package; the
+     * `mailwoman serve` command always passes one.
+     */
+    engine?: EngineStamp;
 }
 /**
  * The document info stamped into the emitted OpenAPI document. Exported (not inlined) so the `mailwoman openapi`

package/out/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../app.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAoC,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAM1F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAErD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAOrD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IAEd;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CACjB;AAUD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,cAoBpC,CAAA;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,EAC5F,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC7B,OAAO,GAAE,mBAAwB,GAC/B,WAAW,CAkDb"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../lib/app.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAmD,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAEzG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAK1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAEjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAejD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IAEd;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;CACpB;AAUD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,cAoBpC,CAAA;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,EAC5F,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC7B,OAAO,GAAE,mBAAwB,GAC/B,WAAW,CAyDb"}

package/out/app.js

@@ -8,11 +8,17 @@
  *   CLI wires the real parse/geocode/resolve stack (phase 4b); tests inject fixtures.
  */
 import { OpenAPIHono } from "@hono/zod-openapi";
-import { errorResponse, attachOpenAPIDocs } from "@mailwoman/api-kit";
+import { attachOpenAPIDocs, engineHeaders, errorResponse } from "@mailwoman/api-kit";
+import { readLocalJSONFile } from "@mailwoman/core/fs/readers";
+import { resolvePackagePath } from "@mailwoman/core/module/resolvers";
 import { bodyLimit } from "hono/body-limit";
 import { cors } from "hono/cors";
-import packageJson from "#package.json" with { type: "json" };
-import { DEFAULT_BATCH_MAX, registerMailwomanAPIRoutes } from "./routes.js";
+import { DEFAULT_BATCH_MAX, registerMailwomanAPIRoutes } from "#routes";
+/**
+ * This package's own manifest, read at load rather than imported as a module: a JSON import makes `tsc` copy the file
+ * into `out/`, where it becomes the package scope for the compiled tree and breaks every `#` import in it.
+ */
+const packageJson = await readLocalJSONFile(resolvePackagePath("@mailwoman/api", "package.json"));
 /**
  * 2 MiB — carried from the express server's `express.json({ limit: "2mb" })` (`mailwoman/server/index.ts`).
  */
@@ -72,6 +78,9 @@ export function createMailwomanAPI(engine, options = {}) {
     if (options.cors !== false) {
         app.use(cors({ origin: "*", allowMethods: ["GET", "POST", "OPTIONS"], allowHeaders: ["*"], maxAge: 86_400 }));
     }
+    if (options.engine) {
+        app.use(engineHeaders(options.engine));
+    }
     // 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) => {
@@ -89,7 +98,10 @@ export function createMailwomanAPI(engine, options = {}) {
         maxSize: options.bodyLimitBytes ?? DEFAULT_BODY_LIMIT_BYTES,
         onError: (c) => errorResponse(c, 413, "request body too large"),
     }));
-    registerMailwomanAPIRoutes(app, engine, { batchMax: options.batchMax ?? DEFAULT_BATCH_MAX });
+    registerMailwomanAPIRoutes(app, engine, {
+        batchMax: options.batchMax ?? DEFAULT_BATCH_MAX,
+        engine: options.engine,
+    });
     attachOpenAPIDocs(app, MAILWOMAN_API_DOC_INFO);
     return app;
 }

package/out/app.js.map

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

package/out/engine.d.ts

@@ -8,7 +8,7 @@
  *   exception — it's wired in-package from `@mailwoman/formatter` (the surface exists to expose it).
  */
 import type { AddressTree } from "@mailwoman/core";
-import type { GeocodeOutcomeLike } from "./schema.ts";
+import type { GeocodeOutcomeLike } from "#schema";
 /**
  * One parsed component in reading order (a `ComponentTag` + the covered text).
  */
@@ -61,6 +61,6 @@ export interface MailwomanAPIEngine<T extends Partial<GeocodeOutcomeLike> = Geoc
         reloaded: boolean;
         versions: unknown;
     }>;
-    health?(): HealthData;
+    health?(): Promise<HealthData>;
 }
 //# sourceMappingURL=engine.d.ts.map

package/out/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAElD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAErD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,cAAc,EAAE,CAAA;IAC5B,IAAI,EAAE,WAAW,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,IAAI,CAAC,GAAG,kBAAkB,CAAA;AAEjH,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,WAAW,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEhD;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,WAAW,CAAA;AAEtD,MAAM,WAAW,SAAS;IACzB,SAAS,CAAC,EAAE,aAAa,CAAA;IACzB,KAAK,CAAC,EAAE,OAAO,CAAA;CACf;AAED,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,IAAI,CACzF,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,SAAS,KACZ,OAAO,CAAC,CAAC,CAAC,CAAA;AAEf,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB;IAC7F,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAA;IACtE,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,CAAA;IAC5B,KAAK,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAA;KAAE,CAAC,CAAA;IAC1F,WAAW,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAC3F,MAAM,CAAC,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;IAC5D,MAAM,CAAC,IAAI,UAAU,CAAA;CACrB"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../lib/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAElD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAEjD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,cAAc,EAAE,CAAA;IAC5B,IAAI,EAAE,WAAW,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,IAAI,CAAC,GAAG,kBAAkB,CAAA;AAEjH,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,WAAW,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEhD;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,WAAW,CAAA;AAEtD,MAAM,WAAW,SAAS;IACzB,SAAS,CAAC,EAAE,aAAa,CAAA;IACzB,KAAK,CAAC,EAAE,OAAO,CAAA;CACf;AAED,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,IAAI,CACzF,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,SAAS,KACZ,OAAO,CAAC,CAAC,CAAC,CAAA;AAEf,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB;IAC7F,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAA;IACtE,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,CAAA;IAC5B,KAAK,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAA;KAAE,CAAC,CAAA;IAC1F,WAAW,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAC3F,MAAM,CAAC,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;IAC5D,MAAM,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,CAAA;CAC9B"}