@ontrails/schema 1.0.0-beta.6 → 1.0.0-beta.8

package/.turbo/turbo-lint.log

@@ -1,3 +1,3 @@
 $ oxlint ./src
 Found 0 warnings and 0 errors.
-Finished in 19ms on 10 files with 93 rules using 24 threads.
+Finished in 30ms on 12 files with 93 rules using 24 threads.

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @ontrails/schema
 
+## 1.0.0-beta.8
+
+### Patch Changes
+
+- Restructure HTTP package and fix Codex review findings.
+
+  **http**: BREAKING — `blaze()` moved to `@ontrails/http/hono` subpath. Hono is now a peer dependency. `buildHttpRoutes()` is framework-agnostic. Fixed: malformed JSON → 400, execute() never throws, query parsing preserves raw strings and supports arrays.
+
+  **schema**: OpenAPI 200 response wraps in `{ data }` envelope matching wire format. Always includes 400 ValidationError with error schema. basePath trailing slash normalized.
+
+  - @ontrails/core@1.0.0-beta.8
+
+## 1.0.0-beta.7
+
+### Minor Changes
+
+- HTTP surface and OpenAPI generation.
+
+  **http**: New `@ontrails/http` package — Hono-based HTTP adapter. `blaze()` derives routes from trail IDs, maps intent to HTTP verbs (read→GET, write→POST, destroy→DELETE), and maps error taxonomy to status codes. Returns the Hono instance.
+
+  **schema**: Add `generateOpenApiSpec(topo)` — generates a complete OpenAPI 3.1 spec from the topo. Each trail becomes an operation with path, method, schemas, and error responses derived from the contract.
+
+  **trails**: `trails survey --openapi` outputs the OpenAPI spec for any Trails app.
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.7
+
 ## 1.0.0-beta.6
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { generateSurfaceMap } from './generate.js';
 export { hashSurfaceMap } from './hash.js';
 export { diffSurfaceMaps } from './diff.js';
