@ontrails/library 0.2.0

package/src/derive.ts

@@ -0,0 +1,207 @@
+/**
+ * `deriveLibraryApi` — the pure rendering from a topo to a `LibraryRenderingPlan`.
+ *
+ * This is the single semantic authority for the library surface: trail
+ * selection, export naming, collision resolution, and the per-export contract
+ * data the emitter renders all live here. The in-memory surface and the package
+ * emitter both consume the rendering; neither re-reads the topo nor reinvents
+ * selection. Pure — no fs/network/db reads (derive* purity contract).
+ */
+import { filterSurfaceTrails, isDraftId } from '@ontrails/core';
+import type { Layer, Topo, Trail } from '@ontrails/core';
+import type { ZodType } from 'zod';
+
+import { renderLibraryInput } from './layer-input.js';
+import type { LibraryLayerInputRendering } from './layer-input.js';
+
+type AnyTrail = Trail<unknown, unknown, unknown>;
+
+/** Where a rendered export name came from. */
+export type LibraryExportSource = 'derived' | 'trail-hint' | 'package-config';
+
+/** A single rendered export: one trail rendered as a library entrypoint. */
+export interface LibraryExport {
+  /** Consumer-native export name (camelCased trail id by default). */
+  readonly exportName: string;
+  /** The trail id this export renders (the source of truth). */
+  readonly trailId: string;
+  /** How `exportName` was chosen. v0 derives; hints/config override later. */
+  readonly nameSource: LibraryExportSource;
+  /**
+   * Authored intent, carried for safety presets and docs. Always present —
+   * core resolves an unset intent to `'write'`, so there is no fallback here.
+   */
+  readonly intent: 'read' | 'write' | 'destroy';
+  /** Current version for versioned trails; undefined when unversioned. */
+  readonly version: number | undefined;
+  /** Trail description — the JSDoc source the emitter carries forward. */
+  readonly description: string | undefined;
+  /**
+   * Input schema reference: the emitter's method-signature and `/schemas`
+   * source. An in-memory Zod reference here; it serializes to JSON Schema when
+   * the rendering is persisted to the artifact family.
+   */
+  readonly input: ZodType;
+  /** Layer input routing rendered onto this export's public library input. */
+  readonly layerInputs: readonly LibraryLayerInputRendering[];
+  /** Output schema reference, when the trail declares one. */
+  readonly output: ZodType | undefined;
+  /**
+   * Resource ids this export depends on. Empty means a stateless function
+   * export; non-empty means the emitter renders the export behind a
+   * `createX()` factory/client, grouped by shared resources. Carrying ids (not
+   * just a boolean) keeps the factory-grouping decision in this authority.
+   */
+  readonly resources: readonly string[];
+}
+
+/** Why a trail did not render into the library (doctrinally-meaningful only). */
+export type LibraryExclusionReason = 'internal' | 'draft' | 'activation';
+
+/**
+ * A trail deliberately excluded from the rendering, recorded for legibility.
+ * `reason` is the primary (first-matched) reason in precedence order
+ * draft > activation > internal; a trail may technically satisfy more than one.
+ */
+export interface LibraryExclusion {
+  readonly trailId: string;
+  readonly reason: LibraryExclusionReason;
+}
+
+/** Two or more trails deriving the same export name. */
+export interface LibraryCollision {
+  readonly exportName: string;
+  readonly trailIds: readonly string[];
+}
+
+/** The resolved library rendering — the story of a topo as a TypeScript library. */
+export interface LibraryRenderingPlan {
+  /** The topo name. */
+  readonly app: string;
+  /** Rendered exports, in stable (trail-id-sorted) order. */
+  readonly exports: readonly LibraryExport[];
+  /** Trails excluded by visibility, draft state, or activation. */
+  readonly excluded: readonly LibraryExclusion[];
+  /** Export-name collisions; first-by-id wins in `exports`, all recorded here. */
+  readonly collisions: readonly LibraryCollision[];
+}
+
+/**
+ * Options for narrowing the rendering. Selectors reuse the trail-filter
+ * grammar (exact ids, `*`, `**`). v0 exposes include/exclude only; intent-based
+ * filtering is deferred (the packet promises the filter grammar, not intent
+ * narrowing, for the library surface).
+ */
+export interface DeriveLibraryApiOptions {
+  /** Narrowing include patterns. Never widens drafts/internal. */
+  readonly include?: readonly string[];
+  /** Exclude patterns. */
+  readonly exclude?: readonly string[];
+  /** Surface-scope layers to render alongside each trail's own input. */
+  readonly layers?: readonly Layer[] | undefined;
+}
+
+/**
+ * Derive a consumer-native export name from a trail id: camelCase across `.`
+ * and `-` segments, preserving the full path so distinct trails stay distinct.
+ * `widget.get` -> `widgetGet`, `entity.list-all` -> `entityListAll`.
+ */
+const deriveExportName = (trailId: string): string => {
+  const words = trailId.split(/[.-]/u).filter((word) => word.length > 0);
+  return words
+    .map((word, index) =>
+      index === 0 ? word : word.charAt(0).toUpperCase() + word.slice(1)
+    )
+    .join('');
+};
+
+/**
+ * Whether a trail is surface-internal. Mirrors `effectiveVisibility` in
+ * `@ontrails/core` `surface-filter.ts`, which is not exported — so this is a
+ * deliberate local copy. Selection still routes through `filterSurfaceTrails`
+ * (authoritative); this duplication only labels exclusion reasons. If core's
+ * visibility rule gains a case, update this in lockstep.
+ */
+const isInternal = (trail: AnyTrail): boolean =>
+  trail.visibility === 'internal' || trail.meta?.['internal'] === true;
+
+/**
+ * Derive a topo into a `LibraryRenderingPlan`. Selection composes
+ * `filterSurfaceTrails` (visibility, activation, intent, include/exclude) and
+ * adds draft exclusion. Established public, current-version trails become
+ * exports; drafts, internal, and activation-driven trails are excluded.
+ *
+ * @example
+ * const rendering = deriveLibraryApi(app);
+ * for (const entry of rendering.exports) {
+ *   console.log(entry.exportName, '->', entry.trailId);
+ * }
+ */
+export const deriveLibraryApi = (
+  graph: Topo,
+  options: DeriveLibraryApiOptions = {}
+): LibraryRenderingPlan => {
+  const all = graph.list();
+
+  const selected = filterSurfaceTrails(all, {
+    exclude: options.exclude,
+    include: options.include,
+  }).filter((trail) => !isDraftId(trail.id));
+  const selectedIds = new Set(selected.map((trail) => trail.id));
+
+  const excluded: LibraryExclusion[] = [];
+  for (const trail of all) {
+    if (selectedIds.has(trail.id)) {
+      continue;
+    }
+    // Precedence: draft > activation > internal. A trail may satisfy more than
+    // one; the first match is recorded as the primary reason.
+    if (isDraftId(trail.id)) {
+      excluded.push({ reason: 'draft', trailId: trail.id });
+    } else if (trail.activationSources.length > 0) {
+      excluded.push({ reason: 'activation', trailId: trail.id });
+    } else if (isInternal(trail)) {
+      excluded.push({ reason: 'internal', trailId: trail.id });
+    }
+    // Trails dropped purely by an explicit include/exclude filter are not
+    // surprising exclusions and are not recorded.
+  }
+
+  const sorted = selected.toSorted((left, right) =>
+    left.id.localeCompare(right.id)
+  );
+  const namesToTrailIds = new Map<string, string[]>();
+  const collisionNames = new Set<string>();
+  const exports: LibraryExport[] = [];
+
+  for (const trail of sorted) {
+    const exportName = deriveExportName(trail.id);
+    const existing = namesToTrailIds.get(exportName);
+    if (existing) {
+      existing.push(trail.id);
+      collisionNames.add(exportName);
+      continue;
+    }
+    namesToTrailIds.set(exportName, [trail.id]);
+    const inputRendering = renderLibraryInput(graph, trail, options.layers);
+    exports.push({
+      description: trail.description,
+      exportName,
+      input: inputRendering.input,
+      intent: trail.intent,
+      layerInputs: inputRendering.layers,
+      nameSource: 'derived',
+      output: trail.output,
+      resources: trail.resources.map((resource) => resource.id),
+      trailId: trail.id,
+      version: trail.version,
+    });
+  }
+
+  const collisions: LibraryCollision[] = [...collisionNames].map((name) => ({
+    exportName: name,
+    trailIds: namesToTrailIds.get(name) ?? [],
+  }));
+
+  return { app: graph.name, collisions, excluded, exports };
+};

