@ontrails/schema 1.0.0-beta.0

package/dist/hash.js

@@ -0,0 +1,44 @@
+/**
+ * SHA-256 hashing for surface maps.
+ *
+ * Uses Bun.CryptoHasher for native hashing.
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Recursively sort all object keys for deterministic JSON serialization.
+ * Arrays preserve order; primitives pass through.
+ */
+const canonicalize = (value) => {
+    if (Array.isArray(value)) {
+        return value.map(canonicalize);
+    }
+    if (value !== null && typeof value === 'object') {
+        const sorted = {};
+        for (const key of Object.keys(value).toSorted()) {
+            sorted[key] = canonicalize(value[key]);
+        }
+        return sorted;
+    }
+    return value;
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Compute a SHA-256 hash of a surface map.
+ *
+ * The `generatedAt` field is excluded so that identical topos always
+ * produce the same hash regardless of when they were generated.
+ */
+export const hashSurfaceMap = (surfaceMap) => {
+    // Strip generatedAt before hashing
+    const { generatedAt: _unused, ...rest } = surfaceMap;
+    const canonical = canonicalize(rest);
+    const json = JSON.stringify(canonical);
+    const hasher = new Bun.CryptoHasher('sha256');
+    hasher.update(json);
+    return hasher.digest('hex');
+};
+//# sourceMappingURL=hash.js.map

package/dist/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,YAAY,GAAG,CAAC,KAAc,EAAW,EAAE;IAC/C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACjC,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;YAChD,MAAM,CAAC,GAAG,CAAC,GAAG,YAAY,CAAE,KAAiC,CAAC,GAAG,CAAC,CAAC,CAAC;QACtE,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAEF,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,UAAsB,EAAU,EAAE;IAC/D,mCAAmC;IACnC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,UAAU,CAAC;IAErD,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAEvC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC9C,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACpB,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { generateSurfaceMap } from './generate.js';
+export { hashSurfaceMap } from './hash.js';
+export { diffSurfaceMaps } from './diff.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

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,7 @@
+// Generation
+export { generateSurfaceMap } from './generate.js';
+export { hashSurfaceMap } from './hash.js';
+export { diffSurfaceMaps } from './diff.js';
+// File I/O
+export { writeSurfaceMap, readSurfaceMap, writeSurfaceLock, readSurfaceLock, } from './io.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/io.d.ts

@@ -0,0 +1,29 @@
+/**
+ * File I/O for surface maps and lock files.
+ */
+import type { ReadOptions, SurfaceMap, WriteOptions } from './types.js';
+/**
+ * Write a surface map to `<dir>/_surface.json`.
+ *
+ * Creates the directory if it doesn't exist. Returns the file path.
+ */
+export declare const writeSurfaceMap: (surfaceMap: SurfaceMap, options?: WriteOptions) => Promise<string>;
+/**
+ * Read a surface map from `<dir>/_surface.json`.
+ *
+ * Returns `null` if the file doesn't exist.
+ */
+export declare const readSurfaceMap: (options?: ReadOptions) => Promise<SurfaceMap | null>;
+/**
+ * Write a hash to `<dir>/surface.lock` as a single line.
+ *
+ * Creates the directory if it doesn't exist. Returns the file path.
+ */
+export declare const writeSurfaceLock: (hash: string, options?: WriteOptions) => Promise<string>;
+/**
+ * Read the hash from `<dir>/surface.lock`.
+ *
+ * Returns `null` if the file doesn't exist.
+ */
+export declare const readSurfaceLock: (options?: ReadOptions) => Promise<string | null>;
+//# sourceMappingURL=io.d.ts.map

package/dist/io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../src/io.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA8BxE;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAC1B,YAAY,UAAU,EACtB,UAAU,YAAY,KACrB,OAAO,CAAC,MAAM,CAOhB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,GACzB,UAAU,WAAW,KACpB,OAAO,CAAC,UAAU,GAAG,IAAI,CAY3B,CAAC;AAMF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAC3B,MAAM,MAAM,EACZ,UAAU,YAAY,KACrB,OAAO,CAAC,MAAM,CAMhB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,WAAW,KACpB,OAAO,CAAC,MAAM,GAAG,IAAI,CAYvB,CAAC"}

package/dist/io.js

@@ -0,0 +1,91 @@
+/**
+ * File I/O for surface maps and lock files.
+ */
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_DIR = '.trails';
+const SURFACE_MAP_FILE = '_surface.json';
+const SURFACE_LOCK_FILE = 'surface.lock';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const isNotFound = (err) => typeof err === 'object' &&
+    err !== null &&
+    err.code === 'ENOENT';
+const resolveDir = (options) => options?.dir ?? DEFAULT_DIR;
+const ensureDir = async (dir) => {
+    await mkdir(dir, { recursive: true });
+};
+// ---------------------------------------------------------------------------
+// Surface Map
+// ---------------------------------------------------------------------------
+/**
+ * Write a surface map to `<dir>/_surface.json`.
+ *
+ * Creates the directory if it doesn't exist. Returns the file path.
+ */
+export const writeSurfaceMap = async (surfaceMap, options) => {
+    const dir = resolveDir(options);
+    await ensureDir(dir);
+    const filePath = join(dir, SURFACE_MAP_FILE);
+    const json = `${JSON.stringify(surfaceMap, null, 2)}\n`;
+    await Bun.write(filePath, json);
+    return filePath;
+};
+/**
+ * Read a surface map from `<dir>/_surface.json`.
+ *
+ * Returns `null` if the file doesn't exist.
+ */
+export const readSurfaceMap = async (options) => {
+    const dir = resolveDir(options);
+    const filePath = join(dir, SURFACE_MAP_FILE);
+    try {
+        const content = await Bun.file(filePath).text();
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (isNotFound(error)) {
+            return null;
+        }
+        throw error;
+    }
+};
+// ---------------------------------------------------------------------------
+// Surface Lock
+// ---------------------------------------------------------------------------
+/**
+ * Write a hash to `<dir>/surface.lock` as a single line.
+ *
+ * Creates the directory if it doesn't exist. Returns the file path.
+ */
+export const writeSurfaceLock = async (hash, options) => {
+    const dir = resolveDir(options);
+    await ensureDir(dir);
+    const filePath = join(dir, SURFACE_LOCK_FILE);
+    await Bun.write(filePath, `${hash}\n`);
+    return filePath;
+};
+/**
+ * Read the hash from `<dir>/surface.lock`.
+ *
+ * Returns `null` if the file doesn't exist.
+ */
+export const readSurfaceLock = async (options) => {
+    const dir = resolveDir(options);
+    const filePath = join(dir, SURFACE_LOCK_FILE);
+    try {
+        const content = await Bun.file(filePath).text();
+        return content.trim();
+    }
+    catch (error) {
+        if (isNotFound(error)) {
+            return null;
+        }
+        throw error;
+    }
+};
+//# sourceMappingURL=io.js.map

package/dist/io.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Types for surface maps, diffing, and lock files.
+ */
+/** A JSON Schema object produced by zodToJsonSchema. */
+export type JsonSchema = Readonly<Record<string, unknown>>;
+export interface SurfaceMapEntry {
+    readonly id: string;
+    readonly kind: 'trail' | 'hike' | 'event';
+    readonly surfaces: readonly string[];
+    readonly input?: JsonSchema | undefined;
+    readonly output?: JsonSchema | undefined;
+    readonly readOnly?: boolean | undefined;
+    readonly destructive?: boolean | undefined;
+    readonly idempotent?: boolean | undefined;
+    readonly deprecated?: boolean | undefined;
+    readonly replacedBy?: string | undefined;
+    readonly follows?: readonly string[] | undefined;
+    readonly detours?: Readonly<Record<string, readonly string[]>> | undefined;
+    readonly exampleCount: number;
+    readonly description?: string | undefined;
+}
+export interface SurfaceMap {
+    readonly version: string;
+    readonly generatedAt: string;
+    readonly entries: readonly SurfaceMapEntry[];
+}
+export interface DiffEntry {
+    readonly id: string;
+    readonly kind: 'trail' | 'hike' | 'event';
+    readonly change: 'added' | 'removed' | 'modified';
+    readonly severity: 'info' | 'warning' | 'breaking';
+    readonly details: readonly string[];
+}
+export interface DiffResult {
+    readonly entries: readonly DiffEntry[];
+    readonly breaking: readonly DiffEntry[];
+    readonly warnings: readonly DiffEntry[];
+    readonly info: readonly DiffEntry[];
+    readonly hasBreaking: boolean;
+}
+export interface WriteOptions {
+    /** Directory to write to. Defaults to ".trails/" */
+    readonly dir?: string | undefined;
+}
+export interface ReadOptions {
+    /** Directory to read from. Defaults to ".trails/" */
+    readonly dir?: string | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAM3D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;CAC9C;AAMD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,UAAU,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;IACnD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,SAAS,EAAE,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,SAAS,EAAE,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAMD,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Types for surface maps, diffing, and lock files.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@ontrails/schema",
+  "version": "1.0.0-beta.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "peerDependencies": {
+    "@ontrails/core": "workspace:*",
+    "zod": "catalog:"
+  }
+}

