@ontrails/warden 1.0.0-beta.39 → 1.0.0-beta.41

package/src/trails/no-sync-result-assumption.trail.ts

@@ -7,12 +7,12 @@ export const noSyncResultAssumptionTrail = wrapRule({
       expected: { diagnostics: [] },
       input: {
         filePath: 'clean.ts',
-        sourceCode: `const result = await myTrail.blaze(input, ctx);
+        sourceCode: `const result = await myTrail.implementation(input, ctx);
 if (result.isOk()) {
   console.log(result.value);
 }`,
       },
-      name: 'Properly awaited .blaze() call',
+      name: 'Properly awaited .implementation() call',
     },
   ],
   rule: noSyncResultAssumption,

package/src/trails/no-throw-in-detour-recover.trail.ts

@@ -14,7 +14,7 @@ export const noThrowInDetourRecoverTrail = wrapRule({
       recover: async () => Result.ok({ recovered: true }),
     },
   ],
-  blaze: () => Result.err(new ConflictError("conflict")),
+  implementation: () => Result.err(new ConflictError("conflict")),
 })`,
       },
       name: 'Detour recover without throw',

package/src/trails/no-throw-in-implementation.trail.ts

@@ -8,7 +8,7 @@ export const noThrowInImplementationTrail = wrapRule({
       input: {
         filePath: 'clean.ts',
         sourceCode: `trail("entity.show", {
-  blaze: async (input, ctx) => {
+  implementation: async (input, ctx) => {
     return Result.ok({ name: "test" });
   }
 })`,

package/src/trails/on-references-exist.trail.ts

@@ -11,7 +11,7 @@ export const onReferencesExistTrail = wrapRule({
         knownTrailIds: ['notify'],
         sourceCode: `trail("notify", {
   on: ["entity.created"],
-  blaze: async (input, ctx) => Result.ok({}),
+  implementation: async (input, ctx) => Result.ok({}),
 })`,
       },
       name: 'Resolved on: reference',

package/src/trails/pending-force.trail.ts

@@ -1,5 +1,5 @@
 import { topo } from '@ontrails/core';
-import { deriveTopoGraph } from '@ontrails/topographer';
+import { deriveTopoGraph } from '@ontrails/topography';
 
 import { pendingForce } from '../rules/trail-versioning-topo.js';
 import { wrapTopoRule } from './wrap-rule.js';

package/src/trails/permit-governance.trail.ts

@@ -5,14 +5,14 @@ import { permitGovernance } from '../rules/permit-governance.js';
 import { wrapTopoRule } from './wrap-rule.js';
 
 const destroyWithoutPermit = trail('entity.delete', {
-  blaze: () => Result.ok({ ok: true }),
+  implementation: () => Result.ok({ ok: true }),
   input: z.object({}),
   intent: 'destroy',
   output: z.object({ ok: z.boolean() }),
 });
 
 const scopedDestroy = trail('entity.delete', {
-  blaze: () => Result.ok({ ok: true }),
+  implementation: () => Result.ok({ ok: true }),
   input: z.object({}),
   intent: 'destroy',
   output: z.object({ ok: z.boolean() }),

package/src/trails/prefer-schema-inference.trail.ts

@@ -9,7 +9,7 @@ export const preferSchemaInferenceTrail = wrapRule({
         filePath: 'clean.ts',
         sourceCode: `trail("entity.show", {
   input: z.object({ name: z.string() }),
-  blaze: async (input, ctx) => {
+  implementation: async (input, ctx) => {
     return Result.ok({ name: input.name });
   }
 })`,

package/src/trails/public-output-schema.trail.ts

@@ -5,7 +5,7 @@ import { publicOutputSchema } from '../rules/public-output-schema.js';
 import { wrapTopoRule } from './wrap-rule.js';
 
 const cleanTrail = trail('report.read', {
-  blaze: () => Result.ok({ ok: true }),
+  implementation: () => Result.ok({ ok: true }),
   input: z.object({}),
   output: z.object({ ok: z.boolean() }),
 });
@@ -15,7 +15,7 @@ const cleanTopo = topo('public-output-schema-clean', {
 });
 
 const missingOutputTrail = trail('report.missing', {
-  blaze: () => Result.ok({ ok: true }),
+  implementation: () => Result.ok({ ok: true }),
   input: z.object({}),
 });
 

package/src/trails/public-union-output-discriminants.trail.ts

@@ -10,7 +10,7 @@ const cleanOutput = z.discriminatedUnion('kind', [
 ]);
 
 const cleanTrail = trail('report.read', {
-  blaze: () => Result.ok({ kind: 'message' as const, message: 'ok' }),
+  implementation: () => Result.ok({ kind: 'message' as const, message: 'ok' }),
   input: z.object({}),
   output: cleanOutput,
 });

package/src/trails/read-intent-fires.trail.ts

@@ -10,7 +10,7 @@ export const readIntentFiresTrail = wrapRule({
         sourceCode: `const entityLoaded = signal('entity.loaded', { payload: z.object({}) });
 trail('entity.read', {
   intent: 'read',
-  blaze: async () => Result.ok({}),
+  implementation: async () => Result.ok({}),
 });`,
       },
       name: 'Read trails without fires stay quiet',

package/src/trails/reference-exists.trail.ts

@@ -6,19 +6,19 @@ export const referenceExistsTrail = wrapRule({
     {
       expected: { diagnostics: [] },
       input: {
-        filePath: 'contours.ts',
-        knownContourIds: ['gist', 'user'],
+        filePath: 'entities.ts',
+        knownEntityIds: ['gist', 'user'],
         knownTrailIds: [],
-        sourceCode: `const user = contour("user", {
+        sourceCode: `const user = entity("user", {
   id: z.string().uuid(),
 }, { identity: "id" });
 
-const gist = contour("gist", {
+const gist = entity("gist", {
   id: z.string().uuid(),
   ownerId: user.id(),
 }, { identity: "id" });`,
       },
-      name: 'Contour references resolve to known project contours',
+      name: 'Entity references resolve to known project entities',
     },
   ],
   rule: referenceExists,

package/src/trails/resource-declarations.trail.ts

@@ -13,7 +13,7 @@ export const resourceDeclarationsTrail = wrapRule({
 
 trail("entity.show", {
   resources: [db],
-  blaze: async (_input, ctx) => {
+  implementation: async (_input, ctx) => {
     return Result.ok(db.from(ctx));
   }
 })`,

package/src/trails/resource-exists.trail.ts

@@ -15,7 +15,7 @@ export const resourceExistsTrail = wrapRule({
 
 trail("entity.show", {
   resources: [db],
-  blaze: async (_input, ctx) => {
+  implementation: async (_input, ctx) => {
     return Result.ok(db.from(ctx));
   }
 })`,

package/src/trails/run.ts

@@ -34,13 +34,11 @@ const appendDiagnostics = (
 type TrailIntentMap = Readonly<Record<string, Intent>>;
 
 interface ProjectRuleOptions {
-  readonly contourReferencesByName?: Readonly<
-    Record<string, readonly string[]>
-  >;
+  readonly entityReferencesByName?: Readonly<Record<string, readonly string[]>>;
   readonly composeTargetTrailIds?: readonly string[];
   readonly crudTableIds?: readonly string[];
   readonly crudCoverageByEntity?: Readonly<Record<string, readonly string[]>>;
-  readonly knownContourIds?: readonly string[];
+  readonly knownEntityIds?: readonly string[];
   readonly importResolutionsByFile?: Readonly<
     Record<string, readonly WardenImportResolution[]>
   >;
@@ -57,11 +55,11 @@ interface ProjectRuleOptions {
 }
 
 const PROJECT_OPTION_KEYS = [
-  'contourReferencesByName',
+  'entityReferencesByName',
   'composeTargetTrailIds',
   'crudTableIds',
   'crudCoverageByEntity',
-  'knownContourIds',
+  'knownEntityIds',
   'importResolutionsByFile',
   'documentedImportResolutionsByFile',
   'knownResourceIds',

package/src/trails/scheduled-destroy-intent.trail.ts

@@ -5,7 +5,7 @@ import { scheduledDestroyIntent } from '../rules/scheduled-destroy-intent.js';
 import { wrapTopoRule } from './wrap-rule.js';
 
 export const scheduledDestroyTrail = trail('billing.purge-expired', {
-  blaze: () => Result.ok({ ok: true }),
+  implementation: () => Result.ok({ ok: true }),
   input: z.object({}),
   intent: 'destroy',
   on: [
@@ -18,7 +18,7 @@ export const scheduledDestroyTrail = trail('billing.purge-expired', {
 });
 
 const scheduledWriteTrail = trail('billing.reconcile', {
-  blaze: () => Result.ok({ ok: true }),
+  implementation: () => Result.ok({ ok: true }),
   input: z.object({}),
   on: [schedule('schedule.billing.reconcile', { cron: '0 * * * *' })],
   output: z.object({ ok: z.boolean() }),

package/src/trails/schema.ts

@@ -7,7 +7,7 @@
 
 import { intentValues } from '@ontrails/core';
 import type { Topo } from '@ontrails/core';
-import type { TopoGraph } from '@ontrails/topographer';
+import type { TopoGraph } from '@ontrails/topography';
 import { z } from 'zod';
 import { wardenImportResolutionErrorKinds } from '../resolve.js';
 import { wardenFixClasses, wardenFixSafeties } from '../rules/metadata.js';
@@ -106,7 +106,7 @@ export const exportedSymbolDefinitionSchema = z.object({
  * Extended input for project-aware warden rule trails.
  *
  * Adds `knownTrailIds` so the caller can supply compose-file context and avoid
- * false positives for `@see` references or compose-file contour relationships.
+ * false positives for `@see` references or compose-file entity relationships.
  */
 export const authoredMcpSurfaceBindingSetSchema = z.object({
   appName: z.string().describe('App/topo label the bindings were authored for'),
@@ -131,10 +131,6 @@ export const projectAwareRuleInput = ruleInput.extend({
     .array(z.string())
     .optional()
     .describe('Trail IDs referenced by composes arrays across the project'),
-  contourReferencesByName: z
-    .record(z.string(), z.array(z.string()))
-    .optional()
-    .describe('Declared contour references keyed by source contour name'),
   crudCoverageByEntity: z
     .record(z.string(), z.array(z.string()))
     .optional()
@@ -149,6 +145,10 @@ export const projectAwareRuleInput = ruleInput.extend({
     .record(z.string(), z.array(importResolutionSchema))
     .optional()
     .describe('Resolved docs/specifier facts keyed by documentation file path'),
+  entityReferencesByName: z
+    .record(z.string(), z.array(z.string()))
+    .optional()
+    .describe('Declared entity references keyed by source entity name'),
   exportedSymbolDefinitionsByName: z
     .record(z.string(), z.array(exportedSymbolDefinitionSchema))
     .optional()
@@ -157,10 +157,10 @@ export const projectAwareRuleInput = ruleInput.extend({
     .record(z.string(), z.array(importResolutionSchema))
     .optional()
     .describe('Resolved import facts keyed by importer file path'),
-  knownContourIds: z
+  knownEntityIds: z
     .array(z.string())
     .optional()
-    .describe('Contour names known across the project'),
+    .describe('Entity names known across the project'),
   knownResourceIds: z
     .array(z.string())
     .optional()
@@ -219,7 +219,7 @@ export const topoAwareRuleInput = z.object({
         value !== null &&
         'trails' in value &&
         'resources' in value &&
-        'contours' in value &&
+        'entities' in value &&
         'signals' in value,
       { message: 'Expected a resolved Topo instance' }
     )

package/src/trails/signal-graph-coaching.trail.ts

@@ -13,11 +13,11 @@ const producedSignal = signal('invoice.created', {
 });
 
 const producerTrail = trail('invoice.create', {
-  blaze: async (_input, ctx) => {
+  fires: [producedSignal],
+  implementation: async (_input, ctx) => {
     await ctx.fire?.(producedSignal, { invoiceId: 'inv_1' });
     return Result.ok({ invoiceId: 'inv_1' });
   },
-  fires: [producedSignal],
   input: z.object({}),
   output: z.object({ invoiceId: z.string() }),
 });

package/src/trails/static-resource-accessor-preference.trail.ts

@@ -13,7 +13,7 @@ export const staticResourceAccessorPreferenceTrail = wrapRule({
 
 trail("entity.show", {
   resources: [db],
-  blaze: async (_input, ctx) => {
+  implementation: async (_input, ctx) => {
     return Result.ok(db.from(ctx));
   }
 })`,

package/src/trails/surface-overlay-coherence.trail.ts

@@ -5,7 +5,7 @@ import { surfaceOverlayCoherence } from '../rules/surface-overlay-coherence.js';
 import { wrapTopoRule } from './wrap-rule.js';
 
 const listTrail = trail('gear.list', {
-  blaze: () => Result.ok([]),
+  implementation: () => Result.ok([]),
   input: z.object({}),
   output: z.array(z.string()),
 });

package/src/trails/trail-fork-coaching.trail.ts

@@ -25,7 +25,7 @@ export const usersManage = trail("users.manage", {
   input: z.object({
     action: z.enum(["create", "delete"]),
   }),
-  blaze: async (input) => {
+  implementation: async (input) => {
     switch (input.action) {
       case "create":
         return Result.ok({ created: true });

package/src/trails/unmaterialized-activation-source.trail.ts

@@ -10,7 +10,7 @@ const invoicePaidWebhook = webhook('webhook.invoice.paid', {
 });
 
 const webhookConsumer = trail('invoice.audit-webhook', {
-  blaze: () => Result.ok({ ok: true }),
+  implementation: () => Result.ok({ ok: true }),
   input: z.object({ invoiceId: z.string() }),
   on: [invoicePaidWebhook],
   output: z.object({ ok: z.boolean() }),
@@ -22,24 +22,24 @@ const invoiceCreated = signal('invoice.created', {
 });
 
 const signalProducer = trail('invoice.create', {
-  blaze: async (_input, ctx) => {
+  fires: [invoiceCreated],
+  implementation: async (_input, ctx) => {
     await ctx.fire?.(invoiceCreated, { invoiceId: 'inv_1' });
     return Result.ok({ invoiceId: 'inv_1' });
   },
-  fires: [invoiceCreated],
   input: z.object({}),
   output: z.object({ invoiceId: z.string() }),
 });
 
 const signalConsumer = trail('invoice.index', {
-  blaze: () => Result.ok({ ok: true }),
+  implementation: () => Result.ok({ ok: true }),
   input: z.object({ invoiceId: z.string() }),
   on: [invoiceCreated],
   output: z.object({ ok: z.boolean() }),
 });
 
 const scheduleConsumer = trail('invoice.reconcile', {
-  blaze: () => Result.ok({ ok: true }),
+  implementation: () => Result.ok({ ok: true }),
   input: z.object({}),
   on: [schedule('schedule.invoice.reconcile', { cron: '0 * * * *' })],
   output: z.object({ ok: z.boolean() }),

package/src/trails/valid-detour-contract.trail.ts

@@ -5,7 +5,6 @@ import { validDetourContract } from '../rules/valid-detour-contract.js';
 import { wrapTopoRule } from './wrap-rule.js';
 
 const validTrail = trail('entity.save', {
-  blaze: () => Result.ok({ ok: true }),
   detours: [
     {
       on: ConflictError,
@@ -15,6 +14,7 @@ const validTrail = trail('entity.save', {
       },
     },
   ],
+  implementation: () => Result.ok({ ok: true }),
   input: z.object({}),
   output: z.object({ ok: z.boolean() }),
 });

package/src/trails/version-gap.trail.ts

@@ -5,7 +5,7 @@ import { versionGap } from '../rules/trail-versioning-topo.js';
 import { wrapTopoRule } from './wrap-rule.js';
 
 const versionedTrail = trail('version.gap.clean', {
-  blaze: () => Result.ok({ ok: true }),
+  implementation: () => Result.ok({ ok: true }),
   input: z.object({}),
   output: z.object({ ok: z.boolean() }),
   version: 2,

package/src/trails/version-pinned-compose.trail.ts

@@ -9,7 +9,7 @@ export const versionPinnedComposeTrail = wrapRule({
         filePath: 'src/trails/current.ts',
         sourceCode: `
 trail('current.parent', {
-  blaze: async (_input, ctx) => {
+  implementation: async (_input, ctx) => {
     await ctx.compose('current.child', {});
     return Result.ok({});
   },

package/src/trails/version-without-examples.trail.ts

@@ -5,7 +5,7 @@ import { versionWithoutExamples } from '../rules/trail-versioning-topo.js';
 import { wrapTopoRule } from './wrap-rule.js';
 
 const archivedWithoutExamples = trail('version.examples.archived', {
-  blaze: () => Result.ok({ ok: true }),
+  implementation: () => Result.ok({ ok: true }),
   input: z.object({}),
   output: z.object({ ok: z.boolean() }),
   version: 2,

package/src/trails/warden-rules-use-ast.trail.ts

@@ -28,7 +28,7 @@ export const wardenRulesUseAstTrail = wrapRule({
             filePath: fakeRulePath,
             line: 1,
             message:
-              'warden-rules-use-ast: sourceCode.split(...) treats source text as a string. Warden rules must inspect the AST via packages/warden/src/rules/ast.ts helpers, not regex-scan raw source text. Use findStringLiterals, findTrailDefinitions, findConfigProperty, or a similar AST walker. Raw-text scanning produces false positives on string literals, template payloads, and docstrings — see TRL-335, ADR-0036.',
+              'warden-rules-use-ast: sourceCode.split(...) treats source text as a string. Warden rules must inspect source code via @ontrails/source helpers, not regex-scan raw source text. Use findStringLiterals, findTrailDefinitions, findConfigProperty, or a similar AST walker. Raw-text scanning produces false positives on string literals, template payloads, and docstrings — see TRL-335, ADR-0036.',
             rule: 'warden-rules-use-ast',
             severity: 'error',
           },
@@ -47,7 +47,7 @@ export const wardenRulesUseAstTrail = wrapRule({
             filePath: fakeRulePath,
             line: 1,
             message:
-              'warden-rules-use-ast: raw AST node-field cast should use typed helpers from ./ast.js (callee -> getNodeCallee). Raw node-field casts drift from the curated @ontrails/warden/ast guard surface.',
+              'warden-rules-use-ast: raw AST node-field cast should use typed helpers from the shared source helpers (callee -> getNodeCallee). Raw node-field casts drift from the shared source helper surface.',
             rule: 'warden-rules-use-ast',
             severity: 'warn',
           },

package/src/trails/webhook-route-collision.trail.ts

@@ -10,14 +10,14 @@ const paymentWebhook = webhook('webhook.payment.received', {
 });
 
 const paymentReceiver = trail('payment.receive', {
-  blaze: () => Result.ok({ ok: true }),
+  implementation: () => Result.ok({ ok: true }),
   input: z.object({ paymentId: z.string() }),
   on: [paymentWebhook],
   output: z.object({ ok: z.boolean() }),
 });
 
 const directRoute = trail('webhooks.payment', {
-  blaze: () => Result.ok({ ok: true }),
+  implementation: () => Result.ok({ ok: true }),
   input: z.object({}),
   output: z.object({ ok: z.boolean() }),
 });

package/src/trails/wrap-rule.ts

@@ -54,10 +54,10 @@ const buildProjectContext = (input: ProjectAwareRuleInput): ProjectContext => ({
   ...(input.authoredMcpSurfaceBindingSets
     ? { authoredMcpSurfaceBindingSets: input.authoredMcpSurfaceBindingSets }
     : {}),
-  ...(input.contourReferencesByName
+  ...(input.entityReferencesByName
     ? {
-        contourReferencesByName: new Map(
-          Object.entries(input.contourReferencesByName)
+        entityReferencesByName: new Map(
+          Object.entries(input.entityReferencesByName)
         ),
       }
     : {}),
@@ -74,8 +74,8 @@ const buildProjectContext = (input: ProjectAwareRuleInput): ProjectContext => ({
         ),
       }
     : {}),
-  ...(input.knownContourIds
-    ? { knownContourIds: new Set(input.knownContourIds) }
+  ...(input.knownEntityIds
+    ? { knownEntityIds: new Set(input.knownEntityIds) }
     : {}),
   ...(input.importResolutionsByFile
     ? {
@@ -145,7 +145,12 @@ export function wrapRule(
   if (isProjectAware) {
     const projectAwareRule = rule as ProjectAwareWardenRule;
     return trail(`warden.rule.${rule.name}`, {
-      blaze: (input: ProjectAwareRuleInput) => {
+      description: rule.description,
+      examples: examples as Trail<
+        ProjectAwareRuleInput,
+        RuleOutput
+      >['examples'],
+      implementation: (input: ProjectAwareRuleInput) => {
         const diagnostics = projectAwareRule.checkWithContext(
           input.sourceCode,
           input.filePath,
@@ -153,11 +158,6 @@ export function wrapRule(
         );
         return Result.ok({ diagnostics: [...diagnostics] });
       },
-      description: rule.description,
-      examples: examples as Trail<
-        ProjectAwareRuleInput,
-        RuleOutput
-      >['examples'],
       input: projectAwareRuleInput,
       intent: 'read',
       meta: buildRuleMeta(rule),
@@ -166,12 +166,12 @@ export function wrapRule(
   }
 
   return trail(`warden.rule.${rule.name}`, {
-    blaze: (input: RuleInput) => {
+    description: rule.description,
+    examples: examples as Trail<RuleInput, RuleOutput>['examples'],
+    implementation: (input: RuleInput) => {
       const diagnostics = rule.check(input.sourceCode, input.filePath);
       return Result.ok({ diagnostics: [...diagnostics] });
     },
-    description: rule.description,
-    examples: examples as Trail<RuleInput, RuleOutput>['examples'],
     input: ruleInput,
     intent: 'read',
     meta: buildRuleMeta(rule),
@@ -198,7 +198,9 @@ export const wrapTopoRule = (
 ): Trail<TopoAwareRuleInput, RuleOutput> => {
   const { rule, examples } = options;
   return trail(`warden.rule.${rule.name}`, {
-    blaze: async (input: TopoAwareRuleInput) => {
+    description: rule.description,
+    examples,
+    implementation: async (input: TopoAwareRuleInput) => {
       try {
         const diagnostics = await rule.checkTopo(input.topo, {
           graph: input.graph,
@@ -214,8 +216,6 @@ export const wrapTopoRule = (
         );
       }
     },
-    description: rule.description,
-    examples,
     input: topoAwareRuleInput,
     intent: 'read',
     meta: buildRuleMeta(rule),