package/src/errors.ts

@@ -0,0 +1,191 @@
+/* oxlint-disable max-classes-per-file -- package-facing error taxonomy stays co-located */
+import {
+  createSurfaceErrorMapper,
+  isTrailsError,
+  renderPublicError,
+} from '@ontrails/core';
+import type { ErrorCategory } from '@ontrails/core';
+
+export interface LibraryErrorOptions {
+  readonly cause?: Error | undefined;
+  readonly originalName?: string | undefined;
+}
+
+/** Base class for package-facing errors thrown or returned by the library surface. */
+export class LibraryError extends Error {
+  readonly category: ErrorCategory;
+  readonly originalName: string;
+  readonly retryable: boolean;
+
+  constructor(
+    message: string,
+    options: LibraryErrorOptions & {
+      readonly category: ErrorCategory;
+      readonly name: string;
+      readonly retryable: boolean;
+    }
+  ) {
+    super(message, { cause: options.cause });
+    this.name = options.name;
+    this.category = options.category;
+    this.originalName = options.originalName ?? options.cause?.name ?? 'Error';
+    this.retryable = options.retryable;
+  }
+}
+
+export class LibraryValidationError extends LibraryError {
+  constructor(message: string, options?: LibraryErrorOptions) {
+    super(message, {
+      ...options,
+      category: 'validation',
+      name: 'LibraryValidationError',
+      retryable: false,
+    });
+  }
+}
+
+export class LibraryNotFoundError extends LibraryError {
+  constructor(message: string, options?: LibraryErrorOptions) {
+    super(message, {
+      ...options,
+      category: 'not_found',
+      name: 'LibraryNotFoundError',
+      retryable: false,
+    });
+  }
+}
+
+export class LibraryConflictError extends LibraryError {
+  constructor(message: string, options?: LibraryErrorOptions) {
+    super(message, {
+      ...options,
+      category: 'conflict',
+      name: 'LibraryConflictError',
+      retryable: false,
+    });
+  }
+}
+
+export class LibraryPermissionError extends LibraryError {
+  constructor(message: string, options?: LibraryErrorOptions) {
+    super(message, {
+      ...options,
+      category: 'permission',
+      name: 'LibraryPermissionError',
+      retryable: false,
+    });
+  }
+}
+
+export class LibraryTimeoutError extends LibraryError {
+  constructor(message: string, options?: LibraryErrorOptions) {
+    super(message, {
+      ...options,
+      category: 'timeout',
+      name: 'LibraryTimeoutError',
+      retryable: true,
+    });
+  }
+}
+
+export class LibraryRateLimitError extends LibraryError {
+  constructor(message: string, options?: LibraryErrorOptions) {
+    super(message, {
+      ...options,
+      category: 'rate_limit',
+      name: 'LibraryRateLimitError',
+      retryable: true,
+    });
+  }
+}
+
+export class LibraryNetworkError extends LibraryError {
+  constructor(message: string, options?: LibraryErrorOptions) {
+    super(message, {
+      ...options,
+      category: 'network',
+      name: 'LibraryNetworkError',
+      retryable: true,
+    });
+  }
+}
+
+export class LibraryShiftError extends LibraryError {
+  constructor(message: string, options?: LibraryErrorOptions) {
+    super(message, {
+      ...options,
+      category: 'shift',
+      name: 'LibraryShiftError',
+      retryable: true,
+    });
+  }
+}
+
+export class LibraryInternalError extends LibraryError {
+  constructor(message: string, options?: LibraryErrorOptions) {
+    super(message, {
+      ...options,
+      category: 'internal',
+      name: 'LibraryInternalError',
+      retryable: false,
+    });
+  }
+}
+
+export class LibraryAuthError extends LibraryError {
+  constructor(message: string, options?: LibraryErrorOptions) {
+    super(message, {
+      ...options,
+      category: 'auth',
+      name: 'LibraryAuthError',
+      retryable: false,
+    });
+  }
+}
+
+export class LibraryCancelledError extends LibraryError {
+  constructor(message: string, options?: LibraryErrorOptions) {
+    super(message, {
+      ...options,
+      category: 'cancelled',
+      name: 'LibraryCancelledError',
+      retryable: false,
+    });
+  }
+}
+
+const libraryErrorClasses = {
+  auth: LibraryAuthError,
+  cancelled: LibraryCancelledError,
+  conflict: LibraryConflictError,
+  internal: LibraryInternalError,
+  network: LibraryNetworkError,
+  not_found: LibraryNotFoundError,
+  permission: LibraryPermissionError,
+  rate_limit: LibraryRateLimitError,
+  shift: LibraryShiftError,
+  timeout: LibraryTimeoutError,
+  validation: LibraryValidationError,
+} as const;
+
+const mapLibraryErrorClass = createSurfaceErrorMapper(libraryErrorClasses);
+
+export const toLibraryError = (error: Error): LibraryError => {
+  if (error instanceof LibraryError) {
+    return error;
+  }
+
+  const rendering = renderPublicError(error);
+  if (!isTrailsError(error)) {
+    return new LibraryInternalError(rendering.message, {
+      cause: error,
+      originalName: error.name || 'Error',
+    });
+  }
+
+  const ErrorClass = mapLibraryErrorClass(error);
+  return new ErrorClass(rendering.message, {
+    cause: error,
+    originalName: error.name,
+  });
+};