package/src/__tests__/diff.test.ts

@@ -0,0 +1,333 @@
+import { describe, test, expect } from 'bun:test';
+
+import { diffSurfaceMaps } from '../diff.js';
+import type { SurfaceMap, SurfaceMapEntry } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const entry = (
+  overrides: Partial<SurfaceMapEntry> & { id: string }
+): SurfaceMapEntry => ({
+  exampleCount: 0,
+  kind: 'trail',
+  surfaces: [],
+  ...overrides,
+});
+
+const surfaceMap = (entries: SurfaceMapEntry[]): SurfaceMap => ({
+  entries,
+  generatedAt: new Date().toISOString(),
+  version: '1.0',
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('diffSurfaceMaps', () => {
+  describe('top-level changes', () => {
+    test('empty diff for identical maps', () => {
+      const e = entry({ id: 'user.create' });
+      const result = diffSurfaceMaps(surfaceMap([e]), surfaceMap([e]));
+
+      expect(result.entries).toHaveLength(0);
+      expect(result.hasBreaking).toBe(false);
+    });
+
+    test('added trail detected as info', () => {
+      const prev = surfaceMap([]);
+      const curr = surfaceMap([entry({ id: 'user.create' })]);
+      const result = diffSurfaceMaps(prev, curr);
+
+      expect(result.entries).toHaveLength(1);
+      expect(result.entries[0]?.change).toBe('added');
+      expect(result.entries[0]?.severity).toBe('info');
+      expect(result.info).toHaveLength(1);
+    });
+
+    test('removed trail detected as breaking', () => {
+      const prev = surfaceMap([entry({ id: 'user.delete' })]);
+      const curr = surfaceMap([]);
+      const result = diffSurfaceMaps(prev, curr);
+
+      expect(result.entries).toHaveLength(1);
+      expect(result.entries[0]?.change).toBe('removed');
+      expect(result.entries[0]?.severity).toBe('breaking');
+      expect(result.hasBreaking).toBe(true);
+    });
+
+    test('DiffResult.hasBreaking is true when any breaking entries exist', () => {
+      const prev = surfaceMap([entry({ id: 'user.delete' })]);
+      const curr = surfaceMap([]);
+      const result = diffSurfaceMaps(prev, curr);
+
+      expect(result.hasBreaking).toBe(true);
+      expect(result.breaking.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('schema changes', () => {
+    test('required input field added classified as breaking', () => {
+      const prev = surfaceMap([
+        entry({
+          id: 'user.create',
+          input: {
+            properties: { name: { type: 'string' } },
+            required: ['name'],
+            type: 'object',
+          },
+        }),
+      ]);
+      const curr = surfaceMap([
+        entry({
+          id: 'user.create',
+          input: {
+            properties: {
+              name: { type: 'string' },
+              type: { type: 'string' },
+            },
+            required: ['name', 'type'],
+            type: 'object',
+          },
+        }),
+      ]);
+      const result = diffSurfaceMaps(prev, curr);
+
+      expect(result.hasBreaking).toBe(true);
+      expect(result.breaking).toHaveLength(1);
+      const [breakingEntry] = result.breaking;
+      expect(breakingEntry).toBeDefined();
+      expect(
+        breakingEntry?.details.some((d) =>
+          d.includes('Required input field "type" added')
+        )
+      ).toBe(true);
+    });
+
+    test('optional input field added classified as info', () => {
+      const prev = surfaceMap([
+        entry({
+          id: 'user.create',
+          input: {
+            properties: { name: { type: 'string' } },
+            required: ['name'],
+            type: 'object',
+          },
+        }),
+      ]);
+      const curr = surfaceMap([
+        entry({
+          id: 'user.create',
+          input: {
+            properties: {
+              filter: { type: 'string' },
+              name: { type: 'string' },
+            },
+            required: ['name'],
+            type: 'object',
+          },
+        }),
+      ]);
+      const result = diffSurfaceMaps(prev, curr);
+
+      expect(result.info).toHaveLength(1);
+      const [infoEntry] = result.info;
+      expect(infoEntry).toBeDefined();
+      expect(
+        infoEntry?.details.some((d) =>
+          d.includes('Optional input field "filter" added')
+        )
+      ).toBe(true);
+    });
+
+    test('output field removed classified as breaking', () => {
+      const prev = surfaceMap([
+        entry({
+          id: 'user.get',
+          output: {
+            properties: {
+              id: { type: 'string' },
+              name: { type: 'string' },
+            },
+            type: 'object',
+          },
+        }),
+      ]);
+      const curr = surfaceMap([
+        entry({
+          id: 'user.get',
+          output: {
+            properties: {
+              id: { type: 'string' },
+            },
+            type: 'object',
+          },
+        }),
+      ]);
+      const result = diffSurfaceMaps(prev, curr);
+
+      expect(result.hasBreaking).toBe(true);
+      expect(
+        result.breaking[0]?.details.some((d) =>
+          d.includes('Output field "name" removed')
+        )
+      ).toBe(true);
+    });
+
+    test('output field type changed classified as breaking', () => {
+      const prev = surfaceMap([
+        entry({
+          id: 'user.get',
+          output: {
+            properties: { count: { type: 'number' } },
+            type: 'object',
+          },
+        }),
+      ]);
+      const curr = surfaceMap([
+        entry({
+          id: 'user.get',
+          output: {
+            properties: { count: { type: 'string' } },
+            type: 'object',
+          },
+        }),
+      ]);
+      const result = diffSurfaceMaps(prev, curr);
+
+      expect(result.hasBreaking).toBe(true);
+      expect(
+        result.breaking[0]?.details.some((d) =>
+          d.includes('Output field "count" type changed: number -> string')
+        )
+      ).toBe(true);
+    });
+  });
+
+  describe('metadata and surfaces', () => {
+    test('surface removed classified as breaking', () => {
+      const prev = surfaceMap([
+        entry({ id: 'user.list', surfaces: ['cli', 'mcp'] }),
+      ]);
+      const curr = surfaceMap([entry({ id: 'user.list', surfaces: ['mcp'] })]);
+      const result = diffSurfaceMaps(prev, curr);
+
+      expect(result.hasBreaking).toBe(true);
+      expect(
+        result.breaking[0]?.details.some((d) =>
+          d.includes('Surface "cli" removed')
+        )
+      ).toBe(true);
+    });
+
+    test('safety marker changed classified as warning', () => {
+      const prev = surfaceMap([entry({ id: 'data.wipe', readOnly: true })]);
+      const curr = surfaceMap([entry({ id: 'data.wipe', readOnly: false })]);
+      const result = diffSurfaceMaps(prev, curr);
+
+      expect(result.warnings).toHaveLength(1);
+      expect(
+        result.warnings[0]?.details.some((d) => d.includes('readOnly changed'))
+      ).toBe(true);
+    });
+
+    test('description change classified as info', () => {
+      const prev = surfaceMap([
+        entry({ description: 'Get a user', id: 'user.get' }),
+      ]);
+      const curr = surfaceMap([
+        entry({ description: 'Fetch a user by ID', id: 'user.get' }),
+      ]);
+      const result = diffSurfaceMaps(prev, curr);
+
+      expect(result.info).toHaveLength(1);
+      expect(
+        result.info[0]?.details.some((d) => d.includes('Description updated'))
+      ).toBe(true);
+    });
+
+    test('deprecation added classified as warning', () => {
+      const prev = surfaceMap([entry({ id: 'entity.list' })]);
+      const curr = surfaceMap([
+        entry({
+          deprecated: true,
+          id: 'entity.list',
+          replacedBy: 'entity.show',
+        }),
+      ]);
+      const result = diffSurfaceMaps(prev, curr);
+
+      expect(result.warnings).toHaveLength(1);
+      expect(
+        result.warnings[0]?.details.some((d) =>
+          d.includes('Deprecated (replaced by entity.show)')
+        )
+      ).toBe(true);
+    });
+
+    test('follows changed produces warning', () => {
+      const prev = surfaceMap([
+        entry({
+          follows: ['user.get', 'user.lookup'],
+          id: 'user.update',
+          kind: 'hike',
+        }),
+      ]);
+      const curr = surfaceMap([
+        entry({
+          follows: ['user.get', 'user.search'],
+          id: 'user.update',
+          kind: 'hike',
+        }),
+      ]);
+      const result = diffSurfaceMaps(prev, curr);
+
+      expect(result.warnings).toHaveLength(1);
+      const followsDetail = result.warnings[0]?.details.find((d) =>
+        d.includes('Follows changed')
+      );
+      expect(followsDetail).toBeDefined();
+      expect(followsDetail).toContain('search');
+      expect(followsDetail).toContain('lookup');
+    });
+  });
+
+  describe('severity partitioning', () => {
+    test('DiffResult partitions correctly into breaking, warnings, info', () => {
+      const prev = surfaceMap([
+        entry({
+          description: 'old',
+          id: 'a.trail',
+          output: {
+            properties: { removed: { type: 'string' } },
+            type: 'object',
+          },
+          readOnly: true,
+        }),
+      ]);
+      const curr = surfaceMap([
+        entry({
+          description: 'new',
+          id: 'a.trail',
+          output: {
+            properties: {},
+            type: 'object',
+          },
+          readOnly: false,
+        }),
+        entry({ id: 'b.trail' }),
+      ]);
+      const result = diffSurfaceMaps(prev, curr);
+
+      expect(result.entries.length).toBeGreaterThanOrEqual(2);
+
+      const modifiedEntry = result.entries.find((e) => e.id === 'a.trail');
+      expect(modifiedEntry?.severity).toBe('breaking');
+
+      const addedEntry = result.entries.find((e) => e.id === 'b.trail');
+      expect(addedEntry?.severity).toBe('info');
+    });
+  });
+});