@ontrails/schema 1.0.0-beta.0 → 1.0.0-beta.1

package/.turbo/turbo-lint.log

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

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @ontrails/schema
 
+## 1.0.0-beta.1
+
+### Patch Changes
+
+- Fix two blocking bugs from real-world migration:
+  - Published packages now resolve correctly (workspace:^ instead of workspace:\*)
+  - Error forwarding works across different success types (Err no longer carries phantom T)
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.1
+
 ## 1.0.0-beta.0
 
 ### Minor Changes

package/README.md

@@ -1,131 +1,63 @@
 # @ontrails/schema
 
-Surface maps, diffing, and lock files for Trails. The machine-readable contract for CI and governance.
+Surface maps, hashing, and semantic diffing for Trails. Generate a machine-readable snapshot of your topo, hash it into a lock file, and detect breaking changes before they ship.
 
-## Installation
-
-```bash
-bun add -d @ontrails/schema
-```
-
-Peer dependencies: `@ontrails/core`, `zod`.
-
-## Quick Start
+## Usage
 
 ```typescript
-import {
-  generateSurfaceMap,
-  hashSurfaceMap,
-  diffSurfaceMaps,
-} from '@ontrails/schema';
+import { generateSurfaceMap, hashSurfaceMap, diffSurfaceMaps } from '@ontrails/schema';
 
-// Generate the surface map from the topo
-const surfaceMap = generateSurfaceMap(app);
+const map = generateSurfaceMap(app);
+const hash = hashSurfaceMap(map);
 
-// Hash it for the lock file
-const hash = hashSurfaceMap(surfaceMap);
+// Later, after changes:
+const newMap = generateSurfaceMap(app);
+const diff = diffSurfaceMaps(map, newMap);
 
-// Diff two surface maps
-const diff = diffSurfaceMaps(previousMap, surfaceMap);
 if (diff.hasBreaking) {
-  console.error('Breaking changes detected:', diff.breaking);
+  console.error('Breaking changes:', diff.breaking);
 }
 ```
 
-## API Overview
-
-### `generateSurfaceMap(topo)`
-
-Produces a deterministic manifest of every trail in the topo. Entries are sorted alphabetically by ID. Input and output schemas are converted to JSON Schema via `zodToJsonSchema()`.
-
-```typescript
-const map = generateSurfaceMap(app);
-// {
-//   version: "1.0",
-//   generatedAt: "2026-03-25T10:00:00.000Z",
-//   entries: [
-//     { id: "entity.show", kind: "trail", input: {...}, readOnly: true, exampleCount: 2 },
-//     { id: "search", kind: "trail", input: {...}, exampleCount: 1 },
-//   ]
-// }
-```
-
-Each `SurfaceMapEntry` includes:
-
-- `id`, `kind` (`"trail"` | `"hike"` | `"event"`)
-- `input` and `output` as JSON Schema
-- Safety markers: `readOnly`, `destructive`, `idempotent`
-- `deprecated`, `replacedBy`
-- `follows` (for hikes), `detours`
-- `exampleCount`, `description`
-
-### `hashSurfaceMap(surfaceMap)`
+The surface map captures every trail's input/output schemas (as JSON Schema), safety markers, follows graph, and example counts. The hash goes into `surface.lock` -- a single committed line that CI can check for drift.
 
-SHA-256 hash of the surface map content. Excludes `generatedAt` so the same topo always produces the same hash byte-for-byte.
+## API
 
-```typescript
-const hash = hashSurfaceMap(map); // "a1b2c3d4..."
-```
+| Export | What it does |
+| --- | --- |
+| `generateSurfaceMap(topo)` | Deterministic manifest of every trail, sorted by ID |
+| `hashSurfaceMap(map)` | SHA-256 hash, excluding timestamps for stability |
+| `diffSurfaceMaps(prev, curr)` | Semantic diff with breaking/warning/info severity |
+| `writeSurfaceMap(map, options?)` | Write `.trails/_surface.json` (gitignored detail file) |
+| `readSurfaceMap(options?)` | Read it back |
+| `writeSurfaceLock(hash, options?)` | Write `surface.lock` (committed, single hash line) |
+| `readSurfaceLock(options?)` | Read the lock hash |
 
-### `diffSurfaceMaps(prev, curr)`
+See the [API Reference](../../docs/api-reference.md) for the full list.
 
-Semantic diff between two surface maps. Classifies every change by severity instead of producing raw JSON diffs.
+## Breaking change detection
 
-```typescript
-const diff = diffSurfaceMaps(previousMap, currentMap);
-
-diff.entries; // All changes
-diff.breaking; // Breaking changes only
-diff.warnings; // Warnings only
-diff.info; // Informational changes
-diff.hasBreaking; // Quick check
-```
+The diff classifies every change by severity:
 
-**Breaking change detection:**
-
-| Change                     | Severity |
-| -------------------------- | -------- |
-| Trail removed              | breaking |
+| Change | Severity |
+| --- | --- |
+| Trail removed | breaking |
 | Required input field added | breaking |
-| Input field removed        | breaking |
-| Output field removed       | breaking |
-| Output field type changed  | breaking |
-| Surface removed            | breaking |
-| Safety marker changed      | warning  |
-| Trail deprecated           | warning  |
-| Follows changed            | warning  |
-| Trail added                | info     |
-| Optional input field added | info     |
-| Output field added         | info     |
-| Surface added              | info     |
-
-### Lock File I/O
-
-```typescript
-import {
-  writeSurfaceMap, // .trails/_surface.json (gitignored detail file)
-  readSurfaceMap, // Read it back
-  writeSurfaceLock, // surface.lock (committed, single hash line)
-  readSurfaceLock, // Read the lock hash
-} from '@ontrails/schema';
-```
+| Input/output field removed | breaking |
+| Output field type changed | breaking |
+| Safety marker changed | warning |
+| Trail deprecated | warning |
+| Follows changed | warning |
+| Trail added | info |
+| Optional input field added | info |
+| Output field added | info |
 
-Default directory: `.trails/`. Override with `{ dir: "./custom" }`.
-
-- `_surface.json` -- Full surface map, gitignored. For local inspection and debugging.
-- `surface.lock` -- Single-line SHA-256 hash, committed to the repo. Source of truth for drift detection.
-
-## Usage with Warden
+## Drift detection with warden
 
 ```typescript
-import {
-  generateSurfaceMap,
-  hashSurfaceMap,
-  readSurfaceLock,
-} from '@ontrails/schema';
+import { generateSurfaceMap, hashSurfaceMap, readSurfaceLock } from '@ontrails/schema';
 
-const map = generateSurfaceMap(app);
-const current = hashSurfaceMap(map);
+const current = hashSurfaceMap(generateSurfaceMap(app));
 const committed = await readSurfaceLock();
 
 if (committed !== current) {
@@ -133,7 +65,10 @@ if (committed !== current) {
 }
 ```
 
-## Further Reading
+The `@ontrails/warden` package wraps this into a `checkDrift()` call with CI integration.
+
+## Installation
 
-- [Architecture](../../docs/architecture.md)
-- [Testing Guide](../../docs/testing.md)
+```bash
+bun add -d @ontrails/schema
+```

package/package.json

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