@ontrails/library 1.0.0-beta.24

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @ontrails/library
+
+## 1.0.0-beta.24
+
+Initial prerelease changelog for the library surface package.

package/README.md

@@ -0,0 +1,87 @@
+# @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 projects 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.
+
+## API
+
+```ts
+import { compile, deriveLibraryApi, surface } from '@ontrails/library';
+
+const projection = 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 projection. It 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 project to root named exports. Resource-bearing trails project 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 projected 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 projected 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 projected 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-projected 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 a blaze behavior change: blazes 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 projection facts are embedded in `TopoGraph.library` by Topographer. Warden's `library-projection-coherence` rule checks that serialized projection 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,33 @@
+{
+  "name": "@ontrails/library",
+  "version": "1.0.0-beta.24",
+  "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": "^1.0.0-beta.24"
+  },
+  "devDependencies": {
+    "@ontrails/testing": "^1.0.0-beta.24"
+  },
+  "peerDependencies": {
+    "zod": "^4.3.5"
+  }
+}

package/src/compile.ts

@@ -0,0 +1,506 @@
+/**
+ * `compile` — the package emitter. Consumes the `LibraryProjection` (never the
+ * topo directly) and produces the source files of a generated TypeScript
+ * package: consumer-fluent root, `/result`, `/schemas`, `/trails` subpaths.
+ *
+ * v0 is runtime-backed: the generated package imports the source topo and the
+ * `@ontrails/library` runtime (the kernel seam), so execution delegates to the
+ * shared pipeline. The standalone trajectory (vendoring the kernel) does not
+ * change consumer code — see the runtime-kernel section of the ADR.
+ *
+ * This slice returns the file plan (path + content); writing it to disk is a
+ * thin apply step. Pure: derives the projection and builds strings, no I/O.
+ */
+import { deriveLibraryApi } from './derive.js';
+import type {
+  DeriveLibraryApiOptions,
+  LibraryExport,
+  LibraryProjection,
+} from './derive.js';
+import type { Topo } from './kernel.js';
+
+/** Options for emitting a generated library package. */
+export interface CompileOptions extends DeriveLibraryApiOptions {
+  /** The generated package name (e.g. `@acme/core`). */
+  readonly packageName: string;
+  /** Import specifier the generated code uses to reach the source topo. */
+  readonly appImportPath: string;
+  /** The exported binding name of the topo at `appImportPath` (default `app`). */
+  readonly appExportName?: string;
+  /** Runtime dependency range for `@ontrails/library` in emitted package.json. */
+  readonly libraryDependency?: string;
+  /** Generated package version. Defaults to `0.0.0`. */
+  readonly version?: string;
+  /** Peer dependency range for Zod in emitted package.json. */
+  readonly zodDependency?: string;
+  /**
+   * Import specifier for source trail type bindings. Defaults to
+   * `appImportPath` when `trailTypeExports` is provided.
+   */
+  readonly typeImportPath?: string;
+  /**
+   * Optional mapping from projected trail id to the source module export that
+   * owns that trail's TypeScript type. Unmapped trails intentionally keep
+   * `unknown` public signatures instead of pretending topo artifacts preserve
+   * erased source types.
+   */
+  readonly trailTypeExports?: Readonly<Record<string, string>>;
+}
+
+/** A single emitted file: project-relative path and full contents. */
+export interface CompiledFile {
+  readonly path: string;
+  readonly content: string;
+}
+
+/** The result of compiling a topo into a generated library package. */
+export interface CompileResult {
+  readonly packageName: string;
+  /** The resolved projection the files were emitted from. */
+  readonly projection: LibraryProjection;
+  /** The emitted files, in stable path order. */
+  readonly files: readonly CompiledFile[];
+}
+
+const pascalCase = (value: string): string =>
+  value
+    .split(/[.\-_]/u)
+    .filter((word) => word.length > 0)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join('');
+
+const isStateless = (entry: LibraryExport): boolean =>
+  entry.resources.length === 0;
+
+const statelessExports = (
+  projection: LibraryProjection
+): readonly LibraryExport[] => projection.exports.filter(isStateless);
+
+const resourceExports = (
+  projection: LibraryProjection
+): readonly LibraryExport[] =>
+  projection.exports.filter((entry) => !isStateless(entry));
+
+const factoryName = (projection: LibraryProjection): string =>
+  `create${pascalCase(projection.app)}`;
+
+const DEFAULT_LIBRARY_DEPENDENCY = '^1.0.0';
+const DEFAULT_ZOD_DEPENDENCY = '^4.3.5';
+
+const sanitizeJsDocLine = (value: string): string =>
+  value.replaceAll('*/', '* /').trim();
+
+const jsDoc = (lines: readonly string[], indent = ''): string =>
+  [
+    `${indent}/**`,
+    ...lines
+      .map(sanitizeJsDocLine)
+      .filter((line) => line.length > 0)
+      .map((line) => `${indent} * ${line}`),
+    `${indent} */`,
+  ].join('\n');
+
+const exportDescription = (entry: LibraryExport): string =>
+  entry.description ?? `Call the \`${entry.trailId}\` trail.`;
+
+const IDENTIFIER_PATTERN = /^[A-Za-z_$][\w$]*$/u;
+
+interface ExportTypeBinding {
+  readonly input: string;
+  readonly output: string;
+  readonly sourceExport: string;
+}
+
+type TypeBindings = ReadonlyMap<string, ExportTypeBinding>;
+
+const typeNamesFor = (
+  entry: LibraryExport
+): Pick<ExportTypeBinding, 'input' | 'output'> => {
+  const base = pascalCase(entry.exportName);
+  return { input: `${base}Input`, output: `${base}Output` };
+};
+
+const resolveTypeBindings = (
+  projection: LibraryProjection,
+  options: CompileOptions
+): TypeBindings => {
+  const configured = options.trailTypeExports ?? {};
+  const bindings = new Map<string, ExportTypeBinding>();
+  for (const entry of projection.exports) {
+    const sourceExport = configured[entry.trailId];
+    if (!sourceExport) {
+      continue;
+    }
+    if (!IDENTIFIER_PATTERN.test(sourceExport)) {
+      throw new Error(
+        `trailTypeExports["${entry.trailId}"] must be an exported identifier`
+      );
+    }
+    bindings.set(entry.trailId, { ...typeNamesFor(entry), sourceExport });
+  }
+  return bindings;
+};
+
+const inputTypeFor = (entry: LibraryExport, bindings: TypeBindings): string => {
+  const input = bindings.get(entry.trailId)?.input;
+  if (entry.layerInputs.length === 0) {
+    return input ?? 'unknown';
+  }
+  return input === undefined
+    ? 'Record<string, unknown>'
+    : `${input} & Record<string, unknown>`;
+};
+
+const outputTypeFor = (entry: LibraryExport, bindings: TypeBindings): string =>
+  bindings.get(entry.trailId)?.output ?? 'unknown';
+
+const schemaTypeImport = (
+  projection: LibraryProjection,
+  bindings: TypeBindings
+): string | undefined => {
+  const names = projection.exports.flatMap((entry) => {
+    const binding = bindings.get(entry.trailId);
+    return binding ? [binding.input, binding.output] : [];
+  });
+  if (names.length === 0) {
+    return undefined;
+  }
+  return `import type { ${names.join(', ')} } from './schemas.js';`;
+};
+
+const generatePackageJson = (options: CompileOptions): string => {
+  const manifest = {
+    dependencies: {
+      '@ontrails/library':
+        options.libraryDependency ?? DEFAULT_LIBRARY_DEPENDENCY,
+      zod: options.zodDependency ?? DEFAULT_ZOD_DEPENDENCY,
+    },
+    exports: {
+      '.': './src/index.ts',
+      './package.json': './package.json',
+      './result': './src/result.ts',
+      './schemas': './src/schemas.ts',
+      './trails': './src/trails.ts',
+    },
+    name: options.packageName,
+    type: 'module',
+    version: options.version ?? '0.0.0',
+  };
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+};
+
+const statelessFunction = (
+  entry: LibraryExport,
+  bindings: TypeBindings
+): string =>
+  [
+    jsDoc([
+      exportDescription(entry),
+      `Projects trail \`${entry.trailId}\` as a stateless library function.`,
+    ]),
+    `export const ${entry.exportName} = (`,
+    `  input: ${inputTypeFor(entry, bindings)}`,
+    `): Promise<${outputTypeFor(entry, bindings)}> =>`,
+    '  // The runtime validates declared output schemas before this unwrap returns.',
+    `  rootClient.call.${entry.exportName}(input) as Promise<${outputTypeFor(entry, bindings)}>;`,
+  ].join('\n');
+
+const factoryMethod = (entry: LibraryExport, bindings: TypeBindings): string =>
+  [
+    jsDoc(
+      [
+        exportDescription(entry),
+        `Projects trail \`${entry.trailId}\` behind the resource client.`,
+      ],
+      '    '
+    ),
+    `    ${entry.exportName}: (`,
+    `      input: ${inputTypeFor(entry, bindings)}`,
+    `    ): Promise<${outputTypeFor(entry, bindings)}> =>`,
+    '      // The runtime validates declared output schemas before this unwrap returns.',
+    `      client.call.${entry.exportName}(input) as Promise<${outputTypeFor(entry, bindings)}>,`,
+  ].join('\n');
+
+const generateIndex = (
+  projection: LibraryProjection,
+  bindings: TypeBindings
+): string => {
+  const stateless = statelessExports(projection);
+  const resourceful = resourceExports(projection);
+  const typedSchemas = schemaTypeImport(projection, bindings);
+
+  const parts: string[] = [
+    "import type { SurfaceLibraryOptions } from '@ontrails/library';",
+    ...(typedSchemas ? [typedSchemas] : []),
+    '',
+    "import { createClient, rootClient } from './client.js';",
+  ];
+
+  for (const entry of stateless) {
+    parts.push('', statelessFunction(entry, bindings));
+  }
+
+  if (resourceful.length > 0) {
+    parts.push(
+      '',
+      `export const ${factoryName(projection)} = async (`,
+      '  options: SurfaceLibraryOptions = {}',
+      ') => {',
+      '  const client = await createClient(options);',
+      '  return {',
+      resourceful.map((entry) => factoryMethod(entry, bindings)).join('\n'),
+      '  };',
+      '};'
+    );
+  }
+
+  return `${parts.join('\n')}\n`;
+};
+
+const generateClient = (): string =>
+  [
+    "import { surface } from '@ontrails/library';",
+    "import type { SurfaceLibraryOptions } from '@ontrails/library';",
+    '',
+    `import { app } from './trails.js';`,
+    '',
+    'export const rootClient = await surface(app);',
+    'export const createClient = (options: SurfaceLibraryOptions = {}) =>',
+    '  surface(app, options);',
+    '',
+  ].join('\n');
+
+const generateSchemas = (
+  projection: LibraryProjection,
+  options: CompileOptions,
+  bindings: TypeBindings
+): string => {
+  const appExport = 'app';
+  const typedEntries = projection.exports.filter((entry) =>
+    bindings.has(entry.trailId)
+  );
+  const sourceTypeExports = [
+    ...new Set(
+      typedEntries.map((entry) => {
+        const binding = bindings.get(entry.trailId);
+        if (binding === undefined) {
+          throw new Error(`missing type binding for trail "${entry.trailId}"`);
+        }
+        return binding.sourceExport;
+      })
+    ),
+  ].toSorted((left, right) => left.localeCompare(right));
+  const lines = [
+    `import { ${appExport} } from './trails.js';`,
+    "import { deriveLibraryApi } from '@ontrails/library';",
+    ...(typedEntries.length > 0
+      ? [
+          "import type { TrailInput, TrailOutput } from '@ontrails/library';",
+          `import type { ${sourceTypeExports.join(', ')} } from '${options.typeImportPath ?? options.appImportPath}';`,
+        ]
+      : []),
+    '',
+    '// Authored Zod schemas, keyed by export name, projected from the topo.',
+    'const projection = deriveLibraryApi(app);',
+    'const byName = new Map(',
+    '  projection.exports.map((entry) => [entry.exportName, entry])',
+    ');',
+    '',
+    'const requireExport = (name: string) => {',
+    '  const entry = byName.get(name);',
+    '  if (!entry) {',
+    "    throw new Error('missing projected library export: ' + name);",
+    '  }',
+    '  return entry;',
+    '};',
+    '',
+  ];
+  for (const entry of projection.exports) {
+    const binding = bindings.get(entry.trailId);
+    if (binding) {
+      lines.push(
+        '',
+        `export type ${binding.input} = TrailInput<typeof ${binding.sourceExport}>;`,
+        `export type ${binding.output} = TrailOutput<typeof ${binding.sourceExport}>;`
+      );
+    }
+    lines.push(
+      '',
+      jsDoc([
+        `Authored input schema for \`${entry.trailId}\`, exported as \`${entry.exportName}\`.`,
+      ]),
+      `export const ${entry.exportName}InputSchema = requireExport('${entry.exportName}').input;`,
+      '',
+      jsDoc([
+        `Authored output schema for \`${entry.trailId}\`, if the trail declares one.`,
+      ]),
+      `export const ${entry.exportName}OutputSchema = requireExport('${entry.exportName}').output;`
+    );
+  }
+  lines.push('', 'export const schemas = {');
+  for (const entry of projection.exports) {
+    lines.push(
+      `  ${entry.exportName}: {`,
+      `    input: ${entry.exportName}InputSchema,`,
+      `    output: ${entry.exportName}OutputSchema,`,
+      '  },'
+    );
+  }
+  lines.push('} as const;');
+  return `${lines.join('\n')}\n`;
+};
+
+const generateTrails = (options: CompileOptions): string => {
+  const appExport = options.appExportName ?? 'app';
+  return [
+    '// Full Trails-native entrypoint: the resolved topo for composition,',
+    '// contract tests, and graph inspection.',
+    `export { ${appExport} as app } from '${options.appImportPath}';`,
+    '',
+  ].join('\n');
+};
+
+const resultStatelessFunction = (
+  entry: LibraryExport,
+  bindings: TypeBindings
+): string =>
+  [
+    jsDoc([
+      exportDescription(entry),
+      `Returns the raw Result boundary for trail \`${entry.trailId}\`.`,
+    ]),
+    `export const ${entry.exportName} = (`,
+    `  input: ${inputTypeFor(entry, bindings)}`,
+    `): Promise<Result<${outputTypeFor(entry, bindings)}, LibraryError>> =>`,
+    '  // The runtime validates declared output schemas before this Result resolves.',
+    `  resultClient.result.${entry.exportName}(input) as Promise<Result<${outputTypeFor(entry, bindings)}, LibraryError>>;`,
+  ].join('\n');
+
+const resultFactoryMethod = (
+  entry: LibraryExport,
+  bindings: TypeBindings
+): string =>
+  [
+    jsDoc(
+      [
+        exportDescription(entry),
+        `Returns the raw Result boundary for trail \`${entry.trailId}\`.`,
+      ],
+      '    '
+    ),
+    `    ${entry.exportName}: (`,
+    `      input: ${inputTypeFor(entry, bindings)}`,
+    `    ): Promise<Result<${outputTypeFor(entry, bindings)}, LibraryError>> =>`,
+    '      // The runtime validates declared output schemas before this Result resolves.',
+    `      client.result.${entry.exportName}(input) as Promise<Result<${outputTypeFor(entry, bindings)}, LibraryError>>,`,
+  ].join('\n');
+
+const generateResult = (
+  projection: LibraryProjection,
+  bindings: TypeBindings
+): string => {
+  const stateless = statelessExports(projection);
+  const resourceful = resourceExports(projection);
+  const typedSchemas = schemaTypeImport(projection, bindings);
+  const parts = [
+    '// No-throw API: returns the Result envelope instead of unwrapping.',
+    "import { runLibraryResult } from '@ontrails/library';",
+    "import type { LibraryError, Result, SurfaceLibraryOptions } from '@ontrails/library';",
+    ...(typedSchemas ? [typedSchemas] : []),
+    '',
+    "import { createClient, rootClient } from './client.js';",
+    "import { app } from './trails.js';",
+    '',
+    'const resultClient = rootClient;',
+  ];
+
+  for (const entry of stateless) {
+    parts.push('', resultStatelessFunction(entry, bindings));
+  }
+
+  if (resourceful.length > 0) {
+    parts.push(
+      '',
+      `export const ${factoryName(projection)} = async (`,
+      '  options: SurfaceLibraryOptions = {}',
+      ') => {',
+      '  const client = await createClient(options);',
+      '  return {',
+      resourceful
+        .map((entry) => resultFactoryMethod(entry, bindings))
+        .join('\n'),
+      '  };',
+      '};'
+    );
+  }
+
+  parts.push(
+    '',
+    'export const call = (',
+    '  id: string,',
+    '  input: unknown,',
+    '  options: SurfaceLibraryOptions = {}',
+    ') => runLibraryResult(app, id, input, options);',
+    ''
+  );
+
+  return `${parts.join('\n')}\n`;
+};
+
+const generateTsconfig = (): string =>
+  `${JSON.stringify(
+    {
+      compilerOptions: {
+        module: 'preserve',
+        moduleResolution: 'bundler',
+        strict: true,
+        target: 'esnext',
+      },
+      include: ['src'],
+    },
+    null,
+    2
+  )}\n`;
+
+/**
+ * Compile a topo into a generated library package. Returns the emitted file
+ * plan; the resolved projection is included for inspection and governance.
+ *
+ * @example
+ * const result = compile(app, {
+ *   packageName: '@acme/core',
+ *   appImportPath: '@acme/app',
+ * });
+ * for (const file of result.files) {
+ *   console.log(file.path);
+ * }
+ */
+export const compile = (
+  graph: Topo,
+  options: CompileOptions
+): CompileResult => {
+  const projection = deriveLibraryApi(graph, options);
+  const typeBindings = resolveTypeBindings(projection, options);
+  const files: CompiledFile[] = [
+    { content: generatePackageJson(options), path: 'package.json' },
+    { content: generateTsconfig(), path: 'tsconfig.json' },
+    {
+      content: generateClient(),
+      path: 'src/client.ts',
+    },
+    {
+      content: generateIndex(projection, typeBindings),
+      path: 'src/index.ts',
+    },
+    {
+      content: generateResult(projection, typeBindings),
+      path: 'src/result.ts',
+    },
+    {
+      content: generateSchemas(projection, options, typeBindings),
+      path: 'src/schemas.ts',
+    },
+    { content: generateTrails(options), path: 'src/trails.ts' },
+  ];
+  return { files, packageName: options.packageName, projection };
+};