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

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;
 

package/src/observe.ts

@@ -210,10 +210,10 @@ const stringifyDefaultConsoleRecord = (record: LogRecord): string => {
 };
 
 /**
- * In-core mirror of `@ontrails/observe`'s `createConsoleSink` shape, kept
+ * In-core mirror of `@ontrails/observability`'s `createConsoleSink` shape, kept
  * minimal and private to avoid a reverse dependency from `@ontrails/core`
- * onto `@ontrails/observe`. It mirrors the console level mapping in
- * `packages/observe/src/sinks.ts:50` and emits each record as a single-line
+ * onto `@ontrails/observability`. It mirrors the console level mapping in
+ * `packages/observability/src/sinks.ts:50` and emits each record as a single-line
  * JSON object written to the matching `console.{debug|info|warn|error}` method.
  *
  * @remarks
@@ -231,7 +231,7 @@ const createDefaultConsoleSink = (): LogSink => ({
       return;
     }
     const payload = stringifyDefaultConsoleRecord(record);
-    // oxlint-disable-next-line trails-local/no-console-in-packages -- ADR 0041 mandates a default console logger in core; this is the single sanctioned console boundary, mirroring `@ontrails/observe`'s `createConsoleSink`.
+    // oxlint-disable-next-line trails-local/no-console-in-packages -- ADR 0041 mandates a default console logger in core; this is the single sanctioned console boundary, mirroring `@ontrails/observability`'s `createConsoleSink`.
     console[method](payload);
   },
 });
@@ -251,8 +251,8 @@ export const normalizeObserve = (
   if (observe === undefined) {
     // ADR 0041 promises a non-null `ctx.logger` with zero configuration.
     // Returning the default config here lets the existing topo → adapter
-    // path project this log sink into `ctx.logger` without a second
-    // resolution point or a reverse dependency on `@ontrails/observe`.
+    // path renders this log sink into `ctx.logger` without a second
+    // resolution point or a reverse dependency on `@ontrails/observability`.
     return DEFAULT_OBSERVE_CONFIG;
   }
 

package/src/resource.ts

@@ -52,7 +52,7 @@ export interface ResourceSpec<T, C = unknown> {
   readonly description?: string | undefined;
   /** Arbitrary meta for tooling and filtering. */
   readonly meta?: Readonly<Record<string, unknown>> | undefined;
-  /** Signals projected or owned by this resource. */
+  /** Signals derived or owned by this resource. */
   readonly signals?: readonly AnySignal[] | undefined;
   /** Reserved for future resource-specific design; trail versioning is trail-only. */
   readonly version?: never;

package/src/schedule-runtime.ts

@@ -1,5 +1,5 @@
 import type { ActivationEntry } from './activation-source.js';
-import { activationSourceKey } from './activation-source-projection.js';
+import { activationSourceKey } from './activation-source-derivation.js';
 import {
   buildActivationProvenanceTraceAttrs,
   withActivationProvenance,

package/src/serialization.ts

@@ -26,7 +26,7 @@ import {
   redactErrorContext,
   redactErrorStack,
   redactErrorString,
-} from './error-projection.js';
+} from './error-rendering.js';
 import { Result } from './result.js';
 
 // ---------------------------------------------------------------------------

package/src/structured-examples.ts