+export { generateOpenApiSpec } from './openapi.js';
+export type { OpenApiOptions, OpenApiSpec, OpenApiServer } from './openapi.js';
 export { writeSurfaceMap, readSurfaceMap, writeSurfaceLock, readSurfaceLock, } from './io.js';
 export type { SurfaceMap, SurfaceMapEntry, DiffEntry, DiffResult, JsonSchema, WriteOptions, ReadOptions, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAG5C,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,eAAe,GAChB,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,UAAU,EACV,eAAe,EACf,SAAS,EACT,UAAU,EACV,UAAU,EACV,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAG5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG/E,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,eAAe,GAChB,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,UAAU,EACV,eAAe,EACf,SAAS,EACT,UAAU,EACV,UAAU,EACV,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -2,6 +2,8 @@
 export { generateSurfaceMap } from './generate.js';
 export { hashSurfaceMap } from './hash.js';
 export { diffSurfaceMaps } from './diff.js';
+// OpenAPI
+export { generateOpenApiSpec } from './openapi.js';
 // File I/O
 export { writeSurfaceMap, readSurfaceMap, writeSurfaceLock, readSurfaceLock, } from './io.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,WAAW;AACX,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,eAAe,GAChB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,UAAU;AACV,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGnD,WAAW;AACX,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,eAAe,GAChB,MAAM,SAAS,CAAC"}

package/dist/openapi.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Generate an OpenAPI 3.1 specification from a Topo.
+ *
+ * Converts each trail into an HTTP operation, deriving paths, methods,
+ * parameters, and response schemas from the trail contract.
+ */
+import type { Topo } from '@ontrails/core';
+export interface OpenApiServer {
+    readonly url: string;
+    readonly description?: string | undefined;
+}
+export interface OpenApiOptions {
+    /** Default: `app.name` */
+    readonly title?: string | undefined;
+    /** Default: `'1.0.0'` */
+    readonly version?: string | undefined;
+    readonly description?: string | undefined;
+    readonly servers?: readonly OpenApiServer[] | undefined;
+    /** Prefix for all paths. Default: `''` */
+    readonly basePath?: string | undefined;
+}
+/** Minimal OpenAPI 3.1 spec shape — intentionally plain objects, no heavy library. */
+export interface OpenApiSpec {
+    readonly openapi: '3.1.0';
+    readonly info: {
+        readonly title: string;
+        readonly version: string;
+        readonly description?: string | undefined;
+    };
+    readonly servers?: readonly OpenApiServer[] | undefined;
+    readonly paths: Record<string, Record<string, unknown>>;
+    readonly components: {
+        readonly schemas: Record<string, unknown>;
+    };
+}
+/**
+ * Generate an OpenAPI 3.1 specification from a Topo.
+ *
+ * Iterates all trails, skipping events and internal trails, and produces
+ * paths, operations, parameters, and response schemas derived from
+ * the trail contract.
+ */
+export declare const generateOpenApiSpec: (app: Topo, options?: OpenApiOptions) => OpenApiSpec;
+//# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAS,MAAM,gBAAgB,CAAC;AAQlD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED,MAAM,WAAW,cAAc;IAC7B,0BAA0B;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,yBAAyB;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,CAAC;IACxD,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAED,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC3C,CAAC;IACF,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;CACpE;AAuQD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAC9B,KAAK,IAAI,EACT,UAAU,cAAc,KACvB,WAQD,CAAC"}

package/dist/openapi.js

@@ -0,0 +1,219 @@
+/**
+ * Generate an OpenAPI 3.1 specification from a Topo.
+ *
+ * Converts each trail into an HTTP operation, deriving paths, methods,
+ * parameters, and response schemas from the trail contract.
+ */
+import { statusCodeMap, zodToJsonSchema } from '@ontrails/core';
+// ---------------------------------------------------------------------------
+// Error name → category lookup
+// ---------------------------------------------------------------------------
+const errorNameToCategory = {
+    AlreadyExistsError: 'conflict',
+    AmbiguousError: 'validation',
+    AssertionError: 'internal',
+    AuthError: 'auth',
+    CancelledError: 'cancelled',
+    ConflictError: 'conflict',
+    InternalError: 'internal',
+    NetworkError: 'network',
+    NotFoundError: 'not_found',
+    PermissionError: 'permission',
+    RateLimitError: 'rate_limit',
+    TimeoutError: 'timeout',
+    ValidationError: 'validation',
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const intentToMethod = {
+    destroy: 'delete',
+    read: 'get',
+    write: 'post',
+};
+/** `entity.show` → `/entity/show` */
+const trailIdToPath = (id, basePath) => `${basePath}/${id.split('.').join('/')}`;
+/** First segment of a dotted ID, used as an OpenAPI tag. */
+const tagFromId = (id) => id.split('.')[0] ?? id;
+/** Convert a Zod schema to JSON Schema via the core helper. */
+const toJsonSchema = (schema) => 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+zodToJsonSchema(schema);
+/** Build query parameters from a JSON Schema `properties` object. */
+const buildQueryParameters = (jsonSchema) => {
+    const properties = jsonSchema['properties'];
+    if (!properties) {
+        return [];
+    }
+    const required = new Set(Array.isArray(jsonSchema['required'])
+        ? jsonSchema['required']
+        : []);
+    return Object.entries(properties).map(([name, schema]) => ({
+        in: 'query',
+        name,
+        required: required.has(name),
+        schema,
+    }));
+};
+/** Map a single error example to a status code entry, or undefined if not mappable. */
+const errorExampleToEntry = (errorName, seen) => {
+    const category = errorNameToCategory[errorName];
+    if (!category) {
+        return undefined;
+    }
+    const code = statusCodeMap[category];
+    if (seen.has(code)) {
+        return undefined;
+    }
+    seen.add(code);
+    return [String(code), { description: errorName }];
+};
+/** Extract error status codes from trail examples that have an `error` field. */
+const errorResponsesFromExamples = (examples) => {
+    const responses = {};
+    const seen = new Set();
+    for (const ex of examples) {
+        if (!ex.error) {
+            continue;
+        }
+        const entry = errorExampleToEntry(ex.error, seen);
+        if (entry) {
+            const [code, value] = entry;
+            responses[code] = value;
+        }
+    }
+    return responses;
+};
+// ---------------------------------------------------------------------------
+// Operation builder — split into focused helpers
+// ---------------------------------------------------------------------------
+/** Build the input portion of an operation (parameters or requestBody). */
+const buildInputSpec = (t, method) => {
+    if (!t.input) {
+        return {};
+    }
+    const inputSchema = toJsonSchema(t.input);
+    if (method === 'get') {
+        const params = buildQueryParameters(inputSchema);
+        return params.length > 0 ? { parameters: params } : {};
+    }
+    return {
+        requestBody: {
+            content: { 'application/json': { schema: inputSchema } },
+            required: true,
+        },
+    };
+};
+/** Wrap a raw output schema in the `{ data: ... }` envelope the HTTP adapter uses. */
+const wrapInDataEnvelope = (outputSchema) => ({
+    properties: { data: outputSchema },
+    required: ['data'],
+    type: 'object',
+});
+/** Shared error response body schema: `{ error: { message, code, category } }`. */
+const errorResponseSchema = {
+    properties: {
+        error: {
+            properties: {
+                category: { type: 'string' },
+                code: { type: 'string' },
+                message: { type: 'string' },
+            },
+            required: ['message', 'code', 'category'],
+            type: 'object',
+        },
+    },
+    required: ['error'],
+    type: 'object',
+};
+/** Build the 200 response entry. */
+const buildSuccessResponse = (t) => {
+    if (!t.output) {
+        return { '200': { description: 'Success' } };
+    }
+    const outputSchema = toJsonSchema(t.output);
+    return {
+        '200': {
+            content: {
+                'application/json': { schema: wrapInDataEnvelope(outputSchema) },
+            },
+            description: 'Success',
+        },
+    };
+};
+/** Build the default 400 validation error response. */
+const validationErrorResponse = {
+    '400': {
+        content: { 'application/json': { schema: errorResponseSchema } },
+        description: 'Validation error',
+    },
+};
+/** Build all responses (success + error) for a trail. */
+const buildResponses = (t) => {
+    const examples = (t.examples ?? []);
+    return {
+        ...buildSuccessResponse(t),
+        ...validationErrorResponse,
+        ...errorResponsesFromExamples(examples),
+    };
+};
+/** Build a complete OpenAPI operation for a trail. */
+const buildOperation = (t, method) => ({
+    operationId: t.id.replaceAll('.', '_'),
+    responses: buildResponses(t),
+    tags: [tagFromId(t.id)],
+    ...(t.description ? { summary: t.description } : {}),
+    ...buildInputSpec(t, method),
+});
+// ---------------------------------------------------------------------------
+// Path collection
+// ---------------------------------------------------------------------------
+/** Check whether a trail should be included in the spec. */
+const isPublicTrail = (t) => {
+    if (t.kind !== 'trail') {
+        return false;
+    }
+    const { metadata } = t;
+    return metadata?.['internal'] !== true;
+};
+/** Collect all paths from public trails in the topo. */
+const collectPaths = (app, basePath) => {
+    const paths = {};
+    for (const item of app.list()) {
+        const t = item;
+        if (!isPublicTrail(t)) {
+            continue;
+        }
+        const method = intentToMethod[t.intent] ?? 'post';
+        paths[trailIdToPath(t.id, basePath)] = {
+            [method]: buildOperation(t, method),
+        };
+    }
+    return paths;
+};
+/** Build the info object from options and app name. */
+const buildInfo = (appName, options) => ({
+    title: options?.title ?? appName,
+    version: options?.version ?? '1.0.0',
+    ...(options?.description ? { description: options.description } : {}),
+});
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Generate an OpenAPI 3.1 specification from a Topo.
+ *
+ * Iterates all trails, skipping events and internal trails, and produces
+ * paths, operations, parameters, and response schemas derived from
+ * the trail contract.
+ */
+export const generateOpenApiSpec = (app, options) => ({
+    components: { schemas: {} },
+    info: buildInfo(app.name, options),
+    openapi: '3.1.0',
+    paths: collectPaths(app, (options?.basePath ?? '').replace(/\/+$/, '')),
+    ...(options?.servers && options.servers.length > 0
+        ? { servers: options.servers }
+        : {}),
+});
+//# sourceMappingURL=openapi.js.map

package/dist/openapi.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/schema",
-  "version": "1.0.0-beta.6",
+  "version": "1.0.0-beta.8",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -14,7 +14,7 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "peerDependencies": {
-    "@ontrails/core": "^1.0.0-beta.0",
+    "@ontrails/core": "^1.0.0-beta.6",
     "zod": "^4.3.5"
   }
 }

package/src/__tests__/openapi.test.ts

@@ -0,0 +1,447 @@
+import { describe, expect, test } from 'bun:test';
+
+import { Result, topo, trail } from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
+import { z } from 'zod';
+
+import { generateOpenApiSpec } from '../openapi.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const topoFrom = (...modules: Record<string, unknown>[]): Topo =>
+  topo('test-app', ...modules);
+
+const noop = () => Result.ok(null as unknown);
+
+/** Extract an operation from a spec by path and method. */
+const getOperation = (
+  spec: ReturnType<typeof generateOpenApiSpec>,
+  path: string,
+  method: string
+): Record<string, unknown> =>
+  spec.paths[path]?.[method] as Record<string, unknown>;
+
+/** Drill into a response to get the JSON schema. */
+const getJsonSchema = (
+  response: Record<string, unknown>
+): Record<string, unknown> => {
+  const content = response['content'] as Record<string, unknown>;
+  const json = content['application/json'] as Record<string, unknown>;
+  return json['schema'] as Record<string, unknown>;
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('generateOpenApiSpec', () => {
+  describe('path and method derivation', () => {
+    test('dotted trail ID becomes a path', () => {
+      const t = trail('entity.show', {
+        input: z.object({ id: z.string() }),
+        intent: 'read',
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+
+      expect(spec.paths['/entity/show']).toBeDefined();
+    });
+
+    test('single-segment trail ID becomes a root path', () => {
+      const t = trail('search', {
+        input: z.object({ q: z.string() }),
+        intent: 'read',
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+
+      expect(spec.paths['/search']).toBeDefined();
+    });
+
+    test('intent read → GET', () => {
+      const t = trail('entity.show', {
+        input: z.object({ id: z.string() }),
+        intent: 'read',
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+
+      expect(spec.paths['/entity/show']?.['get']).toBeDefined();
+    });
+
+    test('intent destroy → DELETE', () => {
+      const t = trail('entity.remove', {
+        input: z.object({ id: z.string() }),
+        intent: 'destroy',
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+
+      expect(spec.paths['/entity/remove']?.['delete']).toBeDefined();
+    });
+
+    test('intent write (default) → POST', () => {
+      const t = trail('entity.create', {
+        input: z.object({ name: z.string() }),
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+
+      expect(spec.paths['/entity/create']?.['post']).toBeDefined();
+    });
+
+    test('basePath is prepended to all paths', () => {
+      const t = trail('entity.show', {
+        input: z.object({ id: z.string() }),
+        intent: 'read',
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }), {
+        basePath: '/api/v1',
+      });
+
+      expect(spec.paths['/api/v1/entity/show']).toBeDefined();
+    });
+
+    test('basePath trailing slash is normalized', () => {
+      const t = trail('entity.show', {
+        input: z.object({ id: z.string() }),
+        intent: 'read',
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }), {
+        basePath: '/api/v1/',
+      });
+
+      expect(spec.paths['/api/v1/entity/show']).toBeDefined();
+      expect(spec.paths['/api/v1//entity/show']).toBeUndefined();
+    });
+  });
+
+  describe('GET query parameters', () => {
+    const buildReadSpec = () => {
+      const t = trail('entity.show', {
+        input: z.object({ id: z.string(), verbose: z.boolean().optional() }),
+        intent: 'read',
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+      const op = spec.paths['/entity/show']?.['get'] as Record<string, unknown>;
+      return op['parameters'] as Record<string, unknown>[];
+    };
+
+    test('produces one parameter per input field', () => {
+      expect(buildReadSpec()).toHaveLength(2);
+    });
+
+    test('required field is marked required with in=query', () => {
+      const idParam = buildReadSpec().find((p) => p['name'] === 'id');
+      expect(idParam?.['in']).toBe('query');
+      expect(idParam?.['required']).toBe(true);
+    });
+
+    test('optional field is marked not required', () => {
+      const verboseParam = buildReadSpec().find((p) => p['name'] === 'verbose');
+      expect(verboseParam).toBeDefined();
+      expect(verboseParam?.['required']).toBe(false);
+    });
+  });
+
+  describe('request body', () => {
+    test('POST input schema becomes requestBody', () => {
+      const t = trail('entity.create', {
+        input: z.object({ name: z.string() }),
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+      const op = spec.paths['/entity/create']?.['post'] as Record<
+        string,
+        unknown
+      >;
+      const body = op['requestBody'] as Record<string, unknown>;
+
+      expect(body['required']).toBe(true);
+      expect(body['content']).toBeDefined();
+      const content = body['content'] as Record<string, unknown>;
+      expect(content['application/json']).toBeDefined();
+    });
+  });
+
+  describe('responses', () => {
+    test('trail with output schema → 200 response wrapped in { data }', () => {
+      const t = trail('entity.show', {
+        input: z.object({ id: z.string() }),
+        intent: 'read',
+        output: z.object({ id: z.string(), name: z.string() }),
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+      const success = (
+        getOperation(spec, '/entity/show', 'get')['responses'] as Record<
+          string,
+          unknown
+        >
+      )['200'] as Record<string, unknown>;
+      const schema = getJsonSchema(success);
+
+      expect(success['description']).toBe('Success');
+      expect(schema['type']).toBe('object');
+      expect(schema['required']).toEqual(['data']);
+      const dataSchema = (schema['properties'] as Record<string, unknown>)[
+        'data'
+      ] as Record<string, unknown>;
+      expect(dataSchema['type']).toBe('object');
+    });
+
+    test('trail without output → 200 with no schema', () => {
+      const t = trail('fire.forget', {
+        input: z.object({ msg: z.string() }),
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+      const op = spec.paths['/fire/forget']?.['post'] as Record<
+        string,
+        unknown
+      >;
+      const responses = op['responses'] as Record<string, unknown>;
+      const success = responses['200'] as Record<string, unknown>;
+
+      expect(success['description']).toBe('Success');
+      expect(success['content']).toBeUndefined();
+    });
+
+    test('trail with error examples → appropriate error responses', () => {
+      const t = trail('entity.show', {
+        examples: [
+          { input: { id: '123' }, name: 'found' },
+          {
+            error: 'NotFoundError',
+            input: { id: 'missing' },
+            name: 'not found',
+          },
+        ],
+        input: z.object({ id: z.string() }),
+        intent: 'read',
+        output: z.object({ id: z.string() }),
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+      const op = spec.paths['/entity/show']?.['get'] as Record<string, unknown>;
+      const responses = op['responses'] as Record<string, unknown>;
+
+      expect(responses['404']).toEqual({ description: 'NotFoundError' });
+    });
+
+    test('every trail includes a default 400 validation error response', () => {
+      const t = trail('entity.show', {
+        input: z.object({ id: z.string() }),
+        intent: 'read',
+        output: z.object({ id: z.string() }),
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+      const op = spec.paths['/entity/show']?.['get'] as Record<string, unknown>;
+      const fourHundred = (op['responses'] as Record<string, unknown>)[
+        '400'
+      ] as Record<string, unknown>;
+
+      expect(fourHundred['description']).toBe('Validation error');
+      expect(fourHundred['content']).toBeDefined();
+      const schema = getJsonSchema(fourHundred);
+      const errorProp = (schema['properties'] as Record<string, unknown>)[
+        'error'
+      ] as Record<string, unknown>;
+      expect(errorProp['type']).toBe('object');
+    });
+
+    test('example-derived 400 does not override the default 400', () => {
+      const t = trail('entity.show', {
+        examples: [{ error: 'ValidationError', input: {}, name: 'bad input' }],
+        input: z.object({ id: z.string() }),
+        intent: 'read',
+        output: z.object({ id: z.string() }),
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+      const op = spec.paths['/entity/show']?.['get'] as Record<string, unknown>;
+      const responses = op['responses'] as Record<string, unknown>;
+
+      // The example-derived 400 (description: 'ValidationError') overrides the default
+      expect(responses['400']).toEqual({ description: 'ValidationError' });
+    });
+  });
+
+  describe('operationId', () => {
+    test('dots replaced with underscores', () => {
+      const t = trail('entity.show', {
+        input: z.object({ id: z.string() }),
+        intent: 'read',
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+      const op = spec.paths['/entity/show']?.['get'] as Record<string, unknown>;
+
+      expect(op['operationId']).toBe('entity_show');
+    });
+
+    test('single segment ID preserved', () => {
+      const t = trail('search', {
+        input: z.object({ q: z.string() }),
+        intent: 'read',
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+      const op = spec.paths['/search']?.['get'] as Record<string, unknown>;
+
+      expect(op['operationId']).toBe('search');
+    });
+  });
+
+  describe('tags', () => {
+    test('tag is first segment of dotted ID', () => {
+      const t = trail('entity.show', {
+        input: z.object({ id: z.string() }),
+        intent: 'read',
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+      const op = spec.paths['/entity/show']?.['get'] as Record<string, unknown>;
+
+      expect(op['tags']).toEqual(['entity']);
+    });
+
+    test('single-segment ID uses itself as tag', () => {
+      const t = trail('search', {
+        input: z.object({ q: z.string() }),
+        intent: 'read',
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+      const op = spec.paths['/search']?.['get'] as Record<string, unknown>;
+
+      expect(op['tags']).toEqual(['search']);
+    });
+  });
+
+  describe('multiple trails', () => {
+    test('all trails populate paths', () => {
+      const a = trail('entity.create', {
+        input: z.object({ name: z.string() }),
+        run: noop,
+      });
+      const b = trail('entity.show', {
+        input: z.object({ id: z.string() }),
+        intent: 'read',
+        run: noop,
+      });
+      const c = trail('entity.remove', {
+        input: z.object({ id: z.string() }),
+        intent: 'destroy',
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ a, b, c }));
+
+      expect(Object.keys(spec.paths)).toHaveLength(3);
+      expect(spec.paths['/entity/create']?.['post']).toBeDefined();
+      expect(spec.paths['/entity/show']?.['get']).toBeDefined();
+      expect(spec.paths['/entity/remove']?.['delete']).toBeDefined();
+    });
+  });
+
+  describe('internal trails', () => {
+    test('trails with metadata.internal are skipped', () => {
+      const pub = trail('entity.show', {
+        input: z.object({ id: z.string() }),
+        intent: 'read',
+        run: noop,
+      });
+      const internal = trail('internal.helper', {
+        input: z.object({}),
+        metadata: { internal: true },
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ internal, pub }));
+
+      expect(Object.keys(spec.paths)).toHaveLength(1);
+      expect(spec.paths['/entity/show']).toBeDefined();
+      expect(spec.paths['/internal/helper']).toBeUndefined();
+    });
+  });
+
+  describe('spec structure', () => {
+    test('openapi version is 3.1.0', () => {
+      const spec = generateOpenApiSpec(topoFrom({}));
+
+      expect(spec.openapi).toBe('3.1.0');
+    });
+
+    test('info defaults from topo name', () => {
+      const spec = generateOpenApiSpec(topoFrom({}));
+
+      expect(spec.info.title).toBe('test-app');
+      expect(spec.info.version).toBe('1.0.0');
+    });
+
+    test('info uses options when provided', () => {
+      const spec = generateOpenApiSpec(topoFrom({}), {
+        description: 'Test API',
+        title: 'My API',
+        version: '2.0.0',
+      });
+
+      expect(spec.info.title).toBe('My API');
+      expect(spec.info.version).toBe('2.0.0');
+      expect(spec.info.description).toBe('Test API');
+    });
+
+    test('servers included when provided', () => {
+      const spec = generateOpenApiSpec(topoFrom({}), {
+        servers: [{ description: 'Local', url: 'http://localhost:3000' }],
+      });
+
+      expect(spec.servers).toHaveLength(1);
+      expect(spec.servers?.[0]?.url).toBe('http://localhost:3000');
+    });
+
+    test('servers omitted when not provided', () => {
+      const spec = generateOpenApiSpec(topoFrom({}));
+
+      expect(spec.servers).toBeUndefined();
+    });
+
+    test('components.schemas is present (empty)', () => {
+      const spec = generateOpenApiSpec(topoFrom({}));
+
+      expect(spec.components.schemas).toEqual({});
+    });
+  });
+
+  describe('summary from description', () => {
+    test('trail description becomes operation summary', () => {
+      const t = trail('entity.show', {
+        description: 'Show an entity by ID',
+        input: z.object({ id: z.string() }),
+        intent: 'read',
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+      const op = spec.paths['/entity/show']?.['get'] as Record<string, unknown>;
+
+      expect(op['summary']).toBe('Show an entity by ID');
+    });
+
+    test('trail without description has no summary', () => {
+      const t = trail('entity.show', {
+        input: z.object({ id: z.string() }),
+        intent: 'read',
+        run: noop,
+      });
+      const spec = generateOpenApiSpec(topoFrom({ t }));
+      const op = spec.paths['/entity/show']?.['get'] as Record<string, unknown>;
+
+      expect(op['summary']).toBeUndefined();
+    });
+  });
+});

package/src/index.ts

@@ -3,6 +3,10 @@ export { generateSurfaceMap } from './generate.js';
 export { hashSurfaceMap } from './hash.js';
 export { diffSurfaceMaps } from './diff.js';
 
+// OpenAPI
+export { generateOpenApiSpec } from './openapi.js';
+export type { OpenApiOptions, OpenApiSpec, OpenApiServer } from './openapi.js';
+
 // File I/O
 export {
   writeSurfaceMap,

package/src/openapi.ts

@@ -0,0 +1,325 @@
+/**
+ * Generate an OpenAPI 3.1 specification from a Topo.
+ *
+ * Converts each trail into an HTTP operation, deriving paths, methods,
+ * parameters, and response schemas from the trail contract.
+ */
+
+import { statusCodeMap, zodToJsonSchema } from '@ontrails/core';
+import type { Topo, Trail } from '@ontrails/core';
+
+import type { JsonSchema } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface OpenApiServer {
+  readonly url: string;
+  readonly description?: string | undefined;
+}
+
+export interface OpenApiOptions {
+  /** Default: `app.name` */
+  readonly title?: string | undefined;
+  /** Default: `'1.0.0'` */
+  readonly version?: string | undefined;
+  readonly description?: string | undefined;
+  readonly servers?: readonly OpenApiServer[] | undefined;
+  /** Prefix for all paths. Default: `''` */
+  readonly basePath?: string | undefined;
+}
+
+/** Minimal OpenAPI 3.1 spec shape — intentionally plain objects, no heavy library. */
+export interface OpenApiSpec {
+  readonly openapi: '3.1.0';
+  readonly info: {
+    readonly title: string;
+    readonly version: string;
+    readonly description?: string | undefined;
+  };
+  readonly servers?: readonly OpenApiServer[] | undefined;
+  readonly paths: Record<string, Record<string, unknown>>;
+  readonly components: { readonly schemas: Record<string, unknown> };
+}
+
+// ---------------------------------------------------------------------------
+// Error name → category lookup
+// ---------------------------------------------------------------------------
+
+const errorNameToCategory: Record<string, keyof typeof statusCodeMap> = {
+  AlreadyExistsError: 'conflict',
+  AmbiguousError: 'validation',
+  AssertionError: 'internal',
+  AuthError: 'auth',
+  CancelledError: 'cancelled',
+  ConflictError: 'conflict',
+  InternalError: 'internal',
+  NetworkError: 'network',
+  NotFoundError: 'not_found',
+  PermissionError: 'permission',
+  RateLimitError: 'rate_limit',
+  TimeoutError: 'timeout',
+  ValidationError: 'validation',
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const intentToMethod: Record<string, string> = {
+  destroy: 'delete',
+  read: 'get',
+  write: 'post',
+};
+
+/** `entity.show` → `/entity/show` */
+const trailIdToPath = (id: string, basePath: string): string =>
+  `${basePath}/${id.split('.').join('/')}`;
+
+/** First segment of a dotted ID, used as an OpenAPI tag. */
+const tagFromId = (id: string): string => id.split('.')[0] ?? id;
+
+/** Convert a Zod schema to JSON Schema via the core helper. */
+const toJsonSchema = (schema: unknown): JsonSchema =>
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  zodToJsonSchema(schema as any) as JsonSchema;
+
+/** Build query parameters from a JSON Schema `properties` object. */
+const buildQueryParameters = (
+  jsonSchema: JsonSchema
+): Record<string, unknown>[] => {
+  const properties = jsonSchema['properties'] as
+    | Record<string, Record<string, unknown>>
+    | undefined;
+  if (!properties) {
+    return [];
+  }
+
+  const required = new Set(
+    Array.isArray(jsonSchema['required'])
+      ? (jsonSchema['required'] as string[])
+      : []
+  );
+
+  return Object.entries(properties).map(([name, schema]) => ({
+    in: 'query',
+    name,
+    required: required.has(name),
+    schema,
+  }));
+};
+
+/** Map a single error example to a status code entry, or undefined if not mappable. */
+const errorExampleToEntry = (
+  errorName: string,
+  seen: Set<number>
+): [string, { description: string }] | undefined => {
+  const category = errorNameToCategory[errorName];
+  if (!category) {
+    return undefined;
+  }
+  const code = statusCodeMap[category];
+  if (seen.has(code)) {
+    return undefined;
+  }
+  seen.add(code);
+  return [String(code), { description: errorName }];
+};
+
+/** Extract error status codes from trail examples that have an `error` field. */
+const errorResponsesFromExamples = (
+  examples: readonly { error?: string | undefined }[]
+): Record<string, { description: string }> => {
+  const responses: Record<string, { description: string }> = {};
+  const seen = new Set<number>();
+
+  for (const ex of examples) {
+    if (!ex.error) {
+      continue;
+    }
+    const entry = errorExampleToEntry(ex.error, seen);
+    if (entry) {
+      const [code, value] = entry;
+      responses[code] = value;
+    }
+  }
+
+  return responses;
+};
+
+// ---------------------------------------------------------------------------
+// Operation builder — split into focused helpers
+// ---------------------------------------------------------------------------
+
+/** Build the input portion of an operation (parameters or requestBody). */
+const buildInputSpec = (
+  t: Trail<unknown, unknown>,
+  method: string
+): Record<string, unknown> => {
+  if (!t.input) {
+    return {};
+  }
+  const inputSchema = toJsonSchema(t.input);
+
+  if (method === 'get') {
+    const params = buildQueryParameters(inputSchema);
+    return params.length > 0 ? { parameters: params } : {};
+  }
+
+  return {
+    requestBody: {
+      content: { 'application/json': { schema: inputSchema } },
+      required: true,
+    },
+  };
+};
+
+/** Wrap a raw output schema in the `{ data: ... }` envelope the HTTP adapter uses. */
+const wrapInDataEnvelope = (outputSchema: JsonSchema): JsonSchema => ({
+  properties: { data: outputSchema },
+  required: ['data'],
+  type: 'object',
+});
+
+/** Shared error response body schema: `{ error: { message, code, category } }`. */
+const errorResponseSchema: JsonSchema = {
+  properties: {
+    error: {
+      properties: {
+        category: { type: 'string' },
+        code: { type: 'string' },
+        message: { type: 'string' },
+      },
+      required: ['message', 'code', 'category'],
+      type: 'object',
+    },
+  },
+  required: ['error'],
+  type: 'object',
+};
+
+/** Build the 200 response entry. */
+const buildSuccessResponse = (
+  t: Trail<unknown, unknown>
+): Record<string, unknown> => {
+  if (!t.output) {
+    return { '200': { description: 'Success' } };
+  }
+  const outputSchema = toJsonSchema(t.output);
+  return {
+    '200': {
+      content: {
+        'application/json': { schema: wrapInDataEnvelope(outputSchema) },
+      },
+      description: 'Success',
+    },
+  };
+};
+
+/** Build the default 400 validation error response. */
+const validationErrorResponse: Record<
+  string,
+  { content: Record<string, unknown>; description: string }
+> = {
+  '400': {
+    content: { 'application/json': { schema: errorResponseSchema } },
+    description: 'Validation error',
+  },
+};
+
+/** Build all responses (success + error) for a trail. */
+const buildResponses = (
+  t: Trail<unknown, unknown>
+): Record<string, unknown> => {
+  const examples = (t.examples ?? []) as readonly {
+    error?: string | undefined;
+  }[];
+  return {
+    ...buildSuccessResponse(t),
+    ...validationErrorResponse,
+    ...errorResponsesFromExamples(examples),
+  };
+};
+
+/** Build a complete OpenAPI operation for a trail. */
+const buildOperation = (
+  t: Trail<unknown, unknown>,
+  method: string
+): Record<string, unknown> => ({
+  operationId: t.id.replaceAll('.', '_'),
+  responses: buildResponses(t),
+  tags: [tagFromId(t.id)],
+  ...(t.description ? { summary: t.description } : {}),
+  ...buildInputSpec(t, method),
+});
+
+// ---------------------------------------------------------------------------
+// Path collection
+// ---------------------------------------------------------------------------
+
+/** Check whether a trail should be included in the spec. */
+const isPublicTrail = (t: Trail<unknown, unknown>): boolean => {
+  if (t.kind !== 'trail') {
+    return false;
+  }
+  const { metadata } = t as unknown as {
+    metadata?: Record<string, unknown>;
+  };
+  return metadata?.['internal'] !== true;
+};
+
+/** Collect all paths from public trails in the topo. */
+const collectPaths = (
+  app: Topo,
+  basePath: string
+): Record<string, Record<string, unknown>> => {
+  const paths: Record<string, Record<string, unknown>> = {};
+
+  for (const item of app.list()) {
+    const t = item as Trail<unknown, unknown>;
+    if (!isPublicTrail(t)) {
+      continue;
+    }
+    const method = intentToMethod[t.intent] ?? 'post';
+    paths[trailIdToPath(t.id, basePath)] = {
+      [method]: buildOperation(t, method),
+    };
+  }
+
+  return paths;
+};
+
+/** Build the info object from options and app name. */
+const buildInfo = (
+  appName: string,
+  options?: OpenApiOptions
+): OpenApiSpec['info'] => ({
+  title: options?.title ?? appName,
+  version: options?.version ?? '1.0.0',
+  ...(options?.description ? { description: options.description } : {}),
+});
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate an OpenAPI 3.1 specification from a Topo.
+ *
+ * Iterates all trails, skipping events and internal trails, and produces
+ * paths, operations, parameters, and response schemas derived from
+ * the trail contract.
+ */
+export const generateOpenApiSpec = (
+  app: Topo,
+  options?: OpenApiOptions
+): OpenApiSpec => ({
+  components: { schemas: {} },
+  info: buildInfo(app.name, options),
+  openapi: '3.1.0',
+  paths: collectPaths(app, (options?.basePath ?? '').replace(/\/+$/, '')),
+  ...(options?.servers && options.servers.length > 0
+    ? { servers: options.servers }
+    : {}),
+});

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/diff.ts","./src/generate.ts","./src/hash.ts","./src/index.ts","./src/io.ts","./src/types.ts"],"version":"5.9.3"}
+{"root":["./src/diff.ts","./src/generate.ts","./src/hash.ts","./src/index.ts","./src/io.ts","./src/openapi.ts","./src/types.ts"],"version":"5.9.3"}