@ontrails/warden 1.0.0-beta.12 → 1.0.0-beta.13

package/src/__tests__/valid-describe-refs.test.ts

@@ -9,7 +9,7 @@ trail("entity.show", {
   input: z.object({
     query: z.string().describe("Search query. @see entity.search"),
   }),
-  run: (input) => Result.ok(input),
+  blaze: (input) => Result.ok(input),
 })`;
 
     const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
@@ -23,14 +23,14 @@ trail("entity.show", {
     const code = `
 trail("entity.search", {
   input: z.object({ query: z.string() }),
-  run: (input) => Result.ok(input),
+  blaze: (input) => Result.ok(input),
 })
 
 trail("entity.show", {
   input: z.object({
     query: z.string().describe("Search query. @see entity.search"),
   }),
-  run: (input) => Result.ok(input),
+  blaze: (input) => Result.ok(input),
 })`;
 
     const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
@@ -44,7 +44,7 @@ trail("entity.show", {
   input: z.object({
     query: z.string().describe("Search query. @see entity.search"),
   }),
-  run: (input) => Result.ok(input),
+  blaze: (input) => Result.ok(input),
 })`;
 
     const diagnostics = validDescribeRefs.checkWithContext(

package/src/__tests__/wrap-rule.test.ts

@@ -6,10 +6,10 @@ import { wrapRule } from '../trails/wrap-rule.js';
 import type { ProjectAwareWardenRule } from '../rules/types.js';
 
 describe('wrapRule', () => {
-  test('preserves undefined knownServiceIds and defaults knownTrailIds to empty set', async () => {
+  test('preserves undefined knownProvisionIds and defaults knownTrailIds to empty set', async () => {
     let capturedContext:
       | {
-          readonly knownServiceIds?: ReadonlySet<string>;
+          readonly knownProvisionIds?: ReadonlySet<string>;
           readonly knownTrailIds?: ReadonlySet<string>;
         }
       | undefined;
@@ -26,7 +26,7 @@ describe('wrapRule', () => {
     };
 
     const wrapped = wrapRule({ examples: [], rule });
-    const result = await wrapped.run(
+    const result = await wrapped.blaze(
       { filePath: 'entity.ts', sourceCode: '' },
       createTrailContext()
     );
@@ -34,7 +34,7 @@ describe('wrapRule', () => {
     expect(result.isOk()).toBe(true);
     expect(result.unwrap()).toEqual({ diagnostics: [] });
     expect(capturedContext).toEqual({
-      knownServiceIds: undefined,
+      knownProvisionIds: undefined,
       knownTrailIds: new Set<string>(),
     });
   });

package/src/cli.ts

@@ -12,7 +12,7 @@ import type { Topo } from '@ontrails/core';
 import type { DriftResult } from './drift.js';
 import { checkDrift } from './drift.js';
 import {
-  collectServiceDefinitionIds,
+  collectProvisionDefinitionIds,
   findConfigProperty,
   findTrailDefinitions,
   parse,
@@ -36,7 +36,7 @@ export interface WardenOptions {
   readonly lintOnly?: boolean | undefined;
   /** Only run drift detection, skip lint rules */
   readonly driftOnly?: boolean | undefined;
-  /** App topology for drift detection. When provided, enables real surface lock comparison. */
+  /** App topology for drift detection. When provided, enables real trailhead lock comparison. */
   readonly topo?: Topo | undefined;
 }
 
@@ -133,17 +133,17 @@ const collectDetourTargetTrailIds = (
   }
 };
 
-const collectKnownServiceIds = (
+const collectKnownProvisionIds = (
   sourceCode: string,
   filePath: string,
-  knownServiceIds: Set<string>
+  knownProvisionIds: Set<string>
 ): void => {
   const ast = parse(filePath, sourceCode);
   if (!ast) {
     return;
   }
-  for (const id of collectServiceDefinitionIds(ast)) {
-    knownServiceIds.add(id);
+  for (const id of collectProvisionDefinitionIds(ast)) {
+    knownProvisionIds.add(id);
   }
 };
 
@@ -190,17 +190,21 @@ const collectTopoDetourTargetTrailIds = (
 
 const buildProjectContextFromTopo = (appTopo: Topo): ProjectContext => {
   const knownTrailIds = new Set<string>(appTopo.trails.keys());
-  const knownServiceIds = new Set<string>(appTopo.services.keys());
+  const knownProvisionIds = new Set<string>(appTopo.provisions.keys());
   const detourTargetTrailIds = collectTopoDetourTargetTrailIds(appTopo);
 
-  return { detourTargetTrailIds, knownServiceIds, knownTrailIds };
+  return {
+    detourTargetTrailIds,
+    knownProvisionIds,
+    knownTrailIds,
+  };
 };
 
 const buildProjectContextFromFiles = (
   sourceFiles: readonly SourceFile[]
 ): ProjectContext => {
   const knownTrailIds = new Set<string>();
-  const knownServiceIds = new Set<string>();
+  const knownProvisionIds = new Set<string>();
   const detourTargetTrailIds = new Set<string>();
 
   for (const sourceFile of sourceFiles) {
@@ -209,10 +213,10 @@ const buildProjectContextFromFiles = (
       sourceFile.filePath,
       knownTrailIds
     );
-    collectKnownServiceIds(
+    collectKnownProvisionIds(
       sourceFile.sourceCode,
       sourceFile.filePath,
-      knownServiceIds
+      knownProvisionIds
     );
     collectDetourTargetTrailIds(
       sourceFile.sourceCode,
@@ -223,7 +227,7 @@ const buildProjectContextFromFiles = (
 
   return {
     detourTargetTrailIds,
-    knownServiceIds,
+    knownProvisionIds,
     knownTrailIds,
   };
 };
@@ -324,7 +328,7 @@ const formatDriftSection = (drift: DriftResult | null): string[] => {
     return [];
   }
   const label = drift.stale
-    ? 'Drift: surface.lock is stale (regenerate with `trails survey generate`)'
+    ? 'Drift: trailhead.lock is stale (regenerate with `trails survey generate`)'
     : 'Drift: clean';
   return [label, ''];
 };

package/src/drift.ts

@@ -1,32 +1,32 @@
 /**
- * Surface lock drift detection.
+ * Trailhead lock drift detection.
  *
- * Compares the committed `surface.lock` hash against a freshly generated
- * surface map hash to detect when the trail topology has changed without
+ * Compares the committed `trailhead.lock` hash against a freshly generated
+ * trailhead map hash to detect when the trail topology has changed without
  * updating the lock file.
  */
 
 import type { Topo } from '@ontrails/core';
 import {
-  generateSurfaceMap,
-  hashSurfaceMap,
-  readSurfaceLock,
+  generateTrailheadMap,
+  hashTrailheadMap,
+  readTrailheadLock,
 } from '@ontrails/schema';
 
 /**
- * Result of a drift check comparing committed surface.lock against the current state.
+ * Result of a drift check comparing committed trailhead.lock against the current state.
  */
 export interface DriftResult {
   /** Whether the committed lock is out of date */
   readonly stale: boolean;
-  /** Hash from the committed surface.lock file, or null if not found */
+  /** Hash from the committed trailhead.lock file, or null if not found */
   readonly committedHash: string | null;
   /** Hash computed from the current trail topology */
   readonly currentHash: string;
 }
 
 /**
- * Check whether the committed surface.lock is stale compared to the current topology.
+ * Check whether the committed trailhead.lock is stale compared to the current topology.
  *
  * When no topo is provided, returns a clean result (no drift detectable without runtime info).
  */
@@ -38,9 +38,9 @@ export const checkDrift = async (
     return { committedHash: null, currentHash: 'unknown', stale: false };
   }
 
-  const surfaceMap = generateSurfaceMap(topo);
-  const currentHash = hashSurfaceMap(surfaceMap);
-  const committedHash = await readSurfaceLock({ dir: rootDir });
+  const trailheadMap = generateTrailheadMap(topo);
+  const currentHash = hashTrailheadMap(trailheadMap);
+  const committedHash = await readTrailheadLock({ dir: rootDir });
 
   return {
     committedHash,

package/src/formatters.ts

@@ -33,7 +33,7 @@ export const formatGitHubAnnotations = (report: WardenReport): string => {
 
   if (report.drift?.stale) {
     lines.push(
-      '::error::drift: surface.lock is stale (regenerate with `trails survey generate`)'
+      '::error::drift: trailhead.lock is stale (regenerate with `trails survey generate`)'
     );
   }
 
@@ -88,7 +88,7 @@ const driftSection = (drift: WardenReport['drift']): readonly string[] => {
   return [
     '',
     '### Drift',
-    '- surface.lock is stale (regenerate with `trails survey generate`)',
+    '- trailhead.lock is stale (regenerate with `trails survey generate`)',
   ];
 };
 

package/src/index.ts

@@ -18,7 +18,7 @@ export type {
 
 // Individual rules
 export { noThrowInImplementation } from './rules/no-throw-in-implementation.js';
-export { contextNoSurfaceTypes } from './rules/context-no-surface-types.js';
+export { contextNoTrailheadTypes } from './rules/context-no-trailhead-types.js';
 export { validDetourRefs } from './rules/valid-detour-refs.js';
 export { noDirectImplInRoute } from './rules/no-direct-impl-in-route.js';
 export { noDirectImplementationCall } from './rules/no-direct-implementation-call.js';
@@ -26,8 +26,8 @@ export { noSyncResultAssumption } from './rules/no-sync-result-assumption.js';
 export { implementationReturnsResult } from './rules/implementation-returns-result.js';
 export { noThrowInDetourTarget } from './rules/no-throw-in-detour-target.js';
 export { preferSchemaInference } from './rules/prefer-schema-inference.js';
-export { serviceDeclarations } from './rules/service-declarations.js';
-export { serviceExists } from './rules/service-exists.js';
+export { provisionDeclarations } from './rules/provision-declarations.js';
+export { provisionExists } from './rules/provision-exists.js';
 export { validDescribeRefs } from './rules/valid-describe-refs.js';
 
 // Rule registry
@@ -48,13 +48,13 @@ export {
 export type { DriftResult } from './drift.js';
 export { checkDrift } from './drift.js';
 
-// Trail layer
+// Trail gate
 export { wardenTopo } from './trails/topo.js';
 export { runWardenTrails } from './trails/run.js';
 export {
-  contextNoSurfaceTypesTrail,
+  contextNoTrailheadTypesTrail,
+  crossDeclarationsTrail,
   diagnosticSchema,
-  followDeclarationsTrail,
   implementationReturnsResultTrail,
   noDirectImplInRouteTrail,
   noDirectImplementationCallTrail,
@@ -64,8 +64,8 @@ export {
   preferSchemaInferenceTrail,
   ruleInput,
   ruleOutput,
-  serviceDeclarationsTrail,
-  serviceExistsTrail,
+  provisionDeclarationsTrail,
+  provisionExistsTrail,
   validDescribeRefsTrail,
   validDetourRefsTrail,
 } from './trails/index.js';

package/src/rules/ast.ts

@@ -92,7 +92,7 @@ const walkScopeInner: WalkFn = (node, visit) => {
 /**
  * Walk an AST node tree without descending into nested function scopes.
  * The root node is always traversed; only inner function boundaries are skipped.
- * Useful for service-access analysis where inner functions may shadow
+ * Useful for provision-access analysis where inner functions may shadow
  * the trail context parameter name.
  */
 export const walkScope: WalkFn = (node, visit) => {
@@ -166,11 +166,11 @@ export const extractFirstStringArg = (node: AstNode): string | null => {
   return extractStringLiteral(firstArg);
 };
 
-const isServiceCall = (node: AstNode | undefined): boolean =>
+const isProvisionCall = (node: AstNode | undefined): boolean =>
   !!node &&
   node.type === 'CallExpression' &&
   identifierName((node as unknown as { callee?: AstNode }).callee) ===
-    'service';
+    'provision';
 
 const extractBindingName = (node: AstNode | undefined): string | null => {
   if (!node) {
@@ -185,8 +185,8 @@ const extractBindingName = (node: AstNode | undefined): string | null => {
   return null;
 };
 
-/** Collect `const foo = service('id', ...)` bindings from a parsed file. */
-export const collectNamedServiceIds = (
+/** Collect `const foo = provision('id', ...)` bindings from a parsed file. */
+export const collectNamedProvisionIds = (
   ast: AstNode
 ): ReadonlyMap<string, string> => {
   const ids = new Map<string, string>();
@@ -200,28 +200,28 @@ export const collectNamedServiceIds = (
       readonly id?: AstNode;
       readonly init?: AstNode;
     };
-    if (!isServiceCall(init)) {
+    if (!isProvisionCall(init)) {
       return;
     }
 
     const name = extractBindingName(id);
-    const serviceId = init ? extractFirstStringArg(init) : null;
-    if (name && serviceId) {
-      ids.set(name, serviceId);
+    const provisionId = init ? extractFirstStringArg(init) : null;
+    if (name && provisionId) {
+      ids.set(name, provisionId);
     }
   });
 
   return ids;
 };
 
-/** Collect all inline `service('id', ...)` definition IDs from a parsed file. */
-export const collectServiceDefinitionIds = (
+/** Collect all inline `provision('id', ...)` definition IDs from a parsed file. */
+export const collectProvisionDefinitionIds = (
   ast: AstNode
 ): ReadonlySet<string> => {
   const ids = new Set<string>();
 
   walk(ast, (node) => {
-    if (!isServiceCall(node)) {
+    if (!isProvisionCall(node)) {
       return;
     }
 
@@ -234,6 +234,11 @@ export const collectServiceDefinitionIds = (
   return ids;
 };
 
+/** Backward-compatible aliases while the migration is in flight. */
+export const collectNamedServiceIds = collectNamedProvisionIds;
+/** Backward-compatible aliases while the migration is in flight. */
+export const collectServiceDefinitionIds = collectProvisionDefinitionIds;
+
 // ---------------------------------------------------------------------------
 // Config property extraction helpers
 // ---------------------------------------------------------------------------
@@ -265,7 +270,7 @@ export const findConfigProperty = (
 export interface TrailDefinition {
   /** Trail ID string, e.g. "entity.show" */
   readonly id: string;
-  /** "trail" or "event" */
+  /** "trail" or "signal" */
   readonly kind: string;
   /** The config object argument (second arg to trail() call) */
   readonly config: AstNode;
@@ -275,11 +280,11 @@ export interface TrailDefinition {
 
 /**
  * Find all `trail("id", { ... })`, `trail({ id: "x", ... })`, and
- * `event("id", { ... })` call sites.
+ * `signal("id", { ... })` call sites.
  *
  * Returns the trail ID, kind, and config object node for each definition.
  */
-const TRAIL_CALLEE_NAMES = new Set(['trail', 'event']);
+const TRAIL_CALLEE_NAMES = new Set(['trail', 'signal']);
 
 const getTrailCalleeName = (node: AstNode): string | null => {
   if (node.type !== 'CallExpression') {
@@ -376,22 +381,22 @@ export const findTrailDefinitions = (ast: AstNode): TrailDefinition[] => {
 };
 
 // ---------------------------------------------------------------------------
-// Run body extraction
+// Blaze body extraction
 // ---------------------------------------------------------------------------
 
 /**
- * Extract top-level `run:` property values from an ObjectExpression's direct properties.
+ * Extract top-level `blaze:` property values from an ObjectExpression's direct properties.
  *
- * Does not recurse into nested objects, so `metadata: { run: ... }` is ignored.
+ * Does not recurse into nested objects, so `meta: { blaze: ... }` is ignored.
  */
-const extractRunFromConfig = (config: AstNode): AstNode[] => {
+const extractBlazeFromConfig = (config: AstNode): AstNode[] => {
   const bodies: AstNode[] = [];
   const properties = config['properties'] as readonly AstNode[] | undefined;
   if (!properties) {
     return bodies;
   }
   for (const prop of properties) {
-    if (prop.type === 'Property' && prop.key?.name === 'run' && prop.value) {
+    if (prop.type === 'Property' && prop.key?.name === 'blaze' && prop.value) {
       bodies.push(prop.value);
     }
   }
@@ -399,22 +404,22 @@ const extractRunFromConfig = (config: AstNode): AstNode[] => {
 };
 
 /**
- * Find `run:` property values.
+ * Find `blaze:` property values.
  *
- * When given an ObjectExpression (trail config), returns only its direct `run:`
+ * When given an ObjectExpression (trail config), returns only its direct `blaze:`
  * properties. When given a full AST, finds trail definitions first and extracts
- * `run:` from each config — in both cases ignoring nested `run:` properties
- * (e.g. `metadata: { run: ... }`).
+ * `blaze:` from each config — in both cases ignoring nested `blaze:` properties
+ * (e.g. `meta: { blaze: ... }`).
  */
-export const findRunBodies = (node: AstNode): AstNode[] => {
+export const findBlazeBodies = (node: AstNode): AstNode[] => {
   if (node.type === 'ObjectExpression') {
-    return extractRunFromConfig(node);
+    return extractBlazeFromConfig(node);
   }
 
-  // Full AST — find trail definitions and extract run from their configs
+  // Full AST — find trail definitions and extract blaze from their configs
   const bodies: AstNode[] = [];
   for (const def of findTrailDefinitions(node)) {
-    bodies.push(...extractRunFromConfig(def.config));
+    bodies.push(...extractBlazeFromConfig(def.config));
   }
   return bodies;
 };
@@ -423,8 +428,8 @@ export const findRunBodies = (node: AstNode): AstNode[] => {
 // Misc helpers
 // ---------------------------------------------------------------------------
 
-/** Check if a node is a call to `.run()` on some object. */
-export const isRunCall = (node: AstNode): boolean => {
+/** Check if a node is a call to `.blaze()` on some object. */
+export const isBlazeCall = (node: AstNode): boolean => {
   if (node.type !== 'CallExpression') {
     return false;
   }
@@ -441,6 +446,6 @@ export const isRunCall = (node: AstNode): boolean => {
   const prop = (callee as unknown as { property?: AstNode }).property;
   return (
     prop?.type === 'Identifier' &&
-    (prop as unknown as { name: string }).name === 'run'
+    (prop as unknown as { name: string }).name === 'blaze'
   );
 };

package/src/rules/{context-no-surface-types.ts → context-no-trailhead-types.ts}

@@ -1,5 +1,5 @@
 /**
- * Detects imports of surface-specific modules and types in trail files.
+ * Detects imports of trailhead-specific modules and types in trail files.
  *
  * Uses AST parsing for accurate detection — no false positives from
  * imports in comments or strings.
@@ -49,7 +49,7 @@ const makeDiag = (
   filePath,
   line: offsetToLine(sourceCode, node.start),
   message,
-  rule: 'context-no-surface-types',
+  rule: 'context-no-trailhead-types',
   severity: 'error',
 });
 
@@ -92,7 +92,7 @@ const checkSpecifiersForSurfaceTypes = (
     filePath,
     sourceCode,
     node,
-    `Do not import surface type "${typeName}" in trail implementation files.`
+    `Do not import trailhead type "${typeName}" in trail implementation files.`
   );
 };
 
@@ -111,7 +111,7 @@ const classifyImport = (
       filePath,
       sourceCode,
       node,
-      `Do not import from surface module "${moduleName}" in trail implementation files.`
+      `Do not import from trailhead module "${moduleName}" in trail implementation files.`
     );
   }
 
@@ -119,9 +119,9 @@ const classifyImport = (
 };
 
 /**
- * Detects imports of surface-specific types in trail implementation files.
+ * Detects imports of trailhead-specific types in trail implementation files.
  */
-export const contextNoSurfaceTypes: WardenRule = {
+export const contextNoTrailheadTypes: WardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
     if (!/\btrail\s*\(/.test(sourceCode)) {
       return [];
@@ -143,8 +143,8 @@ export const contextNoSurfaceTypes: WardenRule = {
     return diagnostics;
   },
   description:
-    'Disallow surface-specific type imports (Request, Response, McpSession, etc.) in trail implementation files.',
-  name: 'context-no-surface-types',
+    'Disallow trailhead-specific type imports (Request, Response, McpSession, etc.) in trail implementation files.',
+  name: 'context-no-trailhead-types',
 
   severity: 'error',
 };