package/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * `@ontrails/library` — render a Trails topo as an idiomatic TypeScript library.
+ *
+ * The library surface is a peer of CLI, MCP, and HTTP. Its public ladder:
+ *
+ * - `deriveLibraryApi(graph, options)` — pure rendering → `LibraryRenderingPlan`
+ * - `surface(graph, options)` — in-memory callable client
+ * - `compile(graph, options)` — TypeScript package emitter
+ *
+ * Those land across the rendering, surface, and emitter lanes (Linear project
+ * "Library surface & compiler"). This scaffold establishes the package and the
+ * runtime-kernel seam; see `./kernel` and the Library Surface and Compiler ADR.
+ */
+export { compile } from './compile.js';
+export type { CompiledFile, CompileOptions, CompileResult } from './compile.js';
+export { deriveLibraryApi } from './derive.js';
+export type {
+  DeriveLibraryApiOptions,
+  LibraryCollision,
+  LibraryExclusion,
+  LibraryExclusionReason,
+  LibraryExport,
+  LibraryExportSource,
+  LibraryRenderingPlan,
+} from './derive.js';
+export {
+  LibraryAuthError,
+  LibraryCancelledError,
+  LibraryConflictError,
+  LibraryError,
+  LibraryInternalError,
+  LibraryNetworkError,
+  LibraryNotFoundError,
+  LibraryPermissionError,
+  LibraryRateLimitError,
+  LibraryShiftError,
+  LibraryTimeoutError,
+  LibraryValidationError,
+  toLibraryError,
+} from './errors.js';
+export type { LibraryErrorOptions } from './errors.js';
+export { kernelRun } from './kernel.js';
+export type { TrailInput, TrailOutput } from '@ontrails/core';
+export type {
+  KernelRunOptions,
+  Result,
+  Topo,
+  TrailContextInit,
+} from './kernel.js';
+export { runLibraryResult, surface } from './surface.js';
+export type {
+  LibraryClient,
+  LibraryMethod,
+  LibraryResultMethod,
+  SurfaceLibraryOptions,
+} from './surface.js';

