@ontrails/trails 1.0.0-beta.15 → 1.0.0-beta.17

package/src/trails/survey.ts

@@ -1,245 +1,471 @@
 /**
  * `survey` trail -- Full topo introspection.
  *
- * Lists trails, shows detail for individual trails, generates surface maps,
- * and diffs against previous versions.
+ * Lists trails, looks up trails/resources/signals, and diffs against previous
+ * versions.
  */
 
-import { join } from 'node:path';
+import { basename, extname, join } from 'node:path';
 
 import type { Topo } from '@ontrails/core';
-import { NotFoundError, Result, trail } from '@ontrails/core';
-import type { DiffResult } from '@ontrails/schema';
 import {
-  deriveSurfaceMapDiff,
-  deriveOpenApiSpec,
-  deriveSurfaceMap,
-  readSurfaceMap,
-} from '@ontrails/schema';
+  deriveSafePath,
+  NotFoundError,
+  Result,
+  trail,
+  ValidationError,
+} from '@ontrails/core';
+import type { DiffEntry, DiffResult, TopoGraph } from '@ontrails/topographer';
+import {
+  createTopoStore,
+  deriveTopoGraphDiff,
+  deriveTopoGraph,
+  TOPO_GRAPH_SCHEMA_VERSION,
+  readTopoGraph,
+} from '@ontrails/topographer';
 import { z } from 'zod';
 
-import { loadApp, loadFreshAppLease } from './load-app.js';
+import { writeIsolatedExampleJsonFile } from '../local-state-io.js';
+
+import { tryLoadFreshAppLease } from './load-app.js';
+import { resolveTrailRootDir } from './root-dir.js';
 import {
   buildCurrentTopoBrief,
-  buildCurrentTopoDetail,
   buildCurrentTopoList,
+  buildCurrentTopoMatches,
+  buildCurrentTrailDetail,
+  buildCurrentResourceDetail,
+  buildCurrentSignalDetail,
+  readSurfaceLayerNamesFromContext,
 } from './topo-read-support.js';
-import { exportCurrentTopo } from './topo-store-support.js';
+import {
+  activationOverviewOutput,
+  resourceDetailOutput,
+  shippedSurfaceInventoryOutput,
+  signalDetailOutput,
+  trailDetailOutput,
+} from './topo-output-schemas.js';
+import { createIsolatedExampleInput } from './topo-support.js';
+import {
+  briefReportSchema,
+  deriveShippedSurfaceProjectionInventory,
+} from './topo-reports.js';
+import type { SurfaceLayerNames } from './topo-reports.js';
 
 export {
+  briefReportSchema,
   deriveBriefReport,
   deriveResourceDetail,
+  deriveShippedSurfaceProjectionInventory,
+  deriveSignalDetail,
   deriveSurveyList,
   deriveTrailDetail,
 } from './topo-reports.js';
 export type {
   BriefReport,
+  ShippedSurfaceInventoryReport,
+  ShippedSurfaceProjection,
+  SignalDetailReport,
+  SurfaceLayerNames,
   SurveyListReport,
   TrailDetailReport,
 } from './topo-reports.js';
 
 // ---------------------------------------------------------------------------
-// Brief report (formerly scout)
+// Survey diff helpers
 // ---------------------------------------------------------------------------
 
