@principal-ai/subsystems-core 0.42.0 → 0.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/subsystems-core",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "Subsystem model types and agent-session tooling for Principal AI",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/schemas/subsystem-model.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://principal-ai.dev/schemas/subsystem-model.schema.json",
   "title": "Subsystem Model",
-  "description": "Portable subsystem model — the shareable standard. Construct-tagged components (nodes) plus runtime walkthroughs describing one subsystem of a codebase. Ontology: construct = what a node is, framework + stereotype = which framework pattern it plays, role = where it sits, process = where it runs, module = which source file/module the export belongs to. Symbol is the code identity; name is the display label (often derived from symbol). Host-only fields (local path binding, provenance, store ids, verification) are NOT part of this document; they belong on a hydrated envelope around it.",
+  "description": "Portable subsystem model — the shareable standard. Construct-tagged components (nodes) plus runtime trails describing one subsystem of a codebase. Ontology: construct = what a node is, framework + stereotype = which framework pattern it plays, role = where it sits, process = where it runs, module = which source file/module the export belongs to. Symbol is the code identity; name is the display label (often derived from symbol). Host-only fields (local path binding, provenance, store ids, verification) are NOT part of this document; they belong on a hydrated envelope around it.",
   "type": "object",
   "required": [
     "title",
@@ -30,11 +30,11 @@
         "$ref": "#/$defs/component"
       }
     },