package/src/kernel.ts

@@ -0,0 +1,63 @@
+/**
+ * The runtime kernel: the minimal, single-sourced surface through which the
+ * library surface (and, later, emitted packages) reach Trails execution.
+ *
+ * **This is the only module in `@ontrails/library` that imports execution
+ * primitives from `@ontrails/core`.** Everything else — the in-memory surface,
+ * the emitter's generated runtime — routes through here.
+ *
+ * Why this exists: standalone output (a generated package with no `@ontrails/*`
+ * runtime dependency) must be reachable as a *vendoring step*, not a rewrite.
+ * Confining the framework-runtime dependency to this one seam means "go
+ * standalone" reduces to "vendor this module's imports," with consumer code and
+ * package derivation unchanged. See the runtime-kernel section of the Library
+ * Surface and Compiler ADR.
+ *
+ * The kernel grows only as materialization demands: today it wraps execution;
+ * error rendering and the context/compose shim join it as the surface and
+ * emitter lanes land. Keep it minimal and dependency-light on purpose.
+ */
+import { run } from '@ontrails/core';
+import type {
+  Result,
+  RunOptions,
+  Topo,
+  TrailContextInit,
+} from '@ontrails/core';
+
+export type { Result, Topo, TrailContextInit };
+
+/** Runtime options the kernel forwards to execution (permit, abort, layers, etc.). */
+export type KernelRunOptions = Pick<
+  RunOptions,
+  | 'abortSignal'
+  | 'configValues'
+  | 'createContext'
+  | 'ctx'
+  | 'dryRun'
+  | 'layerInputs'
+  | 'permit'
+  | 'resources'
+  | 'surfaceLayers'
+  | 'topoLayers'
+  | 'version'
+>;
+
+/**
+ * Execute a trail by id through the shared Trails pipeline. Never throws —
+ * resolves to `Result.ok` on success or `Result.err(TrailsError)` on failure,
+ * exactly as `run()` does. The library surface unwraps this into return/throw
+ * (root API) or returns it directly (`/result`).
+ *
+ * @example
+ * const result = await kernelRun(topo, 'thing.check', { root: '.' });
+ * if (result.isOk()) {
+ *   // result.value is the trail output
+ * }
+ */
+export const kernelRun = (
+  topo: Topo,
+  id: string,
+  input: unknown,
+  options: KernelRunOptions = {}
+): Promise<Result<unknown, Error>> => run(topo, id, input, options);