@@ -40,7 +40,7 @@ export interface StructuredSignalExample {
 // `Date`, `RegExp`, `Map`, and `Set` are objects (`typeof === 'object'`),
 // so they would pass the structural walk and reach `JSON.stringify`, which
 // silently coerces them: a `Date` becomes its ISO string, a `RegExp` and
-// any `Map`/`Set` become `{}`. Either way the projected shape diverges
+// any `Map`/`Set` become `{}`. Either way the derived shape diverges
 // from the example author's declared input. Treat them as non-serializable
 // leaves so the example is dropped rather than misrepresented to MCP
 // clients.
@@ -107,7 +107,7 @@ const signalIdFromAssertion = (
     : undefined;
 };
 
-const projectSignalAssertion = (
+const deriveSignalAssertion = (
   assertion: TrailExampleSignalAssertion
 ): StructuredTrailExampleSignalAssertion | undefined => {
   const signalId = signalIdFromAssertion(assertion);
@@ -115,43 +115,43 @@ const projectSignalAssertion = (
     return undefined;
   }
 
-  const projected: Record<string, unknown> = { signalId };
+  const derived: Record<string, unknown> = { signalId };
   if (assertion.payload !== undefined) {
     const payload = toJsonSerializable(assertion.payload);
     if (payload === undefined) {
       return undefined;
     }
-    projected['payload'] = payload;
+    derived['payload'] = payload;
   }
   if (assertion.payloadMatch !== undefined) {
     const payloadMatch = toJsonSerializable(assertion.payloadMatch);
     if (payloadMatch === undefined) {
       return undefined;
     }
-    projected['payloadMatch'] = payloadMatch;
+    derived['payloadMatch'] = payloadMatch;
   }
   if (assertion.times !== undefined) {
-    projected['times'] = assertion.times;
+    derived['times'] = assertion.times;
   }
   return Object.freeze(
-    projected
+    derived
   ) as unknown as StructuredTrailExampleSignalAssertion;
 };
 
-const projectSignalAssertions = (
+const deriveSignalAssertions = (
   assertions: readonly TrailExampleSignalAssertion[] | undefined
 ): readonly StructuredTrailExampleSignalAssertion[] | undefined => {
   if (assertions === undefined) {
     return undefined;
   }
-  const projected = assertions.map(projectSignalAssertion);
-  if (projected.some((assertion) => assertion === undefined)) {
+  const derived = assertions.map(deriveSignalAssertion);
+  if (derived.some((assertion) => assertion === undefined)) {
     return undefined;
   }
-  return Object.freeze(projected as StructuredTrailExampleSignalAssertion[]);
+  return Object.freeze(derived as StructuredTrailExampleSignalAssertion[]);
 };
 
-const projectExample = (
+const deriveExample = (
   example: TrailExample<unknown, unknown>,
   provenance: StructuredTrailExampleProvenance
 ): StructuredTrailExample | undefined => {
@@ -160,7 +160,7 @@ const projectExample = (
     return undefined;
   }
 
-  const projected: Record<string, unknown> = {
+  const derived: Record<string, unknown> = {
     input,
     kind: example.error === undefined ? 'success' : 'error',
     name: example.name,
@@ -168,37 +168,37 @@ const projectExample = (
   };
 
   if (example.description !== undefined) {
-    projected['description'] = example.description;
+    derived['description'] = example.description;
   }
   if (example.expected !== undefined) {
     const expected = toJsonSerializable(example.expected);
     if (expected === undefined) {
       return undefined;
     }
-    projected['expected'] = expected;
+    derived['expected'] = expected;
   }
   if (example.expectedMatch !== undefined) {
     const expectedMatch = toJsonSerializable(example.expectedMatch);
     if (expectedMatch === undefined) {
       return undefined;
     }
-    projected['expectedMatch'] = expectedMatch;
+    derived['expectedMatch'] = expectedMatch;
   }
   if (example.error !== undefined) {
-    projected['error'] = example.error;
+    derived['error'] = example.error;
   }
   if (example.signals !== undefined) {
-    const signals = projectSignalAssertions(example.signals);
+    const signals = deriveSignalAssertions(example.signals);
     if (signals === undefined) {
       return undefined;
     }
-    projected['signals'] = signals;
+    derived['signals'] = signals;
   }
 
-  return Object.freeze(projected) as unknown as StructuredTrailExample;
+  return Object.freeze(derived) as unknown as StructuredTrailExample;
 };
 
-const projectSignalExample = (
+const deriveSignalExample = (
   payload: unknown
 ): StructuredSignalExample | undefined => {
   const serializablePayload = toJsonSerializable(payload);
@@ -222,13 +222,13 @@ export const deriveStructuredTrailExamples = (
   }
 
   const provenance = options?.provenance ?? { source: 'trail.examples' };
-  const projected = examples
-    .map((example) => projectExample(example, provenance))
+  const derived = examples
+    .map((example) => deriveExample(example, provenance))
     .filter(
       (example): example is StructuredTrailExample => example !== undefined
     );
 
-  return projected.length > 0 ? Object.freeze(projected) : undefined;
+  return derived.length > 0 ? Object.freeze(derived) : undefined;
 };
 
 export const deriveStructuredSignalExamples = (
@@ -238,11 +238,11 @@ export const deriveStructuredSignalExamples = (
     return undefined;
   }
 
-  const projected = examples
-    .map(projectSignalExample)
+  const derived = examples
+    .map(deriveSignalExample)
     .filter(
       (example): example is StructuredSignalExample => example !== undefined
     );
 
-  return projected.length > 0 ? Object.freeze(projected) : undefined;
+  return derived.length > 0 ? Object.freeze(derived) : undefined;
 };

package/src/surface-derivation.ts

@@ -21,7 +21,7 @@ export interface SurfaceSelectionOptions {
 }
 
 export interface SurfaceValidationOptions {
-  /** Set to `false` to skip established-topo validation during projection. */
+  /** Set to `false` to skip established-topo validation during derivation. */
   readonly validate?: boolean | undefined;
 }
 

package/src/surface-overlay.ts

@@ -33,7 +33,7 @@ export const SURFACES_OVERLAY_NAMESPACE = 'surfaces' as const;
 /**
  * Who authored an overlay envelope.
  *
- * `'adapter-derived'` marks facts an adapter projects from the topo;
+ * `'adapter-derived'` marks facts an adapter renders from the topo;
  * `'app-authored'` marks bindings the app wrote by hand. Surfaces obey
  * app-authored overlays only — adapters contribute facts, never bindings.
  *
@@ -242,7 +242,7 @@ export interface SurfaceOverlay {
   /** The bindings schema, enforced again on the compile path. */
   readonly schema: z.ZodType;
   /**
-   * Project the overlay facts. Ignores the topo — bindings are authored —
+   * Derive the overlay facts. Ignores the topo — bindings are authored —
    * so the parameter is optional; the signature stays structurally
    * assignable to the adapter-kit `Overlay` contract's `(topo) => unknown`.
    */
@@ -313,7 +313,7 @@ export interface OverlayEnvelopeLike {
   readonly provenance?: OverlayProvenance | undefined;
   /** The envelope's fact schema. */
   readonly schema: z.ZodType;
-  /** Project the envelope's facts. */
+  /** Derive the envelope's facts. */
   derive(topo?: Topo): unknown;
   /**
    * Static surface bindings, when the envelope carries them directly.
@@ -575,11 +575,11 @@ const assertMcpSynonymBindingName = (name: string): void => {
 
 /**
  * Derive the deterministic default description for an MCP grouped entry
- * projected from the `surfaces` overlay.
+ * rendered from the `surfaces` overlay.
  *
  * Both the MCP surface (the runtime tool description) and Topography (the
  * lock's trailhead entry description) read this helper, so the authored
- * binding projects one description everywhere.
+ * binding renders one description everywhere.
  *
  * @example
  * ```ts

package/src/surface-versioning.ts

@@ -5,7 +5,7 @@ import {
 } from './trail.js';
 import { deriveTrailVersionMarkers } from './version-marker.js';
 
-export interface SurfaceTrailVersionProjection {
+export interface SurfaceTrailVersionRendering {
   readonly current: boolean;
   readonly deprecated: boolean;
   readonly marker?: string | undefined;
@@ -13,9 +13,9 @@ export interface SurfaceTrailVersionProjection {
   readonly version: number;
 }
 
-export const deriveSurfaceTrailVersionProjections = (
+export const deriveSurfaceTrailVersionRenderings = (
   trail: AnyTrail
-): readonly SurfaceTrailVersionProjection[] | undefined => {
+): readonly SurfaceTrailVersionRendering[] | undefined => {
   if (trail.version === undefined) {
     return undefined;
   }

package/src/tracing.ts

@@ -4,7 +4,7 @@
  * This module is the home for the trace record type, the sink interface,
  * the sink registry, and the helpers `executeTrail` uses to create root
  * trace records and child spans. Core keeps this minimal contract public so
- * `@ontrails/observe`, `@ontrails/tracing`, adapters, and tests share the
+ * `@ontrails/observability`, adapters, and tests share the
  * same intrinsic execution record shape.
  *
  * Tracing is intrinsic: every `executeTrail` call automatically produces a
@@ -58,8 +58,8 @@ export interface TraceRecord {
 /**
  * Minimal shape a tracing sink must satisfy.
  *
- * Kept intentionally tiny so adapters in `@ontrails/tracing`,
- * `@ontrails/observe`, and user code can all satisfy it without
+ * Kept intentionally tiny so adapters in `@ontrails/observability`,
+ * `@ontrails/observability`, and user code can all satisfy it without
  * additional dependencies.
  */
 export interface TraceSink {

package/src/trail.ts

@@ -15,7 +15,7 @@ import type { AnyEntity } from './entity.js';
 import type {
   FieldOverride,
   CliCommandPathInput,
-  TrailCliProjection,
+  TrailCliRendering,
 } from './derive.js';
 import type { Layer } from './layer.js';
 import type { Result } from './result.js';
@@ -504,13 +504,13 @@ export interface TrailSpec<
    * `topo → surface → trail → implementation` (outermost-first).
    *
    * Layers are typed and inspectable. Omit `input` for surface-invisible
-   * wrappers that do not project any fields.
+   * wrappers that do not render any fields.
    */
   readonly layers?: readonly Layer[] | undefined;
   /** Per-field overrides for deriveFields() (labels, hints, options) */
   readonly fields?: Readonly<Record<string, FieldOverride>> | undefined;
-  /** CLI projection metadata for canonical command path overrides and aliases. */
-  readonly cli?: CliCommandPathInput | TrailCliProjection | undefined;
+  /** CLI rendering metadata for canonical command path overrides and aliases. */
+  readonly cli?: CliCommandPathInput | TrailCliRendering | undefined;
   /** Entities this trail operates on. */
   readonly entities?: readonly AnyEntity[] | undefined;
   /** IDs or trail objects of downstream trails this trail may invoke via ctx.compose() */
@@ -548,13 +548,13 @@ export interface TrailSpec<
     | undefined;
   /** Auth requirement: scopes object, 'public', or omitted (undeclared) */
   readonly permit?: PermitRequirement | undefined;
-  /** Primary input fields and their order. CLI projects as positional args. */
+  /** Primary input fields and their order. CLI derives as positional args. */
   readonly args?: readonly string[] | false | undefined;
   /** Current trail version number. Omit for current-only unversioned trails. */
   readonly version?: number | undefined;
   /** Explicit historical trail versions. Current stays top-level. */
   readonly versions?: TrailVersions<I, O> | undefined;
-  /** Version markers are projected into the resolved graph, not authored. */
+  /** Version markers are derived into the resolved graph, not authored. */
   readonly marker?: never;
 }
 
@@ -976,12 +976,12 @@ const normalizeVersionEntry = <CurrentInput, CurrentOutput>(
 
   if (hasOwn(raw, 'kind')) {
     throw new ValidationError(
-      `Trail "${trailId}" version ${version} must not author kind; it is projected`
+      `Trail "${trailId}" version ${version} must not author kind; it is derived`
     );
   }
   if (hasOwn(raw, 'marker')) {
     throw new ValidationError(
-      `Trail "${trailId}" version ${version} must not author marker; it is projected`
+      `Trail "${trailId}" version ${version} must not author marker; it is derived`
     );
   }
 
@@ -1286,7 +1286,7 @@ export function trail<
 
   if (hasOwn(rawSpec, 'marker')) {
     throw new ValidationError(
-      `Trail "${resolved.id}" must not author marker; it is projected`
+      `Trail "${resolved.id}" must not author marker; it is derived`
     );
   }
 

package/src/trails/derive-trail.ts

@@ -760,7 +760,7 @@ const synthesizeDefaultImplementation = <
 };
 
 /**
- * Mechanically project one CRUD-shaped trail from a entity declaration.
+ * Mechanically derive one CRUD-shaped trail from a entity declaration.
  *
  * When `spec.implementation` is omitted and the call declares a single resource, the
  * helper derives a default implementation that dispatches to the resource accessor

package/src/transport-error-map.ts

@@ -9,14 +9,12 @@ import {
   codesByCategory,
   errorClasses,
   exitCodeMap,
-  isTrailsError,
   jsonRpcCodeMap,
   statusCodeMap,
 } from './errors.js';
-import {
-  INTERNAL_ERROR_PUBLIC_MESSAGE,
-  redactErrorString,
-} from './error-projection.js';
+import { renderPublicError } from './error-rendering.js';
+
+const CLI_INTERNAL_ERROR_PUBLIC_MESSAGE = 'Internal error';
 
 export const surfaceNames = ['cli', 'http', 'jsonRpc', 'mcp'] as const;
 
@@ -48,7 +46,7 @@ export type SurfaceErrorMappings<T> = Record<ErrorCategory, T>;
 export type SurfaceErrorCode =
   (typeof codesByCategory)[ErrorCategory][(typeof surfaceCodeKeys)[SurfaceName]];
 
-export interface SurfaceErrorProjection {
+export interface SurfaceErrorRendering {
   readonly category: ErrorCategory;
   readonly code: SurfaceErrorCode;
   readonly message: string;
@@ -57,7 +55,7 @@ export interface SurfaceErrorProjection {
   readonly surface: SurfaceName;
 }
 
-export interface ErrorClassSurfaceProjection {
+export interface ErrorClassSurfaceRendering {
   readonly category: ErrorCategory;
   readonly code: SurfaceErrorCode;
   readonly name: string;
@@ -102,10 +100,10 @@ export const mapSurfaceError = (
 ): SurfaceErrorCode =>
   codesByCategory[error.category][surfaceCodeKeys[surface]];
 
-export const projectSurfaceError = (
+export const renderSurfaceError = (
   surface: SurfaceName,
   error: TrailsError
-): SurfaceErrorProjection => ({
+): SurfaceErrorRendering => ({
   category: error.category,
   code: mapSurfaceError(surface, error),
   message: error.message,
@@ -114,27 +112,18 @@ export const projectSurfaceError = (
   surface,
 });
 
-export const projectPublicSurfaceError = (
+export const renderPublicSurfaceError = (
   surface: SurfaceName,
   error: Error
-): SurfaceErrorProjection => {
-  if (isTrailsError(error)) {
-    const projection = projectSurfaceError(surface, error);
-    return {
-      ...projection,
-      message:
-        projection.category === 'internal'
-          ? INTERNAL_ERROR_PUBLIC_MESSAGE
-          : redactErrorString(projection.message),
-    };
-  }
-
+): SurfaceErrorRendering => {
+  const rendering = renderPublicError(error);
   return {
-    category: 'internal',
-    code: codesByCategory.internal[surfaceCodeKeys[surface]],
-    message: INTERNAL_ERROR_PUBLIC_MESSAGE,
-    name: 'InternalError',
-    retryable: false,
+    ...rendering,
+    code: codesByCategory[rendering.category][surfaceCodeKeys[surface]],
+    message:
+      surface === 'cli' && rendering.category === 'internal'
+        ? CLI_INTERNAL_ERROR_PUBLIC_MESSAGE
+        : rendering.message,
     surface,
   };
 };
@@ -151,15 +140,15 @@ const fixedErrorClassByName: ReadonlyMap<string, FixedErrorClassRegistryEntry> =
   );
 
 /**
- * Project a known error class name onto a surface without constructing it.
+ * Render a known error class name onto a surface without constructing it.
  *
  * Dynamic-category errors such as `RetryExhaustedError` return `undefined`
  * because their surface code depends on the wrapped runtime error.
  */
-export const projectErrorClassSurface = (
+export const renderErrorClassSurface = (
   surface: SurfaceName,
   errorName: string
-): ErrorClassSurfaceProjection | undefined => {
+): ErrorClassSurfaceRendering | undefined => {
   const entry = fixedErrorClassByName.get(errorName);
   if (entry === undefined) {
     return undefined;

package/src/types.ts

@@ -215,13 +215,13 @@ export const SURFACE_LAYER_NAMES_KEY = '__trails_surface_layer_names' as const;
 /**
  * Context extension key carrying per-layer runtime input.
  *
- * Surfaces (CLI, MCP, HTTP) project each typed layer's `input` schema onto
+ * Surfaces (CLI, MCP, HTTP) render each typed layer's `input` schema onto
  * their native idioms (flags, tool params, query strings). At execute time
  * the parsed values are partitioned per layer and stored under this key as
  * `Record<layerName, unknown>`. Layers that need runtime input 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 derivation contract.
  */
 export const LAYER_INPUTS_KEY = '__trails_layer_inputs' as const;
 

package/src/validate-established-topo.ts

@@ -5,7 +5,7 @@ import { validateDraftFreeTopo } from './draft.js';
 import type { TopoDiagnostic } from './validate-topo.js';
 import { validateTopo } from './validate-topo.js';
 
-const PROJECTION_BLOCKING_RULES = new Set([
+const DERIVATION_BLOCKING_RULES = new Set([
   'compose-cycle',
   'compose-exists',
   'no-self-compose',
@@ -20,12 +20,12 @@ const PROJECTION_BLOCKING_RULES = new Set([
   'signal-origin-exists',
 ]);
 
-const isProjectionBlockingIssue = (issue: TopoDiagnostic): boolean =>
-  PROJECTION_BLOCKING_RULES.has(issue.rule) ||
+const isDerivationBlockingIssue = (issue: TopoDiagnostic): boolean =>
+  DERIVATION_BLOCKING_RULES.has(issue.rule) ||
   (issue.rule === 'activation-source-input-compatible' &&
     issue.sourceKind === 'queue');
 
-const keepProjectionBlockingIssues = (
+const keepDerivationBlockingIssues = (
   result: ReturnType<typeof validateTopo>
 ) => {
   if (result.isOk()) {
@@ -35,7 +35,7 @@ const keepProjectionBlockingIssues = (
   const issues = (
     result.error.context as { issues?: readonly TopoDiagnostic[] } | undefined
   )?.issues;
-  const remainingIssues = issues?.filter(isProjectionBlockingIssue);
+  const remainingIssues = issues?.filter(isDerivationBlockingIssue);
 
   if (remainingIssues === undefined || remainingIssues.length === 0) {
     return Result.ok();
@@ -59,7 +59,7 @@ const keepProjectionBlockingIssues = (
  * valid, and they must also reject any remaining draft state.
  */
 export const validateEstablishedTopo = (topo: Topo) => {
-  const structural = keepProjectionBlockingIssues(validateTopo(topo));
+  const structural = keepDerivationBlockingIssues(validateTopo(topo));
   if (structural.isErr()) {
     return structural;
   }

package/src/validate-topo.ts

@@ -11,7 +11,7 @@ import { getActivationSourceInputCompatibilityIssues } from './activation-source
 import {
   activationSourceDeclarationSignature,
   activationSourceKey,
-} from './activation-source-projection.js';
+} from './activation-source-derivation.js';
 import type { AnyEntity } from './entity.js';
 import { getEntityReferences } from './entity.js';
 import { ValidationError } from './errors.js';

package/src/validation.ts

@@ -84,9 +84,9 @@ const getSchemaJsonSchemaOverride = (
 };
 
 /**
- * Whether a schema has a deterministic JSON-schema override projection (for
+ * Whether a schema has a deterministic JSON-schema override derivation (for
  * example `blobRefSchema`, a `z.custom(...)` carrying the descriptor metadata).
- * Such schemas project to a canonical descriptor regardless of their underlying
+ * Such schemas derive to a canonical descriptor regardless of their underlying
  * Zod internals, so marker derivation can treat them as supported.
  */
 export const schemaHasJsonSchemaOverride = (schema: z.ZodType): boolean =>