@ontrails/library 1.0.0-beta.41 → 1.0.0-beta.43

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @ontrails/library
 
+## 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

package/README.md

@@ -2,7 +2,7 @@
 
 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.
+`@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.
 
@@ -11,7 +11,7 @@ The package is publishable as the runtime dependency for generated Trails librar
 ```ts
 import { compile, deriveLibraryApi, surface } from '@ontrails/library';
 
-const projection = deriveLibraryApi(app);
+const renderingPlan = deriveLibraryApi(app);
 const client = await surface(app);
 const files = compile(app, {
   appExportName: 'app',
@@ -20,7 +20,7 @@ const files = compile(app, {
 });
 ```
 
-- `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.
+- `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.
 
@@ -35,13 +35,13 @@ Generated packages use one package with subpath exports:
 ./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.
+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 projected trail id to the source trail export that owns its schema types:
+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, {
@@ -57,7 +57,7 @@ const files = compile(app, {
 
 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.
+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
 
@@ -75,7 +75,7 @@ The mapper is built with the shared Trails error taxonomy, so new categories mus
 
 ## Governance and dogfood
 
-Library projection facts are embedded in `TopoGraph.library` by Topography. 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.
+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:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/library",
-  "version": "1.0.0-beta.41",
+  "version": "1.0.0-beta.43",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -22,10 +22,10 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.41"
+    "@ontrails/core": "^1.0.0-beta.43"
   },
   "devDependencies": {
-    "@ontrails/testing": "^1.0.0-beta.41"
+    "@ontrails/testing": "^1.0.0-beta.43"
   },
   "peerDependencies": {
     "zod": "^4.3.5"

package/src/compile.ts

@@ -1,5 +1,5 @@
 /**
- * `compile` — the package emitter. Consumes the `LibraryProjection` (never the
+ * `compile` — the package emitter. Consumes the `LibraryRenderingPlan` (never the
  * topo directly) and produces the source files of a generated TypeScript
  * package: consumer-fluent root, `/result`, `/schemas`, `/trails` subpaths.
  *
@@ -9,13 +9,13 @@
  * 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.
+ * thin apply step. Pure: derives the rendering and builds strings, no I/O.
  */
 import { deriveLibraryApi } from './derive.js';
 import type {
   DeriveLibraryApiOptions,
   LibraryExport,
-  LibraryProjection,
+  LibraryRenderingPlan,
 } from './derive.js';
 import type { Topo } from './kernel.js';
 
@@ -39,7 +39,7 @@ export interface CompileOptions extends DeriveLibraryApiOptions {
    */
   readonly typeImportPath?: string;
   /**
-   * Optional mapping from projected trail id to the source module export that
+   * Optional mapping from rendered 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.
@@ -56,8 +56,8 @@ export interface CompiledFile {
 /** 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 resolved rendering the files were emitted from. */
+  readonly rendering: LibraryRenderingPlan;
   /** The emitted files, in stable path order. */
   readonly files: readonly CompiledFile[];
 }
@@ -73,16 +73,16 @@ const isStateless = (entry: LibraryExport): boolean =>
   entry.resources.length === 0;
 
 const statelessExports = (
-  projection: LibraryProjection
-): readonly LibraryExport[] => projection.exports.filter(isStateless);
+  rendering: LibraryRenderingPlan
+): readonly LibraryExport[] => rendering.exports.filter(isStateless);
 
 const resourceExports = (
-  projection: LibraryProjection
+  rendering: LibraryRenderingPlan
 ): readonly LibraryExport[] =>
-  projection.exports.filter((entry) => !isStateless(entry));
+  rendering.exports.filter((entry) => !isStateless(entry));
 
-const factoryName = (projection: LibraryProjection): string =>
-  `create${pascalCase(projection.app)}`;
+const factoryName = (rendering: LibraryRenderingPlan): string =>
+  `create${pascalCase(rendering.app)}`;
 
 const DEFAULT_LIBRARY_DEPENDENCY = '^1.0.0';
 const DEFAULT_ZOD_DEPENDENCY = '^4.3.5';
@@ -121,12 +121,12 @@ const typeNamesFor = (
 };
 
 const resolveTypeBindings = (
-  projection: LibraryProjection,
+  rendering: LibraryRenderingPlan,
   options: CompileOptions
 ): TypeBindings => {
   const configured = options.trailTypeExports ?? {};
   const bindings = new Map<string, ExportTypeBinding>();
-  for (const entry of projection.exports) {
+  for (const entry of rendering.exports) {
     const sourceExport = configured[entry.trailId];
     if (!sourceExport) {
       continue;
@@ -155,10 +155,10 @@ const outputTypeFor = (entry: LibraryExport, bindings: TypeBindings): string =>
   bindings.get(entry.trailId)?.output ?? 'unknown';
 
 const schemaTypeImport = (
-  projection: LibraryProjection,
+  rendering: LibraryRenderingPlan,
   bindings: TypeBindings
 ): string | undefined => {
-  const names = projection.exports.flatMap((entry) => {
+  const names = rendering.exports.flatMap((entry) => {
     const binding = bindings.get(entry.trailId);
     return binding ? [binding.input, binding.output] : [];
   });
@@ -196,7 +196,7 @@ const statelessFunction = (
   [
     jsDoc([
       exportDescription(entry),
-      `Projects trail \`${entry.trailId}\` as a stateless library function.`,
+      `Renders trail \`${entry.trailId}\` as a stateless library function.`,
     ]),
     `export const ${entry.exportName} = (`,
     `  input: ${inputTypeFor(entry, bindings)}`,