package/src/layer-input.ts

@@ -0,0 +1,188 @@
+import type { AttachedTypedLayer, Layer, Topo, Trail } from '@ontrails/core';
+import {
+  LAYER_FIELD_RESERVED_NAMES,
+  collectAttachedTypedLayers,
+  renderLayerFieldName,
+  zodToJsonSchema,
+} from '@ontrails/core';
+import { z } from 'zod';
+
+type AnyTrail = Trail<unknown, unknown, unknown>;
+type MutableLayerShape = Record<string, z.ZodRawShape[string]>;
+
+export interface LibraryLayerFieldRendering {
+  readonly claimedName: string;
+  readonly routingTarget: string;
+}
+
+export interface LibraryLayerInputRendering {
+  readonly fields: readonly LibraryLayerFieldRendering[];
+  readonly input: z.ZodObject<z.ZodRawShape>;
+  readonly layerName: string;
+}
+
+export interface LibraryInputRendering {
+  readonly input: z.ZodType;
+  readonly layers: readonly LibraryLayerInputRendering[];
+}
+
+const isJsonObjectSchema = (
+  value: unknown
+): value is { properties?: Record<string, unknown> } =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isObjectRecord = (
+  value: unknown
+): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const capitalized = (value: string): string => {
+  if (value.length === 0) {
+    return value;
+  }
+  return `${value.charAt(0).toUpperCase()}${value.slice(1)}`;
+};
+
+const buildLibraryRenameTarget = (
+  layerName: string,
+  originalName: string
+): string => `${layerName}${capitalized(originalName)}`;
+
+const objectPropertiesFor = (schema: z.ZodType): readonly string[] => {
+  const jsonSchema = zodToJsonSchema(schema);
+  if (!isJsonObjectSchema(jsonSchema) || jsonSchema.properties === undefined) {
+    return [];
+  }
+  return Object.keys(jsonSchema.properties);
+};
+
+const isJsonObjectInput = (schema: z.ZodType): boolean =>
+  isJsonObjectSchema(zodToJsonSchema(schema));
+
+const renderLayerInputFields = (
+  attached: AttachedTypedLayer,
+  claimedNames: Set<string>,
+  layerShape: MutableLayerShape
+): LibraryLayerInputRendering => {
+  const { layer } = attached;
+  if (layer.input === undefined) {
+    return { fields: [], input: z.object({}), layerName: layer.name };
+  }
+
+  const fields: LibraryLayerFieldRendering[] = [];
+  for (const [fieldName, fieldSchema] of Object.entries(layer.input.shape)) {
+    const rendering = renderLayerFieldName(
+      layer.name,
+      fieldName,
+      fieldName,
+      buildLibraryRenameTarget(layer.name, fieldName),
+      claimedNames,
+      LAYER_FIELD_RESERVED_NAMES
+    );
+    fields.push({
+      claimedName: rendering.claimedName,
+      routingTarget: rendering.routingTarget,
+    });
+    layerShape[rendering.claimedName] = fieldSchema;
+  }
+
+  return { fields, input: layer.input, layerName: layer.name };
+};
+
+/**
+ * Render a trail's public library input: authored trail input plus any typed
+ * layer input fields attached at topo, surface, or trail scope.
+ */
+export const renderLibraryInput = (
+  graph: Topo,
+  trail: AnyTrail,
+  surfaceLayers?: readonly Layer[]
+): LibraryInputRendering => {
+  const attachedLayers = collectAttachedTypedLayers(
+    graph,
+    trail,
+    surfaceLayers
+  );
+  if (attachedLayers.length === 0) {
+    return { input: trail.input, layers: [] };
+  }
+
+  const trailProperties = objectPropertiesFor(trail.input);
+  const claimedNames = new Set(trailProperties);
+  if (trailProperties.length === 0 && !isJsonObjectInput(trail.input)) {
+    throw new Error(
+      `Library layer input rendering requires object input for trail "${trail.id}".`
+    );
+  }
+
+  const layerShape: MutableLayerShape = {};
+  const layers: LibraryLayerInputRendering[] = [];
+  for (const attached of attachedLayers) {
+    const rendering = renderLayerInputFields(
+      attached,
+      claimedNames,
+      layerShape
+    );
+    if (rendering.fields.length > 0) {
+      layers.push(rendering);
+    }
+  }
+
+  if (layers.length === 0) {
+    return { input: trail.input, layers: [] };
+  }
+
+  return {
+    input: trail.input.and(z.object(layerShape)),
+    layers,
+  };
+};
+
+/**
+ * Split a library method input back into trail input plus per-layer runtime
+ * input slots using the rendering routing table.
+ */
+export const partitionLibraryInput = (
+  input: unknown,
+  renderings: readonly LibraryLayerInputRendering[]
+): {
+  readonly layerInputs: Record<string, unknown>;
+  readonly trailInput: unknown;
+} => {
+  if (renderings.length === 0 || !isObjectRecord(input)) {
+    return { layerInputs: {}, trailInput: input };
+  }
+
+  const claimedKeys = new Set<string>();
+  const layerInputs: Record<string, unknown> = {};
+  for (const rendering of renderings) {
+    const layerInput: Record<string, unknown> = {};
+    let received = false;
+    for (const field of rendering.fields) {
+      claimedKeys.add(field.claimedName);
+      const value = input[field.claimedName];
+      if (value === undefined) {
+        continue;
+      }
+      layerInput[field.routingTarget] = value;
+      received = true;
+    }
+    if (received) {
+      layerInputs[rendering.layerName] = layerInput;
+      continue;
+    }
+
+    const emptyInput = rendering.input.safeParse({});
+    if (emptyInput.success) {
+      layerInputs[rendering.layerName] = emptyInput.data;
+    }
+  }
+
+  const trailInput: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (!claimedKeys.has(key)) {
+      trailInput[key] = value;
+    }
+  }
+  return { layerInputs, trailInput };
+};