@ontrails/library 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,195 @@
+# @ontrails/library
+
+## 0.2.0
+
+### Patch Changes
+
+- [`79d12ca`](https://github.com/outfitter-dev/trails/commit/79d12cae392436e21a1125f3517e08a6b38d12d0): Support the approved initial release on `latest` at `0.2.0`: recognize the unpublished `1.0.0` source reset and the old beta tag predecessor, while retaining downgrade guards for every other transition and requiring manual publication.
+
+  Recognize the approved manual version PR in publication discovery with exact repository, branch, version, and label checks; preserve the normal bot-generated release path.
+
+  Keep the generated Homebrew formula on version scheme 1 so ordinary upgrades move from the beta line to 0.2.0 and continue through subsequent releases.
+
+  Derive generated library runtime ranges from the installed compiler package version so emitted libraries follow the 0.2.x release line and future version changes.
+- [`b3ddf91`](https://github.com/outfitter-dev/trails/commit/b3ddf918ada8211f44983512e2bbdfbc5b66d722): Prepare the first normal Trails release at `0.2.0` on `latest`, replacing the unpublished 1.0.0 source release. The target advances the original `0.1.0` source minor, which was never published under the current package names. Public packages remain in lockstep. Update consumer installation guidance and provide a temporary manifest bridge for old 1.0 beta sources. Published beta versions remain unchanged; minor 0.x releases may carry documented breaking changes.
+
+  The `1.0.0` section retained below records an unpublished preparation, not an npm release. Its accumulated changes are included in `0.2.0`; the section remains as source history alongside the published beta entries.
+
+## 1.0.0
+
+### Minor Changes
+
+- [`5adb995`](https://github.com/outfitter-dev/trails/commit/5adb99551c2dda6190d46cce7f60bb08d63c99aa): Complete the v1 hard cutover from the authored `blaze` field to
+  `implementation` across trail contracts, surface projections, tests, examples,
+  and public source-analysis helpers. Existing applications must rename authored
+  trail behavior fields and direct trail-object access before upgrading.
+- [`88a6a62`](https://github.com/outfitter-dev/trails/commit/88a6a62a9e9e230ca6d368fa78dc3ece6c816204): Complete the v1 classification-first cutover from projection/project vocabulary
+  to derive/derived for contract-owned fact production and render/rendered for
+  surface presentation. Public type, helper, rule, relation, and report names move
+  without compatibility aliases; ordinary repository/project nouns remain
+  explicit preserves or structured review inventory.
+
+### Patch Changes
+
+- [`8097663`](https://github.com/outfitter-dev/trails/commit/80976636d0c40edb92ff458053818050043e7c9e): Project typed layer inputs through the library surface and generated packages. The runtime now validates the combined public input, routes layer-owned fields into per-layer input slots, and generated packages share one held client across root and result subpaths while avoiding Bun-only ambient type assumptions in their emitted tsconfig.
+- [`b1fbe57`](https://github.com/outfitter-dev/trails/commit/b1fbe574e6f44d1fecb5e3a000270955c0a77b7b): Publish Bun-validated package tarballs through an npm trusted-publishing adapter
+  binding, add exact repository metadata for each public workspace package, and
+  correct the native Bun release descriptor to its pack-only runtime boundary.
+- [`3a65ae3`](https://github.com/outfitter-dev/trails/commit/3a65ae363e05b7589f4a9876da4346886353b48c): Rename the durable graph substrate package from `@ontrails/topographer` to
+  `@ontrails/topography` after folding Wayfind graph queries into that owner.
+
+  Update imports to `@ontrails/topography` or
+  `@ontrails/topography/backend-support`. The pre-1.0 cutover does not ship a
+  compatibility package. TopoGraph, lock, topo-store, semantic diff, and Wayfind
+  APIs keep their existing contracts, and the `trails wayfind` CLI and MCP names
+  remain unchanged.
+
+  The governed package-route transition moves legacy `@ontrails/wayfinder`
+  imports directly to `@ontrails/topography`; it does not emit the retired
+  intermediate `@ontrails/topographer` route.
+
+- [`f9533a4`](https://github.com/outfitter-dev/trails/commit/f9533a4ef7392201c71d7f751361b4f7177eeacb): Keep public error projection shared and redacted while using transport-neutral CLI vocabulary and preserving safe topo diagnostics in structured output.
+- [`d4c8600`](https://github.com/outfitter-dev/trails/commit/d4c86009af44348d16bb78cae72054487baf0538): Make the library surface package publishable so generated Trails libraries can depend on the shared runtime-backed surface outside the monorepo.
+
+## 1.0.0-beta.50
+
+## 1.0.0-beta.49
+
+## 1.0.0-beta.48
+
+## 1.0.0-beta.47
+
+## 1.0.0-beta.46
+
+## 1.0.0-beta.45
+
+### Patch Changes
+
+- [`f9533a4`](https://github.com/outfitter-dev/trails/commit/f9533a4ef7392201c71d7f751361b4f7177eeacb): Keep public error projection shared and redacted while using transport-neutral CLI vocabulary and preserving safe topo diagnostics in structured output.
+
+## 1.0.0-beta.44
+
+### Patch Changes
+
+- [`b1fbe57`](https://github.com/outfitter-dev/trails/commit/b1fbe574e6f44d1fecb5e3a000270955c0a77b7b): Publish Bun-validated package tarballs through an npm trusted-publishing adapter
+  binding, add exact repository metadata for each public workspace package, and
+  correct the native Bun release descriptor to its pack-only runtime boundary.
+
+## 1.0.0-beta.43
+
+### Minor Changes
+
+- [`88a6a62`](https://github.com/outfitter-dev/trails/commit/88a6a62a9e9e230ca6d368fa78dc3ece6c816204): Complete the v1 classification-first cutover from projection/project vocabulary
+  to derive/derived for contract-owned fact production and render/rendered for
+  surface presentation. Public type, helper, rule, relation, and report names move
+  without compatibility aliases; ordinary repository/project nouns remain
+  explicit preserves or structured review inventory.
+
+## 1.0.0-beta.42
+
+## 1.0.0-beta.41
+
+## 1.0.0-beta.40
+
+### Minor Changes
+
+- [`5adb995`](https://github.com/outfitter-dev/trails/commit/5adb99551c2dda6190d46cce7f60bb08d63c99aa): Complete the v1 hard cutover from the authored `blaze` field to
+  `implementation` across trail contracts, surface projections, tests, examples,
+  and public source-analysis helpers. Existing applications must rename authored
+  trail behavior fields and direct trail-object access before upgrading.
+
+### Patch Changes
+
+- [`3a65ae3`](https://github.com/outfitter-dev/trails/commit/3a65ae363e05b7589f4a9876da4346886353b48c): Rename the durable graph substrate package from `@ontrails/topographer` to
+  `@ontrails/topography` after folding Wayfind graph queries into that owner.
+
+  Update imports to `@ontrails/topography` or
+  `@ontrails/topography/backend-support`. The pre-1.0 cutover does not ship a
+  compatibility package. TopoGraph, lock, topo-store, semantic diff, and Wayfind
+  APIs keep their existing contracts, and the `trails wayfind` CLI and MCP names
+  remain unchanged.
+
+  The governed package-route transition moves legacy `@ontrails/wayfinder`
+  imports directly to `@ontrails/topography`; it does not emit the retired
+  intermediate `@ontrails/topographer` route.
+
+## 1.0.0-beta.39
+
+## 1.0.0-beta.38
+
+## 1.0.0-beta.37
+
+## 1.0.0-beta.36
+
+## 1.0.0-beta.35
+
+## 1.0.0-beta.34
+
+## 1.0.0-beta.33
+
+## 1.0.0-beta.32
+
+### Patch Changes
+
+- Updated dependencies [3e5c0fc]
+- Updated dependencies [f3c4fef]
+- Updated dependencies [cb0a9d8]
+- Updated dependencies [21c6dda]
+- Updated dependencies [fe72b84]
+  - @ontrails/core@1.0.0-beta.32
+
+## 1.0.0-beta.31
+
+### Patch Changes
+
+- Updated dependencies [4cd5d4e]
+- Updated dependencies [38907cc]
+  - @ontrails/core@1.0.0-beta.31
+
+## 1.0.0-beta.30
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.30
+
+## 1.0.0-beta.29
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.29
+
+## 1.0.0-beta.28
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.28
+
+## 1.0.0-beta.27
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.27
+
+## 1.0.0-beta.26
+
+### Patch Changes
+
+- Updated dependencies [1307568]
+- Updated dependencies [371d19e]
+  - @ontrails/core@1.0.0-beta.26
+
+## 1.0.0-beta.25
+
+### Patch Changes
+
+- 8097663: Project typed layer inputs through the library surface and generated packages. The runtime now validates the combined public input, routes layer-owned fields into per-layer input slots, and generated packages share one held client across root and result subpaths while avoiding Bun-only ambient type assumptions in their emitted tsconfig.
+- d4c8600: Make the library surface package publishable so generated Trails libraries can depend on the shared runtime-backed surface outside the monorepo.
+- Updated dependencies [c36aca9]
+- Updated dependencies [3befcf1]
+- Updated dependencies [a4f9cf6]
+- Updated dependencies [9bcf34e]
+  - @ontrails/core@1.0.0-beta.25
+
+## 1.0.0-beta.24
+
+Initial prerelease changelog for the library surface package.

package/README.md

@@ -0,0 +1,89 @@
+# @ontrails/library
+
+Render a Trails topo as an idiomatic TypeScript library.
+
+`@ontrails/library` is a peer surface for plain TypeScript consumers. It reads the same contract that CLI, MCP, and HTTP read, then renders that graph into function calls, package-facing errors, schema exports, and generated package files.
+
+The package is publishable as the runtime dependency for generated Trails libraries. Generated packages can depend on it while keeping their consumer-facing API idiomatic and package-local.
+
+Generated runtime dependencies default to a caret range of the installed compiler's package version, such as `^0.2.0` for a `0.2.0` compiler. Set `libraryDependency` when generating into an owned workspace or choosing a different runtime range.
+
+## API
+
+```ts
+import { compile, deriveLibraryApi, surface } from '@ontrails/library';
+
+const renderingPlan = deriveLibraryApi(app);
+const client = await surface(app);
+const files = compile(app, {
+  appExportName: 'app',
+  appImportPath: '@acme/app',
+  packageName: '@acme/generated',
+});
+```
+
+- `deriveLibraryApi(graph, options)` is the pure derivation. It returns the rendering plan that decides which public trails become library exports, how export names are derived, which trails are excluded, and where export-name collisions exist.
+- `surface(graph, options)` returns an in-memory callable client. The root call lane unwraps `Result.ok` into a return value and maps `Result.err` into typed `LibraryError` subclasses.
+- `compile(graph, options)` returns a stable file plan for a generated package. Writing those files is intentionally a thin apply step outside the compiler.
+
+## Generated package shape
+
+Generated packages use one package with subpath exports:
+
+```text
+.          consumer-fluent root functions and createX factories
+./result   no-throw Result-returning functions
+./schemas  authored Zod schemas and optional schema-owned type aliases
+./trails   the Trails-native topo entrypoint
+```
+
+Stateless trails render to root named exports. Resource-bearing trails render behind a generated `createX(options)` factory so callers can provide resource configuration once and call several related methods from the same client.
+
+Generated root and `/result` subpaths share one internal client module, so importing both subpaths does not open separate root library surfaces.
+
+## Typed signatures
+
+Topo artifacts carry durable contract facts, but they do not preserve erased source-level TypeScript generics. Generated packages therefore stay honest by defaulting method signatures to `unknown` unless the caller binds a rendered trail id to the source trail export that owns its schema types:
+
+```ts
+const files = compile(app, {
+  appExportName: 'app',
+  appImportPath: '../fixture-app',
+  packageName: '@acme/generated',
+  trailTypeExports: {
+    'widget.ping': 'pingTrail',
+  },
+  typeImportPath: '../fixture-trails',
+});
+```
+
+With that binding, `/schemas` emits aliases such as `WidgetPingInput = TrailInput<typeof pingTrail>` and the root and `/result` subpaths use those aliases in their public signatures.
+
+Typed layer inputs are rendered into the same public method input object as trail fields. When a layer field collides with a trail field or reserved surface name, the generated library input uses the same deterministic `<layerName><Field>` rename rule as other object-shaped surfaces. Runtime calls validate the rendered input, strip layer-owned fields before trail validation, and route them to the layer's own input slot. When a source trail type binding is provided, generated signatures widen layer-rendered inputs with `Record<string, unknown>` until layer input type exports have a source-level owner.
+
+## Errors
+
+The root API throws package-facing `LibraryError` subclasses. This is a surface mapping, not an implementation behavior change: implementations still return `Result`.
+
+The `/result` subpath preserves the no-throw envelope:
+
+```ts
+import { widgetPing } from '@acme/generated/result';
+
+const result = await widgetPing(input);
+```
+
+The mapper is built with the shared Trails error taxonomy, so new categories must be covered before the package can typecheck.
+
+## Governance and dogfood
+
+Library-derived facts are embedded in `TopoGraph.library` by Topography. Warden's `library-render-coherence` rule checks that serialized rendering facts do not drift from the graph, including missing target trails and export name collisions.
+
+Run the focused package checks while changing the surface:
+
+```bash
+bun run library:smoke
+bun run library:dogfood:warden
+```
+
+`library:dogfood:warden` compiles the Warden topo into a generated package, typechecks that generated package, runs a generated consumer test through root, `/result`, `/schemas`, and `/trails`, then dry-run packs it.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@ontrails/library",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/outfitter-dev/trails.git",
+    "directory": "packages/library"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test --timeout 30000",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@ontrails/core": "^0.2.0"
+  },
+  "devDependencies": {
+    "@ontrails/testing": "^0.2.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.3.5"
+  }
+}