@ontrails/core 1.0.0-beta.42 → 1.0.0-beta.43

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @ontrails/core
 
+## 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.
+
+### Patch Changes
+
+- [`113aed6`](https://github.com/outfitter-dev/trails/commit/113aed62d20041e35b0cf9d6c1b1a18df4b88f57): Rename the dependency-light observability owner from `@ontrails/observe` to
+  `@ontrails/observability` as a pre-v1 hard cut. Update dependent packages,
+  documentation, package discovery, and the governed Regrade route; no
+  compatibility package or old import route is retained.
+- [`0938e7b`](https://github.com/outfitter-dev/trails/commit/0938e7badc0c5470d194139d642b673658d099e0): Fold the removed `@ontrails/tracing` package into the truthful existing
+  owners: intrinsic trace contracts remain in core, developer-state tooling now
+  lives at `@ontrails/observability/dev`, and the dependency-light OTel adapter
+  lives at `@ontrails/observability/otel`. There is intentionally no root-package
+  compatibility redirect because the former root had more than one owner.
+
 ## 1.0.0-beta.42
 
 ## 1.0.0-beta.41

package/README.md

@@ -139,7 +139,7 @@ Dynamic classes:
 - `RetryExhaustedError` inherits category and surface codes from its wrapped `TrailsError`; retryable is always No.
 <!-- error-taxonomy:end -->
 
-Public surface projections redact sensitive substrings before exposing a non-internal `TrailsError` message. Internal-category `TrailsError` instances and unknown native errors project with the generic message `Internal server error`; diagnostics and serialized payloads keep their useful structure while redacting messages, context, and stack strings.
+Public surface renderings redact sensitive substrings before exposing a non-internal `TrailsError` message. Internal-category `TrailsError` instances and unknown native errors render with the generic message `Internal server error`; diagnostics and serialized payloads keep their useful structure while redacting messages, context, and stack strings.
 
 The developer returns `Result.err(new NotFoundError(...))`. The framework maps it to the right code on every surface.
 
@@ -161,9 +161,9 @@ The developer returns `Result.err(new NotFoundError(...))`. The framework maps i
 
 The root package also exposes a few low-level contracts that other framework packages build on:
 
-- **Intrinsic tracing** -- `TraceRecord`, `TraceSink`, `TraceContext`, and the sink registry helpers are the core-owned execution record shape shared by `@ontrails/observe`, `@ontrails/tracing`, and adapters.
+- **Intrinsic tracing** -- `TraceRecord`, `TraceSink`, `TraceContext`, and the sink registry helpers are the core-owned execution record shape shared by `@ontrails/observability` and adapters.
 - **Trails DB** -- `deriveTrailsDbPath`, `deriveTrailsStateDir`, `deriveTrailsStateHome`, `deriveTrailsProjectKey`, `deriveTrailsDir`, `ensureSubsystemSchema`, `openReadTrailsDb`, and `openWriteTrailsDb` are the generic database primitive used by framework subsystems.
-- **Surface projection helpers** -- safe error projection, layer field projection, compose-batch validation, late-bound signal references, and Zod default-wrapper stripping are stable root exports for first-party surfaces, store helpers, and tests.
+- **Surface rendering helpers** -- safe error rendering, layer field rendering, compose-batch validation, late-bound signal references, and Zod default-wrapper stripping are stable root exports for first-party surfaces, store helpers, and tests.
 
 See the [API Reference](../../docs/api-reference.md) for the full list.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/core",
-  "version": "1.0.0-beta.42",
+  "version": "1.0.0-beta.43",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",

package/src/{activation-source-projection.ts → activation-source-derivation.ts}

@@ -3,7 +3,7 @@ import { zodToJsonSchema } from './validation.js';
 
 type ZodSchemaInput = Parameters<typeof zodToJsonSchema>[0];
 
-export type ActivationSourceProjection = Readonly<Record<string, unknown>> & {
+export type ActivationSourceFacts = Readonly<Record<string, unknown>> & {
   readonly id: string;
   readonly key: string;
   readonly kind: string;
@@ -113,9 +113,9 @@ const normalizeWebhookMethod = (method: string | undefined): string =>
 
 const normalizeWebhookPath = (path: string): string => path.trim();
 
-export const projectActivationSourceDeclaration = (
+export const deriveActivationSourceFacts = (
   source: ActivationSource
-): ActivationSourceProjection => {
+): ActivationSourceFacts => {
   const record: Record<string, unknown> = {
     id: source.id,
     key: activationSourceKey(source),
@@ -172,7 +172,7 @@ export const projectActivationSourceDeclaration = (
     record['hasVerify'] = true;
   }
 
-  return sortKeys(record) as ActivationSourceProjection;
+  return sortKeys(record) as ActivationSourceFacts;
 };
 
 /**
@@ -182,8 +182,8 @@ export const projectActivationSourceDeclaration = (
  * returned token captures the function's reference identity so it changes when
  * the verifier function changes.
  *
- * The token is intentionally kept out of {@link projectActivationSourceDeclaration}
- * so that the persisted topo-store projection remains stable and free of
+ * The token is intentionally kept out of {@link deriveActivationSourceFacts}
+ * so that the persisted topo-store facts remains stable and free of
  * nondeterministic function identity. Use this only for in-memory comparisons
  * (validation, conflict detection).
  */
@@ -218,10 +218,10 @@ const verifierIdentityToken = (
 export const activationSourceDeclarationSignature = (
   source: ActivationSource
 ): string => {
-  const projection = projectActivationSourceDeclaration(source);
+  const facts = deriveActivationSourceFacts(source);
   const verifyToken = verifierIdentityToken(source);
   if (verifyToken === undefined) {
-    return JSON.stringify(projection);
+    return JSON.stringify(facts);
   }
-  return JSON.stringify({ projection, verify: verifyToken });
+  return JSON.stringify({ facts, verify: verifyToken });
 };

package/src/blob-ref.ts

@@ -4,7 +4,7 @@
 
 import { z } from 'zod';
 
-/** Metadata key used to recognize BlobRef schemas during JSON Schema projection. */
+/** Metadata key used to recognize BlobRef schemas during JSON Schema derivation. */
 export const BLOB_REF_SCHEMA_META_KEY = 'ontrails/blob-ref';
 
 /** Immutable reference to a blob of binary data. */
@@ -15,7 +15,7 @@ export interface BlobRef {
   readonly data: Uint8Array | ReadableStream<Uint8Array>;
 }
 
-/** Schema-projected metadata for a BlobRef value. */
+/** Schema-derived metadata for a BlobRef value. */
 export interface BlobRefDescriptor {
   readonly kind: 'blob';
   readonly mimeType: string;
@@ -74,7 +74,7 @@ export const isBlobRef = (value: unknown): value is BlobRef => {
   );
 };
 
-/** Zod schema for runtime BlobRef values with metadata for descriptor projection. */
+/** Zod schema for runtime BlobRef values with metadata for descriptor derivation. */
 export const blobRefSchema = z
   .custom<BlobRef>(isBlobRef, { error: 'Expected BlobRef' })
   .meta({ [BLOB_REF_SCHEMA_META_KEY]: true });

package/src/derive.ts

@@ -51,7 +51,7 @@ export interface FieldOverride {
 }
 
 // ---------------------------------------------------------------------------
-// CLI command route projection
+// CLI command route rendering
 // ---------------------------------------------------------------------------
 
 /** Authored CLI command path shape. Strings are split on whitespace. */
@@ -71,8 +71,8 @@ export type CliCommandRouteSource = 'derived' | 'trail' | 'surface';
 /** Whether a resolved CLI command route is canonical or an alias. */
 export type CliCommandRouteKind = 'alias' | 'canonical';
 
-/** Trail-authored CLI projection metadata. */
-export interface TrailCliProjection {
+/** Trail-authored CLI rendering metadata. */
+export interface TrailCliRendering {
   readonly aliases?: readonly CliCommandAliasInput[] | undefined;
   readonly path?: CliCommandPathInput | undefined;
 }
@@ -85,18 +85,18 @@ export interface CliCommandRoute {
   readonly target: string;
 }
 
-/** Resolved CLI projection for one trail. */
-export interface TrailCliCommandProjection {
+/** Resolved CLI rendering for one trail. */
+export interface TrailCliCommandRendering {
   readonly path: readonly string[];
   readonly routes: readonly CliCommandRoute[];
 }
 
-interface TrailCliProjectionInput {
-  readonly cli?: CliCommandPathInput | TrailCliProjection | undefined;
+interface TrailCliRenderingInput {
+  readonly cli?: CliCommandPathInput | TrailCliRendering | undefined;
   readonly id: string;
 }
 
-export interface DeriveTrailCliCommandProjectionOptions {
+export interface DeriveTrailCliCommandOptions {
   readonly aliases?: readonly CliCommandAliasInput[] | undefined;
   readonly aliasSource?: Extract<CliCommandRouteSource, 'surface' | 'trail'>;
 }
@@ -306,38 +306,38 @@ export const normalizeCliCommandPath = (
     ? splitCliPathString(value, context)
     : value.map((segment) => validateCliSegment(segment, context));
 
-const isTrailCliProjection = (
-  value: CliCommandPathInput | TrailCliProjection
-): value is TrailCliProjection =>
+const isTrailCliRendering = (
+  value: CliCommandPathInput | TrailCliRendering
+): value is TrailCliRendering =>
   typeof value !== 'string' &&
   !Array.isArray(value) &&
   value !== null &&
   typeof value === 'object';
 
-const trailCliProjectionFor = (
-  trail: TrailCliProjectionInput
-): TrailCliProjection | undefined => {
+const trailCliRenderingFor = (
+  trail: TrailCliRenderingInput
+): TrailCliRendering | undefined => {
   if (trail.cli === undefined) {
     return undefined;
   }
-  return isTrailCliProjection(trail.cli) ? trail.cli : { path: trail.cli };
+  return isTrailCliRendering(trail.cli) ? trail.cli : { path: trail.cli };
 };
 
 const deriveCanonicalCliRoute = (
-  trail: TrailCliProjectionInput
+  trail: TrailCliRenderingInput
 ): CliCommandRoute => {
-  const projection = trailCliProjectionFor(trail);
+  const rendering = trailCliRenderingFor(trail);
   const path =
-    projection?.path === undefined
+    rendering?.path === undefined
       ? deriveCliPath(trail.id)
       : normalizeCliCommandPath(
-          projection.path,
+          rendering.path,
           `CLI command path for trail "${trail.id}"`
         );
   return {
     kind: 'canonical',
     path,
-    source: projection?.path === undefined ? 'derived' : 'trail',
+    source: rendering?.path === undefined ? 'derived' : 'trail',
     target: trail.id,
   };
 };
@@ -387,7 +387,7 @@ const normalizeCliAlias = ({
  *
  * MCP tool names must be `[a-z0-9_]+`: the app name prefixes the trail id,
  * dots and hyphens collapse to underscores, and everything lowercases. This
- * is the one owner for the projection — the MCP surface renders tools with
+ * is the one owner for the rendering — the MCP surface renders tools with
  * it and Warden checks binding-name collisions against it, so the two
  * readers cannot drift.
  *
@@ -404,14 +404,14 @@ export const deriveMcpToolName = (appName: string, trailId: string): string => {
 };
 
 /** Derive resolved CLI command routes for one trail. */
-export const deriveTrailCliCommandProjection = (
-  trail: TrailCliProjectionInput,
-  options?: DeriveTrailCliCommandProjectionOptions
-): TrailCliCommandProjection => {
+export const deriveTrailCliCommandRendering = (
+  trail: TrailCliRenderingInput,
+  options?: DeriveTrailCliCommandOptions
+): TrailCliCommandRendering => {
   const canonical = deriveCanonicalCliRoute(trail);
-  const projection = trailCliProjectionFor(trail);
+  const rendering = trailCliRenderingFor(trail);
   const trailAliases =
-    projection?.aliases?.map((alias) =>
+    rendering?.aliases?.map((alias) =>
       normalizeCliAlias({
         alias,
         canonicalPath: canonical.path,

package/src/detours.ts

@@ -1,7 +1,7 @@
 /**
  * Hard upper bound for detour recovery attempts.
  *
- * Execution and derived surface/topo projections both clamp declared detour
+ * Execution and derived surface/topo facts both clamp declared detour
  * attempts to this value so runtime behavior and inspectable contracts stay in
  * lockstep.
  */

package/src/{error-projection.ts → error-rendering.ts}

@@ -6,7 +6,7 @@ const errorRedactor = createRedactor();
 
 export const INTERNAL_ERROR_PUBLIC_MESSAGE = 'Internal server error';
 
-export interface ErrorDiagnosticsProjection {
+export interface ErrorDiagnosticsRendering {
   readonly category?: ErrorCategory | undefined;
   readonly context?: Record<string, unknown> | undefined;
   readonly message: string;
@@ -28,9 +28,9 @@ export const redactErrorStack = (
 ): string | undefined =>
   stack === undefined ? undefined : redactErrorString(stack);
 
-export const projectErrorDiagnostics = (
+export const renderErrorDiagnostics = (
   error: Error
-): ErrorDiagnosticsProjection => {
+): ErrorDiagnosticsRendering => {
   const context = isTrailsError(error)
     ? redactErrorContext(error.context)
     : undefined;

package/src/errors.ts

@@ -282,7 +282,7 @@ export type ErrorClassRegistryEntry =
 /**
  * Authored registry of concrete TrailsError classes.
  *
- * JavaScript cannot enumerate subclasses at runtime, so rule and projection
+ * JavaScript cannot enumerate subclasses at runtime, so rule and derivation
  * tooling should walk this owner-held list instead of hardcoding parallel
  * class-name tables. `RetryExhaustedError` is marked dynamic because it
  * inherits its runtime category from the wrapped error rather than always

package/src/execute.ts

@@ -158,19 +158,19 @@ export interface ExecuteTrailOptions {
    * Per-layer runtime input keyed by `Layer.name`.
    *
    * Surfaces (CLI, MCP, HTTP) parse their native idiom into a per-layer
-   * input object — usually projected from each layer's `input` schema —
+   * input object — usually derived from each layer's `input` schema —
    * and pass it here. The executor merges these into
    * `ctx.extensions[LAYER_INPUTS_KEY]` so layers can read their own slot
    * via `ctx.extensions?.[LAYER_INPUTS_KEY]?.[layer.name]`.
    *
-   * @see TRL-473 for the CLI projection contract.
+   * @see TRL-473 for the CLI rendering contract.
    */
   readonly layerInputs?: Readonly<Record<string, unknown>> | undefined;
   /**
    * Execute a specific live trail version.
    *
    * Omit for the current top-level contract. Number and numeric-string
-   * references select authored versions; marker references select projected
+   * references select authored versions; marker references select derived
    * content-addressed markers by unambiguous prefix.
    */
   readonly version?: TrailVersionReference | undefined;

package/src/fire.ts

@@ -36,7 +36,7 @@ import {
 import type { ActivationProvenance } from './activation-provenance.js';
 import type { ActivationWhereSpec } from './activation-source.js';
 import { getActivationWherePredicate } from './activation-source.js';
-import { activationSourceKey } from './activation-source-projection.js';
+import { activationSourceKey } from './activation-source-derivation.js';
 import { NotFoundError, TrailsError, ValidationError } from './errors.js';
 import { forkCtx } from './internal/fork-ctx.js';
 import {

package/src/index.ts

@@ -45,29 +45,29 @@ export type {
 export {
   createSurfaceErrorMapper,
   mapSurfaceError,
-  projectErrorClassSurface,
-  projectPublicSurfaceError,
-  projectSurfaceError,
+  renderErrorClassSurface,
+  renderPublicSurfaceError,
+  renderSurfaceError,
   surfaceErrorMap,
   surfaceErrorRegistry,
   surfaceNames,
 } from './transport-error-map.js';
 export type {
-  ErrorClassSurfaceProjection,
+  ErrorClassSurfaceRendering,
   SurfaceErrorCode,
   SurfaceErrorMapper,
   SurfaceErrorMappings,
-  SurfaceErrorProjection,
+  SurfaceErrorRendering,
   SurfaceName,
 } from './transport-error-map.js';
 export {
   INTERNAL_ERROR_PUBLIC_MESSAGE,
-  projectErrorDiagnostics,
+  renderErrorDiagnostics,
   redactErrorContext,
   redactErrorStack,
   redactErrorString,
-} from './error-projection.js';
-export type { ErrorDiagnosticsProjection } from './error-projection.js';
+} from './error-rendering.js';
+export type { ErrorDiagnosticsRendering } from './error-rendering.js';
 export type {
   DiagnosticBase,
   DiagnosticSeverity,
@@ -186,9 +186,9 @@ export type {
 export {
   activationSourceDeclarationSignature,
   activationSourceKey,
-  projectActivationSourceDeclaration,
-} from './activation-source-projection.js';
-export type { ActivationSourceProjection } from './activation-source-projection.js';
+  deriveActivationSourceFacts,
+} from './activation-source-derivation.js';
+export type { ActivationSourceFacts } from './activation-source-derivation.js';
 export {
   deriveSupportedTrailVersions,
   forkVersion,
@@ -260,8 +260,8 @@ export {
   shouldIncludeTrailForSurface,
 } from './surface-filter.js';
 export type { SurfaceFilterOptions } from './surface-filter.js';
-export { deriveSurfaceTrailVersionProjections } from './surface-versioning.js';
-export type { SurfaceTrailVersionProjection } from './surface-versioning.js';
+export { deriveSurfaceTrailVersionRenderings } from './surface-versioning.js';
+export type { SurfaceTrailVersionRendering } from './surface-versioning.js';
 export {
   shouldValidateSurfaceTopo,
   validateSurfaceTopo,
@@ -502,23 +502,23 @@ export {
   collectAttachedTypedLayers,
   LAYER_FIELD_RESERVED_NAMES,
   LAYER_FIELD_RESERVED_NAMES_KEBAB,
-  projectLayerFieldName,
-} from './layer-projection.js';
+  renderLayerFieldName,
+} from './layer-field-rendering.js';
 export type {
   AttachedLayerScope,
   AttachedTypedLayer,
-  LayerFieldProjection,
+  LayerFieldRendering,
   LayerFieldRenameReason,
-  ProjectedLayerField,
-  RenamedLayerFieldProjection,
-} from './layer-projection.js';
+  RenderedLayerField,
+  RenamedLayerFieldRendering,
+} from './layer-field-rendering.js';
 
 // Derive
 export {
   deriveCliPath,
   deriveFields,
   deriveMcpToolName,
-  deriveTrailCliCommandProjection,
+  deriveTrailCliCommandRendering,
   normalizeCliCommandPath,
 } from './derive.js';
 export type {
@@ -527,11 +527,11 @@ export type {
   CliCommandRoute,
   CliCommandRouteKind,
   CliCommandRouteSource,
-  DeriveTrailCliCommandProjectionOptions,
+  DeriveTrailCliCommandOptions,
   Field,
   FieldOverride,
-  TrailCliCommandProjection,
-  TrailCliProjection,
+  TrailCliCommandRendering,
+  TrailCliRendering,
 } from './derive.js';
 
 // Compose schema

package/src/{layer-projection.ts → layer-field-rendering.ts}

@@ -1,25 +1,25 @@
 /**
- * Shared, surface-agnostic helpers for projecting typed layer `input` schemas
+ * Shared, surface-agnostic helpers for rendering typed layer `input` schemas
  * onto a surface's native idiom.
  *
- * Layer projection has two halves:
+ * Layer rendering has two halves:
  *   1. **Collection** — walk the trail's effective layers (topo → surface →
  *      trail) and keep only the ones that declare an `input` schema. These
- *      are the layers a surface needs to project.
- *   2. **Naming/collision policy** — when a layer field's projected name
+ *      are the layers a surface needs to render.
+ *   2. **Naming/collision policy** — when a layer field's rendered name
  *      collides with a name already claimed by the trail, by another layer,
  *      or by a surface-reserved name, the field is renamed using the
  *      deterministic `<layerName>-<originalField>` rule. The collision-detection
- *      logic itself is surface-agnostic; the *shape* of the projected name
+ *      logic itself is surface-agnostic; the *shape* of the rendered name
  *      (kebab-case CLI flag, camelCase MCP parameter, HTTP request field)
  *      stays per-surface.
  *
  * This module owns the surface-agnostic half. CLI/MCP/HTTP each layer their
- * own projection on top: see `@ontrails/cli/build`, `@ontrails/mcp/build`,
+ * own rendering on top: see `@ontrails/cli/build`, `@ontrails/mcp/build`,
  * and `@ontrails/http/build`.
  *
- * @see TRL-473 for the CLI projection that introduced this contract.
- * @see TRL-474 for the MCP and HTTP projections that lifted these helpers.
+ * @see TRL-473 for the CLI rendering that introduced this contract.
+ * @see TRL-474 for the MCP and HTTP renderings that lifted these helpers.
  */
 
 import type { Layer } from './layer.js';
@@ -71,10 +71,10 @@ export interface AttachedTypedLayer {
 /**
  * Collect every typed layer attached to a trail in the same composition order
  * the executor uses (topo → surface → trail). Layers without an `input`
- * schema are skipped — they have nothing to project onto a surface.
+ * schema are skipped — they have nothing to render onto a surface.
  *
  * @param graph - The topo carrying topo-scope layers.
- * @param trail - The trail whose effective layers we are projecting.
+ * @param trail - The trail whose effective layers we are rendering.
  * @param surfaceLayers - Layers attached at surface scope (`options.layers`
  *   on the surface builder).
  */
@@ -109,15 +109,15 @@ export const collectAttachedTypedLayers = (
 // ---------------------------------------------------------------------------
 
 /**
- * Reason a layer field was renamed during projection.
+ * Reason a layer field was renamed during rendering.
  *
  * Surfaces map this onto their own warning/error idiom. CLI emits a stderr
- * warning, while MCP/HTTP rely on the projected schema as the source of truth.
+ * warning, while MCP/HTTP rely on the rendered schema as the source of truth.
  */
 export type LayerFieldRenameReason = 'reserved-name' | 'flag-collision';
 
 /**
- * Outcome of projecting a single layer field's name.
+ * Outcome of rendering a single layer field's name.
  *
  * `claimedName` is the name the surface will publish to consumers; it is the
  * field name when no collision was detected, or `<layerName>-<fieldName>` (or
@@ -125,13 +125,13 @@ export type LayerFieldRenameReason = 'reserved-name' | 'flag-collision';
  * a collision required a rename. `routingTarget` is the original field name
  * the value should be assigned back to inside the layer's runtime input.
  */
-export interface LayerFieldProjection {
+export interface LayerFieldRendering {
   readonly claimedName: string;
   readonly routingTarget: string;
   readonly renamed: false;
 }
 
-export interface RenamedLayerFieldProjection {
+export interface RenamedLayerFieldRendering {
   readonly claimedName: string;
   readonly routingTarget: string;
   readonly renamed: true;
@@ -139,40 +139,40 @@ export interface RenamedLayerFieldProjection {
   readonly reason: LayerFieldRenameReason;
 }
 
-export type ProjectedLayerField =
-  | LayerFieldProjection
-  | RenamedLayerFieldProjection;
+export type RenderedLayerField =
+  | LayerFieldRendering
+  | RenamedLayerFieldRendering;
 
 /**
- * Apply the deterministic collision rename rule to a single projected layer
+ * Apply the deterministic collision rename rule to a single rendered layer
  * field name.
  *
  * @param layerName - The layer's logical name (used as the rename prefix).
  * @param originalName - The layer field's name as authored on its schema.
- * @param projectedName - The candidate name in the surface's native idiom
+ * @param renderedName - The candidate name in the surface's native idiom
  *   (e.g. kebab-case for CLI, camelCase for MCP, request field for HTTP).
  * @param renamedName - The fallback name applied when a collision is detected.
  *   Surfaces compute this with their own casing rule.
  * @param claimedNames - Names already taken by the trail's input or by
- *   previous layer projections. Updated in place when a name is claimed.
+ *   previous layer renderings. Updated in place when a name is claimed.
  * @param reservedNames - Framework-owned names that force a rename across
- *   surface projections.
+ *   surface renderings.
  */
-export const projectLayerFieldName = (
+export const renderLayerFieldName = (
   _layerName: string,
   originalName: string,
-  projectedName: string,
+  renderedName: string,
   renamedName: string,
   claimedNames: Set<string>,
   reservedNames: ReadonlySet<string>
-): ProjectedLayerField => {
-  const collidesWithClaimed = claimedNames.has(projectedName);
-  const collidesWithReserved = reservedNames.has(projectedName);
+): RenderedLayerField => {
+  const collidesWithClaimed = claimedNames.has(renderedName);
+  const collidesWithReserved = reservedNames.has(renderedName);
 
   if (!collidesWithClaimed && !collidesWithReserved) {
-    claimedNames.add(projectedName);
+    claimedNames.add(renderedName);
     return {
-      claimedName: projectedName,
+      claimedName: renderedName,
       renamed: false,
       routingTarget: originalName,
     };
@@ -185,7 +185,7 @@ export const projectLayerFieldName = (
   claimedNames.add(claimedName);
   return {
     claimedName,
-    originalName: projectedName,
+    originalName: renderedName,
     reason: collidesWithReserved ? 'reserved-name' : 'flag-collision',
     renamed: true,
     routingTarget: originalName,

package/src/layer.ts

@@ -12,13 +12,13 @@ import type { Implementation } from './types.js';
  *
  * Layers attach at trail, surface, or topo scope and may declare an object
  * `input` schema describing the configuration they need from the surrounding
- * surface. Surface packages (CLI, MCP, HTTP) project this schema onto their
+ * surface. Surface packages (CLI, MCP, HTTP) render this schema onto their
  * native idioms — flags, tool parameters, query strings — alongside the
  * trail's own input schema.
  *
  * @remarks
- * The `input` schema is metadata for surface projection. It must be an object
- * schema so every surface can project named fields consistently. It is
+ * The `input` schema is metadata for surface rendering. It must be an object
+ * schema so every surface can render named fields consistently. It is
  * optional; layers without an `input` schema behave as plain wrappers. The
  * layer's `wrap` function is the runtime contract.
  */
@@ -31,13 +31,13 @@ export interface Layer {
   /**
    * Authored configuration the layer needs from the surrounding surface.
    *
-   * Surface packages project this schema onto their native idioms (CLI flags,
+   * Surface packages render this schema onto their native idioms (CLI flags,
    * MCP tool parameters, HTTP query strings) so a layer's input fields appear
    * alongside the trail's own input fields. Optional — layers that wrap purely
    * by behavior, with no surface-visible inputs, may omit it.
    *
-   * @see TRL-473 for CLI flag projection.
-   * @see TRL-474 for MCP and HTTP projection.
+   * @see TRL-473 for CLI flag rendering.
+   * @see TRL-474 for MCP and HTTP rendering.
    */
   readonly input?: LayerInputSchema | undefined;