-const formatDiff = (diff: DiffResult): object => ({
+interface SurveyDiffReport {
+  readonly against: string;
+  readonly breaking: readonly DiffEntry[];
+  readonly hasBreaking: boolean;
+  readonly info: readonly DiffEntry[];
+  readonly mode: 'diff';
+  readonly warnings: readonly DiffEntry[];
+}
+
+const formatDiff = (diff: DiffResult, against: string): SurveyDiffReport => ({
+  against,
   breaking: diff.breaking,
   hasBreaking: diff.hasBreaking,
   info: diff.info,
+  mode: 'diff',
   warnings: diff.warnings,
 });
 
+const createDiffExampleInput = (): {
+  readonly against: string;
+  readonly module: string;
+  readonly rootDir: string;
+} => {
+  const input = createIsolatedExampleInput('survey-diff');
+  writeIsolatedExampleJsonFile(input.rootDir, 'baseline/topo.lock', {
+    activationGraph: {
+      edgeCount: 0,
+      edges: [],
+      sourceCount: 0,
+      sourceKeys: [],
+      trailIds: [],
+    },
+    activationSources: {},
+    entries: [],
+    generatedAt: '2026-01-01T00:00:00.000Z',
+    topoGraphSchemaVersion: TOPO_GRAPH_SCHEMA_VERSION,
+  } satisfies TopoGraph);
+  return { ...input, against: 'baseline' };
+};
+
+const isNotFound = (error: unknown): boolean =>
+  typeof error === 'object' &&
+  error !== null &&
+  (error as NodeJS.ErrnoException).code === 'ENOENT';
+
+const readTopoGraphFile = async (
+  filePath: string
+): Promise<TopoGraph | null> => {
+  try {
+    return (await Bun.file(filePath).json()) as TopoGraph;
+  } catch (error: unknown) {
+    if (isNotFound(error)) {
+      return null;
+    }
+    throw error;
+  }
+};
+
+const readStoredTopoGraph = (
+  rootDir: string,
+  against: string
+): TopoGraph | undefined => {
+  try {
+    const store = createTopoStore({ rootDir });
+    const stored =
+      store.exports.get({ pin: against }) ??
+      store.exports.get({ snapshotId: against });
+    return stored === undefined
+      ? undefined
+      : (JSON.parse(stored.topoGraphJson) as TopoGraph);
+  } catch (error: unknown) {
+    if (error instanceof NotFoundError) {
+      return undefined;
+    }
+    throw error;
+  }
+};
+
+const readPathTopoGraph = async (
+  rootDir: string,
+  against: string
+): Promise<Result<TopoGraph | null, Error>> => {
+  const safePath = deriveSafePath(rootDir, against);
+  if (safePath.isErr()) {
+    return safePath;
+  }
+
+  return Result.ok(
+    basename(safePath.value) === 'topo.lock' ||
+      extname(safePath.value) === '.json'
+      ? await readTopoGraphFile(safePath.value)
+      : await readTopoGraph({ dir: safePath.value })
+  );
+};
+
+const describeAgainstPathTarget = (against: string): string =>
+  basename(against) === 'topo.lock' || extname(against) === '.json'
+    ? 'workspace-relative TopoGraph file'
+    : 'workspace-relative directory containing topo.lock';
+
+const topoGraphNotFound = (against: string): NotFoundError =>
+  new NotFoundError(
+    `No TopoGraph found for: ${against}. Tried ${describeAgainstPathTarget(
+      against
+    )}, then topo-store pin and snapshot references.`
+  );
+
+const readAgainstTopoGraph = async (
+  rootDir: string,
+  against?: string | undefined
+): Promise<Result<{ against: string; map: TopoGraph }, Error>> => {
+  if (against === undefined || against === 'saved') {
+    const map = await readTopoGraph({ dir: join(rootDir, '.trails') });
+    return map === null
+      ? Result.err(
+          new NotFoundError(
+            'No saved TopoGraph found. Run `trails topo compile` first.'
+          )
+        )
+      : Result.ok({ against: 'saved', map });
+  }
+
+  // Treat explicit filesystem targets as the most local user intent; stored
+  // pins and snapshot ids are fallback references when no path exists.
+  const pathMap = await readPathTopoGraph(rootDir, against);
+  if (pathMap.isErr()) {
+    return pathMap;
+  }
+  if (pathMap.value !== null) {
+    return Result.ok({ against, map: pathMap.value });
+  }
+
+  const storedMap = readStoredTopoGraph(rootDir, against);
+  if (storedMap !== undefined) {
+    return Result.ok({ against, map: storedMap });
+  }
+
+  return Result.err(topoGraphNotFound(against));
+};
+
 const buildSurveyDiff = async (
   app: Topo,
   rootDir: string,
-  breakingOnly: boolean
-): Promise<Result<object, Error>> => {
-  const currentMap = deriveSurfaceMap(app);
-  const previousMap = await readSurfaceMap({ dir: join(rootDir, '.trails') });
-  if (!previousMap) {
-    return Result.err(
-      new NotFoundError(
-        'No saved surface map found. Run `trails topo export` first.'
-      )
-    );
+  breakingOnly: boolean,
+  against?: string | undefined
+): Promise<Result<SurveyDiffReport, Error>> => {
+  const currentMap = deriveTopoGraph(app);
+  const previous = await readAgainstTopoGraph(rootDir, against);
+  if (previous.isErr()) {
+    return previous;
   }
 
-  const diff = deriveSurfaceMapDiff(previousMap, currentMap);
+  const diff = deriveTopoGraphDiff(previous.value.map, currentMap);
   return Result.ok(
     breakingOnly
-      ? formatDiff({
-          ...diff,
-          entries: diff.breaking,
-          info: [],
-          warnings: [],
-        })
-      : formatDiff(diff)
+      ? formatDiff({ ...diff, info: [], warnings: [] }, previous.value.against)
+      : formatDiff(diff, previous.value.against)
   );
 };
 
-const buildSurveyDetail = (
+const buildSurveyLookup = (
+  app: Topo,
+  entityId: string,
+  rootDir: string,
+  surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined
+): Result<object, Error> => {
+  const matches = buildCurrentTopoMatches(app, entityId, {
+    rootDir,
+    surfaceLayerNames,
+  });
+  return Result.ok({ matches });
+};
+
+const buildSurveyTrailDetail = (
+  app: Topo,
+  id: string,
+  rootDir: string,
+  surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined
+): Result<object, Error> => {
+  const detail = buildCurrentTrailDetail(app, id, {
+    rootDir,
+    surfaceLayerNames,
+  });
+  return detail === undefined
+    ? Result.err(new NotFoundError(`Trail not found: ${id}`))
+    : Result.ok(detail);
+};
+
+const buildSurveyResourceDetail = (
   app: Topo,
-  trailId: string,
+  id: string,
   rootDir: string
 ): Result<object, Error> => {
-  const detail = buildCurrentTopoDetail(app, trailId, { rootDir });
-  if (detail !== undefined) {
-    return Result.ok(detail);
-  }
-  return Result.err(
-    new NotFoundError(`Trail or resource not found: ${trailId}`)
-  );
+  const detail = buildCurrentResourceDetail(app, id, { rootDir });
+  return detail === undefined
+    ? Result.err(new NotFoundError(`Resource not found: ${id}`))
+    : Result.ok(detail);
 };
 
-const buildSurveyGenerate = async (
+const buildSurveySignalDetail = (
   app: Topo,
+  id: string,
   rootDir: string
-): Promise<Result<object, Error>> => {
-  const exported = await exportCurrentTopo(app, { rootDir });
-  if (exported.isErr()) {
-    return exported;
-  }
-  return Result.ok({
-    hash: exported.value.hash,
-    lockPath: exported.value.lockPath,
-    mapPath: exported.value.mapPath,
-  });
+): Result<object, Error> => {
+  const detail = buildCurrentSignalDetail(app, id, { rootDir });
+  return detail === undefined
+    ? Result.err(new NotFoundError(`Signal not found: ${id}`))
+    : Result.ok(detail);
 };
 
+const buildSurveySurfaceInventory = (app: Topo): Result<object, Error> =>
+  Result.ok(deriveShippedSurfaceProjectionInventory(app));
+
 interface SurveyInput {
-  breakingOnly: boolean;
-  brief: boolean;
-  diffSaved: boolean;
-  generate: boolean;
-  openapi: boolean;
-  trailId?: string | undefined;
+  id?: string | undefined;
+  module?: string | undefined;
+  rootDir?: string | undefined;
 }
 
-type SurveyMode = 'brief' | 'detail' | 'diff' | 'generate' | 'list' | 'openapi';
+type SurveyMode = 'lookup' | 'overview';
 
-/** Ordered mode checks — first truthy predicate wins, otherwise 'list'. */
-const modeChecks: readonly [(input: SurveyInput) => boolean, SurveyMode][] = [
-  [(i) => i.brief, 'brief'],
-  [(i) => i.diffSaved, 'diff'],
-  [(i) => Boolean(i.trailId), 'detail'],
-  [(i) => i.generate, 'generate'],
-  [(i) => i.openapi, 'openapi'],
-];
+type SurveyEnvelope = { readonly mode: SurveyMode } & Record<string, unknown>;
 
-/** Determine which survey mode was requested, falling back to 'list'. */
+/** Determine which survey mode was requested, falling back to 'overview'. */
 const deriveSurveyMode = (input: SurveyInput): SurveyMode =>
-  modeChecks.find(([predicate]) => predicate(input))?.[1] ?? 'list';
+  input.id === undefined || input.id === '' ? 'overview' : 'lookup';
 
 type SurveyHandler = (
   app: Topo,
   input: SurveyInput,
-  rootDir: string
+  rootDir: string,
+  surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined
 ) => Result<object, Error> | Promise<Result<object, Error>>;
 
 /** Handlers keyed by survey mode. */
 const surveyHandlers: Record<SurveyMode, SurveyHandler> = {
-  brief: (app, _input, rootDir) =>
-    Result.ok(buildCurrentTopoBrief(app, { rootDir })),
-  detail: (app, input, rootDir) =>
-    buildSurveyDetail(app, input.trailId ?? '', rootDir),
-  diff: (app, input, rootDir) =>
-    buildSurveyDiff(app, rootDir, input.breakingOnly),
-  generate: (app, _input, rootDir) => buildSurveyGenerate(app, rootDir),
-  list: (app, _input, rootDir) =>
+  lookup: (app, input, rootDir, surfaceLayerNames) =>
+    input.id === undefined || input.id === ''
+      ? Result.err(new ValidationError('Survey lookup requires an id'))
+      : buildSurveyLookup(app, input.id, rootDir, surfaceLayerNames),
+  overview: (app, _input, rootDir) =>
     Result.ok(buildCurrentTopoList(app, { rootDir })),
-  openapi: (app) => Result.ok(deriveOpenApiSpec(app)),
 };
 
+const envelopeSurveyValue = (
+  mode: SurveyMode,
+  value: object
+): SurveyEnvelope => ({ ...value, mode });
+
 /** Dispatch to the appropriate survey sub-command based on input flags. */
-const dispatchSurvey = (
+const dispatchSurvey = async (
   app: Topo,
   input: SurveyInput,
-  rootDir: string
-): Result<object, Error> | Promise<Result<object, Error>> => {
+  rootDir: string,
+  surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined
+): Promise<Result<SurveyEnvelope, Error>> => {
   const mode = deriveSurveyMode(input);
   const handler = surveyHandlers[mode];
-  return handler(app, input, rootDir);
+  const result = await handler(app, input, rootDir, surfaceLayerNames);
+  if (result.isErr()) {
+    return result;
+  }
+  return Result.ok(envelopeSurveyValue(mode, result.value));
+};
+
+const detailInputSchema = z.object({
+  id: z.string().describe('Trail, resource, or signal ID'),
+  module: z.string().optional().describe('Path to the app module'),
+  rootDir: z.string().optional().describe('Workspace root directory'),
+});
+
+const withFreshSurveyApp = async <T>(
+  input: { readonly module?: string | undefined },
+  rootDir: string,
+  consume: (app: Topo) => Promise<Result<T, Error>> | Result<T, Error>
+): Promise<Result<T, Error>> => {
+  const leaseResult = await tryLoadFreshAppLease(input.module, rootDir);
+  if (leaseResult.isErr()) {
+    return Result.err(leaseResult.error);
+  }
+  const lease = leaseResult.value;
+  try {
+    return await consume(lease.app);
+  } finally {
+    lease.release();
+  }
+};
+
+const withResolvedSurveyApp = async <T>(
+  input: {
+    readonly module?: string | undefined;
+    readonly rootDir?: string | undefined;
+  },
+  cwd: string | undefined,
+  consume: (
+    app: Topo,
+    rootDir: string
+  ) => Promise<Result<T, Error>> | Result<T, Error>
+): Promise<Result<T, Error>> => {
+  const rootDirResult = resolveTrailRootDir(input.rootDir, cwd);
+  if (rootDirResult.isErr()) {
+    return Result.err(rootDirResult.error);
+  }
+  const rootDir = rootDirResult.value;
+  return withFreshSurveyApp(input, rootDir, (app) => consume(app, rootDir));
 };
 
+const moduleInputSchema = z.object({
+  module: z.string().optional().describe('Path to the app module'),
+  rootDir: z.string().optional().describe('Workspace root directory'),
+});
+
+const diffEntryOutput = z.object({
+  change: z.enum(['added', 'removed', 'modified']),
+  details: z.array(z.string()).readonly(),
+  id: z.string(),
+  kind: z.enum(['contour', 'trail', 'signal', 'resource']),
+  severity: z.enum(['info', 'warning', 'breaking']),
+});
+
+const diffOutput = z.object({
+  against: z.string(),
+  breaking: z.array(diffEntryOutput),
+  hasBreaking: z.boolean(),
+  info: z.array(diffEntryOutput),
+  mode: z.literal('diff'),
+  warnings: z.array(diffEntryOutput),
+});
+
+const surveyMatchOutput = z.discriminatedUnion('kind', [
+  z.object({
+    detail: trailDetailOutput,
+    kind: z.literal('trail'),
+  }),
+  z.object({
+    detail: resourceDetailOutput,
+    kind: z.literal('resource'),
+  }),
+  z.object({
+    detail: signalDetailOutput,
+    kind: z.literal('signal'),
+  }),
+]);
+
 // ---------------------------------------------------------------------------
 // Trail definition
 // ---------------------------------------------------------------------------
 
 export const surveyTrail = trail('survey', {
-  blaze: async (input, ctx) => {
-    const rootDir = ctx.cwd ?? '.';
-    const mode = deriveSurveyMode(input);
-    // Fresh load only for diffSaved: comparing against a previously-saved
-    // surface map requires the current app's source state, not any cached
-    // module graph that a prior import may have frozen. Other modes read
-    // the in-memory topo and benefit from the standard import cache.
-    //
-    // For diff specifically, use a disposable lease rather than retained
-    // fresh mirrors — the returned diff result is serialisable data, not
-    // a Topo reference with deferred imports, so the mirror can be
-    // released the moment dispatchSurvey returns. That keeps MCP/dev
-    // sessions that poll diff repeatedly from growing .trails-tmp/
-    // without bound.
-    if (mode === 'diff') {
-      const lease = await loadFreshAppLease(input.module, rootDir);
-      try {
-        return await dispatchSurvey(lease.app, input, rootDir);
-      } finally {
-        lease.release();
-      }
-    }
-
-    const app = await loadApp(input.module, rootDir);
-    return dispatchSurvey(app, input, rootDir);
-  },
+  args: ['id'],
+  blaze: async (input, ctx) =>
+    withResolvedSurveyApp(input, ctx.cwd, (app, rootDir) =>
+      dispatchSurvey(app, input, rootDir, readSurfaceLayerNamesFromContext(ctx))
+    ),
   description: 'Full topo introspection',
   examples: [
     {
-      description: 'Lists all registered trails with safety and surface info',
-      input: { module: './src/app.ts' },
-      name: 'List all trails',
-    },
-    {
-      description: 'Quick capability summary with counts and feature flags',
-      input: { brief: true, module: './src/app.ts' },
-      name: 'Brief capability report',
+      description: 'Show all registered trails, resources, and signals',
+      input: createIsolatedExampleInput('survey-overview'),
+      name: 'Overview',
     },
     {
-      description: 'Generate an OpenAPI 3.1 specification for the topo',
-      input: { module: './src/app.ts', openapi: true },
-      name: 'OpenAPI spec',
+      description: 'Find every trail, resource, or signal with a matching ID',
+      input: { ...createIsolatedExampleInput('survey-lookup'), id: 'survey' },
+      name: 'Lookup by ID',
     },
   ],
   input: z.object({
-    breakingOnly: z
-      .boolean()
-      .default(false)
-      .describe('Only show breaking changes'),
-    brief: z.boolean().default(false).describe('Quick capability summary'),
-    diffSaved: z
-      .boolean()
-      .default(false)
-      .describe('Diff against the saved local surface map'),
-    generate: z
-      .boolean()
-      .default(false)
-      .describe('Generate surface map and lock file'),
+    id: z
+      .string()
+      .optional()
+      .describe('Trail, resource, or signal ID to look up'),
     module: z.string().optional().describe('Path to the app module'),
-    openapi: z.boolean().default(false).describe('Output OpenAPI 3.1 spec'),
-    trailId: z.string().optional().describe('Trail ID for detail view'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
   }),
   intent: 'read',
-  output: z.union([
+  output: z.discriminatedUnion('mode', [
     z.object({
+      activation: activationOverviewOutput,
       count: z.number(),
       entries: z.array(
         z.object({
+          activatedBy: z.array(z.string()).readonly(),
+          activates: z.array(z.string()).readonly(),
           examples: z.number(),
           id: z.string(),
           kind: z.string(),
           safety: z.string(),
         })
       ),
+      mode: z.literal('overview'),
       resourceCount: z.number(),
       resources: z.array(
         z.object({
@@ -251,71 +477,179 @@ export const surveyTrail = trail('survey', {
           usedBy: z.array(z.string()),
         })
       ),
+      signalCount: z.number(),
+      signals: z.array(
+        z.object({
+          consumers: z.array(z.string()).readonly(),
+          description: z.string().nullable(),
+          examples: z.number(),
+          from: z.array(z.string()).readonly(),
+          id: z.string(),
+          kind: z.literal('signal'),
+          payloadSchema: z.boolean(),
+          producers: z.array(z.string()).readonly(),
+        })
+      ),
     }),
     z.object({
-      contractVersion: z.string(),
-      features: z.object({
-        detours: z.boolean(),
-        examples: z.boolean(),
-        outputSchemas: z.boolean(),
-        resources: z.boolean(),
-        signals: z.boolean(),
-      }),
-      name: z.string(),
-      resources: z.number(),
-      signals: z.number(),
-      trails: z.number(),
-      version: z.string(),
-    }),
-    z.object({
-      breaking: z.array(z.unknown()),
-      hasBreaking: z.boolean(),
-      info: z.array(z.unknown()),
-      warnings: z.array(z.unknown()),
-    }),
-    z.object({
-      crosses: z.array(z.string()),
-      description: z.unknown().nullable(),
-      detours: z.unknown().nullable(),
-      examples: z.array(z.unknown()),
-      id: z.string(),
-      intent: z.enum(['read', 'write', 'destroy']),
-      kind: z.string(),
-      resources: z.array(z.string()),
-      safety: z.string(),
-    }),
-    z.object({
-      description: z.string().nullable(),
-      health: z.enum(['available', 'none']),
-      id: z.string(),
-      kind: z.literal('resource'),
-      lifetime: z.literal('singleton'),
-      usedBy: z.array(z.string()),
-    }),
-    z.object({
-      hash: z.string(),
-      lockPath: z.string(),
-      mapPath: z.string(),
-    }),
-    z.object({
-      components: z.object({
-        schemas: z.record(z.string(), z.unknown()),
-      }),
-      info: z.object({
-        description: z.string().optional(),
-        title: z.string(),
-        version: z.string(),
-      }),
-      openapi: z.literal('3.1.0'),
-      paths: z.record(z.string(), z.record(z.string(), z.unknown())),
-      servers: z
-        .array(
-          z.object({
-            description: z.string().optional(),
-            url: z.string(),
-          })
-        )
-        .optional(),
+      matches: z.array(surveyMatchOutput),
+      mode: z.literal('lookup'),
     }),
   ]),
 });
+
+export const surveyBriefTrail = trail('survey.brief', {
+  blaze: async (input, ctx) =>
+    withResolvedSurveyApp(input, ctx.cwd, (app, rootDir) =>
+      Result.ok(buildCurrentTopoBrief(app, { rootDir }))
+    ),
+  description: 'Summarize topo capabilities',
+  examples: [
+    {
+      description: 'Show counts and feature flags',
+      input: createIsolatedExampleInput('survey-brief'),
+      name: 'Brief capability report',
+    },
+  ],
+  input: moduleInputSchema,
+  intent: 'read',
+  output: briefReportSchema,
+});
+
+export const surveySurfacesTrail = trail('survey.surfaces', {
+  blaze: async (input, ctx) =>
+    withResolvedSurveyApp(input, ctx.cwd, (app) =>
+      buildSurveySurfaceInventory(app)
+    ),
+  description: 'Inventory shipped surface projections',
+  examples: [
+    {
+      description: 'Show CLI, MCP, and HTTP projections for public trails',
+      input: createIsolatedExampleInput('survey-surfaces'),
+      name: 'Shipped surface inventory',
+    },
+  ],
+  input: moduleInputSchema,
+  intent: 'read',
+  output: shippedSurfaceInventoryOutput,
+});
+
+export const surveyDiffTrail = trail('survey.diff', {
+  blaze: async (input, ctx) =>
+    withResolvedSurveyApp(input, ctx.cwd, (app, rootDir) =>
+      buildSurveyDiff(app, rootDir, input.breakingOnly, input.against)
+    ),
+  description: 'Diff the current topo against a saved TopoGraph',
+  examples: [
+    {
+      description: 'Compare current topo to a saved TopoGraph directory',
+      input: createDiffExampleInput(),
+      name: 'Diff against baseline',
+    },
+    {
+      description: 'Reject an empty saved map target',
+      error: 'ValidationError',
+      input: { against: '' },
+      name: 'Reject empty diff target',
+    },
+    {
+      description: 'Reject an empty target before filtering breaking drift',
+      error: 'ValidationError',
+      input: {
+        against: '',
+        breakingOnly: true,
+      },
+      name: 'Reject empty breaking-only target',
+    },
+  ],
+  input: z.object({
+    against: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        'Saved TopoGraph target: "saved", a workspace path (topo.lock, .json file, or directory with topo.lock), then a pin/snapshot id'
+      ),
+    breakingOnly: z
+      .boolean()
+      .default(false)
+      .describe('Only show breaking changes'),
+    module: z.string().optional().describe('Path to the app module'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+  }),
+  intent: 'read',
+  output: diffOutput,
+});
+
+export const surveyTrailDetailTrail = trail('survey.trail', {
+  args: ['id'],
+  blaze: async (input, ctx) =>
+    withResolvedSurveyApp(input, ctx.cwd, (app, rootDir) =>
+      buildSurveyTrailDetail(
+        app,
+        input.id,
+        rootDir,
+        readSurfaceLayerNamesFromContext(ctx)
+      )
+    ),
+  description: 'Inspect one trail by ID',
+  examples: [
+    {
+      description: 'Show trail contract detail',
+      input: {
+        ...createIsolatedExampleInput('survey-trail-detail'),
+        id: 'survey',
+      },
+      name: 'Trail detail',
+    },
+  ],
+  input: detailInputSchema,
+  intent: 'read',
+  output: trailDetailOutput,
+});
+
+export const surveyResourceTrail = trail('survey.resource', {
+  args: ['id'],
+  blaze: async (input, ctx) =>
+    withResolvedSurveyApp(input, ctx.cwd, (app, rootDir) =>
+      buildSurveyResourceDetail(app, input.id, rootDir)
+    ),
+  description: 'Inspect one resource by ID',
+  examples: [
+    {
+      description: 'Show resource usage detail',
+      error: 'NotFoundError',
+      input: {
+        ...createIsolatedExampleInput('survey-resource-detail'),
+        id: 'db.main',
+      },
+      name: 'Resource detail',
+    },
+  ],
+  input: detailInputSchema,
+  intent: 'read',
+  output: resourceDetailOutput,
+});
+
+export const surveySignalTrail = trail('survey.signal', {
+  args: ['id'],
+  blaze: async (input, ctx) =>
+    withResolvedSurveyApp(input, ctx.cwd, (app, rootDir) =>
+      buildSurveySignalDetail(app, input.id, rootDir)
+    ),
+  description: 'Inspect one signal by ID',
+  examples: [
+    {
+      description: 'Show signal producer and consumer detail',
+      error: 'NotFoundError',
+      input: {
+        ...createIsolatedExampleInput('survey-signal-detail'),
+        id: 'hello.greeted',
+      },
+      name: 'Signal detail',
+    },
+  ],
+  input: detailInputSchema,
+  intent: 'read',
+  output: signalDetailOutput,
+});