@ontrails/http 1.0.0-beta.14 → 1.0.0-beta.16

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @ontrails/http
 
+## 1.0.0-beta.16
+
+### Minor Changes
+
+- 2bf239e: Move OpenAPI generation ownership to the HTTP surface.
+
+  **http**: Export `deriveOpenApiSpec()` and its OpenAPI types from `@ontrails/http`.
+
+  **schema**: Remove the OpenAPI helper export so schema stays focused on surface maps, locks, and semantic diffing.
+
+- 26f9ffd: Project typed-layer `input` schemas onto MCP and HTTP surfaces. Closes Phase 7. Lifts `collectAttachedTypedLayers` and `projectLayerFieldName` (collision-rename rule) into `@ontrails/core/internal/layer-projection` so all three surfaces share one source of truth. The CLI surface refactors to consume the lifted helpers (no behavior change). MCP merges layer fields into each tool's `inputSchema` and partitions inbound args at invocation time. HTTP merges layer fields into the route's request schema (query for reads, body for writes) and exposes new optional `HttpRouteDefinition.inputSchema` + `layerInputProjections` for surface adapters / OpenAPI generators. Collision rule matches TRL-473's: deterministic rename to a layer-prefixed camelCase name with the original captured in the routing table. Side fix: MCP and HTTP handlers now forward `topoLayers: graph.layers` + `surfaceLayers: layers` so topo-scope layers actually compose at runtime (previously the handlers used the deprecated `layers` alias and never read `graph.layers`).
+- 22c6c06: Accept ADR-0041 Unified Observability and ship the first activation and
+  observability primitives it depends on: activation trace records, topo-level
+  observe configuration, webhook activation materialization, signal/webhook
+  warden coaching, the `@ontrails/observe` package, sink composition, and
+  zero-dependency observe sinks.
+
+### Patch Changes
+
+- 6300f70: Refresh source comments and test labels for retired connector terminology as adapter guardrails become strict.
+- 95bf132: Wire HTTP permit resolution through the Hono adapter, including request headers for Bearer Authorization handling.
+- 49c2e7d: Refresh published package README taxonomy to use adapter language instead of retired connector vocabulary.
+- df9a7d0: Add project-aware public export-map governance for @ontrails workspace docs,
+  imports, root barrels, and bin-only package surfaces.
+- Updated dependencies [73622ae]
+- Updated dependencies [6300f70]
+- Updated dependencies [d172013]
+- Updated dependencies [c3fc5c3]
+- Updated dependencies [20d7a5c]
+- Updated dependencies [be5fb46]
+- Updated dependencies [e898cc4]
+- Updated dependencies [3395234]
+- Updated dependencies [bcdc484]
+- Updated dependencies [331e3a9]
+- Updated dependencies [4399fdb]
+- Updated dependencies [4b8d13b]
+- Updated dependencies [112b9f2]
+- Updated dependencies [893025e]
+- Updated dependencies [eec5e9d]
+- Updated dependencies [ebd4434]
+- Updated dependencies [863d473]
+- Updated dependencies [344f2f7]
+- Updated dependencies [26f9ffd]
+- Updated dependencies [10eae9a]
+- Updated dependencies [22c6c06]
+  - @ontrails/core@1.0.0-beta.16
+
+## 1.0.0-beta.15
+
+### Patch Changes
+
+- Updated dependencies [4ad6b25]
+  - @ontrails/core@1.0.0-beta.15
+
 ## 1.0.0-beta.14
 
 ### Minor Changes

package/README.md

@@ -1,12 +1,12 @@
 # @ontrails/http
 
-HTTP trailhead connector. One `trailhead()` call turns a topo into a Hono-based HTTP server with routes, input validation, and error mapping -- all derived from the trail contracts.
+Framework-agnostic HTTP route derivation for Trails. Pair this package with `@ontrails/hono` when you want the Hono surface adapter.
 
 ## Usage
 
 ```typescript
 import { trail, topo, Result } from '@ontrails/core';
-import { trailhead } from '@ontrails/http/hono';
+import { surface } from '@ontrails/hono';
 import { z } from 'zod';
 
 const greet = trail('greet', {
@@ -16,8 +16,8 @@ const greet = trail('greet', {
   blaze: (input) => Result.ok({ message: `Hello, ${input.name}!` }),
 });
 
-const app = topo('myapp', { greet });
-await trailhead(app, { port: 3000 });
+const graph = topo('myapp', { greet });
+await surface(graph, { port: 3000 });
 ```
 
 This starts a Hono-based HTTP server. The `greet` trail becomes `GET /greet?name=...` because its `intent` is `'read'`.
@@ -25,23 +25,34 @@ This starts a Hono-based HTTP server. The `greet` trail becomes `GET /greet?name
 For more control, build the routes yourself:
 
 ```typescript
-import { buildHttpRoutes } from '@ontrails/http';
+import { deriveHttpRoutes } from '@ontrails/http';
 