-    "walkthroughs": {
+    "trails": {
       "type": "array",
-      "description": "Ordered runtime walkthroughs (one per named behavior). Each step names from/to/mechanism and the concrete file:line where that seam fires.",
+      "description": "Ordered runtime trails (one per named behavior). Each step names from/to/mechanism and the concrete file:line where that seam fires.",
       "items": {
-        "$ref": "#/$defs/walkthrough"
+        "$ref": "#/$defs/trail"
       }
     },
     "createdAtCommits": {
@@ -100,7 +100,7 @@
     },
     "mechanism": {
       "type": "string",
-      "description": "Walkthrough hop mechanism — how `from` relates to `to` at a runtime site. `uses` = general dependency; `feeds` = data-flow into a processor; `produces` = emits an output; `writes`/`reads`/`watches` = retained-state interactions.",
+      "description": "Trail step mechanism — how `from` relates to `to` at a runtime site. `uses` = general dependency; `feeds` = data-flow into a processor; `produces` = emits an output; `writes`/`reads`/`watches` = retained-state interactions.",
       "enum": [
         "calls",
         "uses",
@@ -126,7 +126,7 @@
         "alias": {
           "type": "string",
           "minLength": 1,
-          "description": "Model-local stable alias, unique per model. Referenced by walkthrough `from` / `to`; edges point at the alias, not the location, so a file move or symbol rename leaves edges intact. Code identity (for composed multi-model views) lives on `purl` + `file` + `symbol`, not here."
+          "description": "Model-local stable alias, unique per model. Referenced by trail `from` / `to`; edges point at the alias, not the location, so a file move or symbol rename leaves edges intact. Code identity (for composed multi-model views) lives on `purl` + `file` + `symbol`, not here."
         },
         "name": {
           "type": "string",
@@ -138,7 +138,8 @@
         },
         "file": {
           "type": "string",
-          "description": "Repo-root-relative path of the source location this component lives in. Resolved against the checkout of the repo named by this component's `purl` (via the Alexandria registry). Empty string allowed for pure externals."
+          "pattern": "^(?!.*(^|/)node_modules(/|$)).*$",
+          "description": "Repo-root-relative path of the source location this component lives in. Resolved against the checkout of the repo named by this component's `purl` (via the Alexandria registry). Empty string allowed for pure externals. `node_modules/` is rejected: installed artifacts are not part of the repo — model a third-party dependency as `construct: external` with `purl: pkg:npm/<package>` and no file."
         },
         "purl": {
           "type": "string",
@@ -205,7 +206,7 @@
         }
       }
     },
-    "walkthroughStep": {
+    "trailStep": {
       "type": "object",
       "required": [
         "from",
@@ -234,7 +235,8 @@
         "file": {
           "type": "string",
           "minLength": 1,
-          "description": "Repo-root-relative path where the seam fires for this walkthrough."
+          "pattern": "^(?!.*(^|/)node_modules(/|$)).*$",
+          "description": "Repo-root-relative path where the seam fires for this trail."
         },
         "line": {
           "type": "integer",
@@ -249,16 +251,16 @@
         "symbol": {
           "type": "string",
           "minLength": 1,
-          "description": "Frame name for this hop — the function/method on the stack at the site. Required; the Walkthroughs list shows this instead of a bare mechanism + filename fallback."
+          "description": "Frame name for this step — the function/method on the stack at the site. Required; the Trails list shows this instead of a bare mechanism + filename fallback."
         },
         "annotation": {
           "type": "string",
           "minLength": 1,
-          "description": "Free-text note anchored to this hop's site line. Optional, informative only, never verified against source; viewers surface it in the codeview's annotation column."
+          "description": "Free-text note anchored to this step's site line. Optional, informative only, never verified against source; viewers surface it in the codeview's annotation column."
         }
       }
     },
-    "walkthrough": {
+    "trail": {
       "type": "object",
       "required": [
         "id",
@@ -270,18 +272,18 @@
         "id": {
           "type": "string",
           "minLength": 1,
-          "description": "Stable unique walkthrough id."
+          "description": "Stable unique trail id."
         },
         "title": {
           "type": "string",
           "minLength": 1,
-          "description": "Walkthrough name (e.g. save, load, refresh)."
+          "description": "Trail name (e.g. save, load, refresh)."
         },
         "steps": {
           "type": "array",
-          "description": "Ordered hops; array order is execution order.",
+          "description": "Ordered steps; array order is execution order.",
           "items": {
-            "$ref": "#/$defs/walkthroughStep"
+            "$ref": "#/$defs/trailStep"
           }
         }
       }

package/src/storage/topicStore.test.ts

@@ -91,25 +91,6 @@ describe('CRUD', () => {
     expect(published.repos).toEqual(['pkg:github/acme/web']);
   });
 
-  test('trail membership add/remove/reorder', async () => {
-    const store = makeStore();
-    await store.createTopic({ id: 'topic-m', title: 'M', trailIds: [] });
-    await store.addTrailToTopic('topic-m', 'a');
-    await store.addTrailToTopic('topic-m', 'b');
-    await store.addTrailToTopic('topic-m', 'a'); // dup no-op
-    expect((await store.getTopic('topic-m'))?.trailIds).toEqual(['a', 'b']);
-
-    await store.reorderTopicTrails('topic-m', ['b', 'a']);
-    expect((await store.getTopic('topic-m'))?.trailIds).toEqual(['b', 'a']);
-
-    await expect(
-      store.reorderTopicTrails('topic-m', ['b', 'c']),
-    ).rejects.toThrow(/permutation/);
-
-    await store.removeTrailFromTopic('topic-m', 'b');
-    expect((await store.getTopic('topic-m'))?.trailIds).toEqual(['a']);
-  });
-
   test('delete removes the file and the index entry', async () => {
     const store = makeStore();
     await store.createTopic({ id: 'topic-d', title: 'D', trailIds: [] });

package/src/storage/topicStore.ts

@@ -1,24 +1,23 @@
 /**
  * File-per-topic store under `~/.principal/topics/`.
  *
- * Layout (mirrors the trail store at `~/.principal/trails/`, so topics become
- * locally greppable and an agent can read one directly):
+ * Layout (file-per-entity, so topics become locally greppable and an agent can
+ * read one directly):
  *
  *   ~/.principal/topics/
  *     _index.json          private, rebuildable manifest (entries[])
  *     <id>.json            one pretty-printed DraftTopic per file
  *
- * Topics are the *least* repo-bound artifact (a bundle of trails spanning
- * repos), so — unlike trails, which bucket by repo Purl — they are stored flat
- * by id. No purl, no buckets, no `node:os`/Purl dependency beyond `homedir()`.
+ * Topics are the *least* repo-bound artifact (a bundle spanning many repos), so
+ * they are stored flat by id rather than bucketed by repo Purl. No purl, no
+ * buckets, no `node:os`/Purl dependency beyond `homedir()`.
  *
  * The `_index.json` manifest is store-private and rebuildable: it is rebuilt by
  * scanning the directory whenever it is missing or unparseable. It exists only
  * to make `getTopics()` / `list()` cheap (no per-file read for listing).
  *
- * There is intentionally NO eviction cap. The trail store caps trails per repo
- * (`PER_REPO_CAP`); topics are few, user-curated, and must never be silently
- * dropped, so the cap is deliberately not carried over.
+ * There is intentionally NO eviction cap. Topics are few, user-curated, and must
+ * never be silently dropped.
  *
  * Migration from the legacy single-blob `~/.alexandria/topics.json` is explicit
  * (`migrateFromLegacyBlob`) — it is never run automatically on load; the desktop
@@ -125,8 +124,9 @@ export interface MigrationResult {
 
 /**
  * Fields a caller may set when updating a topic. `id`, `createdAt`, and
- * `trailIds` are not updatable here — use the trail-membership methods for
- * `trailIds`, and `id`/`createdAt` are immutable.
+ * `trailIds` are immutable here — `id`/`createdAt` are set once at creation, and
+ * `trailIds` is foreign-keyed membership owned by the desktop's trail store, so
+ * a topic update here can never rewrite it.
  */
 export type TopicUpdate = Partial<
   Pick<DraftTopic, 'title' | 'description' | 'status' | 'createdBy' | 'assets' | 'repos'>
@@ -241,65 +241,13 @@ export class TopicStore {
     return true;
   }
 
-  // ===== Trail membership =====
-
-  async addTrailToTopic(topicId: string, trailId: string): Promise<DraftTopic> {
-    const idx = await this.getIndex();
-    const topic = await this.requireTopic(idx, topicId);
-    if (topic.trailIds.includes(trailId)) return topic;
-    const next: DraftTopic = {
-      ...topic,
-      trailIds: [...topic.trailIds, trailId],
-      updatedAt: nowIso(),
-    };
-    await this.writeTopic(next, idx);
-    return next;
-  }
-
-  async removeTrailFromTopic(topicId: string, trailId: string): Promise<DraftTopic> {
-    const idx = await this.getIndex();
-    const topic = await this.requireTopic(idx, topicId);
-    if (!topic.trailIds.includes(trailId)) return topic;
-    const next: DraftTopic = {
-      ...topic,
-      trailIds: topic.trailIds.filter((t) => t !== trailId),
-      updatedAt: nowIso(),
-    };
-    await this.writeTopic(next, idx);
-    return next;
-  }
-
-  async reorderTopicTrails(topicId: string, trailIds: string[]): Promise<DraftTopic> {
-    const idx = await this.getIndex();
-    const topic = await this.requireTopic(idx, topicId);
-    const current = new Set(topic.trailIds);
-    const next = new Set(trailIds);
-    if (current.size !== next.size || [...current].some((t) => !next.has(t))) {
-      throw new Error(
-        'reorderTopicTrails expects a permutation of the existing trail list',
-      );
-    }
-    const updated: DraftTopic = {
-      ...topic,
-      trailIds: [...trailIds],
-      updatedAt: nowIso(),
-    };
-    await this.writeTopic(updated, idx);
-    return updated;
-  }
-
-  async getTopicsForTrail(trailId: string): Promise<DraftTopic[]> {
-    const topics = await this.getTopics();
-    return topics.filter((t) => t.trailIds.includes(trailId));
-  }
-
   // ===== Migration =====
 
   /**
    * One-shot migration from the legacy single-blob `~/.alexandria/topics.json`
    * to file-per-topic. Reads the blob's `topics[]`, writes each as
    * `<id>.json`, rebuilds the index, then renames the blob to `<blob>.bak` so
-   * a re-run is a no-op (mirrors the trail store's `migrateLegacyIfPresent`).
+   * a re-run is a no-op.
    *
    * Explicit by design — the desktop calls this from a Settings action, never
    * on load. Idempotent: once the blob is `.bak`'d, subsequent calls report

package/src/types/subsystem-model.ts

@@ -59,10 +59,10 @@ export type SubsystemFramework = string;
 export type SubsystemStereotype = string;
 
 /**
- * Walkthrough hop mechanism — runtime seams with a `file:line` site.
- * Belongs on walkthrough steps; graph edges for these are derived.
+ * Trail step mechanism — runtime seams with a `file:line` site.
+ * Belongs on trail steps; graph edges for these are derived.
  */
-export type SubsystemWalkthroughMechanism =
+export type SubsystemTrailMechanism =
   | 'calls'
   | 'uses'
   | 'feeds'
@@ -74,9 +74,9 @@ export type SubsystemWalkthroughMechanism =
 
 /**
  * Edge mechanism used by derived display edges / styling. Display edges are
- * derived from walkthrough hops, so this is the walkthrough mechanism.
+ * derived from trail steps, so this is the trail mechanism.
  */
-export type SubsystemEdgeMechanism = SubsystemWalkthroughMechanism;
+export type SubsystemEdgeMechanism = SubsystemTrailMechanism;
 
 export type SubsystemDeclarationProvenance = 'verified' | 'authored';
 
@@ -267,7 +267,7 @@ export type SubsystemConstructDeclaration =
 /** A component node — the named unit, construct-tagged. */
 export interface SubsystemComponent {
   /**
-   * Model-local stable alias. Referenced by walkthrough `from` /
+   * Model-local stable alias. Referenced by trail `from` /
    * `to`; unique per model. Edges point at the alias, not the location — a
    * file move or symbol rename leaves edges intact. Code identity lives on
    * `purl` + `file` + `symbol` and is what composed (multi-model) views
@@ -332,8 +332,8 @@ export interface SubsystemComponent {
 }
 
 /**
- * Derived / display graph edge used by renderers. Built from walkthrough
- * hops — not authored as its own document field.
+ * Derived / display graph edge used by renderers. Built from trail
+ * steps — not authored as its own document field.
  */
 export interface SubsystemComponentEdge {
   id: string;
@@ -342,13 +342,13 @@ export interface SubsystemComponentEdge {
   mechanism: SubsystemEdgeMechanism;
 }
 
-export interface SubsystemWalkthroughStep {
+export interface SubsystemTrailStep {
   /** Source component alias. */
   from: string;
   /** Target component alias. */
   to: string;
   /** Runtime seam label (Set B). */
-  mechanism: SubsystemWalkthroughMechanism;
+  mechanism: SubsystemTrailMechanism;
   file: string;
   /** 1-based line within `file`. */
   line: number;
@@ -360,24 +360,24 @@ export interface SubsystemWalkthroughStep {
    */
   purl: string;
   /**
-   * Frame name for this hop — the function/method on the stack at the site.
-   * Required: the Walkthroughs list shows this instead of a bare
+   * Frame name for this step — the function/method on the stack at the site.
+   * Required: the Trails list shows this instead of a bare
    * mechanism + filename fallback.
    */
   symbol: string;
   /**
-   * Free-text note anchored to this hop's site line. Optional — informative
+   * Free-text note anchored to this step's site line. Optional — informative
    * only, never verified against source; viewers surface it via the codeview's
    * annotation column.
    */
   annotation?: string;
 }
 
-/** Ordered runtime walkthrough (one named behavior story). */
-export interface SubsystemWalkthrough {
+/** Ordered runtime trail (one named behavior story). */
+export interface SubsystemTrail {
   id: string;
   title: string;
-  steps: SubsystemWalkthroughStep[];
+  steps: SubsystemTrailStep[];
 }
 
 /**
@@ -402,8 +402,8 @@ export interface SubsystemModelDocument {
   title: string;
   description?: string;
   components: SubsystemComponent[];
-  /** Runtime walkthroughs (ordered hops with sites). */
-  walkthroughs?: SubsystemWalkthrough[];
+  /** Runtime trails (ordered steps with sites). */
+  trails?: SubsystemTrail[];
   /**
    * The commit each referenced repo was at when the model was created. The
    * coordinate system for every `file:line` in the document: without it, a
@@ -460,13 +460,13 @@ export function toPortableDocument(
   };
   if (doc.$schema) out.$schema = doc.$schema;
   if (doc.description) out.description = doc.description;
-  if (doc.walkthroughs) out.walkthroughs = doc.walkthroughs;
+  if (doc.trails) out.trails = doc.trails;
   if (doc.createdAtCommits) out.createdAtCommits = doc.createdAtCommits;
   if (doc.verifiedAtCommits) out.verifiedAtCommits = doc.verifiedAtCommits;
   return out;
 }
 
-/** Stable id for a derived graph edge from a walkthrough hop. */
+/** Stable id for a derived graph edge from a trail step. */
 export function derivedGraphEdgeId(
   from: string,
   to: string,
@@ -476,14 +476,14 @@ export function derivedGraphEdgeId(
 }
 
 /**
- * Build display edges for the graph canvas from walkthrough hops
+ * Build display edges for the graph canvas from trail steps
  * (deduped by from/to/mechanism).
  */
 export function deriveGraphEdges(doc: {
-  walkthroughs?: SubsystemWalkthrough[];
+  trails?: SubsystemTrail[];
 }): SubsystemComponentEdge[] {
   const byId = new Map<string, SubsystemComponentEdge>();
-  for (const w of doc.walkthroughs ?? []) {
+  for (const w of doc.trails ?? []) {
     for (const step of w.steps) {
       const id = derivedGraphEdgeId(step.from, step.to, step.mechanism);
       if (!byId.has(id)) {

package/src/validation.test.ts

@@ -28,7 +28,7 @@ describe('validateSubsystemModelCrossField', () => {
   test('accepts a consistent document', () => {
     const d = doc({
       components: [comp('a'), comp('b')],
-      walkthroughs: [
+      trails: [
         {
           id: 'w1',
           title: 'flow',
@@ -47,11 +47,11 @@ describe('validateSubsystemModelCrossField', () => {
     expect(problems[0]!.message).toContain('duplicate alias');
   });
 
-  test('flags walkthrough step endpoints that reference no component', () => {
+  test('flags trail step endpoints that reference no component', () => {
     const problems = validateSubsystemModelCrossField(
       doc({
         components: [comp('a')],
-        walkthroughs: [
+        trails: [
           {
             id: 'w1',
             title: 'flow',
@@ -61,14 +61,14 @@ describe('validateSubsystemModelCrossField', () => {
       }),
     );
     expect(problems).toHaveLength(1);
-    expect(problems[0]!.path).toBe('/walkthroughs/0/steps/0/from');
+    expect(problems[0]!.path).toBe('/trails/0/steps/0/from');
   });
 
-  test('flags walkthrough step purl fragments that mismatch the step file', () => {
+  test('flags trail step purl fragments that mismatch the step file', () => {
     const problems = validateSubsystemModelCrossField(
       doc({
         components: [comp('a')],
-        walkthroughs: [
+        trails: [
           {
             id: 'w1',
             title: 'flow',
@@ -78,7 +78,7 @@ describe('validateSubsystemModelCrossField', () => {
       }),
     );
     expect(problems).toHaveLength(1);
-    expect(problems[0]!.path).toBe('/walkthroughs/0/steps/0/purl');
+    expect(problems[0]!.path).toBe('/trails/0/steps/0/purl');
   });
 
   test('module implies file, exempting external/proposed', () => {
@@ -100,4 +100,77 @@ describe('validateSubsystemModelCrossField', () => {
       ),
     ).toEqual([]);
   });
+
+  test('flags a component file pointing into node_modules', () => {
+    const problems = validateSubsystemModelCrossField(
+      doc({
+        components: [
+          comp('dep', {
+            construct: 'store',
+            file: 'packages/react/node_modules/@pierre/diffs/dist/highlighter/shared_highlighter.js',
+          }),
+          comp('bare', { file: 'node_modules/left-pad/index.js' }),
+          // An external may carry such a path too — the path is the defect
+          // whichever construct claims it.
+          comp('ext', {
+            construct: 'external',
+            file: 'packages/react/node_modules/@pierre/diffs/dist/components/CodeView.js',
+          }),
+        ],
+      }),
+    );
+    expect(problems).toHaveLength(3);
+    expect(problems[0]!.path).toBe('/components/0/file');
+    expect(problems[0]!.message).toContain('node_modules');
+    expect(problems[1]!.path).toBe('/components/1/file');
+    expect(problems[2]!.path).toBe('/components/2/file');
+  });
+
+  test('accepts node_modules only as an external/proposed component identity', () => {
+    expect(
+      validateSubsystemModelCrossField(
+        doc({
+          components: [
+            // A dependency modeled as a package: no file, npm purl.
+            comp('dep', {
+              construct: 'external',
+              file: '',
+              purl: 'pkg:npm/@pierre/diffs',
+            }),
+            // A planned in-repo component may sit where it will live.
+            comp('plan', { file: 'packages/x/node_modules/y/z.ts', proposed: true }),
+            // `node_modulesx` is an ordinary directory, not the install root.
+            comp('ok', { file: 'packages/node_modulesx/z.ts' }),
+          ],
+        }),
+      ),
+    ).toEqual([]);
+  });
+
+  test('flags a trail step anchored in node_modules', () => {
+    const problems = validateSubsystemModelCrossField(
+      doc({
+        components: [comp('a')],
+        trails: [
+          {
+            id: 'w1',
+            title: 'flow',
+            steps: [
+              {
+                from: 'a',
+                to: 'a',
+                mechanism: 'calls',
+                file: 'packages/react/node_modules/@pierre/diffs/dist/index.js',
+                line: 1,
+                purl: 'pkg:npm/@pierre/diffs#packages/react/node_modules/@pierre/diffs/dist/index.js',
+                symbol: 'a',
+              },
+            ],
+          },
+        ],
+      }),
+    );
+    expect(problems).toHaveLength(1);
+    expect(problems[0]!.path).toBe('/trails/0/steps/0/file');
+  });
 });

package/src/validation.ts

@@ -3,7 +3,7 @@
  *
  * These are the rules the JSON Schema (`schemas/subsystem-model.schema.json`)
  * cannot express — anything that spans fields or arrays: alias uniqueness,
- * referential integrity between walkthroughs and components, and the
+ * referential integrity between trails and components, and the
  * `module` implies `file` invariant. Structural checks (types, `required`,
  * enums, ranges, closed objects) belong to the schema and are enforced per
  * surface; this module owns only what the schema can't.
@@ -14,11 +14,11 @@
 import type {
   SubsystemModelDocument,
   SubsystemComponent,
-  SubsystemWalkthrough,
+  SubsystemTrail,
 } from './types/subsystem-model';
 
 export interface SubsystemValidationProblem {
-  /** JSON-pointer-ish location, e.g. `/components/2` or `/walkthroughs/0/steps/0/from`. */
+  /** JSON-pointer-ish location, e.g. `/components/2` or `/trails/0/steps/0/from`. */
   path: string;
   message: string;
 }
@@ -27,6 +27,25 @@ function isUngrounded(c: SubsystemComponent): boolean {
   return c.construct === 'external' || c.proposed === true;
 }
 
+/**
+ * `file` is a path *inside the repo named by `purl`* — it resolves against that
+ * checkout, never against an installed artifact. `node_modules/` is installed,
+ * gitignored, and its layout depends on hoisting, so a claim anchored there can
+ * never resolve and is unverifiable by construction.
+ *
+ * Such a component is a third-party dependency: model it as `construct:
+ * 'external'` with `purl: 'pkg:npm/<package>'` and no file. Applies to externals
+ * too — they carry no file by design, so an install path there is dead weight
+ * that draws a link nothing can open. `proposed` is exempt like every other
+ * grounding rule: its file is a placeholder for something not placed yet.
+ *
+ * The same rule covers trail step files — a seam into an external belongs
+ * at the call site in the caller, which *is* in the repo.
+ */
+function mentionsNodeModules(path: string): boolean {
+  return /(^|\/)node_modules(\/|$)/.test(path);
+}
+
 /**
  * Validate the cross-field rules of a subsystem model document. Returns an
  * empty array when the document is consistent.
@@ -36,10 +55,10 @@ export function validateSubsystemModelCrossField(
 ): SubsystemValidationProblem[] {
   const problems: SubsystemValidationProblem[] = [];
   const components = doc.components ?? [];
-  const walkthroughs = doc.walkthroughs ?? [];
+  const trails = doc.trails ?? [];
 
   // Component aliases must be unique, and the set is the referential target
-  // for walkthrough steps.
+  // for trail steps.
   const ids = new Set<string>();
   components.forEach((c, i) => {
     if (ids.has(c.alias)) {
@@ -60,20 +79,26 @@ export function validateSubsystemModelCrossField(
         message: `component ${JSON.stringify(c.alias)}: module ${JSON.stringify(module)} is set but file is empty — a module frame needs a file to ground it (mark the component proposed if it is not placed yet).`,
       });
     }
+    if (file && c.proposed !== true && mentionsNodeModules(file)) {
+      problems.push({
+        path: `/components/${i}/file`,
+        message: `component ${JSON.stringify(c.alias)}: file ${JSON.stringify(file)} points into node_modules — installed artifacts are not part of the repo and cannot be verified. Model the dependency as construct "external" with purl "pkg:npm/<package>" and no file, or anchor the claim to the package's real source.`,
+      });
+    }
   });
 
-  walkthroughs.forEach((w: SubsystemWalkthrough, wi) => {
+  trails.forEach((w: SubsystemTrail, ti) => {
     (w.steps ?? []).forEach((step, si) => {
       if (!ids.has(step.from)) {
         problems.push({
-          path: `/walkthroughs/${wi}/steps/${si}/from`,
-          message: `walkthrough ${JSON.stringify(w.id)}: step ${si} from ${JSON.stringify(step.from)} does not match any component alias`,
+          path: `/trails/${ti}/steps/${si}/from`,
+          message: `trail ${JSON.stringify(w.id)}: step ${si} from ${JSON.stringify(step.from)} does not match any component alias`,
         });
       }
       if (!ids.has(step.to)) {
         problems.push({
-          path: `/walkthroughs/${wi}/steps/${si}/to`,
-          message: `walkthrough ${JSON.stringify(w.id)}: step ${si} to ${JSON.stringify(step.to)} does not match any component alias`,
+          path: `/trails/${ti}/steps/${si}/to`,
+          message: `trail ${JSON.stringify(w.id)}: step ${si} to ${JSON.stringify(step.to)} does not match any component alias`,
         });
       }
       // A file-anchored step purl names its own site: the fragment must be
@@ -83,11 +108,17 @@ export function validateSubsystemModelCrossField(
         const fragment = step.purl.split('#').slice(1).join('#');
         if (fragment !== step.file) {
           problems.push({
-            path: `/walkthroughs/${wi}/steps/${si}/purl`,
-            message: `walkthrough ${JSON.stringify(w.id)}: step ${si} purl fragment ${JSON.stringify(fragment)} does not match step file ${JSON.stringify(step.file)}`,
+            path: `/trails/${ti}/steps/${si}/purl`,
+            message: `trail ${JSON.stringify(w.id)}: step ${si} purl fragment ${JSON.stringify(fragment)} does not match step file ${JSON.stringify(step.file)}`,
           });
         }
       }
+      if (mentionsNodeModules(step.file)) {
+        problems.push({
+          path: `/trails/${ti}/steps/${si}/file`,
+          message: `trail ${JSON.stringify(w.id)}: step ${si} file ${JSON.stringify(step.file)} points into node_modules — anchor the seam at the call site inside the repo instead.`,
+        });
+      }
     });
   });