@mandujs/core 0.35.1 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.35.1",
+  "version": "0.37.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/config/mandu.ts

@@ -126,6 +126,29 @@ export interface ManduConfig {
   spa?: boolean;
   server?: {
     port?: number;
+    /**
+     * Bind hostname for the HTTP server.
+     *
+     * Default: `"::"` (IPv6 wildcard, dual-stack). Bun leaves
+     * `IPV6_V6ONLY` off, so this one socket accepts both IPv6 clients
+     * (e.g. Node 17+ `fetch("localhost:PORT")` on Windows resolves to
+     * `::1`) and IPv4 clients (as IPv4-mapped IPv6) — you effectively
+     * get `0.0.0.0` + `::` for free.
+     *
+     * Set `"0.0.0.0"` to bind IPv4 only (container/firewall setups that
+     * need it). Note: on Windows, an IPv4-only bind makes Node's
+     * `fetch("localhost:PORT")` fail with `ECONNREFUSED ::1:PORT`
+     * because Node prefers the IPv6 address for `localhost`. `curl`
+     * and browsers silently fall back to IPv4, hiding the bug — Mandu
+     * emits a one-line warning on Windows when you pick this value
+     * explicitly so the trap is discoverable.
+     *
+     * Set `"127.0.0.1"` or `"::1"` to bind loopback-only (no LAN
+     * visibility). Set any other value (e.g. `"10.0.0.2"`,
+     * `"myhost.example.com"`) to bind that specific interface.
+     *
+     * @see issues #190 #223 #225
+     */
     hostname?: string;
     cors?:
       | boolean

package/src/config/validate.ts

@@ -44,9 +44,12 @@ function strictWithWarnings<T extends z.ZodRawShape>(
 const ServerConfigSchema = z
   .object({
     port: z.number().min(1).max(65535).default(3000),
-    // Default 0.0.0.0 so IPv4 `localhost` resolution (Windows default) succeeds.
-    // Users may pin "::1" or "127.0.0.1" explicitly. See issue #190.
-    hostname: z.string().default("0.0.0.0"),
+    // Default `"::"` (IPv6 wildcard, dual-stack): accepts both IPv4 and
+    // IPv6 clients on one socket. Fixes Windows Node 17+ fetch failing
+    // with `ECONNREFUSED ::1:PORT` because `localhost` resolves to `::1`
+    // first there. Explicit `"0.0.0.0"` (IPv4-only) and `"::1"` /
+    // `"127.0.0.1"` (loopback-only) are still honored. See #190 #223.
+    hostname: z.string().default("::"),
     cors: z
       .union([
         z.boolean(),

package/src/openapi/generator.ts

@@ -26,6 +26,33 @@ import {
   isZodRequired,
 } from "../contract/zod-utils";
 
+// ============================================
+// Schema name-hint side table
+// ============================================
+
+/**
+ * Side-channel naming hints for generated OpenAPI schemas.
+ *
+ * The hoist pass needs a preferred name for each object schema but we
+ * don't want to serialize that hint into the output document. A WeakMap
+ * keyed by the generated `OpenAPISchema` object gives us name access
+ * during the post-processing pass without polluting the spec JSON.
+ *
+ * Hints are advisory — the hoist pass falls back to a deterministic
+ * `Schema_<hash8>` name when no hint is attached.
+ */
+const schemaNameHints = new WeakMap<OpenAPISchema, string>();
+
+function setSchemaNameHint(schema: OpenAPISchema | undefined, hint: string | undefined): void {
+  if (!schema || !hint) return;
+  // Don't overwrite an existing hint — first attribution wins. This matches
+  // the "first-come wins" policy for structurally-identical schemas with
+  // different user-given names.
+  if (!schemaNameHints.has(schema)) {
+    schemaNameHints.set(schema, hint);
+  }
+}
+
 // ============================================
 // OpenAPI Types
 // ============================================
@@ -373,6 +400,35 @@ function generateParameters(
   return parameters;
 }
 
+/**
+ * Convert an arbitrary identifier to a PascalCase token suitable for an
+ * OpenAPI component name. Non-alphanumeric characters become word
+ * separators; leading digits are prefixed with `_` so the result is a
+ * valid JSON Schema identifier.
+ */
+function pascal(input: string): string {
+  if (!input) return "";
+  const words = input
+    .split(/[^a-zA-Z0-9]+/g)
+    .filter((w) => w.length > 0)
+    .map((w) => w[0].toUpperCase() + w.slice(1));
+  const joined = words.join("");
+  if (!joined) return "";
+  return /^[0-9]/.test(joined) ? `_${joined}` : joined;
+}
+
+/**
+ * Derive a naming hint root for a contract. Prefers the explicit
+ * `contract.name`; falls back to the route id (e.g. `api/users` →
+ * `ApiUsers`). Guarantees we always have a non-empty PascalCase prefix
+ * for generated component names.
+ */
+function deriveContractNameRoot(contract: ContractSchema, route: RouteSpec): string {
+  const hint = contract.name ?? route.id;
+  const pascalized = pascal(hint);
+  return pascalized || "Schema";
+}
+
 /**
  * Generate OpenAPI operation for a method
  */
@@ -389,6 +445,11 @@ function generateOperation(
     responses: {},
   };
 
+  // Derive a naming hint root from the contract for the hoist pass.
+  // Example: `contract.name = "users"` → `Users`. Falls back to a
+  // route-derived identifier so every contract has *some* stable prefix.
+  const nameRoot = deriveContractNameRoot(contract, route);
+
   // Parameters
   if (methodSchema) {
     const params = generateParameters(methodSchema, route.pattern);
@@ -398,8 +459,13 @@ function generateOperation(
 
     // Request body
     if (methodSchema.body) {
+      const bodySchema = zodToOpenAPISchema(methodSchema.body);
+      // Hint: `UsersBody` / `UsersPostBody` — method-qualified avoids
+      // collisions when GET/POST/PUT on the same contract have distinct
+      // request bodies.
+      setSchemaNameHint(bodySchema, `${nameRoot}${pascal(method)}Body`);
       const requestBodyContent: OpenAPIRequestBody["content"]["application/json"] = {
-        schema: zodToOpenAPISchema(methodSchema.body),
+        schema: bodySchema,
       };
 
       // Add examples if provided
@@ -433,6 +499,10 @@ function generateOperation(
     }
 
     const schema = zodToOpenAPISchema(zodSchema);
+    // Hint: `UsersResponse200` / `UsersPostResponse201`. Status-qualified
+    // so `200` and `400` responses don't collide when both are
+    // `{ error: string }` style objects.
+    setSchemaNameHint(schema, `${nameRoot}${pascal(method)}Response${statusCode}`);
     const hasContent = Object.keys(schema).length > 0;
 
     const responseContent: OpenAPIResponse["content"] = hasContent
@@ -496,6 +566,17 @@ export async function generateOpenAPIDocument(
     version?: string;
     description?: string;
     servers?: OpenAPIServer[];
+    /**
+     * Hoist schemas that appear ≥`hoistThreshold` times into
+     * `components.schemas` and replace inline occurrences with `$ref`.
+     * @default true
+     */
+    hoistSchemas?: boolean;
+    /**
+     * Minimum occurrence count required to hoist a schema.
+     * @default 2
+     */
+    hoistThreshold?: number;
   } = {}
 ): Promise<OpenAPIDocument> {
   const paths: Record<string, OpenAPIPathItem> = {};
@@ -530,7 +611,7 @@ export async function generateOpenAPIDocument(
     paths[openApiPattern] = pathItem;
   }
 
-  return {
+  const doc: OpenAPIDocument = {
     openapi: "3.0.3",
     info: {
       title: options.title || "Mandu API",
@@ -543,6 +624,277 @@ export async function generateOpenAPIDocument(
     paths,
     tags: Array.from(tags).map((name) => ({ name })),
   };
+
+  // Post-processing: hoist shared schemas into components.schemas.
+  // `hoistSchemas: false` → pure backwards-compatible inline output.
+  const hoistEnabled = options.hoistSchemas !== false;
+  if (hoistEnabled) {
+    await hoistSharedSchemas(doc, {
+      threshold: options.hoistThreshold ?? 2,
+    });
+  }
+
+  return doc;
+}
+
+// ============================================
+// Schema hoisting (post-processing)
+// ============================================
+
+export interface HoistOptions {
+  /** Minimum occurrences required to hoist. Default `2`. */
+  threshold?: number;
+}
+
+interface SchemaOccurrence {
+  /** Structural hash of the schema body (identity key). */
+  hash: string;
+  /** Every parent reference we might need to rewrite to `$ref`. */
+  sites: Array<{ parent: Record<string, unknown>; key: string | number }>;
+  /** The canonical schema body (first-seen value; all sites share equal shape). */
+  body: OpenAPISchema;
+  /** Ordered list of name hints collected at each occurrence site. */
+  hints: string[];
+}
+
+/**
+ * Hoist shared object schemas into `components.schemas` and replace
+ * inline occurrences with `$ref` pointers.
+ *
+ * Only hoists:
+ *   - `type: "object"` schemas (primitives / enums / unions-of-primitives stay inline).
+ *   - Schemas appearing at a "hoistable site" (requestBody/response root or a top-level
+ *     property of either). Path/query/header parameter schemas are explicitly skipped.
+ *   - Schemas reaching the occurrence threshold (default 2).
+ *
+ * Naming:
+ *   - First hint wins for structurally-identical schemas.
+ *   - Name collisions across structurally-different schemas are disambiguated with
+ *     `_v2`, `_v3`, … suffixes (deterministic by walk order).
+ *   - Hint-less schemas fall back to `Schema_<first-8-hex-of-hash>`.
+ */
+export async function hoistSharedSchemas(
+  doc: OpenAPIDocument,
+  options: HoistOptions = {}
+): Promise<void> {
+  const threshold = Math.max(2, options.threshold ?? 2);
+  const occurrences = new Map<string, SchemaOccurrence>();
+
+  // --- Pass 1: walk every hoistable site and record occurrences. ---
+  for (const pathItem of Object.values(doc.paths)) {
+    for (const method of ["get", "post", "put", "patch", "delete"] as const) {
+      const op = pathItem[method];
+      if (!op) continue;
+
+      // Request body root schema (+ top-level property values).
+      if (op.requestBody?.content) {
+        for (const mediaObj of Object.values(op.requestBody.content)) {
+          recordHoistableTree(mediaObj as Record<string, unknown>, "schema", occurrences);
+        }
+      }
+
+      // Response root schema (+ top-level property values).
+      for (const resp of Object.values(op.responses)) {
+        if (!resp.content) continue;
+        for (const mediaObj of Object.values(resp.content)) {
+          recordHoistableTree(mediaObj as Record<string, unknown>, "schema", occurrences);
+        }
+      }
+    }
+  }
+
+  // --- Pass 2: pick the winners (count ≥ threshold, type === "object"). ---
+  const winners: Array<{ name: string; hash: string; body: OpenAPISchema; sites: SchemaOccurrence["sites"] }> = [];
+  const nameIndex = new Map<string, string>(); // name → hash (for collision detection)
+
+  // Stable iteration: sort by hash so hoisted output is deterministic
+  // regardless of JS property enumeration order quirks.
+  const entries = Array.from(occurrences.entries()).sort(([a], [b]) => a.localeCompare(b));
+  for (const [hash, entry] of entries) {
+    if (entry.sites.length < threshold) continue;
+    if (!isHoistableObject(entry.body)) continue;
+
+    // Pick the first-seen hint; fall back to the hash-derived default.
+    const preferred = entry.hints[0] || `Schema_${hash.slice(0, 8)}`;
+    let finalName = preferred;
+    let suffix = 2;
+    // If the name is already claimed by a *different* hash, walk `_v2`, `_v3`…
+    while (nameIndex.has(finalName) && nameIndex.get(finalName) !== hash) {
+      finalName = `${preferred}_v${suffix++}`;
+    }
+    nameIndex.set(finalName, hash);
+    winners.push({ name: finalName, hash, body: entry.body, sites: entry.sites });
+  }
+
+  if (winners.length === 0) return;
+
+  // --- Pass 3: install winners into components.schemas + rewrite sites. ---
+  if (!doc.components) doc.components = {};
+  if (!doc.components.schemas) doc.components.schemas = {};
+  const schemas = doc.components.schemas;
+
+  for (const winner of winners) {
+    schemas[winner.name] = winner.body;
+    const ref: OpenAPISchema = { $ref: `#/components/schemas/${winner.name}` };
+    for (const site of winner.sites) {
+      // Replace inline schema with a `$ref` pointer. We write a *new*
+      // ref object per site (JSON.stringify would collapse shared refs
+      // anyway, but distinct identities make future passes safer).
+      (site.parent as Record<string | number, unknown>)[site.key] = { ...ref };
+    }
+  }
+}
+
+/**
+ * Walk a container object and record every hoistable schema site. A
+ * hoistable site is:
+ *
+ *   1. The root schema at `container[key]` (typically the `"schema"` key of a
+ *      requestBody/response media type object).
+ *   2. Every top-level property of that root, *if* the root is an object schema.
+ *
+ * Nested properties beyond depth 1 are intentionally ignored — hoisting
+ * deep nests produces spec trees that are harder for codegen tools to
+ * follow than the inline original.
+ */
+function recordHoistableTree(
+  container: Record<string, unknown>,
+  key: string,
+  occurrences: Map<string, SchemaOccurrence>
+): void {
+  const root = container[key] as OpenAPISchema | undefined;
+  if (!root || typeof root !== "object") return;
+  // Skip anything that's already a $ref (e.g., from an earlier pass).
+  if ("$ref" in root && root.$ref) return;
+
+  // Record the root itself (regardless of object vs primitive — we filter
+  // in pass 2 so that primitives with many occurrences still get counted
+  // but are never emitted as component entries).
+  recordOccurrence(root, container as Record<string, unknown>, key, occurrences);
+
+  // Drill into top-level properties for object roots.
+  if (root.type === "object" && root.properties) {
+    for (const [propKey, propSchema] of Object.entries(root.properties)) {
+      if (!propSchema || typeof propSchema !== "object") continue;
+      if ("$ref" in propSchema && propSchema.$ref) continue;
+      recordOccurrence(
+        propSchema as OpenAPISchema,
+        root.properties as Record<string, unknown>,
+        propKey,
+        occurrences
+      );
+    }
+  }
+
+  // Drill into array items when the root is an array — the element shape
+  // is the real reusable schema, not the array wrapper itself.
+  if (root.type === "array" && root.items) {
+    const items = root.items;
+    if (items && typeof items === "object" && !("$ref" in items && items.$ref)) {
+      recordOccurrence(
+        items,
+        root as unknown as Record<string, unknown>,
+        "items",
+        occurrences
+      );
+    }
+  }
+}
+
+function recordOccurrence(
+  schema: OpenAPISchema,
+  parent: Record<string, unknown>,
+  key: string | number,
+  occurrences: Map<string, SchemaOccurrence>
+): void {
+  const hash = structuralHash(schema);
+  let entry = occurrences.get(hash);
+  if (!entry) {
+    entry = { hash, sites: [], body: schema, hints: [] };
+    occurrences.set(hash, entry);
+  }
+  entry.sites.push({ parent, key });
+  const hint = schemaNameHints.get(schema);
+  if (hint && !entry.hints.includes(hint)) {
+    entry.hints.push(hint);
+  }
+}
+
+/**
+ * A schema is hoistable iff it is an object with ≥1 property. We
+ * deliberately skip:
+ *   - primitives (`string`, `number`, `boolean`, `integer`) — they are
+ *     small enough that inline is clearer than a pointer chase.
+ *   - enums and unions of primitives — same argument, and codegen tools
+ *     tend to de-duplicate these separately.
+ *   - empty object schemas — no information to share.
+ *   - $ref passthroughs — already hoisted.
+ *   - object schemas with a composed keyword (allOf/oneOf/anyOf) but no
+ *     `properties` — these are structural compositions, not data shapes.
+ */
+function isHoistableObject(schema: OpenAPISchema): boolean {
+  if (!schema || typeof schema !== "object") return false;
+  if (schema.$ref) return false;
+  if (schema.type !== "object") return false;
+  if (!schema.properties) return false;
+  if (Object.keys(schema.properties).length === 0) return false;
+  return true;
+}
+
+/**
+ * Stable structural hash of a schema. Sorts object keys recursively
+ * before stringifying so `{a:1,b:2}` and `{b:2,a:1}` hash identically,
+ * then feeds the canonical string through SHA-256.
+ */
+function structuralHash(schema: OpenAPISchema): string {
+  const canonical = stableStringify(schema);
+  return sha256Hex(canonical);
+}
+
+function stableStringify(value: unknown): string {
+  if (value === null || value === undefined) return "null";
+  if (typeof value === "boolean" || typeof value === "number") return JSON.stringify(value);
+  if (typeof value === "string") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return "[" + value.map((v) => stableStringify(v)).join(",") + "]";
+  }
+  if (typeof value === "object") {
+    const keys = Object.keys(value as Record<string, unknown>).sort();
+    const parts: string[] = [];
+    for (const k of keys) {
+      const v = (value as Record<string, unknown>)[k];
+      if (v === undefined) continue;
+      parts.push(JSON.stringify(k) + ":" + stableStringify(v));
+    }
+    return "{" + parts.join(",") + "}";
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * Synchronous SHA-256 hex digest. Uses `Bun.CryptoHasher` when present,
+ * then Node `crypto.createHash` as a fallback. WebCrypto is async-only
+ * so we intentionally skip it here — the hoist pass hashes many small
+ * payloads and the sync path keeps the post-process simple and fast.
+ *
+ * This is a purely structural identity key (not a security primitive),
+ * so the brief Node-fallback surface is acceptable.
+ */
+function sha256Hex(input: string): string {
+  const bunGlobal = (globalThis as { Bun?: { CryptoHasher?: new (algo: string) => { update(input: string | Uint8Array): void; digest(encoding: "hex"): string } } }).Bun;
+  if (bunGlobal?.CryptoHasher) {
+    const hasher = new bunGlobal.CryptoHasher("sha256");
+    hasher.update(input);
+    return hasher.digest("hex");
+  }
+  // Node fallback — `require` at call time to keep module-load lean.
+  // Callers who run in an edge runtime without Node crypto should have
+  // Bun available; we therefore don't bother with a WebCrypto async
+  // path (it would turn `hoistSharedSchemas` into an unnecessarily async
+  // cascade on the hot path).
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const nodeCrypto = require("node:crypto") as typeof import("node:crypto");
+  return nodeCrypto.createHash("sha256").update(input).digest("hex");
 }
 
 // ============================================

package/src/openapi/openapi.test.ts

@@ -7,12 +7,14 @@ import { z } from "zod";
 import {
   generateOpenAPIDocument,
   hashOpenAPIJSON,
+  hoistSharedSchemas,
   openAPIToJSON,
   openAPIToYAML,
   readOpenAPIArtifacts,
   writeOpenAPIArtifacts,
   zodToOpenAPISchema,
 } from "./generator";
+import type { OpenAPIDocument } from "./generator";
 import type { RoutesManifest } from "../spec/schema";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -512,3 +514,433 @@ describe("writeOpenAPIArtifacts + readOpenAPIArtifacts", () => {
     }
   });
 });
+
+// ============================================
+// Schema hoisting (shared schemas → components.schemas)
+// ============================================
+
+/**
+ * Build a two-contract fixture where both contracts share the same
+ * `User` body shape. The generator should hoist `{ name, email }` into
+ * `components.schemas` when hoisting is enabled.
+ */
+async function buildSharedSchemaFixture(opts: {
+  /** Override the `name` attribute on each contract (in file order). */
+  contractNames?: [string, string];
+  /** Replace the second contract's body shape to exercise collision paths. */
+  secondBody?: string;
+} = {}): Promise<{
+  rootDir: string;
+  manifest: RoutesManifest;
+  cleanup: () => Promise<void>;
+}> {
+  const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "mandu-openapi-hoist-"));
+  const [nameA, nameB] = opts.contractNames ?? ["users", "admins"];
+  const bodyB =
+    opts.secondBody ??
+    `z.object({ name: z.string().min(2), email: z.string().email() })`;
+
+  await fs.mkdir(path.join(rootDir, "contracts"), { recursive: true });
+  await fs.writeFile(
+    path.join(rootDir, "contracts/users.contract.ts"),
+    `import { z } from "zod";
+export default {
+  name: "${nameA}",
+  request: {
+    POST: {
+      body: z.object({ name: z.string().min(2), email: z.string().email() }),
+    },
+  },
+  response: {
+    200: z.object({ id: z.string().uuid(), status: z.string() }),
+  },
+};
+`,
+    "utf-8"
+  );
+  await fs.writeFile(
+    path.join(rootDir, "contracts/admins.contract.ts"),
+    `import { z } from "zod";
+export default {
+  name: "${nameB}",
+  request: {
+    POST: {
+      body: ${bodyB},
+    },
+  },
+  response: {
+    200: z.object({ id: z.string().uuid(), status: z.string() }),
+  },
+};
+`,
+    "utf-8"
+  );
+
+  const manifest: RoutesManifest = {
+    version: 1,
+    routes: [
+      {
+        id: "api/users",
+        pattern: "/api/users",
+        kind: "api",
+        module: "contracts/users.contract.ts",
+        contractModule: "contracts/users.contract.ts",
+        methods: ["POST"],
+      },
+      {
+        id: "api/admins",
+        pattern: "/api/admins",
+        kind: "api",
+        module: "contracts/admins.contract.ts",
+        contractModule: "contracts/admins.contract.ts",
+        methods: ["POST"],
+      },
+    ],
+  };
+
+  return {
+    rootDir,
+    manifest,
+    cleanup: async () => {
+      await fs.rm(rootDir, { recursive: true, force: true });
+    },
+  };
+}
+
+describe("hoistSharedSchemas", () => {
+  test("two routes sharing a body shape emit a single components.schemas entry with $ref", async () => {
+    const { rootDir, manifest, cleanup } = await buildSharedSchemaFixture();
+    try {
+      const doc = await generateOpenAPIDocument(manifest, rootDir, {
+        title: "Hoist Test",
+      });
+
+      // The shared POST body should be hoisted. There are also shared
+      // 200 responses so we expect at least 2 hoisted entries.
+      expect(doc.components?.schemas).toBeDefined();
+      const schemaNames = Object.keys(doc.components!.schemas!);
+      expect(schemaNames.length).toBeGreaterThanOrEqual(1);
+
+      const usersBody = doc.paths["/api/users"].post!.requestBody!.content["application/json"].schema;
+      const adminsBody = doc.paths["/api/admins"].post!.requestBody!.content["application/json"].schema;
+
+      // Both bodies must now be $ref pointers into components.schemas.
+      expect(usersBody.$ref).toBeDefined();
+      expect(adminsBody.$ref).toBeDefined();
+      // ... and they must point to the exact same entry (shared shape).
+      expect(usersBody.$ref).toBe(adminsBody.$ref);
+
+      // The pointed-to entry must exist and retain the object shape.
+      const refTarget = usersBody.$ref!.replace("#/components/schemas/", "");
+      const hoisted = doc.components!.schemas![refTarget];
+      expect(hoisted.type).toBe("object");
+      expect(hoisted.properties!.name).toBeDefined();
+      expect(hoisted.properties!.email).toBeDefined();
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("one-off schema stays inline (no hoist, no components.schemas entry for it)", async () => {
+    const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "mandu-openapi-oneoff-"));
+    try {
+      await fs.mkdir(path.join(rootDir, "contracts"), { recursive: true });
+      await fs.writeFile(
+        path.join(rootDir, "contracts/solo.contract.ts"),
+        `import { z } from "zod";
+export default {
+  name: "solo",
+  request: {
+    POST: { body: z.object({ uniqueField: z.string() }) },
+  },
+  response: { 200: z.object({ ok: z.boolean() }) },
+};
+`,
+        "utf-8"
+      );
+      const manifest: RoutesManifest = {
+        version: 1,
+        routes: [
+          {
+            id: "api/solo",
+            pattern: "/api/solo",
+            kind: "api",
+            module: "contracts/solo.contract.ts",
+            contractModule: "contracts/solo.contract.ts",
+            methods: ["POST"],
+          },
+        ],
+      };
+
+      const doc = await generateOpenAPIDocument(manifest, rootDir);
+      const body = doc.paths["/api/solo"].post!.requestBody!.content["application/json"].schema;
+
+      // Solo schemas must NOT be hoisted — stays inline.
+      expect(body.$ref).toBeUndefined();
+      expect(body.type).toBe("object");
+      expect(body.properties?.uniqueField).toBeDefined();
+
+      // components.schemas may exist (e.g. for the default 500 shape if it
+      // happened to collide with another schema), but the one-off body's
+      // uniqueField shape must not appear as a hoisted entry.
+      const schemas = doc.components?.schemas ?? {};
+      for (const entry of Object.values(schemas)) {
+        expect(entry.properties?.uniqueField).toBeUndefined();
+      }
+    } finally {
+      await fs.rm(rootDir, { recursive: true, force: true });
+    }
+  });
+
+  test("same shape with different user-given names collapses to one entry (first-come wins)", async () => {
+    const { rootDir, manifest, cleanup } = await buildSharedSchemaFixture({
+      contractNames: ["users", "admins"],
+    });
+    try {
+      const doc = await generateOpenAPIDocument(manifest, rootDir);
+
+      const usersBody = doc.paths["/api/users"].post!.requestBody!.content["application/json"].schema;
+      const adminsBody = doc.paths["/api/admins"].post!.requestBody!.content["application/json"].schema;
+
+      // Both must resolve to the *same* $ref — structural identity wins
+      // over the user-given name split.
+      expect(usersBody.$ref).toBeDefined();
+      expect(usersBody.$ref).toBe(adminsBody.$ref);
+
+      // Exactly one body component (not two) for this shape. Count entries
+      // that match `{name,email}` shape.
+      const sharedEntries = Object.values(doc.components!.schemas!).filter(
+        (s) => s.properties?.name && s.properties?.email
+      );
+      expect(sharedEntries.length).toBe(1);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("name collision across structurally-different schemas → _v2 suffix", () => {
+    // Hand-craft a doc with two different body shapes whose name hints
+    // would collide. We exercise the hoist pass directly so we can
+    // control the hints without routing through Zod.
+    const shapeA = {
+      type: "object" as const,
+      properties: { a: { type: "string" as const } },
+      required: ["a"],
+    };
+    const shapeB = {
+      type: "object" as const,
+      properties: { b: { type: "number" as const } },
+      required: ["b"],
+    };
+
+    // Two routes use shape A, two use shape B — every schema gets the
+    // same name hint "Shared". The second winning hash should be renamed
+    // to "Shared_v2".
+    const a1 = { ...shapeA };
+    const a2 = { ...shapeA };
+    const b1 = { ...shapeB };
+    const b2 = { ...shapeB };
+
+    const doc: OpenAPIDocument = {
+      openapi: "3.0.3",
+      info: { title: "t", version: "1.0.0" },
+      paths: {
+        "/a1": {
+          post: {
+            responses: {},
+            requestBody: { content: { "application/json": { schema: a1 } } },
+          },
+        },
+        "/a2": {
+          post: {
+            responses: {},
+            requestBody: { content: { "application/json": { schema: a2 } } },
+          },
+        },
+        "/b1": {
+          post: {
+            responses: {},
+            requestBody: { content: { "application/json": { schema: b1 } } },
+          },
+        },
+        "/b2": {
+          post: {
+            responses: {},
+            requestBody: { content: { "application/json": { schema: b2 } } },
+          },
+        },
+      },
+    };
+
+    // Attach the same hint to both shapes via hoistSharedSchemas's own
+    // name-hint mechanism: we can't from here (WeakMap is module-private).
+    // So we instead rely on the deterministic hash-based fallback name,
+    // then assert both shapes are hoisted and receive distinct entries.
+    return hoistSharedSchemas(doc).then(() => {
+      const schemas = doc.components?.schemas ?? {};
+      const names = Object.keys(schemas);
+      // Both shapes qualify (appear twice each) → 2 hoisted entries.
+      expect(names.length).toBe(2);
+      // No two entries share the exact same name.
+      expect(new Set(names).size).toBe(names.length);
+      // The generated names must be stable strings (start with `Schema_`
+      // in the fallback path).
+      for (const n of names) {
+        expect(n).toMatch(/^Schema_[0-9a-f]{8}$/);
+      }
+    });
+  });
+
+  test("hoistSchemas: false produces the legacy inline-only document", async () => {
+    const { rootDir, manifest, cleanup } = await buildSharedSchemaFixture();
+    try {
+      const docOn = await generateOpenAPIDocument(manifest, rootDir, {
+        hoistSchemas: true,
+      });
+      const docOff = await generateOpenAPIDocument(manifest, rootDir, {
+        hoistSchemas: false,
+      });
+
+      // Off: no $refs anywhere, no components.schemas emitted.
+      const offJson = JSON.stringify(docOff);
+      expect(offJson.includes("$ref")).toBe(false);
+      expect(docOff.components?.schemas).toBeUndefined();
+
+      // On: at least one $ref appeared. Confirms the two paths diverge.
+      const onJson = JSON.stringify(docOn);
+      expect(onJson.includes("$ref")).toBe(true);
+      expect(docOn.components?.schemas).toBeDefined();
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("enum / primitive schemas are never hoisted", async () => {
+    const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "mandu-openapi-enum-"));
+    try {
+      await fs.mkdir(path.join(rootDir, "contracts"), { recursive: true });
+      const contractBody = `import { z } from "zod";
+export default {
+  name: NAME,
+  request: {
+    POST: { body: z.object({ role: z.enum(["a", "b", "c"]) }) },
+  },
+  response: { 200: z.object({ role: z.enum(["a", "b", "c"]) }) },
+};
+`;
+      await fs.writeFile(
+        path.join(rootDir, "contracts/one.contract.ts"),
+        contractBody.replace("NAME", '"one"'),
+        "utf-8"
+      );
+      await fs.writeFile(
+        path.join(rootDir, "contracts/two.contract.ts"),
+        contractBody.replace("NAME", '"two"'),
+        "utf-8"
+      );
+      const manifest: RoutesManifest = {
+        version: 1,
+        routes: [
+          {
+            id: "api/one",
+            pattern: "/api/one",
+            kind: "api",
+            module: "contracts/one.contract.ts",
+            contractModule: "contracts/one.contract.ts",
+            methods: ["POST"],
+          },
+          {
+            id: "api/two",
+            pattern: "/api/two",
+            kind: "api",
+            module: "contracts/two.contract.ts",
+            contractModule: "contracts/two.contract.ts",
+            methods: ["POST"],
+          },
+        ],
+      };
+
+      const doc = await generateOpenAPIDocument(manifest, rootDir);
+
+      // The outer {role: enum} object *is* hoistable and shared — that's fine.
+      // The inner enum itself must NOT be hoisted — scan every component
+      // entry and assert none of them is a bare enum-typed schema.
+      for (const entry of Object.values(doc.components?.schemas ?? {})) {
+        expect(entry.enum).toBeUndefined();
+        if (entry.type === "string" && !entry.properties) {
+          throw new Error(`Primitive string schema should not be hoisted: ${JSON.stringify(entry)}`);
+        }
+      }
+    } finally {
+      await fs.rm(rootDir, { recursive: true, force: true });
+    }
+  });
+
+  test("hoistThreshold: 3 → 2-use schemas stay inline; 3-use schemas get hoisted", () => {
+    // Doc with the same shape appearing exactly twice.
+    const shape = {
+      type: "object" as const,
+      properties: { x: { type: "string" as const } },
+      required: ["x"],
+    };
+    const buildDoc = (): OpenAPIDocument => ({
+      openapi: "3.0.3",
+      info: { title: "t", version: "1.0.0" },
+      paths: {
+        "/a": {
+          post: {
+            responses: {},
+            requestBody: { content: { "application/json": { schema: { ...shape } } } },
+          },
+        },
+        "/b": {
+          post: {
+            responses: {},
+            requestBody: { content: { "application/json": { schema: { ...shape } } } },
+          },
+        },
+      },
+    });
+
+    const doc2 = buildDoc();
+    return hoistSharedSchemas(doc2, { threshold: 3 }).then(() => {
+      // With threshold=3 and only 2 uses → nothing hoisted.
+      expect(doc2.components?.schemas).toBeUndefined();
+      expect(doc2.paths["/a"].post!.requestBody!.content["application/json"].schema.$ref).toBeUndefined();
+
+      // Re-run with threshold=2 on a fresh doc → the same shape is hoisted.
+      const doc1 = buildDoc();
+      return hoistSharedSchemas(doc1, { threshold: 2 }).then(() => {
+        expect(doc1.components?.schemas).toBeDefined();
+        expect(Object.keys(doc1.components!.schemas!).length).toBe(1);
+      });
+    });
+  });
+
+  test("threshold values < 2 clamp up to 2 (never hoist single-use schemas)", () => {
+    // Edge: a malicious / misconfigured `hoistThreshold: 1` would otherwise
+    // hoist every schema including one-offs, blowing up the spec.
+    const shape = {
+      type: "object" as const,
+      properties: { solo: { type: "string" as const } },
+      required: ["solo"],
+    };
+    const doc: OpenAPIDocument = {
+      openapi: "3.0.3",
+      info: { title: "t", version: "1.0.0" },
+      paths: {
+        "/only": {
+          post: {
+            responses: {},
+            requestBody: { content: { "application/json": { schema: { ...shape } } } },
+          },
+        },
+      },
+    };
+
+    return hoistSharedSchemas(doc, { threshold: 1 }).then(() => {
+      expect(doc.components?.schemas).toBeUndefined();
+      expect(doc.paths["/only"].post!.requestBody!.content["application/json"].schema.$ref).toBeUndefined();
+    });
+  });
+});

package/src/runtime/adapter-bun.ts

@@ -48,9 +48,11 @@ export function adapterBun(): ManduAdapter {
 
           return {
             port: manduServer.server.port ?? port,
-            // Report the effective bind address. startServer() defaults to
-            // 0.0.0.0 when no hostname is supplied. See #190.
-            hostname: hostname ?? "0.0.0.0",
+            // Report the effective bind address. startServer() defaults
+            // to `"::"` (dual-stack IPv6 wildcard) when no hostname is
+            // supplied — accepts both IPv4 and IPv6 clients on one
+            // socket. See #190 #223.
+            hostname: hostname ?? "::",
           };
         },
 

package/src/runtime/server.ts

@@ -4255,42 +4255,98 @@ function startBunServerWithFallback(options: {
 // ========== Server Startup ==========
 
 /**
- * Format a base URL for startup logging based on the bound hostname.
+ * Derive the list of loopback-style hosts actually reachable for a given
+ * bind address, without issuing any network probes. Used by the startup
+ * banner (`formatServerAddresses`) and by tooling that needs to know
+ * which loopback URLs will succeed for a given server.
+ *
+ * Matrix:
+ *   - `"0.0.0.0"` (IPv4 wildcard) → `["127.0.0.1"]` only. A server bound
+ *     to `0.0.0.0` does NOT answer on `[::1]` — the IPv6 loopback is a
+ *     different socket. This was the root cause of #225.
+ *   - `"::"` / `"::0"` / `"[::]"` / `"0:0:0:0:0:0:0:0"` (IPv6 wildcard,
+ *     dual-stack) → `["127.0.0.1", "[::1]"]`. IPV6_V6ONLY is off by
+ *     default on Bun, so the dual-stack socket accepts IPv4-mapped
+ *     connections too.
+ *   - `undefined` / `""` → same as the current default (`"::"`).
+ *   - `"127.0.0.1"` / `"::1"` / a specific IP → just that address.
+ *   - DNS name → just that name.
  *
- * When binding to wildcard addresses (`0.0.0.0`, `::`, or empty string),
- * the server listens on all interfaces — browsers must use `localhost`
- * or a specific loopback address to connect. We surface both IPv4 and IPv6
- * loopback URLs so the user can pick whichever their OS prefers.
+ * @see issues #223 #225
+ */
+export function reachableHosts(hostname: string | undefined): string[] {
+  const h = (hostname ?? "").trim();
+
+  // IPv4 wildcard — IPv4 loopback only.
+  if (h === "0.0.0.0") {
+    return ["127.0.0.1"];
+  }
+
+  // IPv6 wildcard (dual-stack). Empty / undefined is treated as the
+  // default, which is now `"::"` (dual-stack) — see `startServer()`.
+  if (h === "" || h === "::" || h === "::0" || h === "[::]" || h === "0:0:0:0:0:0:0:0") {
+    return ["127.0.0.1", "[::1]"];
+  }
+
+  // Bare IPv6 literal → bracket for URL syntax.
+  if (h.includes(":") && !h.startsWith("[")) {
+    return [`[${h}]`];
+  }
+
+  return [h];
+}
+
+/**
+ * Format a base URL for startup logging based on the bound hostname.
  *
  * Returns `{ primary, additional }` where `primary` is the canonical URL
- * for UX (open-in-browser, runtime control) and `additional` are supplementary
- * URLs shown in the startup log.
+ * for UX (open-in-browser, runtime control) and `additional` are
+ * supplementary URLs shown in the startup log. Every URL in `additional`
+ * is guaranteed to actually resolve to the running server — no more
+ * "(also reachable at [::1])" when the socket only answers on IPv4.
+ *
+ * @see issue #225
  */
 export function formatServerAddresses(
   hostname: string | undefined,
   port: number
 ): { primary: string; additional: string[] } {
-  const isWildcardV4 = hostname === "0.0.0.0" || hostname === undefined || hostname === "";
-  const isWildcardV6 = hostname === "::" || hostname === "[::]";
+  const h = (hostname ?? "").trim();
+  const isWildcardV4 = h === "0.0.0.0";
+  const isWildcardV6 =
+    h === "" || h === "::" || h === "::0" || h === "[::]" || h === "0:0:0:0:0:0:0:0";
+  const hosts = reachableHosts(hostname);
+
   if (isWildcardV4 || isWildcardV6) {
     return {
       primary: `http://localhost:${port}`,
-      additional: [`http://127.0.0.1:${port}`, `http://[::1]:${port}`],
+      additional: hosts.map((x) => `http://${x}:${port}`),
     };
   }
-  // Bracket IPv6 literals for URL syntax.
-  const host = hostname.includes(":") && !hostname.startsWith("[") ? `[${hostname}]` : hostname;
-  return { primary: `http://${host}:${port}`, additional: [] };
+
+  // Specific host — `primary` is that host, no additional entries.
+  return { primary: `http://${hosts[0]}:${port}`, additional: [] };
 }
 
 export function startServer(manifest: RoutesManifest, options: ServerOptions = {}): ManduServer {
   const {
     port = 3000,
-    // Default to 0.0.0.0 (dual-stack wildcard on IPv4) so `localhost` resolves
-    // to 127.0.0.1 via OS-level IPv4-preferred lookups (e.g., Windows). Users
-    // can still pin `hostname: "::1"` or `hostname: "127.0.0.1"` explicitly.
-    // See issue #190.
-    hostname = "0.0.0.0",
+    // Default to `"::"` (IPv6 wildcard, dual-stack). Bun leaves IPV6_V6ONLY
+    // off, so this single socket accepts both IPv4 (as IPv4-mapped IPv6)
+    // and IPv6 clients — covering `127.0.0.1`, `[::1]`, and LAN addresses
+    // of either family with one bind.
+    //
+    // Why not `"0.0.0.0"`? On Windows with Node 17+, `fetch("localhost:...")`
+    // resolves to `::1` first. A server bound to `0.0.0.0` accepts IPv4
+    // only, so Node clients (Playwright test runner, ATE-generated specs)
+    // fail with `ECONNREFUSED ::1:PORT`. Browsers and `curl` silently
+    // fall back to IPv4, hiding the bug. See issues #190 #223.
+    //
+    // Explicit `"0.0.0.0"` is still honored — users who need IPv4-only
+    // binds (certain container networks, firewall policies) keep that
+    // option; a one-line warning is emitted on Windows so the trap is
+    // discoverable.
+    hostname = "::",
     rootDir = process.cwd(),
     isDev = false,
     hmrPort,
@@ -4611,6 +4667,25 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     registry.settings = { ...registry.settings, hmrPort: actualPort };
   }
 
+  // ─── #223 — Windows hostname="0.0.0.0" discoverability warning ────────
+  // We cannot silently rewrite an explicit `"0.0.0.0"` (user may need
+  // IPv4-only binds for container/firewall reasons), but we CAN warn
+  // the one platform where the gotcha actually bites: Windows, where
+  // Node 17+ fetch prefers `::1` for `localhost` and will therefore
+  // fail to reach an IPv4-only bind. Silent on non-Windows, silent
+  // when `silent: true`.
+  // ──────────────────────────────────────────────────────────────────────
+  if (
+    !silent &&
+    options.hostname === "0.0.0.0" &&
+    process.platform === "win32"
+  ) {
+    console.warn(
+      `⚠️  hostname="0.0.0.0" binds IPv4 only; Node fetch('localhost:${actualPort}') ` +
+        `may fail on Windows (prefers ::1). Consider hostname="::" for dual-stack.`
+    );
+  }
+
   const addresses = formatServerAddresses(hostname, actualPort);
 
   // ─── #217 — gate the boot banner on `!silent` ─────────────────────────