@mailwoman/api-kit 9.1.0 → 9.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @mailwoman/api-kit
 
-Plumbing for [Mailwoman](https://mailwoman.sister.software)'s HTTP surfaces — a node `serve` wrapper and
+Plumbing for [Mailwoman](https://mailwoman.ai)'s HTTP surfaces — a node `serve` wrapper and
 OpenAPI emit helpers shared by the drop-in packages ([`@mailwoman/libpostal`](../libpostal),
 [`@mailwoman/photon`](../photon), [`@mailwoman/nominatim`](../nominatim)).
 

package/lib/engine-stamp.ts

@@ -0,0 +1,66 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The engine stamp on the HTTP side: the zod schema every app documents it with, the two headers every response
+ *   carries, and the helper that attaches the body field. The stamp itself is built by the `mailwoman` package and
+ *   arrives as an option value: an app factory (`lib/app.ts`, `lib/routes.ts`, `lib/schema.ts`) is engine-agnostic and
+ *   must not import `mailwoman`; the bin (`lib/cli.ts`) is the wiring layer that resolves the stamp and passes it in.
+ */
+
+import { z } from "@hono/zod-openapi"
+import type { EngineStamp } from "@mailwoman/core/license"
+import type { MiddlewareHandler } from "hono"
+
+/**
+ * Strict on purpose: the stamp carries no licensee and no key id, and a strict object makes a field that leaks one a
+ * schema failure rather than a documented extension.
+ */
+export const EngineStampSchema = z
+	.strictObject({
+		name: z.literal("mailwoman"),
+		version: z.string(),
+		license: z.string(),
+		license_url: z.string(),
+		notice: z.string().optional(),
+	})
+	.openapi("EngineStamp") satisfies z.ZodType<EngineStamp>
+
+/**
+ * A route's response schema once the route attaches the stamp: the body schema intersected with the optional `engine`
+ * field. Applied at the ROUTE, never on an outcome schema, so an outcome schema keeps describing what the engine
+ * produces (the schema drift pin in `mailwoman` depends on that) and the OpenAPI document references the outcome
+ * component through `allOf` instead of cloning it.
+ */
+export function stampedResponseSchema<S extends z.ZodTypeAny>(schema: S) {
+	return z.intersection(schema, z.object({ engine: EngineStampSchema.optional() }))
+}
+
+/**
+ * `Server` names the engine and its license branch; `Link: rel="license"` is the registered relation (RFC 8288) that
+ * lets a proxy, a browser, or `curl -I` find the terms without a body change. Set before the handler runs, so the
+ * headers are on the context when any `c.json` — the route's or the error net's — builds its response.
+ */
+export function engineHeaders(stamp: EngineStamp): MiddlewareHandler {
+	const server = `mailwoman/${stamp.version} (${stamp.license})`
+	const link = `<${stamp.license_url}>; rel="license"`
+
+	return async (c, next) => {
+		c.header("Server", server)
+		c.header("Link", link)
+
+		await next()
+	}
+}
+
+/**
+ * Attach the `engine` field when a stamp is configured. The field goes LAST, so a body that already spells a key of the
+ * same name keeps the stamp's value.
+ */
+export function withEngineStamp<T extends object>(
+	body: T,
+	stamp: EngineStamp | undefined
+): T & { engine?: EngineStamp } {
+	return stamp ? { ...body, engine: stamp } : body
+}

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

@@ -29,6 +29,21 @@ export const APIErrorSchema = z
  * handler's return type against that specific route's declared per-status `responses` map. A flat-typed `status` param
  * would widen every branch to "any content-carrying status", which no single declared response branch matches.
  */
-export function apiError<S extends ContentfulStatusCode>(c: Context, status: S, error: string, detail?: string) {
+export function errorResponse<S extends ContentfulStatusCode>(c: Context, status: S, error: string, detail?: string) {
 	return c.json(detail === undefined ? { error } : { error, detail }, status)
 }
+
+const GEOCODER_UNAVAILABLE_DETAIL =
+	"install @mailwoman/neural + @mailwoman/resolver-wof-sqlite and provide gazetteer data (MAILWOMAN_WOF_DB / MAILWOMAN_CANDIDATE_DB)"
+
+/**
+ * The "engine method absent" 503, for the engine method the route actually needed.
+ *
+ * `subject` is a WIRE VALUE, not a label. `<subject> not available` is published verbatim in the HTTP API reference
+ * table and in the docker deploy guide, so a caller branching on it is doing what the docs told them to — and
+ * `/v1/resolve` answers `resolver`, not `geocoder`, because the method it found missing is `engine.resolveTree`. Rename
+ * this function freely; never the string it emits.
+ */
+export function geocoderUnavailableError(c: Context, subject: "geocoder" | "resolver" = "geocoder") {
+	return errorResponse(c, 503, `${subject} not available`, GEOCODER_UNAVAILABLE_DETAIL)
+}

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

@@ -9,9 +9,10 @@
  *   2026-07-12 design spec's anti-meta guardrails).
  */
 
-export * from "./error.ts"
-export * from "./geo.ts"
-export * from "./metrics.ts"
-export * from "./openapi.ts"
-export * from "./request.ts"
-export * from "./serve.ts"
+export * from "#error"
+export * from "#geo"
+export * from "#metrics"
+export * from "#openapi"
+export * from "#request"
+export * from "#serve"
+export * from "#engine-stamp"

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

@@ -12,6 +12,8 @@
  *   state: under `node:cluster` each worker reports its own snapshot — aggregate at the scraper.
  */
 
+import { percentileSorted } from "@mailwoman/core/stats"
+
 /**
  * Recent-latency reservoir size. ~2k samples gives stable p99 without unbounded memory.
  */
@@ -50,18 +52,15 @@ export function recordTimed(latencyMs: number, tier: string): void {
 }
 
 /**
- * Percentile for the metrics snapshot — deliberately NOT `percentile` from `@mailwoman/core/utils`.
- *
- * Three differences, each on purpose for a hot request-path counter: it takes an ALREADY-sorted array (the caller sorts
- * once per snapshot, not once per percentile), returns `0` rather than `null` on empty so the snapshot stays a plain
- * number map, and rounds to two decimals because these are milliseconds on a wire format. Core's returns `null` and
- * does not round.
+ * A latency percentile as milliseconds on a wire format: two decimals. The caller sorts once per snapshot and
+ * guarantees a non-empty sample, so `percentileSorted`'s `null` is a caller error here, never a reading.
  */
-function percentile(sorted: number[], p: number): number {
-	if (!sorted.length) return 0
-	const idx = Math.min(sorted.length - 1, Math.floor(p * sorted.length))
+function latencyPercentile(sorted: readonly number[], p: number): number {
+	const value = percentileSorted(sorted, p)
+
+	if (value === null) throw new Error("latencyPercentile requires a non-empty sample")
 
-	return Math.round(sorted[idx]! * 100) / 100
+	return Math.round(value * 100) / 100
 }
 
 export interface MetricsSnapshot {
@@ -93,9 +92,9 @@ export function metricsSnapshot(): MetricsSnapshot {
 			tiers: { ...tierCounts },
 			latency_ms: sorted.length
 				? {
-						p50: percentile(sorted, 0.5),
-						p90: percentile(sorted, 0.9),
-						p99: percentile(sorted, 0.99),
+						p50: latencyPercentile(sorted, 50),
+						p90: latencyPercentile(sorted, 90),
+						p99: latencyPercentile(sorted, 99),
 						max: Math.round(sorted.at(-1)! * 100) / 100,
 					}
 				: null,

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

@@ -8,10 +8,10 @@
  *   (progenitor), replacing the old hand-downgrade step.
  */
 
-import { mkdirSync, writeFileSync } from "node:fs"
-import { dirname } from "node:path"
-
 import type { OpenAPIHono } from "@hono/zod-openapi"
+import { writeLocalTextFile } from "@mailwoman/core/fs/writers"
+
+type OpenAPISecurityRequirements = Parameters<OpenAPIHono["getOpenAPI31Document"]>[0]["security"]
 
 /**
  * The document config stamped into emitted documents: `title`/`version`/`description`/`summary`/`license`/`contact`
@@ -32,7 +32,7 @@ export interface OpenAPIDocInfo {
 		variables?: Record<string, { default: string; description?: string }>
 	}>
 	tags?: Array<{ name: string; description?: string }>
-	security?: unknown[]
+	security?: OpenAPISecurityRequirements
 }
 
 /**
@@ -54,18 +54,28 @@ function toDocumentConfig(info: OpenAPIDocInfo) {
  * Mount the OpenAPI 3.1 document endpoint on `app` (default `/openapi.json`).
  */
 export function attachOpenAPIDocs(app: OpenAPIHono, info: OpenAPIDocInfo, path = "/openapi.json"): void {
-	// openapi3-ts's InfoObject/OpenAPIObject carry an `x-${string}` extension index signature that
-	// a plain interface can't satisfy — cast at the boundary rather than widening the public type.
-	app.doc31(path, { openapi: "3.1.0", ...toDocumentConfig(info) } as never)
+	const config: Parameters<OpenAPIHono["doc31"]>[1] = { openapi: "3.1.0", ...toDocumentConfig(info) }
+
+	app.doc31(path, config)
 }
 
 /**
  * Emit both document flavors programmatically (build artifacts, parity tests, client generation).
  */
 export function emitOpenAPIDocuments(app: OpenAPIHono, info: OpenAPIDocInfo): { v31: object; v30: object } {
+	const v31Config: Parameters<OpenAPIHono["getOpenAPI31Document"]>[0] = {
+		openapi: "3.1.0",
+		...toDocumentConfig(info),
+	}
+
+	const v30Config: Parameters<OpenAPIHono["getOpenAPIDocument"]>[0] = {
+		openapi: "3.0.3",
+		...toDocumentConfig(info),
+	}
+
 	return {
-		v31: app.getOpenAPI31Document({ openapi: "3.1.0", ...toDocumentConfig(info) } as never),
-		v30: app.getOpenAPIDocument({ openapi: "3.0.3", ...toDocumentConfig(info) } as never),
+		v31: app.getOpenAPI31Document(v31Config),
+		v30: app.getOpenAPIDocument(v30Config),
 	}
 }
 
@@ -78,19 +88,20 @@ export function emitOpenAPIDocuments(app: OpenAPIHono, info: OpenAPIDocInfo): {
  * gitignored, not-yet-existing `docs/static/openapi/`). One place owns this so the four emitters can't drift out of
  * lockstep with each other.
  */
-export function printOpenAPIDocument(
+export async function printOpenAPIDocument(
 	app: OpenAPIHono,
 	info: OpenAPIDocInfo,
 	opts: { flavor?: string; out?: string } = {}
-): void {
+): Promise<void> {
 	const { v31, v30 } = emitOpenAPIDocuments(app, info)
-	const json = JSON.stringify(opts.flavor === "3.0" ? v30 : v31)
+	// Compact JSON, one line, the same bytes to a file and to stdout — a consumer piping either into a diff or a
+	// generator sees one form.
+	const json = `${JSON.stringify(opts.flavor === "3.0" ? v30 : v31)}\n`
 
 	if (opts.out) {
-		mkdirSync(dirname(opts.out), { recursive: true })
-		writeFileSync(opts.out, `${json}\n`)
+		await writeLocalTextFile(json, opts.out)
 	} else {
-		console.log(json)
+		process.stdout.write(json)
 	}
 }
 

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

@@ -20,6 +20,14 @@ import type { Context } from "hono"
  * this shape rather than Hono's uniformly-array `queries()`. Built on a null-prototype object so a query key of
  * `__proto__` or `constructor` cannot reach `Object`'s prototype — these handlers take arbitrary internet input.
  */
+/**
+ * A non-empty string query value, else `undefined`. An empty `?q=` is treated as absent, since every drop-in reads it
+ * that way.
+ */
+export function asString(raw: unknown): string | undefined {
+	return typeof raw === "string" && raw.length ? raw : undefined
+}
+
 export function legacyQuery(c: Context): Record<string, string | string[]> {
 	const out: Record<string, string | string[]> = Object.create(null)
 

package/lib/serve.ts

@@ -0,0 +1,61 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Node serve wrapper over `@hono/node-server`. The one place the node listener is created —
+ *   surface packages stay web-standard (they only export `fetch`-shaped apps) so an edge
+ *   deployment needs no changes to them.
+ */
+
+import { serve, type ServerType } from "@hono/node-server"
+
+/**
+ * A `fetch`-shaped request handler (what `OpenAPIHono.fetch` provides).
+ */
+export type FetchLike = (request: Request, ...args: never[]) => Response | Promise<Response>
+
+/**
+ * Options for `serveNode()`. Extracted since Hono doesn't seem to export them.
+ */
+export type ServeNodeOptions = Parameters<typeof serve>[0] & {
+	/**
+	 * Called once the listener is bound — receives the actual port (useful with `port: 0`).
+	 */
+	onListen?: (info: { port: number; address: string }) => void
+}
+
+/**
+ * The listener plus the port it bound, which `port: 0` callers need. Only `port` is added: `net.Server` already owns an
+ * `address()` method, and Node's cluster child calls it inside its own `listening` handler, so a value property of that
+ * name on the handle breaks every cluster worker at listen.
+ */
+export type ServerHandle = ServerType &
+	AsyncDisposable & {
+		readonly port: number
+	}
+
+const defaultOnListen = ({ port, address }: { port: number; address: string }) =>
+	console.error(`[mailwoman] native /v1 API listening on http://${address}:${port}`)
+
+/**
+ * Boot a node HTTP listener for a Hono app. Returns an async-disposable handle once the listener is ready.
+ */
+export function serveNode({ onListen = defaultOnListen, ...options }: ServeNodeOptions): Promise<ServerHandle> {
+	return new Promise<ServerHandle>((resolve, reject) => {
+		const server = serve(options, (info) => {
+			server.off("error", reject)
+
+			Object.defineProperty(server, "port", { value: info.port, writable: false })
+
+			try {
+				onListen(info)
+				resolve(server as ServerHandle)
+			} catch (error) {
+				void server[Symbol.asyncDispose]().then(() => reject(error), reject)
+			}
+		})
+
+		server.once("error", reject)
+	})
+}

package/out/engine-stamp.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The engine stamp on the HTTP side: the zod schema every app documents it with, the two headers every response
+ *   carries, and the helper that attaches the body field. The stamp itself is built by the `mailwoman` package and
+ *   arrives as an option value: an app factory (`lib/app.ts`, `lib/routes.ts`, `lib/schema.ts`) is engine-agnostic and
+ *   must not import `mailwoman`; the bin (`lib/cli.ts`) is the wiring layer that resolves the stamp and passes it in.
+ */
+import { z } from "@hono/zod-openapi";
+import type { EngineStamp } from "@mailwoman/core/license";
+import type { MiddlewareHandler } from "hono";
+/**
+ * Strict on purpose: the stamp carries no licensee and no key id, and a strict object makes a field that leaks one a
+ * schema failure rather than a documented extension.
+ */
+export declare const EngineStampSchema: z.ZodObject<{
+    name: z.ZodLiteral<"mailwoman">;
+    version: z.ZodString;
+    license: z.ZodString;
+    license_url: z.ZodString;
+    notice: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * A route's response schema once the route attaches the stamp: the body schema intersected with the optional `engine`
+ * field. Applied at the ROUTE, never on an outcome schema, so an outcome schema keeps describing what the engine
+ * produces (the schema drift pin in `mailwoman` depends on that) and the OpenAPI document references the outcome
+ * component through `allOf` instead of cloning it.
+ */
+export declare function stampedResponseSchema<S extends z.ZodTypeAny>(schema: S): z.ZodIntersection<S, z.ZodObject<{
+    engine: z.ZodOptional<z.ZodObject<{
+        name: z.ZodLiteral<"mailwoman">;
+        version: z.ZodString;
+        license: z.ZodString;
+        license_url: z.ZodString;
+        notice: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strip>>;
+/**
+ * `Server` names the engine and its license branch; `Link: rel="license"` is the registered relation (RFC 8288) that
+ * lets a proxy, a browser, or `curl -I` find the terms without a body change. Set before the handler runs, so the
+ * headers are on the context when any `c.json` — the route's or the error net's — builds its response.
+ */
+export declare function engineHeaders(stamp: EngineStamp): MiddlewareHandler;
+/**
+ * Attach the `engine` field when a stamp is configured. The field goes LAST, so a body that already spells a key of the
+ * same name keeps the stamp's value.
+ */
+export declare function withEngineStamp<T extends object>(body: T, stamp: EngineStamp | undefined): T & {
+    engine?: EngineStamp;
+};
+//# sourceMappingURL=engine-stamp.d.ts.map

package/out/engine-stamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-stamp.d.ts","sourceRoot":"","sources":["../lib/engine-stamp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AACrC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAE7C;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;kBAQ2B,CAAA;AAEzD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;;;;;;;;mBAEtE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,iBAAiB,CAUnE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAC/C,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,WAAW,GAAG,SAAS,GAC5B,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,CAE9B"}

package/out/engine-stamp.js

@@ -0,0 +1,55 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The engine stamp on the HTTP side: the zod schema every app documents it with, the two headers every response
+ *   carries, and the helper that attaches the body field. The stamp itself is built by the `mailwoman` package and
+ *   arrives as an option value: an app factory (`lib/app.ts`, `lib/routes.ts`, `lib/schema.ts`) is engine-agnostic and
+ *   must not import `mailwoman`; the bin (`lib/cli.ts`) is the wiring layer that resolves the stamp and passes it in.
+ */
+import { z } from "@hono/zod-openapi";
+/**
+ * Strict on purpose: the stamp carries no licensee and no key id, and a strict object makes a field that leaks one a
+ * schema failure rather than a documented extension.
+ */
+export const EngineStampSchema = z
+    .strictObject({
+    name: z.literal("mailwoman"),
+    version: z.string(),
+    license: z.string(),
+    license_url: z.string(),
+    notice: z.string().optional(),
+})
+    .openapi("EngineStamp");
+/**
+ * A route's response schema once the route attaches the stamp: the body schema intersected with the optional `engine`
+ * field. Applied at the ROUTE, never on an outcome schema, so an outcome schema keeps describing what the engine
+ * produces (the schema drift pin in `mailwoman` depends on that) and the OpenAPI document references the outcome
+ * component through `allOf` instead of cloning it.
+ */
+export function stampedResponseSchema(schema) {
+    return z.intersection(schema, z.object({ engine: EngineStampSchema.optional() }));
+}
+/**
+ * `Server` names the engine and its license branch; `Link: rel="license"` is the registered relation (RFC 8288) that
+ * lets a proxy, a browser, or `curl -I` find the terms without a body change. Set before the handler runs, so the
+ * headers are on the context when any `c.json` — the route's or the error net's — builds its response.
+ */
+export function engineHeaders(stamp) {
+    const server = `mailwoman/${stamp.version} (${stamp.license})`;
+    const link = `<${stamp.license_url}>; rel="license"`;
+    return async (c, next) => {
+        c.header("Server", server);
+        c.header("Link", link);
+        await next();
+    };
+}
+/**
+ * Attach the `engine` field when a stamp is configured. The field goes LAST, so a body that already spells a key of the
+ * same name keeps the stamp's value.
+ */
+export function withEngineStamp(body, stamp) {
+    return stamp ? { ...body, engine: stamp } : body;
+}
+//# sourceMappingURL=engine-stamp.js.map

package/out/engine-stamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-stamp.js","sourceRoot":"","sources":["../lib/engine-stamp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AAIrC;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAChC,YAAY,CAAC;IACb,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;IAC5B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC7B,CAAC;KACD,OAAO,CAAC,aAAa,CAAkC,CAAA;AAEzD;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAyB,MAAS;IACtE,OAAO,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,iBAAiB,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAA;AAClF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAkB;IAC/C,MAAM,MAAM,GAAG,aAAa,KAAK,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO,GAAG,CAAA;IAC9D,MAAM,IAAI,GAAG,IAAI,KAAK,CAAC,WAAW,kBAAkB,CAAA;IAEpD,OAAO,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QACxB,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;QAC1B,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;QAEtB,MAAM,IAAI,EAAE,CAAA;IACb,CAAC,CAAA;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC9B,IAAO,EACP,KAA8B;IAE9B,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;AACjD,CAAC"}

package/out/error.d.ts

@@ -24,10 +24,24 @@ export declare const APIErrorSchema: z.ZodObject<{
  * handler's return type against that specific route's declared per-status `responses` map. A flat-typed `status` param
  * would widen every branch to "any content-carrying status", which no single declared response branch matches.
  */
-export declare function apiError<S extends ContentfulStatusCode>(c: Context, status: S, error: string, detail?: string): Response & import("hono").TypedResponse<{
+export declare function errorResponse<S extends ContentfulStatusCode>(c: Context, status: S, error: string, detail?: string): Response & import("hono").TypedResponse<{
     error: string;
 } | {
     error: string;
     detail: string;
 }, S, "json">;
+/**
+ * The "engine method absent" 503, for the engine method the route actually needed.
+ *
+ * `subject` is a WIRE VALUE, not a label. `<subject> not available` is published verbatim in the HTTP API reference
+ * table and in the docker deploy guide, so a caller branching on it is doing what the docs told them to — and
+ * `/v1/resolve` answers `resolver`, not `geocoder`, because the method it found missing is `engine.resolveTree`. Rename
+ * this function freely; never the string it emits.
+ */
+export declare function geocoderUnavailableError(c: Context, subject?: "geocoder" | "resolver"): Response & import("hono").TypedResponse<{
+    error: string;
+} | {
+    error: string;
+    detail: string;
+}, 503, "json">;
 //# sourceMappingURL=error.d.ts.map

package/out/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../error.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AACrC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AACnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAElE;;GAEG;AACH,eAAO,MAAM,cAAc;;;iBAKN,CAAA;AAErB;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,oBAAoB,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;;;;;cAE7G"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../lib/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AACrC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AACnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAElE;;GAEG;AACH,eAAO,MAAM,cAAc;;;iBAKN,CAAA;AAErB;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,oBAAoB,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;;;;;cAElH;AAKD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,GAAE,UAAU,GAAG,UAAuB;;;;;gBAEjG"}

package/out/error.js

@@ -24,7 +24,19 @@ export const APIErrorSchema = z
  * handler's return type against that specific route's declared per-status `responses` map. A flat-typed `status` param
  * would widen every branch to "any content-carrying status", which no single declared response branch matches.
  */
-export function apiError(c, status, error, detail) {
+export function errorResponse(c, status, error, detail) {
     return c.json(detail === undefined ? { error } : { error, detail }, status);
 }
+const GEOCODER_UNAVAILABLE_DETAIL = "install @mailwoman/neural + @mailwoman/resolver-wof-sqlite and provide gazetteer data (MAILWOMAN_WOF_DB / MAILWOMAN_CANDIDATE_DB)";
+/**
+ * The "engine method absent" 503, for the engine method the route actually needed.
+ *
+ * `subject` is a WIRE VALUE, not a label. `<subject> not available` is published verbatim in the HTTP API reference
+ * table and in the docker deploy guide, so a caller branching on it is doing what the docs told them to — and
+ * `/v1/resolve` answers `resolver`, not `geocoder`, because the method it found missing is `engine.resolveTree`. Rename
+ * this function freely; never the string it emits.
+ */
+export function geocoderUnavailableError(c, subject = "geocoder") {
+    return errorResponse(c, 503, `${subject} not available`, GEOCODER_UNAVAILABLE_DETAIL);
+}
 //# sourceMappingURL=error.js.map

package/out/error.js.map

@@ -1 +1 @@
-{"version":3,"file":"error.js","sourceRoot":"","sources":["../error.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AAIrC;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC7B,MAAM,CAAC;IACP,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC7B,CAAC;KACD,OAAO,CAAC,UAAU,CAAC,CAAA;AAErB;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAiC,CAAU,EAAE,MAAS,EAAE,KAAa,EAAE,MAAe;IAC7G,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,CAAA;AAC5E,CAAC"}
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../lib/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AAIrC;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC7B,MAAM,CAAC;IACP,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC7B,CAAC;KACD,OAAO,CAAC,UAAU,CAAC,CAAA;AAErB;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAiC,CAAU,EAAE,MAAS,EAAE,KAAa,EAAE,MAAe;IAClH,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,CAAA;AAC5E,CAAC;AAED,MAAM,2BAA2B,GAChC,mIAAmI,CAAA;AAEpI;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CAAC,CAAU,EAAE,UAAmC,UAAU;IACjG,OAAO,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,gBAAgB,EAAE,2BAA2B,CAAC,CAAA;AACtF,CAAC"}

package/out/geo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"geo.d.ts","sourceRoot":"","sources":["../geo.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AAErC;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;iBAKN,CAAA;AAE1B;;GAEG;AACH,eAAO,MAAM,UAAU,wEAA4D,CAAA;AAEnF;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,CAAC;;;;;;;kBAMlE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC;;;kBAKzE"}
+{"version":3,"file":"geo.d.ts","sourceRoot":"","sources":["../lib/geo.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AAErC;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;iBAKN,CAAA;AAE1B;;GAEG;AACH,eAAO,MAAM,UAAU,wEAA4D,CAAA;AAEnF;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,CAAC;;;;;;;kBAMlE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC;;;kBAKzE"}

package/out/geo.js.map

@@ -1 +1 @@
-{"version":3,"file":"geo.js","sourceRoot":"","sources":["../geo.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AAErC;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KAClC,MAAM,CAAC;IACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACxB,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;CAC9C,CAAC;KACD,OAAO,CAAC,eAAe,CAAC,CAAA;AAE1B;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;AAEnF;;GAEG;AACH,MAAM,UAAU,aAAa,CAAyB,UAAa;IAClE,OAAO,CAAC,CAAC,MAAM,CAAC;QACf,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;QAC1B,QAAQ,EAAE,mBAAmB;QAC7B,UAAU;KACV,CAAC,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAyB,OAAU;IACzE,OAAO,CAAC,CAAC,MAAM,CAAC;QACf,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC;QACpC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;KAC1B,CAAC,CAAA;AACH,CAAC"}
+{"version":3,"file":"geo.js","sourceRoot":"","sources":["../lib/geo.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AAErC;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KAClC,MAAM,CAAC;IACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACxB,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;CAC9C,CAAC;KACD,OAAO,CAAC,eAAe,CAAC,CAAA;AAE1B;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;AAEnF;;GAEG;AACH,MAAM,UAAU,aAAa,CAAyB,UAAa;IAClE,OAAO,CAAC,CAAC,MAAM,CAAC;QACf,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;QAC1B,QAAQ,EAAE,mBAAmB;QAC7B,UAAU;KACV,CAAC,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAyB,OAAU;IACzE,OAAO,CAAC,CAAC,MAAM,CAAC;QACf,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC;QACpC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;KAC1B,CAAC,CAAA;AACH,CAAC"}

package/out/index.d.ts

@@ -8,10 +8,11 @@
  *   domain schemas live next to their routes in the package that owns the wire contract (see the
  *   2026-07-12 design spec's anti-meta guardrails).
  */
-export * from "./error.ts";
-export * from "./geo.ts";
-export * from "./metrics.ts";
-export * from "./openapi.ts";
-export * from "./request.ts";
-export * from "./serve.ts";
+export * from "#error";
+export * from "#geo";
+export * from "#metrics";
+export * from "#openapi";
+export * from "#request";
+export * from "#serve";
+export * from "#engine-stamp";
 //# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,QAAQ,CAAA;AACtB,cAAc,MAAM,CAAA;AACpB,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,QAAQ,CAAA;AACtB,cAAc,eAAe,CAAA"}

package/out/index.js

@@ -8,10 +8,11 @@
  *   domain schemas live next to their routes in the package that owns the wire contract (see the
  *   2026-07-12 design spec's anti-meta guardrails).
  */
-export * from "./error.js";
-export * from "./geo.js";
-export * from "./metrics.js";
-export * from "./openapi.js";
-export * from "./request.js";
-export * from "./serve.js";
+export * from "#error";
+export * from "#geo";
+export * from "#metrics";
+export * from "#openapi";
+export * from "#request";
+export * from "#serve";
+export * from "#engine-stamp";
 //# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,QAAQ,CAAA;AACtB,cAAc,MAAM,CAAA;AACpB,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,QAAQ,CAAA;AACtB,cAAc,eAAe,CAAA"}

package/out/metrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAkBH;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAejE;AAiBD,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE;QACR,KAAK,EAAE,MAAM,CAAA;QACb,MAAM,EAAE,MAAM,CAAA;QACd;;;WAGG;QACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC7B,UAAU,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;QACzE,eAAe,EAAE,MAAM,CAAA;KACvB,CAAA;CACD;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAoBjD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAW1C"}
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../lib/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAoBH;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAejE;AAcD,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE;QACR,KAAK,EAAE,MAAM,CAAA;QACb,MAAM,EAAE,MAAM,CAAA;QACd;;;WAGG;QACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC7B,UAAU,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;QACzE,eAAe,EAAE,MAAM,CAAA;KACvB,CAAA;CACD;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAoBjD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAW1C"}

package/out/metrics.js

@@ -11,6 +11,7 @@
  *   Surfaced by `GET /metrics`; reset on process restart (no persistence — scrape it). Per-process
  *   state: under `node:cluster` each worker reports its own snapshot — aggregate at the scraper.
  */
+import { percentileSorted } from "@mailwoman/core/stats";
 /**
  * Recent-latency reservoir size. ~2k samples gives stable p99 without unbounded memory.
  */
@@ -45,18 +46,14 @@ export function recordTimed(latencyMs, tier) {
     }
 }
 /**
- * Percentile for the metrics snapshot — deliberately NOT `percentile` from `@mailwoman/core/utils`.
- *
- * Three differences, each on purpose for a hot request-path counter: it takes an ALREADY-sorted array (the caller sorts
- * once per snapshot, not once per percentile), returns `0` rather than `null` on empty so the snapshot stays a plain
- * number map, and rounds to two decimals because these are milliseconds on a wire format. Core's returns `null` and
- * does not round.
+ * A latency percentile as milliseconds on a wire format: two decimals. The caller sorts once per snapshot and
+ * guarantees a non-empty sample, so `percentileSorted`'s `null` is a caller error here, never a reading.
  */
-function percentile(sorted, p) {
-    if (!sorted.length)
-        return 0;
-    const idx = Math.min(sorted.length - 1, Math.floor(p * sorted.length));
-    return Math.round(sorted[idx] * 100) / 100;
+function latencyPercentile(sorted, p) {
+    const value = percentileSorted(sorted, p);
+    if (value === null)
+        throw new Error("latencyPercentile requires a non-empty sample");
+    return Math.round(value * 100) / 100;
 }
 /**
  * Current metrics snapshot — sorted-reservoir percentiles + counters.
@@ -71,9 +68,9 @@ export function metricsSnapshot() {
             tiers: { ...tierCounts },
             latency_ms: sorted.length
                 ? {
-                    p50: percentile(sorted, 0.5),
-                    p90: percentile(sorted, 0.9),
-                    p99: percentile(sorted, 0.99),
+                    p50: latencyPercentile(sorted, 50),
+                    p90: latencyPercentile(sorted, 90),
+                    p99: latencyPercentile(sorted, 99),
                     max: Math.round(sorted.at(-1) * 100) / 100,
                 }
                 : null,

package/out/metrics.js.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,WAAW,GAAG,IAAI,CAAA;AAExB,MAAM,SAAS,GAAa,EAAE,CAAA;AAC9B,IAAI,QAAQ,GAAG,CAAC,CAAA;AAEhB;;GAEG;AACH,MAAM,UAAU,GAA2B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;AAC9D,IAAI,KAAK,GAAG,CAAC,CAAA;AACb,IAAI,MAAM,GAAG,CAAC,CAAA;AACd,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;AAE5B;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,SAAiB,EAAE,IAAY;IAC1D,KAAK,EAAE,CAAA;IAEP,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACtB,MAAM,EAAE,CAAA;IACT,CAAC;SAAM,CAAC;QACP,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAA;IAC/C,CAAC;IAED,IAAI,SAAS,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;QACpC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IAC1B,CAAC;SAAM,CAAC;QACP,SAAS,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;QAC/B,QAAQ,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC,GAAG,WAAW,CAAA;IACxC,CAAC;AACF,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,UAAU,CAAC,MAAgB,EAAE,CAAS;IAC9C,IAAI,CAAC,MAAM,CAAC,MAAM;QAAE,OAAO,CAAC,CAAA;IAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAA;IAEtE,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAE,GAAG,GAAG,CAAC,GAAG,GAAG,CAAA;AAC5C,CAAC;AAiBD;;GAEG;AACH,MAAM,UAAU,eAAe;IAC9B,MAAM,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;IAEvD,OAAO;QACN,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC;QACrD,OAAO,EAAE;YACR,KAAK;YACL,MAAM;YACN,KAAK,EAAE,EAAE,GAAG,UAAU,EAAE;YACxB,UAAU,EAAE,MAAM,CAAC,MAAM;gBACxB,CAAC,CAAC;oBACA,GAAG,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC;oBAC5B,GAAG,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC;oBAC5B,GAAG,EAAE,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC;oBAC7B,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAE,GAAG,GAAG,CAAC,GAAG,GAAG;iBAC3C;gBACF,CAAC,CAAC,IAAI;YACP,eAAe,EAAE,MAAM,CAAC,MAAM;SAC9B;KACD,CAAA;AACF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB;IAClC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAA;IACpB,QAAQ,GAAG,CAAC,CAAA;IAEZ,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3C,iIAAiI;QACjI,OAAO,UAAU,CAAC,GAAG,CAAC,CAAA;IACvB,CAAC;IAED,KAAK,GAAG,CAAC,CAAA;IACT,MAAM,GAAG,CAAC,CAAA;AACX,CAAC"}
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../lib/metrics.ts"],"names":[],"mappings":"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"}

package/out/openapi.d.ts

@@ -8,6 +8,7 @@
  *   (progenitor), replacing the old hand-downgrade step.
  */
 import type { OpenAPIHono } from "@hono/zod-openapi";
+type OpenAPISecurityRequirements = Parameters<OpenAPIHono["getOpenAPI31Document"]>[0]["security"];
 /**
  * The document config stamped into emitted documents: `title`/`version`/`description`/`summary`/`license`/`contact`
  * land under the document's `info` block; `externalDocs`/`servers`/`tags`/`security` are top-level document fields. All
@@ -42,7 +43,7 @@ export interface OpenAPIDocInfo {
         name: string;
         description?: string;
     }>;
-    security?: unknown[];
+    security?: OpenAPISecurityRequirements;
 }
 /**
  * Mount the OpenAPI 3.1 document endpoint on `app` (default `/openapi.json`).
@@ -67,7 +68,7 @@ export declare function emitOpenAPIDocuments(app: OpenAPIHono, info: OpenAPIDocI
 export declare function printOpenAPIDocument(app: OpenAPIHono, info: OpenAPIDocInfo, opts?: {
     flavor?: string;
     out?: string;
-}): void;
+}): Promise<void>;
 /**
  * An OpenAPI error-response descriptor: a description plus a JSON body of `schema`.
  *
@@ -83,4 +84,5 @@ export declare function errorContent<S>(description: string, schema: S): {
         };
     };
 };
+export {};
 //# sourceMappingURL=openapi.d.ts.map

package/out/openapi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/C,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACzC,YAAY,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;IACpD,OAAO,CAAC,EAAE,KAAK,CAAC;QACf,GAAG,EAAE,MAAM,CAAA;QACX,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KACrE,CAAC,CAAA;IACF,IAAI,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACpD,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;CACpB;AAiBD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,SAAkB,GAAG,IAAI,CAItG;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAKzG;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,cAAc,EACpB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1C,IAAI,CAUN;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;;;;;;;EAK7D"}
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../lib/openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAGpD,KAAK,2BAA2B,GAAG,UAAU,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAA;AAEjG;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/C,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACzC,YAAY,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;IACpD,OAAO,CAAC,EAAE,KAAK,CAAC;QACf,GAAG,EAAE,MAAM,CAAA;QACX,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KACrE,CAAC,CAAA;IACF,IAAI,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACpD,QAAQ,CAAC,EAAE,2BAA2B,CAAA;CACtC;AAiBD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,SAAkB,GAAG,IAAI,CAItG;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAezG;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACzC,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,cAAc,EACpB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1C,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;;;;;;;EAK7D"}

package/out/openapi.js

@@ -7,8 +7,7 @@
  *   handwritten. 3.1 is the published flavor; 3.0 exists solely for client generators that lag
  *   (progenitor), replacing the old hand-downgrade step.
  */
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { writeLocalTextFile } from "@mailwoman/core/fs/writers";
 /**
  * Split an `OpenAPIDocInfo` into the document's `info` block and its top-level sibling fields.
  */
@@ -26,17 +25,24 @@ function toDocumentConfig(info) {
  * Mount the OpenAPI 3.1 document endpoint on `app` (default `/openapi.json`).
  */
 export function attachOpenAPIDocs(app, info, path = "/openapi.json") {
-    // openapi3-ts's InfoObject/OpenAPIObject carry an `x-${string}` extension index signature that
-    // a plain interface can't satisfy — cast at the boundary rather than widening the public type.
-    app.doc31(path, { openapi: "3.1.0", ...toDocumentConfig(info) });
+    const config = { openapi: "3.1.0", ...toDocumentConfig(info) };
+    app.doc31(path, config);
 }
 /**
  * Emit both document flavors programmatically (build artifacts, parity tests, client generation).
  */
 export function emitOpenAPIDocuments(app, info) {
+    const v31Config = {
+        openapi: "3.1.0",
+        ...toDocumentConfig(info),
+    };
+    const v30Config = {
+        openapi: "3.0.3",
+        ...toDocumentConfig(info),
+    };
     return {
-        v31: app.getOpenAPI31Document({ openapi: "3.1.0", ...toDocumentConfig(info) }),
-        v30: app.getOpenAPIDocument({ openapi: "3.0.3", ...toDocumentConfig(info) }),
+        v31: app.getOpenAPI31Document(v31Config),
+        v30: app.getOpenAPIDocument(v30Config),
     };
 }
 /**
@@ -48,15 +54,16 @@ export function emitOpenAPIDocuments(app, info) {
  * gitignored, not-yet-existing `docs/static/openapi/`). One place owns this so the four emitters can't drift out of
  * lockstep with each other.
  */
-export function printOpenAPIDocument(app, info, opts = {}) {
+export async function printOpenAPIDocument(app, info, opts = {}) {
     const { v31, v30 } = emitOpenAPIDocuments(app, info);
-    const json = JSON.stringify(opts.flavor === "3.0" ? v30 : v31);
+    // Compact JSON, one line, the same bytes to a file and to stdout — a consumer piping either into a diff or a
+    // generator sees one form.
+    const json = `${JSON.stringify(opts.flavor === "3.0" ? v30 : v31)}\n`;
     if (opts.out) {
-        mkdirSync(dirname(opts.out), { recursive: true });
-        writeFileSync(opts.out, `${json}\n`);
+        await writeLocalTextFile(json, opts.out);
     }
     else {
-        console.log(json);
+        process.stdout.write(json);
     }
 }
 /**

package/out/openapi.js.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AA0BnC;;GAEG;AACH,SAAS,gBAAgB,CAAC,IAAoB;IAC7C,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAA;IAE9G,OAAO;QACN,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE;QAChE,YAAY;QACZ,OAAO;QACP,IAAI;QACJ,QAAQ;KACR,CAAA;AACF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAgB,EAAE,IAAoB,EAAE,IAAI,GAAG,eAAe;IAC/F,+FAA+F;IAC/F,+FAA+F;IAC/F,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAW,CAAC,CAAA;AAC1E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAgB,EAAE,IAAoB;IAC1E,OAAO;QACN,GAAG,EAAE,GAAG,CAAC,oBAAoB,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAW,CAAC;QACvF,GAAG,EAAE,GAAG,CAAC,kBAAkB,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAW,CAAC;KACrF,CAAA;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CACnC,GAAgB,EAChB,IAAoB,EACpB,OAA0C,EAAE;IAE5C,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IAE9D,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QACd,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QACjD,aAAa,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,CAAA;IACrC,CAAC;SAAM,CAAC;QACP,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAClB,CAAC;AACF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAI,WAAmB,EAAE,MAAS;IAC7D,OAAO;QACN,WAAW;QACX,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,EAAE;KAC3C,CAAA;AACF,CAAC"}
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../lib/openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AA0B/D;;GAEG;AACH,SAAS,gBAAgB,CAAC,IAAoB;IAC7C,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAA;IAE9G,OAAO;QACN,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE;QAChE,YAAY;QACZ,OAAO;QACP,IAAI;QACJ,QAAQ;KACR,CAAA;AACF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAgB,EAAE,IAAoB,EAAE,IAAI,GAAG,eAAe;IAC/F,MAAM,MAAM,GAAwC,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAA;IAEnG,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;AACxB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAgB,EAAE,IAAoB;IAC1E,MAAM,SAAS,GAAuD;QACrE,OAAO,EAAE,OAAO;QAChB,GAAG,gBAAgB,CAAC,IAAI,CAAC;KACzB,CAAA;IAED,MAAM,SAAS,GAAqD;QACnE,OAAO,EAAE,OAAO;QAChB,GAAG,gBAAgB,CAAC,IAAI,CAAC;KACzB,CAAA;IAED,OAAO;QACN,GAAG,EAAE,GAAG,CAAC,oBAAoB,CAAC,SAAS,CAAC;QACxC,GAAG,EAAE,GAAG,CAAC,kBAAkB,CAAC,SAAS,CAAC;KACtC,CAAA;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACzC,GAAgB,EAChB,IAAoB,EACpB,OAA0C,EAAE;IAE5C,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IACpD,6GAA6G;IAC7G,2BAA2B;IAC3B,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAA;IAErE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QACd,MAAM,kBAAkB,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;IACzC,CAAC;SAAM,CAAC;QACP,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAC3B,CAAC;AACF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAI,WAAmB,EAAE,MAAS;IAC7D,OAAO;QACN,WAAW;QACX,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,EAAE;KAC3C,CAAA;AACF,CAAC"}

package/out/request.d.ts

@@ -18,5 +18,10 @@ import type { Context } from "hono";
  * this shape rather than Hono's uniformly-array `queries()`. Built on a null-prototype object so a query key of
  * `__proto__` or `constructor` cannot reach `Object`'s prototype — these handlers take arbitrary internet input.
  */
+/**
+ * A non-empty string query value, else `undefined`. An empty `?q=` is treated as absent, since every drop-in reads it
+ * that way.
+ */
+export declare function asString(raw: unknown): string | undefined;
 export declare function legacyQuery(c: Context): Record<string, string | string[]>;
 //# sourceMappingURL=request.d.ts.map

package/out/request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAQzE"}
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../lib/request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC;;;;;;GAMG;AACH;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEzD;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAQzE"}

package/out/request.js

@@ -17,6 +17,13 @@
  * this shape rather than Hono's uniformly-array `queries()`. Built on a null-prototype object so a query key of
  * `__proto__` or `constructor` cannot reach `Object`'s prototype — these handlers take arbitrary internet input.
  */
+/**
+ * A non-empty string query value, else `undefined`. An empty `?q=` is treated as absent, since every drop-in reads it
+ * that way.
+ */
+export function asString(raw) {
+    return typeof raw === "string" && raw.length ? raw : undefined;
+}
 export function legacyQuery(c) {
     const out = Object.create(null);
     for (const [key, values] of Object.entries(c.req.queries())) {

package/out/request.js.map

@@ -1 +1 @@
-{"version":3,"file":"request.js","sourceRoot":"","sources":["../request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,CAAU;IACrC,MAAM,GAAG,GAAsC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAElE,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,MAAM,CAAA;IACrD,CAAC;IAED,OAAO,GAAG,CAAA;AACX,CAAC"}
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../lib/request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;GAMG;AACH;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAY;IACpC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAA;AAC/D,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAU;IACrC,MAAM,GAAG,GAAsC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAElE,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,MAAM,CAAA;IACrD,CAAC;IAED,OAAO,GAAG,CAAA;AACX,CAAC"}

package/out/serve.d.ts

@@ -7,14 +7,15 @@
  *   surface packages stay web-standard (they only export `fetch`-shaped apps) so an edge
  *   deployment needs no changes to them.
  */
+import { serve, type ServerType } from "@hono/node-server";
 /**
  * A `fetch`-shaped request handler (what `OpenAPIHono.fetch` provides).
  */
 export type FetchLike = (request: Request, ...args: never[]) => Response | Promise<Response>;
-export interface ServeNodeOptions {
-    fetch: FetchLike;
-    port: number;
-    hostname: string;
+/**
+ * Options for `serveNode()`. Extracted since Hono doesn't seem to export them.
+ */
+export type ServeNodeOptions = Parameters<typeof serve>[0] & {
     /**
      * Called once the listener is bound — receives the actual port (useful with `port: 0`).
      */
@@ -22,12 +23,17 @@ export interface ServeNodeOptions {
         port: number;
         address: string;
     }) => void;
-}
-export interface ServerHandle {
-    close(): Promise<void>;
-}
+};
+/**
+ * The listener plus the port it bound, which `port: 0` callers need. Only `port` is added: `net.Server` already owns an
+ * `address()` method, and Node's cluster child calls it inside its own `listening` handler, so a value property of that
+ * name on the handle breaks every cluster worker at listen.
+ */
+export type ServerHandle = ServerType & AsyncDisposable & {
+    readonly port: number;
+};
 /**
- * Boot a node HTTP listener for a Hono app. Returns a handle whose `close()` resolves when the listener is down.
+ * Boot a node HTTP listener for a Hono app. Returns an async-disposable handle once the listener is ready.
  */
-export declare function serveNode(options: ServeNodeOptions): ServerHandle;
+export declare function serveNode({ onListen, ...options }: ServeNodeOptions): Promise<ServerHandle>;
 //# sourceMappingURL=serve.d.ts.map

package/out/serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;AAE5F,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,SAAS,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CAC5D;AAED,MAAM,WAAW,YAAY;IAC5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACtB;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,CAWjE"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../lib/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAE1D;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;AAE5F;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG;IAC5D;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CAC5D,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GACpC,eAAe,GAAG;IACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACrB,CAAA;AAKF;;GAEG;AACH,wBAAgB,SAAS,CAAC,EAAE,QAA0B,EAAE,GAAG,OAAO,EAAE,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAiB7G"}

package/out/serve.js

@@ -8,15 +8,24 @@
  *   deployment needs no changes to them.
  */
 import { serve } from "@hono/node-server";
+const defaultOnListen = ({ port, address }) => console.error(`[mailwoman] native /v1 API listening on http://${address}:${port}`);
 /**
- * Boot a node HTTP listener for a Hono app. Returns a handle whose `close()` resolves when the listener is down.
+ * Boot a node HTTP listener for a Hono app. Returns an async-disposable handle once the listener is ready.
  */
-export function serveNode(options) {
-    const server = serve({ fetch: options.fetch, port: options.port, hostname: options.hostname }, (info) => options.onListen?.({ port: info.port, address: info.address }));
-    return {
-        close: () => new Promise((resolve, reject) => {
-            server.close((error) => (error ? reject(error) : resolve()));
-        }),
-    };
+export function serveNode({ onListen = defaultOnListen, ...options }) {
+    return new Promise((resolve, reject) => {
+        const server = serve(options, (info) => {
+            server.off("error", reject);
+            Object.defineProperty(server, "port", { value: info.port, writable: false });
+            try {
+                onListen(info);
+                resolve(server);
+            }
+            catch (error) {
+                void server[Symbol.asyncDispose]().then(() => reject(error), reject);
+            }
+        });
+        server.once("error", reject);
+    });
 }
 //# sourceMappingURL=serve.js.map

package/out/serve.js.map

@@ -1 +1 @@
-{"version":3,"file":"serve.js","sourceRoot":"","sources":["../serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAqBzC;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,OAAyB;IAClD,MAAM,MAAM,GAAG,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAc,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE,CAChH,OAAO,CAAC,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAC9D,CAAA;IAED,OAAO;QACN,KAAK,EAAE,GAAG,EAAE,CACX,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAa,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;QACrE,CAAC,CAAC;KACH,CAAA;AACF,CAAC"}
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../lib/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,EAAmB,MAAM,mBAAmB,CAAA;AA2B1D,MAAM,eAAe,GAAG,CAAC,EAAE,IAAI,EAAE,OAAO,EAAqC,EAAE,EAAE,CAChF,OAAO,CAAC,KAAK,CAAC,kDAAkD,OAAO,IAAI,IAAI,EAAE,CAAC,CAAA;AAEnF;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,EAAE,QAAQ,GAAG,eAAe,EAAE,GAAG,OAAO,EAAoB;IACrF,OAAO,IAAI,OAAO,CAAe,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACpD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACtC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;YAE3B,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAA;YAE5E,IAAI,CAAC;gBACJ,QAAQ,CAAC,IAAI,CAAC,CAAA;gBACd,OAAO,CAAC,MAAsB,CAAC,CAAA;YAChC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,KAAK,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAA;YACrE,CAAC;QACF,CAAC,CAAC,CAAA;QAEF,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;IAC7B,CAAC,CAAC,CAAA;AACH,CAAC"}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@mailwoman/api-kit",
-  "version": "9.1.0",
+  "version": "9.3.0",
   "description": "API plumbing for Mailwoman's HTTP surfaces — Hono node serve wrapper, OpenAPI emit helpers, shared wire atoms. Plumbing only: domain schemas live with their routes.",
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "repository": {
     "type": "git",
     "url": "https://github.com/sister-software/mailwoman.git",
-    "directory": "api-kit"
+    "directory": "packages/api-kit"
   },
   "files": [
     "out/**/*.js",
@@ -21,14 +21,29 @@
     "!*.test.ts",
     "!*.test.tsx",
     "!**/*.test.ts",
-    "!**/*.test.tsx"
+    "!**/*.test.tsx",
+    "!test/**"
   ],
   "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#*": {
+      "types": "./out/*.d.ts",
+      "node": "./out/*.js",
+      "default": "./out/*.js"
+    }
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {
       "types": "./out/index.d.ts",
+      "node": "./out/index.js",
       "default": "./out/index.js"
+    },
+    "./metrics": {
+      "types": "./out/metrics.d.ts",
+      "node": "./out/metrics.js",
+      "default": "./out/metrics.js"
     }
   },
   "publishConfig": {
@@ -37,14 +52,28 @@
       "./package.json": "./package.json",
       ".": {
         "types": "./out/index.d.ts",
+        "node": "./out/index.js",
         "default": "./out/index.js"
+      },
+      "./metrics": {
+        "types": "./out/metrics.d.ts",
+        "node": "./out/metrics.js",
+        "default": "./out/metrics.js"
+      }
+    },
+    "imports": {
+      "#*": {
+        "types": "./out/*.d.ts",
+        "node": "./out/*.js",
+        "default": "./out/*.js"
       }
     }
   },
   "dependencies": {
-    "@hono/node-server": "^2.0.12",
-    "@hono/zod-openapi": "^1.5.1",
-    "hono": "^4.13.0",
-    "zod": "^4.4.3"
+    "@hono/node-server": "^2.1.1",
+    "@hono/zod-openapi": "^1.6.3",
+    "@mailwoman/core": "9.3.0",
+    "hono": "^4.13.7",
+    "zod": "^4.5.4"
   }
 }

package/serve.ts

@@ -1,46 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   Node serve wrapper over `@hono/node-server`. The one place the node listener is created —
- *   surface packages stay web-standard (they only export `fetch`-shaped apps) so an edge
- *   deployment needs no changes to them.
- */
-
-import { serve } from "@hono/node-server"
-
-/**
- * A `fetch`-shaped request handler (what `OpenAPIHono.fetch` provides).
- */
-export type FetchLike = (request: Request, ...args: never[]) => Response | Promise<Response>
-
-export interface ServeNodeOptions {
-	fetch: FetchLike
-	port: number
-	hostname: string
-	/**
-	 * Called once the listener is bound — receives the actual port (useful with `port: 0`).
-	 */
-	onListen?: (info: { port: number; address: string }) => void
-}
-
-export interface ServerHandle {
-	close(): Promise<void>
-}
-
-/**
- * Boot a node HTTP listener for a Hono app. Returns a handle whose `close()` resolves when the listener is down.
- */
-export function serveNode(options: ServeNodeOptions): ServerHandle {
-	const server = serve({ fetch: options.fetch as never, port: options.port, hostname: options.hostname }, (info) =>
-		options.onListen?.({ port: info.port, address: info.address })
-	)
-
-	return {
-		close: () =>
-			new Promise<void>((resolve, reject) => {
-				server.close((error?: Error) => (error ? reject(error) : resolve()))
-			}),
-	}
-}