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

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @ontrails/topography
 
+## 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
+
+- [`9f0842e`](https://github.com/outfitter-dev/trails/commit/9f0842ee9d7c7155d86a4fd023760ac0a5636f5d): Retire the temporary root vocabulary-cutover toolchain now that Regrade owns
+  structured migration plans, safe rewrites, classification, census, CLI/MCP
+  reports, and immutable history. Remove the obsolete source exemptions so
+  Oxlint and Warden enforce the durable transition contract directly, and add a
+  history-driven Regrade audit surface for current-tree regression checks.
+
+## 1.0.0-beta.42
+
 ## 1.0.0-beta.41
 
 ## 1.0.0-beta.40

package/README.md

@@ -20,7 +20,7 @@ This is not a private helper package. The Trails operator app consumes Topograph
 ## What it owns
 
 - deterministic TopoGraph generation from an established topo
-- structured example and field-override provenance projection for TopoGraph entries
+- structured example and field-override provenance derivation for TopoGraph entries
 - stable hashing for CI drift detection
 - semantic diffing between two TopoGraphs
 - file I/O helpers for root `trails.lock` plus legacy artifact-family readers
@@ -91,11 +91,11 @@ Compatibility helpers still read the previous `.trails/trails.lock` plus `.trail
 | `readTopoGraph(options?)` | Read a TopoGraph from v4 `trails.lock` or legacy `topo.lock` |
 | `writeTopoGraph(topoGraph, options?)` | Write legacy `topo.lock` for explicit migration/testing paths |
 | `writeLockManifest(manifest, options?)` | Write legacy `trails.lock` as a v3 manifest |
-| `readLockManifest(options?)` | Read v3 manifests, projecting v4 locks back to v3 for compatibility |
+| `readLockManifest(options?)` | Read v3 manifests, deriving v4 locks back to v3 for compatibility |
 | `createTopoStore(options?)` | Read-only query interface over the persisted topo state in the Trails state-store `trails.db` |
 | `createMockTopoStore(seed?)` | Seeded in-memory mock for tests that need a `ReadOnlyTopoStore` |
 | `topoStore` | Read-only `resource()` wrapper around `createTopoStore`, suitable for `resources: [...]` |
-| `createTopoSnapshot(topo, options?)` | Persist a new topo snapshot row plus its denormalized projections |
+| `createTopoSnapshot(topo, options?)` | Persist a new topo snapshot row plus its denormalized derived facts |
 | `listTopoSnapshots(options?)` | List historical topo snapshots (filterable by pinned status) |
 | `pinTopoSnapshot(id, name, options?)` / `unpinTopoSnapshot(nameOrId, options?)` | Manage human-named pins |
 
@@ -132,7 +132,7 @@ Wayfind trails are internal by default. Surface hosts expose selected query trai
 
 ### Operator File Outline
 
-File outline is an operator capability, not a public Topographer query trail. Use `trails wayfind file <file> --outline` for a compact map of authored trail and app declarations, surface membership, saved graph matches, and diagnostics. Add `--source` when the inspection also needs import, export, and declaration rows. The operator parses the explicit file through `@ontrails/source` and reconciles trail IDs with saved Topographer artifacts. Missing artifacts are diagnostics, not hard failures, so outline remains useful in a fresh checkout or during repair work.
+File outline is an operator capability, not a public Topography query trail. Use `trails wayfind file <file> --outline` for a compact map of authored trail and app declarations, surface membership, saved graph matches, and diagnostics. Add `--source` when the inspection also needs import, export, and declaration rows. The operator parses the explicit file through `@ontrails/source` and reconciles trail IDs with saved Topography artifacts. Missing artifacts are diagnostics, not hard failures, so outline remains useful in a fresh checkout or during repair work.
 
 ### Backend Support Subpath
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/topography",
-  "version": "1.0.0-beta.41",
+  "version": "1.0.0-beta.43",
   "description": "Durable graph substrate for Trails: deterministic TopoGraphs, lockfile helpers, and semantic diffing.",
   "files": [
     "src/**/*.ts",
@@ -24,10 +24,10 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/adapter-kit": "^1.0.0-beta.41"
+    "@ontrails/adapter-kit": "^1.0.0-beta.43"
   },
   "peerDependencies": {
-    "@ontrails/core": "^1.0.0-beta.41",
+    "@ontrails/core": "^1.0.0-beta.43",
     "zod": "^4.3.5"
   }
 }

package/src/activation-report.ts

@@ -1,13 +1,13 @@
 import type {
   ActivationEntry,
   ActivationSource,
-  ActivationSourceProjection,
+  ActivationSourceFacts,
   AnyTrail,
   Topo,
 } from '@ontrails/core';
 import {
   activationSourceKey,
-  projectActivationSourceDeclaration,
+  deriveActivationSourceFacts,
 } from '@ontrails/core';
 
 export interface ActivationChainReport {
@@ -18,7 +18,7 @@ export interface ActivationChainReport {
 
 type JsonSchemaReport = Readonly<Record<string, unknown>>;
 
-export interface ActivationSourceReport extends ActivationSourceProjection {
+export interface ActivationSourceReport extends ActivationSourceFacts {
   readonly cron?: string | undefined;
   readonly hasParse?: true | undefined;
   readonly hasPayloadSchema?: true | undefined;
@@ -153,12 +153,12 @@ const compareChains = (
 const sortedUnique = (values: Iterable<string>): readonly string[] =>
   [...new Set(values)].toSorted();
 
-const projectActivationSource = (
+const deriveActivationSource = (
   source: ActivationSource
 ): ActivationSourceReport =>
-  projectActivationSourceDeclaration(source) as ActivationSourceReport;
+  deriveActivationSourceFacts(source) as ActivationSourceReport;
 
-const projectActivationEdge = (
+const deriveActivationEdge = (
   trailId: string,
   activation: ActivationEntry
 ): ActivationEdgeReport => {
@@ -187,8 +187,8 @@ const collectActivationSourceCatalog = (
   const sources = new Map<string, ActivationSourceReport>();
   for (const trail of trails) {
     for (const activation of trail.activationSources) {
-      const projected = projectActivationSource(activation.source);
-      sources.set(projected.key, projected);
+      const derived = deriveActivationSource(activation.source);
+      sources.set(derived.key, derived);
     }
   }
   return [...sources.values()].toSorted((a, b) => a.key.localeCompare(b.key));
@@ -200,7 +200,7 @@ const collectActivationEdges = (
   const edges = new Map<string, ActivationEdgeReport>();
   for (const trail of trails) {
     for (const activation of trail.activationSources) {
-      const edge = projectActivationEdge(trail.id, activation);
+      const edge = deriveActivationEdge(trail.id, activation);
       const key = `${edge.sourceKey}\0${edge.trailId}`;
       const previous = edges.get(key);
       edges.set(

package/src/derive.ts

@@ -7,9 +7,9 @@ import {
   activationSourceKey,
   deriveStructuredSignalExamples,
   deriveStructuredTrailExamples,
-  deriveTrailCliCommandProjection,
+  deriveTrailCliCommandRendering,
   getEntityReferences,
-  projectActivationSourceDeclaration,
+  deriveActivationSourceFacts,
   validateEstablishedTopo,
   signalDiagnosticDefinitions,
   zodToJsonSchema,
@@ -28,14 +28,14 @@ import type {
 } from '@ontrails/core';
 
 import { addPermitRequirement } from './permit.js';
-import { collectLibraryProjection } from './library-projection.js';
+import { deriveTopoGraphLibrary } from './library-derivation.js';
 import { collectTopoGraphOverlays } from './overlays.js';
 import {
   resolveCliAliasInputsFromOverlays,
   resolveTrailheadEntriesFromOverlays,
 } from './surface-bindings.js';
 import { TOPO_GRAPH_SCHEMA_VERSION } from './types.js';
-import { projectTrailVersions } from './versioning.js';
+import { deriveTrailVersions } from './versioning.js';
 import type {
   DeriveTopoGraphOptions,
   JsonSchema,
@@ -156,12 +156,12 @@ const SIGNAL_GOVERNANCE_HOOKS = {
   producers: 'trail.fires',
 } as const;
 
-const projectActivationSource = (
+const deriveActivationSource = (
   source: ActivationSource
 ): TopoGraphActivationSource =>
-  projectActivationSourceDeclaration(source) as TopoGraphActivationSource;
+  deriveActivationSourceFacts(source) as TopoGraphActivationSource;
 
-const projectActivationEdge = (
+const deriveActivationEdge = (
   trailId: string,
   activation: ActivationEntry
 ): TopoGraphActivationEdge => {
@@ -190,8 +190,8 @@ const collectActivationSourceCatalog = (
   const sources = new Map<string, TopoGraphActivationSource>();
   for (const trail of topo.trails.values()) {
     for (const activation of trail.activationSources) {
-      const projected = projectActivationSource(activation.source);
-      sources.set(projected.key, projected);
+      const derived = deriveActivationSource(activation.source);
+      sources.set(derived.key, derived);
     }
   }
   return [...sources.values()].toSorted((a, b) => a.key.localeCompare(b.key));
@@ -203,7 +203,7 @@ const collectActivationGraphEdges = (
   const edges = new Map<string, TopoGraphActivationEdge>();
   for (const trail of topo.trails.values()) {
     for (const activation of trail.activationSources) {
-      const edge = projectActivationEdge(trail.id, activation);
+      const edge = deriveActivationEdge(trail.id, activation);
       const key = `${edge.sourceKey}\0${edge.trailId}`;
       const previous = edges.get(key);
       edges.set(
@@ -359,7 +359,7 @@ const addTrailRelations = (
         ...(activation.meta === undefined
           ? {}
           : { meta: canonicalize(activation.meta) }),
-        source: projectActivationSource(activation.source),
+        source: deriveActivationSource(activation.source),
         ...(activation.where === undefined
           ? {}
           : { where: sortKeys({ predicate: true }) }),
@@ -482,16 +482,16 @@ const addVersioning = (
   if (t.version === undefined) {
     return;
   }
-  const projection = projectTrailVersions(t, toSortedJsonSchema);
-  if (projection === undefined) {
+  const derivation = deriveTrailVersions(t, toSortedJsonSchema);
+  if (derivation === undefined) {
     return;
   }
 
-  entry['marker'] = projection.marker;
-  entry['supports'] = projection.supports;
-  entry['version'] = projection.version;
-  if (projection.versions !== undefined) {
-    entry['versions'] = projection.versions;
+  entry['marker'] = derivation.marker;
+  entry['supports'] = derivation.supports;
+  entry['version'] = derivation.version;
+  if (derivation.versions !== undefined) {
+    entry['versions'] = derivation.versions;
   }
 };
 
@@ -503,7 +503,7 @@ const trailToEntry = (
   const raw = t as unknown as Record<string, unknown>;
   const surfaces = extractSurfaces(raw);
   const entry: Record<string, unknown> = {
-    cli: deriveTrailCliCommandProjection(t, {
+    cli: deriveTrailCliCommandRendering(t, {
       aliasSource: 'surface',
       aliases: surfaceAliases?.[t.id],
     }),
@@ -673,7 +673,7 @@ export const deriveTopoGraph = (
     options?.overlays
   );
   const overlays = collectTopoGraphOverlays(topo, options?.overlays);
-  const library = collectLibraryProjection(topo);
+  const library = deriveTopoGraphLibrary(topo);
 
   return {
     activationGraph: buildActivationGraph(activationEdges, activationSources),

package/src/index.ts

@@ -61,7 +61,7 @@ export {
   TRAILS_LOCK_SCHEMA_VERSION,
   trailsLockSchema,
   topoGraphTrailheadEntrySchema,
-  topoGraphLibraryProjectionSchema,
+  topoGraphLibraryDerivedSchema,
   workspaceTopoMetadataSchema,
   workspaceTrailCollisionSchema,
   workspaceTrailEntrySchema,
@@ -98,7 +98,7 @@ export type {
   TopoGraphLibraryExclusionReason,
   TopoGraphLibraryExport,
   TopoGraphLibraryExportSource,
-  TopoGraphLibraryProjection,
+  TopoGraphLibraryDerived,
   TopoGraphLayerReference,
   TopoGraphOverlayRegistration,
   TopoGraphOverlays,
@@ -151,7 +151,7 @@ export type {
   TopoStoreRef,
   TopoStoreSignalDetailRecord,
   TopoStoreSignalRecord,
-  TopoStoreSurfaceProjectionRecord,
+  TopoStoreSurfaceDerivedRecord,
   TopoStoreTopoGraphEntryRecord,
   TopoStoreTopoGraphRecord,
   TopoStoreTrailDetailRecord,
@@ -169,7 +169,7 @@ export type {
   TrailErrorFacts,
   TrailErrorFactsCompleteness,
   TrailErrorFactsOptions,
-  TrailErrorTaxonomyProjection,
+  TrailErrorTaxonomyFacts,
 } from './wayfind/error-facts.js';
 export {
   createWayfinderEntityPredicate,

package/src/internal/topo-store-read.ts

@@ -52,7 +52,7 @@ export interface TopoStoreActivationContextRecord {
   readonly trailIds: readonly string[];
 }
 
-export interface TopoStoreSurfaceProjectionRecord {
+export interface TopoStoreSurfaceDerivedRecord {
   readonly derivedName: string;
   readonly method: string | null;
   readonly surface: string;
@@ -103,7 +103,7 @@ export interface TopoStoreTrailDetailRecord extends TopoStoreTrailRecord {
   readonly layers: readonly TopoGraphLayerReference[];
   readonly output: JsonSchema | null;
   readonly resources: readonly string[];
-  readonly surfaceProjections: readonly TopoStoreSurfaceProjectionRecord[];
+  readonly derivedSurfaces: readonly TopoStoreSurfaceDerivedRecord[];
   readonly surfaces: readonly string[];
 }
 
@@ -175,7 +175,7 @@ interface TopoExampleRow {
   readonly signals: string | null;
 }
 
-interface TopoSurfaceProjectionRow {
+interface TopoSurfaceDerivedRow {
   readonly derived_name: string;
   readonly method: string | null;
   readonly surface: string;
@@ -424,13 +424,13 @@ const readTrailExamples = (
       signals: row.signals === null ? null : parseJson(row.signals),
     }));
 
-const readTrailSurfaceProjections = (
+const readTrailSurfaceDerived = (
   db: Database,
   snapshotId: string,
   trailId: string
-): readonly TopoStoreSurfaceProjectionRecord[] =>
+): readonly TopoStoreSurfaceDerivedRecord[] =>
   db
-    .query<TopoSurfaceProjectionRow, [string, string]>(
+    .query<TopoSurfaceDerivedRow, [string, string]>(
       `SELECT trail_id, surface, derived_name, method
        FROM topo_surfaces
        WHERE snapshot_id = ? AND trail_id = ?
@@ -567,7 +567,7 @@ const buildTrailGraphDetail = (
   | 'input'
   | 'layers'
   | 'output'
-  | 'surfaceProjections'
+  | 'derivedSurfaces'
   | 'surfaces'
 > => {
   const storedTopoGraph = readStoredTopoGraph(db, snapshotId);
@@ -579,6 +579,7 @@ const buildTrailGraphDetail = (
     activationEdges: readTrailActivationEdges(storedTopoGraph, trailId),
     activationSources: entryDetail.activationSources,
     cli: entryDetail.cli,
+    derivedSurfaces: readTrailSurfaceDerived(db, snapshotId, trailId),
     detours: entryDetail.detours,
     entities: entryDetail.entities,
     entityDetails: readTrailEntityDetails(
@@ -591,7 +592,6 @@ const buildTrailGraphDetail = (
     input: entryDetail.input,
     layers: entryDetail.layers,
     output: entryDetail.output,
-    surfaceProjections: readTrailSurfaceProjections(db, snapshotId, trailId),
     surfaces: entryDetail.surfaces,
   };
 };
@@ -871,6 +871,7 @@ export const getTopoStoreTrail = (
     activationSources: graphDetail.activationSources,
     cli: graphDetail.cli,
     composes: readTrailComposings(db, snapshot.id, trailId),
+    derivedSurfaces: graphDetail.derivedSurfaces,
     detours: graphDetail.detours,
     entities: graphDetail.entities,
     entityDetails: graphDetail.entityDetails,
@@ -881,7 +882,6 @@ export const getTopoStoreTrail = (
     layers: graphDetail.layers,
     output: graphDetail.output,
     resources: readTrailResourceIds(db, snapshot.id, trailId),
-    surfaceProjections: graphDetail.surfaceProjections,
     surfaces: graphDetail.surfaces,
   };
 };

package/src/internal/topo-store.ts

@@ -7,9 +7,9 @@ import {
   deriveCliPath,
   deriveStructuredSignalExamples,
   deriveStructuredTrailExamples,
-  deriveTrailCliCommandProjection,
+  deriveTrailCliCommandRendering,
   getEntityReferences,
-  projectActivationSourceDeclaration,
+  deriveActivationSourceFacts,
   signalDiagnosticDefinitions,
   validateEstablishedTopo,
   zodToJsonSchema,
@@ -28,7 +28,7 @@ import type {
 } from '@ontrails/core';
 
 import { addPermitRequirement } from '../permit.js';
-import { collectLibraryProjection } from '../library-projection.js';
+import { deriveTopoGraphLibrary } from '../library-derivation.js';
 import { collectTopoGraphOverlays } from '../overlays.js';
 import {
   resolveCliAliasInputsFromOverlays,
@@ -39,12 +39,12 @@ import {
   LOCK_MANIFEST_SCHEMA_VERSION,
   TOPO_GRAPH_SCHEMA_VERSION,
 } from '../types.js';
-import { projectTrailVersions } from '../versioning.js';
+import { deriveTrailVersions } from '../versioning.js';
 import type {
   LockManifest,
   TopoGraphFieldOverride,
   TopoGraphFieldOverrideKey,
-  TopoGraphLibraryProjection,
+  TopoGraphLibraryDerived,
   TopoGraphOverlays,
   TopoGraphTrailheadEntry,
 } from '../types.js';
@@ -69,7 +69,7 @@ type TopoGraphRecord = Readonly<{
   >;
   readonly entries: readonly TopoGraphEntryRecord[];
   readonly generatedAt: string;
-  readonly library: TopoGraphLibraryProjection;
+  readonly library: TopoGraphLibraryDerived;
   readonly overlays?: TopoGraphOverlays | undefined;
   readonly topoGraphSchemaVersion: typeof TOPO_GRAPH_SCHEMA_VERSION;
   readonly trailheads?: readonly TopoGraphTrailheadEntry[] | undefined;
@@ -268,7 +268,7 @@ const SIGNAL_GOVERNANCE_HOOKS = {
   producers: 'trail.fires',
 } as const;
 
-interface NormalizedTopoProjection {
+interface NormalizedTopoFacts {
   readonly activationEdges: readonly TopoActivationEdgeRow[];
   readonly activationSources: readonly TopoActivationSourceRow[];
   readonly composings: readonly TopoComposingRow[];
@@ -450,12 +450,12 @@ export const normalizeOnRows = (
     }))
   );
 
-const projectActivationSource = (
+const deriveActivationSource = (
   source: ActivationSource
 ): ActivationSourceCatalogRecord =>
-  projectActivationSourceDeclaration(source) as ActivationSourceCatalogRecord;
+  deriveActivationSourceFacts(source) as ActivationSourceCatalogRecord;
 
-const projectActivationEdge = (
+const deriveActivationEdge = (
   trailId: string,
   activation: ActivationEntry
 ): ActivationGraphEdgeRecord => {
@@ -484,8 +484,8 @@ const collectActivationSourceCatalog = (
   const sources = new Map<string, ActivationSourceCatalogRecord>();
   for (const trail of trails) {
     for (const activation of trail.activationSources) {
-      const projected = projectActivationSource(activation.source);
-      sources.set(projected.key, projected);
+      const derived = deriveActivationSource(activation.source);
+      sources.set(derived.key, derived);
     }
   }
   return [...sources.values()].toSorted((a, b) => a.key.localeCompare(b.key));
@@ -497,7 +497,7 @@ const collectActivationGraphEdges = (
   const edges = new Map<string, ActivationGraphEdgeRecord>();
   for (const trail of trails) {
     for (const activation of trail.activationSources) {
-      const edge = projectActivationEdge(trail.id, activation);
+      const edge = deriveActivationEdge(trail.id, activation);
       const key = `${edge.sourceKey}\0${edge.trailId}`;
       const previous = edges.get(key);
       edges.set(
@@ -606,10 +606,10 @@ const normalizeTrailSignalRows = (
   });
 
 /**
- * Project surface rows for stored topo.
+ * Derive surface rows for stored topo.
  *
  * Currently records only CLI-derived rows. MCP, HTTP, and other surface
- * projections are intentionally deferred until the topo-store schema supports
+ * derivations are intentionally deferred until the topo-store schema supports
  * multi-surface representation. The JSON export (`topo_graph` in
  * `topo_exports`) is more faithful for now. See ADR-0015 for the target shape.
  */
@@ -657,10 +657,10 @@ const normalizeExampleRows = (
     }));
   });
 
-const normalizeTopoProjection = (
+const deriveNormalizedTopoRows = (
   topo: Topo,
   snapshotId: string
-): NormalizedTopoProjection => {
+): NormalizedTopoFacts => {
   const trails = topo.list().toSorted((a, b) => a.id.localeCompare(b.id));
   const resources = topo
     .listResources()
@@ -896,7 +896,7 @@ const addTrailRelations = (
         ...(activation.meta === undefined
           ? {}
           : { meta: canonicalize(activation.meta) }),
-        source: projectActivationSource(activation.source),
+        source: deriveActivationSource(activation.source),
         ...(activation.where === undefined
           ? {}
           : { where: sortKeys({ predicate: true }) }),
@@ -1024,7 +1024,7 @@ const buildTrailEntryBase = (
 } => {
   const raw = trail as unknown as Record<string, unknown>;
   const entry: Record<string, unknown> = {
-    cli: deriveTrailCliCommandProjection(trail, {
+    cli: deriveTrailCliCommandRendering(trail, {
       aliasSource: 'surface',
       aliases: surfaceAliases?.[trail.id],
     }),
@@ -1065,19 +1065,19 @@ const addVersioning = (
   if (trail.version === undefined) {
     return;
   }
-  const projection = projectTrailVersions(
+  const derivation = deriveTrailVersions(
     trail,
     (schema) => sortedJsonSchema(schema as ZodSchemaInput).value
   );
-  if (projection === undefined) {
+  if (derivation === undefined) {
     return;
   }
 
-  entry['marker'] = projection.marker;
-  entry['supports'] = projection.supports;
-  entry['version'] = projection.version;
-  if (projection.versions !== undefined) {
-    entry['versions'] = projection.versions;
+  entry['marker'] = derivation.marker;
+  entry['supports'] = derivation.supports;
+  entry['version'] = derivation.version;
+  if (derivation.versions !== undefined) {
+    entry['versions'] = derivation.versions;
   }
 };
 
@@ -1306,7 +1306,7 @@ const buildTopoGraph = (
     ),
     entries,
     generatedAt,
-    library: collectLibraryProjection(topo),
+    library: deriveTopoGraphLibrary(topo),
     ...(overlays === undefined ? {} : { overlays }),
     topoGraphSchemaVersion: TOPO_GRAPH_SCHEMA_VERSION,
     ...(trailheads === undefined ? {} : { trailheads }),
@@ -1400,13 +1400,13 @@ const insertRows = <TRow>(
   }
 };
 
-const insertProjectedRows = (
+const insertDerivedRows = (
   db: Database,
-  projection: NormalizedTopoProjection
+  derivation: NormalizedTopoFacts
 ): void => {
   insertRows(
     db,
-    projection.trails,
+    derivation.trails,
     `INSERT INTO topo_trails (
       id, intent, idempotent, has_output, has_examples, example_count, description, pattern, meta, snapshot_id
     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
@@ -1425,54 +1425,54 @@ const insertProjectedRows = (
   );
   insertRows(
     db,
-    projection.composings,
+    derivation.composings,
     'INSERT INTO topo_composings (source_id, target_id, snapshot_id) VALUES (?, ?, ?)',
     (row) => [row.sourceId, row.targetId, row.snapshotId]
   );
   insertRows(
     db,
-    projection.trailResources,
+    derivation.trailResources,
     `INSERT INTO topo_trail_resources (trail_id, resource_id, snapshot_id)
      VALUES (?, ?, ?)`,
     (row) => [row.trailId, row.resourceId, row.snapshotId]
   );
   insertRows(
     db,
-    projection.resources,
+    derivation.resources,
     `INSERT INTO topo_resources (id, has_mock, has_health, snapshot_id)
      VALUES (?, ?, ?, ?)`,
     (row) => [row.id, row.hasMock, row.hasHealth, row.snapshotId]
   );
   insertRows(
     db,
-    projection.signals,
+    derivation.signals,
     'INSERT INTO topo_signals (id, description, snapshot_id) VALUES (?, ?, ?)',
     (row) => [row.id, row.description, row.snapshotId]
   );
   insertRows(
     db,
-    projection.trailSignals,
+    derivation.trailSignals,
     `INSERT INTO topo_trail_signals (trail_id, signal_id, snapshot_id)
      VALUES (?, ?, ?)`,
     (row) => [row.trailId, row.signalId, row.snapshotId]
   );
   insertRows(
     db,
-    projection.fires,
+    derivation.fires,
     `INSERT INTO topo_trail_fires (trail_id, signal_id, snapshot_id)
      VALUES (?, ?, ?)`,
     (row) => [row.trailId, row.signalId, row.snapshotId]
   );
   insertRows(
     db,
-    projection.on,
+    derivation.on,
     `INSERT INTO topo_trail_on (trail_id, signal_id, snapshot_id)
      VALUES (?, ?, ?)`,
     (row) => [row.trailId, row.signalId, row.snapshotId]
   );
   insertRows(
     db,
-    projection.activationSources,
+    derivation.activationSources,
     `INSERT INTO topo_activation_sources (
       source_key, source_id, source_kind, source, snapshot_id
     ) VALUES (?, ?, ?, ?, ?)`,
@@ -1486,7 +1486,7 @@ const insertProjectedRows = (
   );
   insertRows(
     db,
-    projection.activationEdges,
+    derivation.activationEdges,
     `INSERT INTO topo_activation_edges (
       source_key, source_id, source_kind, trail_id, has_where, edge, snapshot_id
     ) VALUES (?, ?, ?, ?, ?, ?, ?)`,
@@ -1502,7 +1502,7 @@ const insertProjectedRows = (
   );
   insertRows(
     db,
-    projection.surfaces,
+    derivation.surfaces,
     `INSERT INTO topo_surfaces (trail_id, surface, derived_name, method, snapshot_id)
      VALUES (?, ?, ?, ?, ?)`,
     (row) => [
@@ -1515,7 +1515,7 @@ const insertProjectedRows = (
   );
   insertRows(
     db,
-    projection.examples,
+    derivation.examples,
     `INSERT INTO topo_examples (
       id, trail_id, ordinal, name, description, input, expected, expected_match, error, signals, snapshot_id
     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
@@ -1641,7 +1641,7 @@ export const createTopoSnapshot = (
   const snapshot = db.transaction(() => {
     const record = insertTopoSnapshotRecord(db, snapshotInput);
     const artifacts = buildStoredTopoExport(db, record, topo, snapshotInput);
-    insertProjectedRows(db, normalizeTopoProjection(topo, record.id));
+    insertDerivedRows(db, deriveNormalizedTopoRows(topo, record.id));
     insertSchemaRows(db, artifacts.schemaRows);
     insertStoredExport(db, artifacts.exportRow);
     return record;

package/src/io.ts

@@ -222,7 +222,7 @@ export const writeTrailsLock = async (
 /**
  * Read a lock v4 manifest from `<dir>/trails.lock`.
  *
- * v5 root locks are projected back to the v4 manifest shape for compatibility.
+ * v5 root locks are derived back to the v4 manifest shape for compatibility.
  */
 export const readLockManifest = async (
   options?: ReadOptions

package/src/{library-projection.ts → library-derivation.ts}

@@ -10,7 +10,7 @@ import type {
   TopoGraphLibraryCollision,
   TopoGraphLibraryExclusion,
   TopoGraphLibraryExport,
-  TopoGraphLibraryProjection,
+  TopoGraphLibraryDerived,
 } from './types.js';
 
 const sortKeys = <T extends Record<string, unknown>>(obj: T): T => {
@@ -75,9 +75,7 @@ const collectLibraryExclusions = (
   return excluded.toSorted((a, b) => a.trailId.localeCompare(b.trailId));
 };
 
-export const collectLibraryProjection = (
-  topo: Topo
-): TopoGraphLibraryProjection => {
+export const deriveTopoGraphLibrary = (topo: Topo): TopoGraphLibraryDerived => {
   const selected = filterSurfaceTrails([...topo.trails.values()]).filter(
     (trail) => !isDraftId(trail.id)
   );
@@ -129,5 +127,5 @@ export const collectLibraryProjection = (
     collisions,
     excluded: collectLibraryExclusions(topo, selectedIds),
     exports,
-  }) as unknown as TopoGraphLibraryProjection;
+  }) as unknown as TopoGraphLibraryDerived;
 };

package/src/permit.ts

@@ -1,12 +1,12 @@
 import type { AnyTrail, PermitRequirement } from '@ontrails/core';
 
-export type ProjectedPermitRequirement =
+export type DerivedPermitRequirement =
   | 'public'
   | { readonly scopes: readonly string[] };
 
-export const projectPermitRequirement = (
+export const derivePermitRequirement = (
   permit: PermitRequirement
-): ProjectedPermitRequirement =>
+): DerivedPermitRequirement =>
   permit === 'public' ? 'public' : { scopes: [...permit.scopes].toSorted() };
 
 export const addPermitRequirement = (
@@ -14,6 +14,6 @@ export const addPermitRequirement = (
   trail: AnyTrail
 ): void => {
   if (trail.permit !== undefined) {
-    entry['permit'] = projectPermitRequirement(trail.permit);
+    entry['permit'] = derivePermitRequirement(trail.permit);
   }
 };

package/src/surface-bindings.ts

@@ -4,7 +4,7 @@
  * Both derivation pipelines — `deriveTopoGraph` and the store-side
  * `buildTopoGraph` — resolve the app-authored `surfaces` overlay's `cli`
  * bindings into per-trail CLI alias inputs and its `mcp` list bindings into
- * projected trailhead entries through this single helper module, so compiled
+ * derived trailhead entries through this single helper module, so compiled
  * locks and fresh derivations cannot diverge from the runtime surfaces'
  * reading of the same bindings.
  */
@@ -55,15 +55,15 @@ export const resolveCliAliasInputsFromOverlays = (
 };
 
 /**
- * Resolve projected trailhead entries from overlay registrations.
+ * Resolve derived trailhead entries from overlay registrations.
  *
  * Finds the app-authored `surfaces` overlay among the registrations and
- * projects each `mcp` list binding into one `TopoGraphTrailheadEntry`: the
+ * derives each `mcp` list binding into one `TopoGraphTrailheadEntry`: the
  * binding name becomes the trailhead id, the sorted expanded member trail
  * ids become `memberIds`, the surfaces list is `['mcp']`, and the
  * description is the deterministic derived default shared with the MCP
  * surface. Scalar `mcp` bindings are tool synonyms, not grouped entries, so
- * they project no trailhead. Throws a `ValidationError` for group bindings
+ * they render no trailhead. Throws a `ValidationError` for group bindings
  * whose member union is empty or synonym bindings that violate the shared
  * expansion rules. Returns `undefined` when no `mcp` list bindings exist.
  *

package/src/topo-store.ts

@@ -190,7 +190,7 @@ export type {
   TopoStoreRef,
   TopoStoreSignalDetailRecord,
   TopoStoreSignalRecord,
-  TopoStoreSurfaceProjectionRecord,
+  TopoStoreSurfaceDerivedRecord,
   TopoStoreTopoGraphEntryRecord,
   TopoStoreTopoGraphRecord,
   TopoStoreTrailDetailRecord,

package/src/types.ts

@@ -173,7 +173,7 @@ export interface TopoGraphLibraryCollision {
   readonly trailIds: readonly string[];
 }
 
-export interface TopoGraphLibraryProjection {
+export interface TopoGraphLibraryDerived {
   readonly app: string;
   readonly collisions: readonly TopoGraphLibraryCollision[];
   readonly excluded: readonly TopoGraphLibraryExclusion[];
@@ -278,7 +278,7 @@ export interface TopoGraph {
   readonly entries: readonly TopoGraphEntry[];
   readonly trailheads?: readonly TopoGraphTrailheadEntry[] | undefined;
   readonly forces?: readonly TopoGraphForceEntry[] | undefined;
-  readonly library?: TopoGraphLibraryProjection | undefined;
+  readonly library?: TopoGraphLibraryDerived | undefined;
   /**
    * Namespaced fact overlays contributed by registered overlay contributions
    * (adapters). Unknown namespaces are preserved verbatim by every reader
@@ -406,7 +406,7 @@ const topoGraphLibraryCollisionSchema = z
   })
   .strict();
 
-export const topoGraphLibraryProjectionSchema = z
+export const topoGraphLibraryDerivedSchema = z
   .object({
     app: z.string(),
     collisions: z.array(topoGraphLibraryCollisionSchema),
@@ -661,7 +661,7 @@ export const topoGraphSchema = z
     entries: z.array(topoGraphEntrySchema),
     forces: z.array(topoGraphForceEntrySchema).optional(),
     generatedAt: z.string().optional(),
-    library: topoGraphLibraryProjectionSchema.optional(),
+    library: topoGraphLibraryDerivedSchema.optional(),
     overlays: z.record(z.string(), z.unknown()).optional(),
     topoGraphSchemaVersion: z.literal(TOPO_GRAPH_SCHEMA_VERSION),
     trailheads: z.array(topoGraphTrailheadEntrySchema).optional(),

package/src/versioning.ts

@@ -23,7 +23,7 @@ import type {
   TopoGraphVersionEntry,
 } from './types.js';
 
-type SchemaProjector = (schema: unknown) => JsonSchema;
+type SchemaDeriver = (schema: unknown) => JsonSchema;
 
 const sortPlainRecord = <T extends Record<string, unknown>>(value: T): T => {
   const sorted: Record<string, unknown> = {};
@@ -33,7 +33,7 @@ const sortPlainRecord = <T extends Record<string, unknown>>(value: T): T => {
   return sorted as T;
 };
 
-const projectVersionDetours = (
+const deriveVersionDetours = (
   entry: TrailVersionEntry
 ): TopoGraphVersionEntry['detours'] => {
   const raw = entry as unknown as Record<string, unknown>;
@@ -57,7 +57,7 @@ const projectVersionDetours = (
   });
 };
 
-const projectVersionRuntimeRefs = (
+const deriveVersionRuntimeRefs = (
   entry: TrailVersionEntry,
   field: 'composes' | 'resources'
 ): readonly string[] | undefined => {
@@ -85,46 +85,46 @@ const projectVersionRuntimeRefs = (
   return refs.toSorted();
 };
 
-export const projectTrailVersionEntry = (
+export const deriveTrailVersionEntry = (
   entry: TrailVersionEntry,
-  projectSchema: SchemaProjector
+  deriveSchema: SchemaDeriver
 ): TopoGraphVersionEntry => {
   const kind = getTrailVersionEntryKind(entry);
   const examples = deriveStructuredTrailExamples(entry.examples, {
     provenance: { source: 'trail.versions.examples' },
   });
-  const projected: Record<string, unknown> = {
+  const derived: Record<string, unknown> = {
     exampleCount: entry.examples?.length ?? 0,
-    input: projectSchema(entry.input),
+    input: deriveSchema(entry.input),
     kind,
     marker: deriveTrailVersionEntryMarker(entry),
-    output: projectSchema(entry.output),
+    output: deriveSchema(entry.output),
   };
 
   if (examples !== undefined) {
-    projected['examples'] = examples;
+    derived['examples'] = examples;
   }
 
   if (entry.status !== undefined) {
-    projected['status'] = sortPlainRecord({ ...entry.status });
+    derived['status'] = sortPlainRecord({ ...entry.status });
   }
 
   if (kind === 'fork') {
-    const composes = projectVersionRuntimeRefs(entry, 'composes');
-    const resources = projectVersionRuntimeRefs(entry, 'resources');
-    const detours = projectVersionDetours(entry);
+    const composes = deriveVersionRuntimeRefs(entry, 'composes');
+    const resources = deriveVersionRuntimeRefs(entry, 'resources');
+    const detours = deriveVersionDetours(entry);
     if (composes !== undefined) {
-      projected['composes'] = composes;
+      derived['composes'] = composes;
     }
     if (resources !== undefined) {
-      projected['resources'] = resources;
+      derived['resources'] = resources;
     }
     if (detours !== undefined) {
-      projected['detours'] = detours;
+      derived['detours'] = detours;
     }
   }
 
-  return sortPlainRecord(projected) as unknown as TopoGraphVersionEntry;
+  return sortPlainRecord(derived) as unknown as TopoGraphVersionEntry;
 };
 
 export interface TopoGraphVersionMarkerRecord {
@@ -241,9 +241,9 @@ export const resolveTopoGraphVersionReference = (
   };
 };
 
-export const projectTrailVersions = (
+export const deriveTrailVersions = (
   trail: AnyTrail,
-  projectSchema: SchemaProjector
+  deriveSchema: SchemaDeriver
 ):
   | {
       readonly marker: string;
@@ -256,14 +256,11 @@ export const projectTrailVersions = (
     return undefined;
   }
 
-  const projectedEntries: Record<string, TopoGraphVersionEntry> = {};
+  const derivedEntries: Record<string, TopoGraphVersionEntry> = {};
   for (const [rawVersion, entry] of Object.entries(
     trail.versions ?? {}
   ).toSorted(([left], [right]) => Number(left) - Number(right))) {
-    projectedEntries[rawVersion] = projectTrailVersionEntry(
-      entry,
-      projectSchema
-    );
+    derivedEntries[rawVersion] = deriveTrailVersionEntry(entry, deriveSchema);
   }
 
   const currentMarker = deriveCurrentTrailVersionMarker(trail);
@@ -273,8 +270,8 @@ export const projectTrailVersions = (
     marker: currentMarker,
     supports: deriveSupportedTrailVersions(trail),
     version: trail.version,
-    ...(Object.keys(projectedEntries).length > 0
-      ? { versions: projectedEntries }
+    ...(Object.keys(derivedEntries).length > 0
+      ? { versions: derivedEntries }
       : {}),
   };
 };

package/src/wayfind/error-facts.ts

@@ -1,12 +1,12 @@
 import {
   errorClasses,
-  projectErrorClassSurface,
+  renderErrorClassSurface,
   surfaceNames,
 } from '@ontrails/core';
 import type {
   ErrorCategory,
   ErrorClassRegistryEntry,
-  ErrorClassSurfaceProjection,
+  ErrorClassSurfaceRendering,
   SurfaceName,
 } from '@ontrails/core';
 import type {
@@ -35,7 +35,7 @@ export type TrailErrorFactsCompleteness =
       readonly status: 'unknown';
     };
 
-export interface TrailErrorTaxonomyProjection {
+export interface TrailErrorTaxonomyFacts {
   readonly category?: ErrorCategory | undefined;
   readonly dynamicCategory?:
     | {
@@ -45,7 +45,7 @@ export interface TrailErrorTaxonomyProjection {
   readonly known: boolean;
   readonly name: string;
   readonly retryable?: boolean | undefined;
-  readonly surfaces: readonly ErrorClassSurfaceProjection[];
+  readonly surfaces: readonly ErrorClassSurfaceRendering[];
 }
 
 export type TrailErrorFactProvenance =
@@ -78,7 +78,7 @@ export interface TrailErrorFact {
   readonly completeness: TrailErrorFactsCompleteness;
   readonly kind: TrailErrorFactKind;
   readonly provenance: TrailErrorFactProvenance;
-  readonly taxonomy: TrailErrorTaxonomyProjection;
+  readonly taxonomy: TrailErrorTaxonomyFacts;
 }
 
 export interface TrailErrorFacts {
@@ -110,10 +110,10 @@ const errorClassByName: ReadonlyMap<string, ErrorClassRegistryEntry> = new Map(
   errorClasses.map((entry) => [entry.name, entry])
 );
 
-const taxonomyProjection = (
+const deriveTaxonomyFacts = (
   errorName: string,
   surfaces: readonly SurfaceName[]
-): TrailErrorTaxonomyProjection => {
+): TrailErrorTaxonomyFacts => {
   const registryEntry = errorClassByName.get(errorName);
   if (registryEntry === undefined) {
     return {
@@ -141,8 +141,8 @@ const taxonomyProjection = (
     name: registryEntry.name,
     retryable: registryEntry.retryable,
     surfaces: surfaces.flatMap((surface) => {
-      const projected = projectErrorClassSurface(surface, errorName);
-      return projected === undefined ? [] : [projected];
+      const derived = renderErrorClassSurface(surface, errorName);
+      return derived === undefined ? [] : [derived];
     }),
   };
 };
@@ -189,7 +189,7 @@ const documentedFacts = (
           source: 'trail.examples',
           trailId: entry.id,
         },
-        taxonomy: taxonomyProjection(example.error, surfaces),
+        taxonomy: deriveTaxonomyFacts(example.error, surfaces),
       },
     ];
   });
@@ -207,7 +207,7 @@ const handledFacts = (
         source: 'trail.detours',
         trailId: entry.id,
       },
-      taxonomy: taxonomyProjection(detour.on, surfaces),
+      taxonomy: deriveTaxonomyFacts(detour.on, surfaces),
     })
   );
 
@@ -231,7 +231,7 @@ const versionDocumentedFacts = (
           trailId,
           version,
         },
-        taxonomy: taxonomyProjection(example.error, surfaces),
+        taxonomy: deriveTaxonomyFacts(example.error, surfaces),
       },
     ];
   });
@@ -252,7 +252,7 @@ const versionHandledFacts = (
         trailId,
         version,
       },
-      taxonomy: taxonomyProjection(detour.on, surfaces),
+      taxonomy: deriveTaxonomyFacts(detour.on, surfaces),
     })
   );
 
@@ -285,7 +285,7 @@ const inputFact = (
     trailId: input.trailId,
     ...(input.version === undefined ? {} : { version: input.version }),
   },
-  taxonomy: taxonomyProjection(input.errorName, surfaces),
+  taxonomy: deriveTaxonomyFacts(input.errorName, surfaces),
 });
 
 const byTrail = (

package/src/wayfind/queries.ts

@@ -198,7 +198,7 @@ const cliRouteSchema = z.object({
   target: z.string(),
 });
 
-const cliProjectionSchema = z
+const cliDerivedSchema = z
   .object({
     path: z.array(z.string()).readonly(),
     routes: z.array(cliRouteSchema).readonly().optional(),
@@ -206,7 +206,7 @@ const cliProjectionSchema = z
   .nullable();
 
 const trailSummarySchema = entrySummarySchema.extend({
-  cli: cliProjectionSchema,
+  cli: cliDerivedSchema,
   composes: z.array(z.string()).readonly(),
   intent: z.enum(['destroy', 'read', 'write']),
   kind: z.literal('trail'),
@@ -280,7 +280,7 @@ const errorFactsCompletenessSchema = z.discriminatedUnion('status', [
   }),
 ]);
 
-const errorSurfaceProjectionSchema = z.object({
+const errorSurfaceDerivedSchema = z.object({
   category: z.enum(errorCategories),
   code: z.number(),
   name: z.string(),
@@ -288,7 +288,7 @@ const errorSurfaceProjectionSchema = z.object({
   surface: z.enum(surfaceNames),
 });
 
-const errorTaxonomyProjectionSchema = z.object({
+const errorTaxonomyDerivedSchema = z.object({
   category: z.enum(errorCategories).optional(),
   dynamicCategory: z
     .object({
@@ -298,7 +298,7 @@ const errorTaxonomyProjectionSchema = z.object({
   known: z.boolean(),
   name: z.string(),
   retryable: z.boolean().optional(),
-  surfaces: z.array(errorSurfaceProjectionSchema).readonly(),
+  surfaces: z.array(errorSurfaceDerivedSchema).readonly(),
 });
 
 const errorFactProvenanceSchema = z.object({
@@ -321,7 +321,7 @@ const errorFactSchema = z.object({
   completeness: errorFactsCompletenessSchema,
   kind: z.enum(['documented', 'handled', 'inferred', 'observed']),
   provenance: errorFactProvenanceSchema,
-  taxonomy: errorTaxonomyProjectionSchema,
+  taxonomy: errorTaxonomyDerivedSchema,
 });
 
 const trailErrorFactsSchema = z.object({
@@ -1097,13 +1097,13 @@ const contractFor = (
 const withGraph = async <TValue>(
   input: SourceInput,
   cwd: string | undefined,
-  project: (loaded: LoadedWayfinderGraph) => TValue
+  derive: (loaded: LoadedWayfinderGraph) => TValue
 ): Promise<Result<TValue, TrailsError>> => {
   const loaded = await loadGraph(input, cwd);
   if (loaded.isErr()) {
     return loaded;
   }
-  return Result.ok(project(loaded.value));
+  return Result.ok(derive(loaded.value));
 };
 
 const notFound = (kind: string, id: string): NotFoundError =>

package/src/wayfind/relations.ts

@@ -12,7 +12,7 @@ export const relationKindSchema = z.enum([
   'trailhead-groups',
   'fired-by',
   'has-version',
-  'surface-projects',
+  'surface-renders',
   'used-by',
 ]);
 
@@ -142,7 +142,7 @@ export const relationEdges = (graph: TopoGraph): readonly RelationEdge[] => {
       add(refFor(graph, signalId, 'signal'), relation, target);
     }
     for (const surfaceId of entry.surfaces) {
-      add(refFor(graph, surfaceId, 'surface'), 'surface-projects', target);
+      add(refFor(graph, surfaceId, 'surface'), 'surface-renders', target);
     }
     if (entry.kind === 'trail' && entry.version !== undefined) {
       add(target, 'has-version', {
@@ -174,7 +174,7 @@ export const relationEdges = (graph: TopoGraph): readonly RelationEdge[] => {
       const memberRef = refFor(graph, memberId, 'trail');
       add(trailheadRef, 'trailhead-groups', memberRef);
       for (const surfaceRef of surfaceRefs) {
-        add(surfaceRef, 'surface-projects', memberRef);
+        add(surfaceRef, 'surface-renders', memberRef);
       }
     }
   }