@@ -210,7 +210,7 @@ const factoryMethod = (entry: LibraryExport, bindings: TypeBindings): string =>
     jsDoc(
       [
         exportDescription(entry),
-        `Projects trail \`${entry.trailId}\` behind the resource client.`,
+        `Renders trail \`${entry.trailId}\` behind the resource client.`,
       ],
       '    '
     ),
@@ -222,12 +222,12 @@ const factoryMethod = (entry: LibraryExport, bindings: TypeBindings): string =>
   ].join('\n');
 
 const generateIndex = (
-  projection: LibraryProjection,
+  rendering: LibraryRenderingPlan,
   bindings: TypeBindings
 ): string => {
-  const stateless = statelessExports(projection);
-  const resourceful = resourceExports(projection);
-  const typedSchemas = schemaTypeImport(projection, bindings);
+  const stateless = statelessExports(rendering);
+  const resourceful = resourceExports(rendering);
+  const typedSchemas = schemaTypeImport(rendering, bindings);
 
   const parts: string[] = [
     "import type { SurfaceLibraryOptions } from '@ontrails/library';",
@@ -243,7 +243,7 @@ const generateIndex = (
   if (resourceful.length > 0) {
     parts.push(
       '',
-      `export const ${factoryName(projection)} = async (`,
+      `export const ${factoryName(rendering)} = async (`,
       '  options: SurfaceLibraryOptions = {}',
       ') => {',
       '  const client = await createClient(options);',
@@ -271,12 +271,12 @@ const generateClient = (): string =>
   ].join('\n');
 
 const generateSchemas = (
-  projection: LibraryProjection,
+  rendering: LibraryRenderingPlan,
   options: CompileOptions,
   bindings: TypeBindings
 ): string => {
   const appExport = 'app';
-  const typedEntries = projection.exports.filter((entry) =>
+  const typedEntries = rendering.exports.filter((entry) =>
     bindings.has(entry.trailId)
   );
   const sourceTypeExports = [
@@ -300,22 +300,22 @@ const generateSchemas = (
         ]
       : []),
     '',
-    '// Authored Zod schemas, keyed by export name, projected from the topo.',
-    'const projection = deriveLibraryApi(app);',
+    '// Authored Zod schemas, keyed by export name, rendered from the topo.',
+    'const rendering = deriveLibraryApi(app);',
     'const byName = new Map(',
-    '  projection.exports.map((entry) => [entry.exportName, entry])',
+    '  rendering.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);",
+    "    throw new Error('missing rendered library export: ' + name);",
     '  }',
     '  return entry;',
     '};',
     '',
   ];
-  for (const entry of projection.exports) {
+  for (const entry of rendering.exports) {
     const binding = bindings.get(entry.trailId);
     if (binding) {
       lines.push(
@@ -338,7 +338,7 @@ const generateSchemas = (
     );
   }
   lines.push('', 'export const schemas = {');
-  for (const entry of projection.exports) {
+  for (const entry of rendering.exports) {
     lines.push(
       `  ${entry.exportName}: {`,
       `    input: ${entry.exportName}InputSchema,`,
@@ -396,12 +396,12 @@ const resultFactoryMethod = (
   ].join('\n');
 
 const generateResult = (
-  projection: LibraryProjection,
+  rendering: LibraryRenderingPlan,
   bindings: TypeBindings
 ): string => {
-  const stateless = statelessExports(projection);
-  const resourceful = resourceExports(projection);
-  const typedSchemas = schemaTypeImport(projection, bindings);
+  const stateless = statelessExports(rendering);
+  const resourceful = resourceExports(rendering);
+  const typedSchemas = schemaTypeImport(rendering, bindings);
   const parts = [
     '// No-throw API: returns the Result envelope instead of unwrapping.',
     "import { runLibraryResult } from '@ontrails/library';",
@@ -421,7 +421,7 @@ const generateResult = (
   if (resourceful.length > 0) {
     parts.push(
       '',
-      `export const ${factoryName(projection)} = async (`,
+      `export const ${factoryName(rendering)} = async (`,
       '  options: SurfaceLibraryOptions = {}',
       ') => {',
       '  const client = await createClient(options);',
@@ -464,7 +464,7 @@ const generateTsconfig = (): string =>
 
 /**
  * Compile a topo into a generated library package. Returns the emitted file
- * plan; the resolved projection is included for inspection and governance.
+ * plan; the resolved rendering is included for inspection and governance.
  *
  * @example
  * const result = compile(app, {
@@ -479,8 +479,8 @@ export const compile = (
   graph: Topo,
   options: CompileOptions
 ): CompileResult => {
-  const projection = deriveLibraryApi(graph, options);
-  const typeBindings = resolveTypeBindings(projection, options);
+  const rendering = deriveLibraryApi(graph, options);
+  const typeBindings = resolveTypeBindings(rendering, options);
   const files: CompiledFile[] = [
     { content: generatePackageJson(options), path: 'package.json' },
     { content: generateTsconfig(), path: 'tsconfig.json' },
@@ -489,18 +489,18 @@ export const compile = (
       path: 'src/client.ts',
     },
     {
-      content: generateIndex(projection, typeBindings),
+      content: generateIndex(rendering, typeBindings),
       path: 'src/index.ts',
     },
     {
-      content: generateResult(projection, typeBindings),
+      content: generateResult(rendering, typeBindings),
       path: 'src/result.ts',
     },
     {
-      content: generateSchemas(projection, options, typeBindings),
+      content: generateSchemas(rendering, options, typeBindings),
       path: 'src/schemas.ts',
     },
     { content: generateTrails(options), path: 'src/trails.ts' },
   ];
-  return { files, packageName: options.packageName, projection };
+  return { files, packageName: options.packageName, rendering };
 };

package/src/derive.ts

@@ -1,29 +1,29 @@
 /**
- * `deriveLibraryApi` — the pure projection from a topo to a `LibraryProjection`.
+ * `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 projection; neither re-reads the topo nor reinvents
+ * 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 { projectLibraryInput } from './layer-input.js';
-import type { LibraryLayerInputProjection } from './layer-input.js';
+import { renderLibraryInput } from './layer-input.js';
+import type { LibraryLayerInputRendering } from './layer-input.js';
 
 type AnyTrail = Trail<unknown, unknown, unknown>;
 
-/** Where a projected export name came from. */
+/** Where a rendered export name came from. */
 export type LibraryExportSource = 'derived' | 'trail-hint' | 'package-config';
 
-/** A single projected export: one trail rendered as a library entrypoint. */
+/** 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 projects (the source of truth). */
+  /** 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;
@@ -39,27 +39,27 @@ export interface LibraryExport {
   /**
    * Input schema reference: the emitter's method-signature and `/schemas`
    * source. An in-memory Zod reference here; it serializes to JSON Schema when
-   * the projection is persisted to the artifact family.
+   * the rendering is persisted to the artifact family.
    */
   readonly input: ZodType;
-  /** Layer input routing projected onto this export's public library input. */
-  readonly layerInputs: readonly LibraryLayerInputProjection[];
+  /** 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 projects the export behind a
+   * 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 project into the library (doctrinally-meaningful only). */
+/** Why a trail did not render into the library (doctrinally-meaningful only). */
 export type LibraryExclusionReason = 'internal' | 'draft' | 'activation';
 
 /**
- * A trail deliberately excluded from the projection, recorded for legibility.
+ * 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.
  */
@@ -74,11 +74,11 @@ export interface LibraryCollision {
   readonly trailIds: readonly string[];
 }
 
-/** The resolved library projection — the story of a topo as a TypeScript library. */
-export interface LibraryProjection {
+/** The resolved library rendering — the story of a topo as a TypeScript library. */
+export interface LibraryRenderingPlan {
   /** The topo name. */
   readonly app: string;
-  /** Projected exports, in stable (trail-id-sorted) order. */
+  /** Rendered exports, in stable (trail-id-sorted) order. */
   readonly exports: readonly LibraryExport[];
   /** Trails excluded by visibility, draft state, or activation. */
   readonly excluded: readonly LibraryExclusion[];
@@ -87,7 +87,7 @@ export interface LibraryProjection {
 }
 
 /**
- * Options for narrowing the projection. Selectors reuse the trail-filter
+ * 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).
@@ -97,7 +97,7 @@ export interface DeriveLibraryApiOptions {
   readonly include?: readonly string[];
   /** Exclude patterns. */
   readonly exclude?: readonly string[];
-  /** Surface-scope layers to project alongside each trail's own input. */
+  /** Surface-scope layers to render alongside each trail's own input. */
   readonly layers?: readonly Layer[] | undefined;
 }
 
@@ -126,21 +126,21 @@ const isInternal = (trail: AnyTrail): boolean =>
   trail.visibility === 'internal' || trail.meta?.['internal'] === true;
 
 /**
- * Project a topo into a `LibraryProjection`. Selection composes
+ * 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 projection = deriveLibraryApi(app);
- * for (const entry of projection.exports) {
+ * const rendering = deriveLibraryApi(app);
+ * for (const entry of rendering.exports) {
  *   console.log(entry.exportName, '->', entry.trailId);
  * }
  */
 export const deriveLibraryApi = (
   graph: Topo,
   options: DeriveLibraryApiOptions = {}
-): LibraryProjection => {
+): LibraryRenderingPlan => {
   const all = graph.list();
 
   const selected = filterSurfaceTrails(all, {
@@ -183,13 +183,13 @@ export const deriveLibraryApi = (
       continue;
     }
     namesToTrailIds.set(exportName, [trail.id]);
-    const inputProjection = projectLibraryInput(graph, trail, options.layers);
+    const inputRendering = renderLibraryInput(graph, trail, options.layers);
     exports.push({
       description: trail.description,
       exportName,
-      input: inputProjection.input,
+      input: inputRendering.input,
       intent: trail.intent,
-      layerInputs: inputProjection.layers,
+      layerInputs: inputRendering.layers,
       nameSource: 'derived',
       output: trail.output,
       resources: trail.resources.map((resource) => resource.id),

package/src/index.ts

@@ -3,11 +3,11 @@
  *
  * The library surface is a peer of CLI, MCP, and HTTP. Its public ladder:
  *
- * - `deriveLibraryApi(graph, options)` — pure projection → `LibraryProjection`
+ * - `deriveLibraryApi(graph, options)` — pure rendering → `LibraryRenderingPlan`
  * - `surface(graph, options)` — in-memory callable client
  * - `compile(graph, options)` — TypeScript package emitter
  *
- * Those land across the projection, surface, and emitter lanes (Linear project
+ * 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.
  */
@@ -21,7 +21,7 @@ export type {
   LibraryExclusionReason,
   LibraryExport,
   LibraryExportSource,
-  LibraryProjection,
+  LibraryRenderingPlan,
 } from './derive.js';
 export {
   LibraryAuthError,

package/src/kernel.ts

@@ -14,7 +14,7 @@
  * Surface and Compiler ADR.
  *
  * The kernel grows only as materialization demands: today it wraps execution;
- * error projection and the context/compose shim join it as the surface and
+ * 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';

package/src/layer-input.ts

@@ -2,7 +2,7 @@ import type { AttachedTypedLayer, Layer, Topo, Trail } from '@ontrails/core';
 import {
   LAYER_FIELD_RESERVED_NAMES,
   collectAttachedTypedLayers,
-  projectLayerFieldName,
+  renderLayerFieldName,
   zodToJsonSchema,
 } from '@ontrails/core';
 import { z } from 'zod';
@@ -10,20 +10,20 @@ import { z } from 'zod';
 type AnyTrail = Trail<unknown, unknown, unknown>;
 type MutableLayerShape = Record<string, z.ZodRawShape[string]>;
 
-export interface LibraryLayerFieldProjection {
+export interface LibraryLayerFieldRendering {
   readonly claimedName: string;
   readonly routingTarget: string;
 }
 
-export interface LibraryLayerInputProjection {
-  readonly fields: readonly LibraryLayerFieldProjection[];
+export interface LibraryLayerInputRendering {
+  readonly fields: readonly LibraryLayerFieldRendering[];
   readonly input: z.ZodObject<z.ZodRawShape>;
   readonly layerName: string;
 }
 
-export interface LibraryInputProjection {
+export interface LibraryInputRendering {
   readonly input: z.ZodType;
-  readonly layers: readonly LibraryLayerInputProjection[];
+  readonly layers: readonly LibraryLayerInputRendering[];
 }
 
 const isJsonObjectSchema = (
@@ -59,19 +59,19 @@ const objectPropertiesFor = (schema: z.ZodType): readonly string[] => {
 const isJsonObjectInput = (schema: z.ZodType): boolean =>
   isJsonObjectSchema(zodToJsonSchema(schema));
 
-const projectLayerInputFields = (
+const renderLayerInputFields = (
   attached: AttachedTypedLayer,
   claimedNames: Set<string>,
   layerShape: MutableLayerShape
-): LibraryLayerInputProjection => {
+): LibraryLayerInputRendering => {
   const { layer } = attached;
   if (layer.input === undefined) {
     return { fields: [], input: z.object({}), layerName: layer.name };
   }
 
-  const fields: LibraryLayerFieldProjection[] = [];
+  const fields: LibraryLayerFieldRendering[] = [];
   for (const [fieldName, fieldSchema] of Object.entries(layer.input.shape)) {
-    const projection = projectLayerFieldName(
+    const rendering = renderLayerFieldName(
       layer.name,
       fieldName,
       fieldName,
@@ -80,24 +80,24 @@ const projectLayerInputFields = (
       LAYER_FIELD_RESERVED_NAMES
     );
     fields.push({
-      claimedName: projection.claimedName,
-      routingTarget: projection.routingTarget,
+      claimedName: rendering.claimedName,
+      routingTarget: rendering.routingTarget,
     });
-    layerShape[projection.claimedName] = fieldSchema;
+    layerShape[rendering.claimedName] = fieldSchema;
   }
 
   return { fields, input: layer.input, layerName: layer.name };
 };
 
 /**
- * Project a trail's public library input: authored trail input plus any typed
+ * 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 projectLibraryInput = (
+export const renderLibraryInput = (
   graph: Topo,
   trail: AnyTrail,
   surfaceLayers?: readonly Layer[]
-): LibraryInputProjection => {
+): LibraryInputRendering => {
   const attachedLayers = collectAttachedTypedLayers(
     graph,
     trail,
@@ -111,20 +111,20 @@ export const projectLibraryInput = (
   const claimedNames = new Set(trailProperties);
   if (trailProperties.length === 0 && !isJsonObjectInput(trail.input)) {
     throw new Error(
-      `Library layer input projection requires object input for trail "${trail.id}".`
+      `Library layer input rendering requires object input for trail "${trail.id}".`
     );
   }
 
   const layerShape: MutableLayerShape = {};
-  const layers: LibraryLayerInputProjection[] = [];
+  const layers: LibraryLayerInputRendering[] = [];
   for (const attached of attachedLayers) {
-    const projection = projectLayerInputFields(
+    const rendering = renderLayerInputFields(
       attached,
       claimedNames,
       layerShape
     );
-    if (projection.fields.length > 0) {
-      layers.push(projection);
+    if (rendering.fields.length > 0) {
+      layers.push(rendering);
     }
   }
 
@@ -140,25 +140,25 @@ export const projectLibraryInput = (
 
 /**
  * Split a library method input back into trail input plus per-layer runtime
- * input slots using the projection routing table.
+ * input slots using the rendering routing table.
  */
 export const partitionLibraryInput = (
   input: unknown,
-  projections: readonly LibraryLayerInputProjection[]
+  renderings: readonly LibraryLayerInputRendering[]
 ): {
   readonly layerInputs: Record<string, unknown>;
   readonly trailInput: unknown;
 } => {
-  if (projections.length === 0 || !isObjectRecord(input)) {
+  if (renderings.length === 0 || !isObjectRecord(input)) {
     return { layerInputs: {}, trailInput: input };
   }
 
   const claimedKeys = new Set<string>();
   const layerInputs: Record<string, unknown> = {};
-  for (const projection of projections) {
+  for (const rendering of renderings) {
     const layerInput: Record<string, unknown> = {};
     let received = false;
-    for (const field of projection.fields) {
+    for (const field of rendering.fields) {
       claimedKeys.add(field.claimedName);
       const value = input[field.claimedName];
       if (value === undefined) {
@@ -168,13 +168,13 @@ export const partitionLibraryInput = (
       received = true;
     }
     if (received) {
-      layerInputs[projection.layerName] = layerInput;
+      layerInputs[rendering.layerName] = layerInput;
       continue;
     }
 
-    const emptyInput = projection.input.safeParse({});
+    const emptyInput = rendering.input.safeParse({});
     if (emptyInput.success) {
-      layerInputs[projection.layerName] = emptyInput.data;
+      layerInputs[rendering.layerName] = emptyInput.data;
     }
   }
 

package/src/surface.ts

@@ -17,7 +17,7 @@ import { deriveLibraryApi } from './derive.js';
 import type {
   DeriveLibraryApiOptions,
   LibraryExport,
-  LibraryProjection,
+  LibraryRenderingPlan,
 } from './derive.js';
 import { toLibraryError } from './errors.js';
 import type { LibraryError } from './errors.js';
@@ -26,7 +26,7 @@ import { kernelRun } from './kernel.js';
 import type { KernelRunOptions, Topo } from './kernel.js';
 
 /**
- * Options for the in-memory library surface: projection selectors plus the
+ * Options for the in-memory library surface: rendering selectors plus the
  * runtime context the client owns (e.g. a permit for permitted trails).
  */
 export interface SurfaceLibraryOptions
@@ -42,14 +42,14 @@ export type LibraryResultMethod = (
   input: unknown
 ) => Promise<Result<unknown, LibraryError>>;
 
-/** The held in-memory client: one method per projected export, plus the projection. */
+/** The held in-memory client: one method per rendered export, plus the rendering. */
 export interface LibraryClient {
   /** Invoke an exported trail by its consumer-native name. */
   readonly call: Readonly<Record<string, LibraryMethod>>;
   /** Invoke an exported trail by name without unwrapping the Result boundary. */
   readonly result: Readonly<Record<string, LibraryResultMethod>>;
-  /** The resolved projection this client was built from (introspection). */
-  readonly projection: LibraryProjection;
+  /** The resolved rendering this client was built from (introspection). */
+  readonly rendering: LibraryRenderingPlan;
 }
 
 const prepareLibraryInput = (
@@ -96,11 +96,9 @@ export const runLibraryResult = async (
   input: unknown,
   options: SurfaceLibraryOptions = {}
 ): Promise<Result<unknown, LibraryError>> => {
-  const projection = deriveLibraryApi(graph, options);
+  const rendering = deriveLibraryApi(graph, options);
   const runOptions = runtimeOptionsFor(graph, options);
-  const entry = projection.exports.find(
-    (candidate) => candidate.trailId === id
-  );
+  const entry = rendering.exports.find((candidate) => candidate.trailId === id);
   const prepared = entry
     ? prepareLibraryInput(entry, input)
     : { layerInputs: {}, trailInput: input };
@@ -117,7 +115,7 @@ export const runLibraryResult = async (
 };
 
 /**
- * Materialize a topo as an in-memory library client. Each projected export
+ * Materialize a topo as an in-memory library client. Each rendered export
  * becomes a method that executes its trail through the shared pipeline and
  * unwraps the Result — returning the value or throwing the error. The same
  * export names are available under `result` for callers that want the raw
@@ -132,12 +130,12 @@ export const surface = async (
   options: SurfaceLibraryOptions = {}
   // oxlint-disable-next-line require-await -- async to match peer surfaces and allow future resource init
 ): Promise<LibraryClient> => {
-  const projection = deriveLibraryApi(graph, options);
+  const rendering = deriveLibraryApi(graph, options);
   const runOptions = runtimeOptionsFor(graph, options);
   const call: Record<string, LibraryMethod> = {};
   const result: Record<string, LibraryResultMethod> = {};
 
-  for (const entry of projection.exports) {
+  for (const entry of rendering.exports) {
     const runExport: LibraryResultMethod = async (input: unknown) => {
       const prepared = prepareLibraryInput(entry, input);
       if (prepared instanceof ValidationError) {
@@ -169,7 +167,7 @@ export const surface = async (
 
   return {
     call: Object.freeze(call),
-    projection,
+    rendering,
     result: Object.freeze(result),
   };
 };