-const result = buildHttpRoutes(app);
+const result = deriveHttpRoutes(graph);
 if (result.isErr()) throw result.error; // ValidationError on route collision
 for (const route of result.value) {
   console.log(`${route.method} ${route.path} → ${route.trailId}`);
 }
 ```
 
-`buildHttpRoutes` returns `Result<HttpRouteDefinition[], Error>` rather than a bare array. It returns `Result.err(ValidationError)` if two trails derive the same `(method, path)` pair.
+`deriveHttpRoutes` returns `Result<HttpRouteDefinition[], Error>` rather than a bare array. It returns `Result.err(ValidationError)` if two trails derive the same `(method, path)` pair.
+
+OpenAPI is the HTTP surface's persisted client contract projection:
+
+```typescript
+import { deriveOpenApiSpec } from '@ontrails/http';
+
+const spec = deriveOpenApiSpec(graph, { basePath: '/api' });
+```
+
+`deriveOpenApiSpec()` emits an OpenAPI 3.1 document from the same trail
+contracts used by `deriveHttpRoutes()`.
 
 ## API
 
 | Export | What it does |
 | --- | --- |
-| `buildHttpRoutes(app, options?)` | Build framework-agnostic route definitions from a topo |
-| `trailhead(app, options?)` (`@ontrails/http/hono`) | Start a Hono HTTP server with all trails as routes |
+| `deriveHttpRoutes(graph, options?)` | Build framework-agnostic route definitions from a topo |
+| `deriveOpenApiSpec(graph, options?)` | Generate an OpenAPI 3.1 document for the HTTP surface |
 
 ## Route derivation
 
@@ -58,19 +69,32 @@ Trail IDs map to paths: `entity.show` becomes `/entity/show`. Dots become slashe
 
 ## Collision detection
 
-`buildHttpRoutes` detects when two trails would produce the same `(method, path)` pair and returns `Result.err(ValidationError)` describing both trail IDs. The `trailhead()` Hono connector throws on collision.
+`deriveHttpRoutes` detects when two trails would produce the same `(method, path)` pair and returns `Result.err(ValidationError)` describing both trail IDs. The `surface()` helper from `@ontrails/hono` throws on collision.
+
+## Resource resolution
+
+Declared resources on each trail are resolved into the context before the implementation runs.
 
-## Provision resolution
+## Filtering
 
-Declared provisions on each trail are resolved into the context before the implementation runs.
+```typescript
+const result = deriveHttpRoutes(graph, {
+  include: ['entity.**'],
+  exclude: ['dev.**'],
+});
+```
+
+`*` matches one dotted segment and `**` matches any depth. Trails declared
+with `visibility: 'internal'` stay hidden unless you include their exact trail
+ID intentionally.
 
-## AbortSignal propagation
+## Request context and abort propagation
 
-The `execute` function on each `HttpRouteDefinition` accepts an optional `abortSignal`. The Hono connector extracts `signal` from `c.req.raw` and forwards it as `abortSignal`, so client disconnects propagate into trail execution.
+The `execute` function on each `HttpRouteDefinition` accepts optional `requestId`, `abortSignal`, and request context arguments. HTTP adapters should pass the request's `AbortSignal` so client disconnects propagate into trail execution, and pass headers in the request context when Bearer auth should resolve into `ctx.permit`.
 
 ## `HttpRouteDefinition`
 
-Each route definition produced by `buildHttpRoutes` includes:
+Each route definition produced by `deriveHttpRoutes` includes:
 
 | Field | Type | What it is |
 | --- | --- | --- |
@@ -79,10 +103,23 @@ Each route definition produced by `buildHttpRoutes` includes:
 | `trailId` | `string` | The trail ID this route was derived from |
 | `inputSource` | `'query' \| 'body'` | Where to read input |
 | `trail` | `Trail` | The original trail definition |
-| `execute` | `(input, requestId?, abortSignal?) => Promise<Result>` | Validates, gates, and runs the implementation |
+| `execute` | `(input, requestId?, abortSignal?, context?) => Promise<Result>` | Validates, layers, resolves request auth when configured, and runs the implementation |
+
+For GET routes on the Hono surface, repeated query keys are passed through as
+arrays (`?tag=one&tag=two` -> `{ tag: ['one', 'two'] }`) while a single
+occurrence stays a scalar string. The adapter does not coerce singleton query
+values into arrays.
 
 ## Installation
 
 ```bash
-bun add @ontrails/http hono
+bun add @ontrails/http @ontrails/hono
 ```
+
+## Migration
+
+Hono integration now lives in `@ontrails/hono`.
+
+<!-- warden-ignore-next-line -->
+- Replace `import { trailhead } from '@ontrails/http/hono'` with `import { surface } from '@ontrails/hono'`
+- Keep `deriveHttpRoutes()` and the route model imports on `@ontrails/http`

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "@ontrails/http",
-  "version": "1.0.0-beta.14",
+  "version": "1.0.0-beta.16",
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./hono": "./src/hono/index.ts",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -15,15 +22,9 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.13"
+    "@ontrails/core": "^1.0.0-beta.15"
   },
   "peerDependencies": {
-    "hono": "^4.7.0",
     "zod": "^4.3.5"
-  },
-  "peerDependenciesMeta": {
-    "hono": {
-      "optional": true
-    }
   }
 }