@principal-ai/principal-view-core 0.28.1 → 0.28.3

package/src/scopes/ScopePathIndex.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from 'bun:test';
+import { ScopePathIndex } from './ScopePathIndex';
+
+function makeIndex(entries: Array<{ scope: string; paths: string[] }>) {
+  const idx = new ScopePathIndex();
+  idx.addAll(entries);
+  return idx;
+}
+
+describe('ScopePathIndex.resolve', () => {
+  test('empty index resolves to null', () => {
+    const idx = new ScopePathIndex();
+    expect(idx.resolve('packages/core/src/foo.ts')).toBeNull();
+  });
+
+  test('matches file nested under a declared folder path', () => {
+    const idx = makeIndex([{ scope: 'principal-ai.core', paths: ['packages/core/src'] }]);
+    const match = idx.resolve('packages/core/src/events/foo.ts');
+    expect(match?.entry.scope).toBe('principal-ai.core');
+    expect(match?.matchedPath).toBe('packages/core/src');
+  });
+
+  test('returns null when no path covers the file', () => {
+    const idx = makeIndex([{ scope: 'principal-ai.core', paths: ['packages/core/src'] }]);
+    expect(idx.resolve('packages/cli/src/foo.ts')).toBeNull();
+  });
+
+  test('longest-prefix wins: nested child scope beats parent', () => {
+    const idx = makeIndex([
+      { scope: 'principal-ai.core', paths: ['packages/core/src'] },
+      { scope: 'principal-ai.core.validation', paths: ['packages/core/src/validation'] },
+    ]);
+
+    // Parent-only subtree → parent wins
+    expect(idx.resolve('packages/core/src/events/foo.ts')?.entry.scope).toBe('principal-ai.core');
+    // Child subtree → child wins (longer prefix)
+    expect(idx.resolve('packages/core/src/validation/engine.ts')?.entry.scope).toBe(
+      'principal-ai.core.validation',
+    );
+    // Deeper under child → still child (inherited)
+    expect(idx.resolve('packages/core/src/validation/rules/foo.ts')?.entry.scope).toBe(
+      'principal-ai.core.validation',
+    );
+  });
+
+  test('sibling scopes resolve disjointly', () => {
+    const idx = makeIndex([
+      { scope: 'principal-ai.core', paths: ['packages/core/src'] },
+      { scope: 'principal-ai.cli', paths: ['packages/cli/src'] },
+    ]);
+    expect(idx.resolve('packages/core/src/foo.ts')?.entry.scope).toBe('principal-ai.core');
+    expect(idx.resolve('packages/cli/src/foo.ts')?.entry.scope).toBe('principal-ai.cli');
+  });
+
+  test('exact-file path matches when declared as a file', () => {
+    const idx = makeIndex([{ scope: 'tiny', paths: ['packages/tiny/src/index.ts'] }]);
+    expect(idx.resolve('packages/tiny/src/index.ts')?.entry.scope).toBe('tiny');
+    expect(idx.resolve('packages/tiny/src/other.ts')).toBeNull();
+  });
+
+  test('normalization: trailing slash and ./ prefix are equivalent', () => {
+    const idx = makeIndex([{ scope: 's', paths: ['packages/core/src/'] }]);
+    expect(idx.resolve('./packages/core/src/foo.ts')?.entry.scope).toBe('s');
+  });
+
+  test('similar-prefix paths are not mistaken for nesting', () => {
+    const idx = makeIndex([
+      { scope: 'foo', paths: ['packages/foo/src'] },
+      { scope: 'foobar', paths: ['packages/foobar/src'] },
+    ]);
+    expect(idx.resolve('packages/foobar/src/x.ts')?.entry.scope).toBe('foobar');
+    expect(idx.resolve('packages/foo/src/x.ts')?.entry.scope).toBe('foo');
+  });
+});
+
+describe('ScopePathIndex.getEntry / getScopes', () => {
+  test('getEntry returns null when scope not registered', () => {
+    const idx = makeIndex([{ scope: 's', paths: ['packages/core/src'] }]);
+    expect(idx.getEntry('other')).toBeNull();
+  });
+
+  test('getEntry returns the entry when present', () => {
+    const idx = makeIndex([{ scope: 's', paths: ['packages/core/src'] }]);
+    expect(idx.getEntry('s')?.paths).toEqual(['packages/core/src']);
+  });
+
+  test('getScopes lists each scope once', () => {
+    const idx = makeIndex([
+      { scope: 'a', paths: ['packages/a/src'] },
+      { scope: 'b', paths: ['packages/b/src'] },
+    ]);
+    expect(idx.getScopes().slice().sort()).toEqual(['a', 'b']);
+  });
+});

package/src/scopes/ScopePathIndex.ts

@@ -0,0 +1,89 @@
+/**
+ * Scope Path Index
+ *
+ * Maps a filepath to the `otel-scope` that owns it, using the `paths` field
+ * declared on `otel-scope` nodes.
+ *
+ * Resolution uses the longest-prefix partitioning rule: when multiple scopes
+ * have paths covering the same file, the one whose matched path is the most
+ * specific (longest after normalization) wins. This naturally supports nested
+ * scopes by dotted-name (e.g. `principal-ai.core` and
+ * `principal-ai.core.validation`), where the child claims its subtree without
+ * stealing the parent's.
+ *
+ * Pure/browser-safe — no filesystem access, just string comparison.
+ */
+
+import { normalizePath, pathCovers } from '../events/path-helpers';
+
+/**
+ * One declared scope/paths tuple. Multiple entries may share the same scope
+ * if a scope canvas needs to declare more than one region (generated code,
+ * platform splits, migration periods).
+ */
+export interface ScopePathEntry {
+  scope: string;
+  paths: string[];
+  /** Optional — useful for surfacing where a match came from in diagnostics. */
+  sourceCanvasPath?: string;
+}
+
+/**
+ * Result of resolving a file against the index.
+ */
+export interface ScopePathMatch {
+  /** The winning entry (by longest-prefix). */
+  entry: ScopePathEntry;
+  /** Which of the entry's paths covered the file — the one that won. */
+  matchedPath: string;
+}
+
+export class ScopePathIndex {
+  private entries: ScopePathEntry[] = [];
+
+  /** Register a single scope/paths entry. */
+  add(entry: ScopePathEntry): void {
+    this.entries.push(entry);
+  }
+
+  /** Register many entries at once. */
+  addAll(entries: readonly ScopePathEntry[]): void {
+    for (const e of entries) this.add(e);
+  }
+
+  /**
+   * Resolve a filepath to its owning scope.
+   * Returns null if no entry has a path covering the file.
+   */
+  resolve(filepath: string): ScopePathMatch | null {
+    const normalizedFile = normalizePath(filepath);
+    let best: { entry: ScopePathEntry; matchedPath: string; length: number } | null = null;
+
+    for (const entry of this.entries) {
+      for (const declared of entry.paths) {
+        if (!pathCovers(declared, normalizedFile)) continue;
+        const normalizedDeclared = normalizePath(declared);
+        const length = normalizedDeclared.length;
+        if (best === null || length > best.length) {
+          best = { entry, matchedPath: declared, length };
+        }
+      }
+    }
+
+    return best ? { entry: best.entry, matchedPath: best.matchedPath } : null;
+  }
+
+  /**
+   * Look up the entry for a specific scope. Returns null when the scope
+   * isn't registered — either because its scopes-canvas node omits `paths`
+   * (opt-out of enforcement) or because no such scope is declared.
+   */
+  getEntry(scope: string): ScopePathEntry | null {
+    return this.entries.find((e) => e.scope === scope) ?? null;
+  }
+
+  /** All scopes present in the index. */
+  getScopes(): readonly string[] {
+    return Array.from(new Set(this.entries.map((e) => e.scope)));
+  }
+}

package/src/scopes/ScopesCanvasValidator.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { ScopesCanvasValidator } from './ScopesCanvasValidator';
+import type { ExtendedCanvas } from '../types/canvas';
+
+function makeScopeNode(opts: {
+  id: string;
+  scope: string;
+  description?: string;
+  paths?: string[];
+}): any {
+  return {
+    id: opts.id,
+    type: 'otel-scope',
+    description: opts.description ?? `${opts.scope} scope`,
+    ...(opts.paths !== undefined ? { paths: opts.paths } : {}),
+    otel: { scope: opts.scope },
+    x: 0,
+    y: 0,
+    width: 100,
+    height: 50,
+  };
+}
+
+function makeCanvas(nodes: any[]): ExtendedCanvas {
+  return { nodes, edges: [] } as ExtendedCanvas;
+}
+
+function withTempRepo(layout: string[], fn: (root: string) => Promise<void>): Promise<void> {
+  const root = mkdtempSync(join(tmpdir(), 'scope-paths-'));
+  try {
+    for (const rel of layout) {
+      const full = join(root, rel);
+      mkdirSync(full, { recursive: true });
+      writeFileSync(join(full, '.keep'), '');
+    }
+    return fn(root).finally(() => rmSync(root, { recursive: true, force: true }));
+  } catch (e) {
+    rmSync(root, { recursive: true, force: true });
+    throw e;
+  }
+}
+
+describe('ScopesCanvasValidator scope paths', () => {
+  test('no paths declared → no path violations', async () => {
+    const canvas = makeCanvas([makeScopeNode({ id: 's1', scope: 'a.b' })]);
+    const v = new ScopesCanvasValidator();
+    const r = await v.validate({
+      scopesCanvas: canvas,
+      ownedScopes: ['a.b'],
+      basePath: '/tmp',
+    });
+    expect(r.violations.find(x => x.ruleId.startsWith('scopes-paths'))).toBeUndefined();
+  });
+
+  test('scopes-paths-multiple warns when more than one path', async () => {
+    await withTempRepo(['packages/a/src', 'packages/a/generated'], async (root) => {
+      const canvas = makeCanvas([
+        makeScopeNode({
+          id: 's1',
+          scope: 'a',
+          paths: ['packages/a/src', 'packages/a/generated'],
+        }),
+      ]);
+      const v = new ScopesCanvasValidator();
+      const r = await v.validate({ scopesCanvas: canvas, ownedScopes: ['a'], basePath: root });
+      const w = r.violations.find(x => x.ruleId === 'scopes-paths-multiple');
+      expect(w).toBeDefined();
+      expect(w?.severity).toBe('warn');
+    });
+  });
+
+  test('scopes-paths-missing warns when path does not exist', async () => {
+    await withTempRepo(['packages/a/src'], async (root) => {
+      const canvas = makeCanvas([
+        makeScopeNode({ id: 's1', scope: 'a', paths: ['packages/a/missing'] }),
+      ]);
+      const v = new ScopesCanvasValidator();
+      const r = await v.validate({ scopesCanvas: canvas, ownedScopes: ['a'], basePath: root });
+      const w = r.violations.find(x => x.ruleId === 'scopes-paths-missing');
+      expect(w).toBeDefined();
+      expect(w?.severity).toBe('warn');
+    });
+  });
+
+  test('scopes-paths-overlap errors on identical paths across scopes', async () => {
+    await withTempRepo(['packages/shared/src'], async (root) => {
+      const canvas = makeCanvas([
+        makeScopeNode({ id: 's1', scope: 'a', paths: ['packages/shared/src'] }),
+        makeScopeNode({ id: 's2', scope: 'b', paths: ['packages/shared/src'] }),
+      ]);
+      const v = new ScopesCanvasValidator();
+      const r = await v.validate({
+        scopesCanvas: canvas,
+        ownedScopes: ['a', 'b'],
+        basePath: root,
+      });
+      const e = r.violations.find(x => x.ruleId === 'scopes-paths-overlap');
+      expect(e).toBeDefined();
+      expect(e?.severity).toBe('error');
+      expect(r.valid).toBe(false);
+    });
+  });
+
+  test('parent-child path nesting is allowed (no overlap error)', async () => {
+    await withTempRepo(['packages/core/src/validation'], async (root) => {
+      const canvas = makeCanvas([
+        makeScopeNode({ id: 's1', scope: 'principal-ai.core', paths: ['packages/core/src'] }),
+        makeScopeNode({
+          id: 's2',
+          scope: 'principal-ai.core.validation',
+          paths: ['packages/core/src/validation'],
+        }),
+      ]);
+      const v = new ScopesCanvasValidator();
+      const r = await v.validate({
+        scopesCanvas: canvas,
+        ownedScopes: ['principal-ai.core', 'principal-ai.core.validation'],
+        basePath: root,
+      });
+      expect(r.violations.find(x => x.ruleId === 'scopes-paths-overlap')).toBeUndefined();
+    });
+  });
+});

package/src/scopes/ScopesCanvasValidator.ts

@@ -5,8 +5,11 @@
  * all instrumentation scopes declared in library.yaml.
  */
 
+import { existsSync } from 'fs';
+import { resolve } from 'path';
 import type { ExtendedCanvas, ExtendedCanvasNode, OtelScopeNode, isOtelScopeNode } from '../types/canvas';
 import { isOtelScopeNode as checkOtelScopeNode } from '../types/canvas';
+import { pathsOverlap } from '../events/path-helpers';
 
 /**
  * Scopes canvas validation context
@@ -194,6 +197,71 @@ export class ScopesCanvasValidator {
       }
     }
 
+    // Validate scope paths (optional field — enforcement is opt-in per scope).
+    // Collects declared paths across scopes to check for cross-scope overlap.
+    const declaredPaths: Array<{ scope: string; nodeId: string; path: string }> = [];
+    for (const { scope, nodeId, node } of canvasScopes) {
+      const otelScopeNode = node as unknown as OtelScopeNode;
+      const paths = otelScopeNode.paths;
+      if (!paths || paths.length === 0) continue;
+
+      // Warn when a scope declares more than one path — prompt author to
+      // confirm the multi-location is intentional (monorepo bundling,
+      // generated code, platform splits, migration) rather than accidental.
+      if (paths.length > 1) {
+        violations.push({
+          ruleId: 'scopes-paths-multiple',
+          severity: 'warn',
+          file: scopesCanvasPath || '.principal-views/architecture.scopes.canvas',
+          path: `nodes[${nodeId}].paths`,
+          message: `Scope "${scope}" declares ${paths.length} paths`,
+          impact: 'Multiple paths can indicate legitimate cases (monorepo bundling, generated code, platform splits, migration) but often signal that the scope should be split',
+          suggestion: 'Confirm the multi-location is intentional. Otherwise consider splitting the scope or grouping the code under a single parent folder.',
+        });
+      }
+
+      for (const p of paths) {
+        declaredPaths.push({ scope, nodeId, path: p });
+
+        // Warn when a declared path does not exist relative to the repo root.
+        const resolved = resolve(basePath, p);
+        if (!existsSync(resolved)) {
+          violations.push({
+            ruleId: 'scopes-paths-missing',
+            severity: 'warn',
+            file: scopesCanvasPath || '.principal-views/architecture.scopes.canvas',
+            path: `nodes[${nodeId}].paths`,
+            message: `Path "${p}" declared by scope "${scope}" does not exist`,
+            impact: 'Events emitted under this scope cannot be validated against a real code location',
+            suggestion: 'Verify the path exists relative to the repository root, or remove it from the scope declaration.',
+          });
+        }
+      }
+    }
+
+    // Cross-scope overlap check. Parent-child path nesting is a valid partition
+    // (longest-prefix wins at runtime); any other overlap makes scope ownership
+    // of a file ambiguous.
+    for (let i = 0; i < declaredPaths.length; i++) {
+      for (let j = i + 1; j < declaredPaths.length; j++) {
+        const a = declaredPaths[i];
+        const b = declaredPaths[j];
+        if (a.scope === b.scope) continue;
+
+        const relationship = pathsOverlap(a.path, b.path);
+        if (relationship === 'conflict') {
+          violations.push({
+            ruleId: 'scopes-paths-overlap',
+            severity: 'error',
+            file: scopesCanvasPath || '.principal-views/architecture.scopes.canvas',
+            message: `Paths overlap between scopes "${a.scope}" ("${a.path}") and "${b.scope}" ("${b.path}")`,
+            impact: 'A file covered by two scopes makes scope ownership ambiguous',
+            suggestion: 'Separate the paths so they are disjoint, or restructure as parent/child scopes by dotted name (e.g., "principal-ai.core" covering "packages/core/src" and "principal-ai.core.validation" covering "packages/core/src/validation").',
+          });
+        }
+      }
+    }
+
     const errors = violations.filter(v => v.severity === 'error');
 
     return {

package/src/scopes/index.ts

@@ -13,6 +13,18 @@ export {
   type ScopesCanvasViolation,
 } from './ScopesCanvasValidator';
 
+export {
+  ScopePathIndex,
+  type ScopePathEntry,
+  type ScopePathMatch,
+} from './ScopePathIndex';
+
+export {
+  validateScopeNamespaceNesting,
+  type ScopeEventsCanvasPair,
+  type ValidateScopeNamespaceNestingInput,
+} from './validateScopeNamespaceNesting';
+
 export {
   DEFAULT_SCOPE_COLOR,
   DRAFT_NODE_COLOR,

package/src/scopes/validateScopeNamespaceNesting.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, test } from 'bun:test';
+import { validateScopeNamespaceNesting } from './validateScopeNamespaceNesting';
+import type { ExtendedCanvas } from '../types/canvas';
+
+function scopesCanvas(nodes: Array<{ scope: string; paths?: string[] }>): ExtendedCanvas {
+  return {
+    nodes: nodes.map((n, i) => ({
+      id: `s${i}`,
+      type: 'otel-scope',
+      description: `${n.scope} scope`,
+      ...(n.paths !== undefined ? { paths: n.paths } : {}),
+      otel: { scope: n.scope },
+      x: 0, y: 0, width: 100, height: 50,
+    })),
+    edges: [],
+  } as ExtendedCanvas;
+}
+
+function eventsCanvas(namespaces: Array<{ name: string; paths?: string[] }>): ExtendedCanvas {
+  return {
+    nodes: namespaces.map((ns, i) => ({
+      id: `n${i}`,
+      type: 'event-namespace',
+      namespace: {
+        name: ns.name,
+        description: `${ns.name} namespace`,
+        ...(ns.paths !== undefined ? { paths: ns.paths } : {}),
+        events: [],
+      },
+      x: 0, y: 0, width: 100, height: 50,
+    })),
+    edges: [],
+  } as ExtendedCanvas;
+}
+
+describe('validateScopeNamespaceNesting', () => {
+  test('passes when every namespace path is covered by its scope path', () => {
+    const violations = validateScopeNamespaceNesting({
+      scopesCanvas: scopesCanvas([{ scope: 'a', paths: ['packages/core/src'] }]),
+      eventsCanvases: [
+        {
+          scope: 'a',
+          eventsCanvas: eventsCanvas([
+            { name: 'events', paths: ['packages/core/src/events'] },
+            { name: 'workflow', paths: ['packages/core/src/workflow'] },
+          ]),
+        },
+      ],
+    });
+    expect(violations).toHaveLength(0);
+  });
+
+  test('flags namespace paths that escape their scope', () => {
+    const violations = validateScopeNamespaceNesting({
+      scopesCanvas: scopesCanvas([{ scope: 'a', paths: ['packages/core/src'] }]),
+      eventsCanvases: [
+        {
+          scope: 'a',
+          eventsCanvas: eventsCanvas([
+            { name: 'rogue', paths: ['packages/react/src/hooks'] },
+          ]),
+        },
+      ],
+    });
+    expect(violations).toHaveLength(1);
+    expect(violations[0].ruleId).toBe('scopes-namespace-paths-escape');
+    expect(violations[0].severity).toBe('error');
+    expect(violations[0].message).toContain('rogue');
+    expect(violations[0].message).toContain('packages/react/src/hooks');
+  });
+
+  test('namespace path equal to scope path is covered (not an escape)', () => {
+    const violations = validateScopeNamespaceNesting({
+      scopesCanvas: scopesCanvas([{ scope: 'a', paths: ['packages/core/src'] }]),
+      eventsCanvases: [
+        {
+          scope: 'a',
+          eventsCanvas: eventsCanvas([{ name: 'whole', paths: ['packages/core/src'] }]),
+        },
+      ],
+    });
+    expect(violations).toHaveLength(0);
+  });
+
+  test('scope without paths imposes no constraint (opt-out)', () => {
+    const violations = validateScopeNamespaceNesting({
+      scopesCanvas: scopesCanvas([{ scope: 'a' }]),
+      eventsCanvases: [
+        {
+          scope: 'a',
+          eventsCanvas: eventsCanvas([{ name: 'anywhere', paths: ['packages/anywhere/src'] }]),
+        },
+      ],
+    });
+    expect(violations).toHaveLength(0);
+  });
+
+  test('namespaces without paths are skipped (opt-in per namespace)', () => {
+    const violations = validateScopeNamespaceNesting({
+      scopesCanvas: scopesCanvas([{ scope: 'a', paths: ['packages/core/src'] }]),
+      eventsCanvases: [
+        {
+          scope: 'a',
+          eventsCanvas: eventsCanvas([{ name: 'unenforced' }]),
+        },
+      ],
+    });
+    expect(violations).toHaveLength(0);
+  });
+
+  test('multiple scope paths: namespace covered by any one is allowed', () => {
+    const violations = validateScopeNamespaceNesting({
+      scopesCanvas: scopesCanvas([
+        { scope: 'a', paths: ['packages/core/src', 'packages/core/generated'] },
+      ]),
+      eventsCanvases: [
+        {
+          scope: 'a',
+          eventsCanvas: eventsCanvas([
+            { name: 'gen', paths: ['packages/core/generated/events'] },
+          ]),
+        },
+      ],
+    });
+    expect(violations).toHaveLength(0);
+  });
+});

package/src/scopes/validateScopeNamespaceNesting.ts

@@ -0,0 +1,88 @@
+/**
+ * Scope-Namespace Nesting Validator
+ *
+ * Cross-canvas check: every `event-namespace.paths` entry declared in a
+ * scope's events canvas must be covered by that scope's own `paths`.
+ * Surfaces `scopes-namespace-paths-escape` when a namespace claims a region
+ * outside its owning scope.
+ *
+ * Runs alongside the existing scopes-canvas validation but requires both
+ * canvases as input, so it lives outside `ScopesCanvasValidator` (which is
+ * single-canvas).
+ */
+
+import type { ExtendedCanvas } from '../types/canvas';
+import { isOtelScopeNode } from '../types/canvas';
+import { pathCovers } from '../events/path-helpers';
+import type { ScopesCanvasViolation } from './ScopesCanvasValidator';
+
+/**
+ * One events canvas paired with the scope it documents.
+ * The mapping comes from the existing scope → events-canvas filename
+ * convention (see `ScopeEventsValidator`); callers resolve it before
+ * passing it in.
+ */
+export interface ScopeEventsCanvasPair {
+  scope: string;
+  eventsCanvas: ExtendedCanvas;
+  eventsCanvasPath?: string;
+}
+
+export interface ValidateScopeNamespaceNestingInput {
+  scopesCanvas: ExtendedCanvas;
+  scopesCanvasPath?: string;
+  eventsCanvases: readonly ScopeEventsCanvasPair[];
+}
+
+/**
+ * For every namespace.paths entry, verify it is covered by its scope's paths.
+ * Scopes without `paths` impose no constraint (opt-in per scope) and are
+ * skipped. Namespaces without `paths` are also skipped — namespace-level
+ * enforcement remains independently opt-in.
+ */
+export function validateScopeNamespaceNesting(
+  input: ValidateScopeNamespaceNestingInput,
+): ScopesCanvasViolation[] {
+  const { scopesCanvas, scopesCanvasPath, eventsCanvases } = input;
+  const violations: ScopesCanvasViolation[] = [];
+
+  // Build scope → paths map from the scopes canvas.
+  const scopePaths = new Map<string, string[]>();
+  for (const node of scopesCanvas.nodes || []) {
+    if (!isOtelScopeNode(node)) continue;
+    const scope = node.otel?.scope;
+    const paths = node.paths;
+    if (!scope || !paths || paths.length === 0) continue;
+    scopePaths.set(scope, paths);
+  }
+
+  // For each events canvas, walk its event-namespace nodes and check that
+  // every namespace.paths entry sits inside the owning scope's paths.
+  for (const pair of eventsCanvases) {
+    const ownerPaths = scopePaths.get(pair.scope);
+    if (!ownerPaths) continue; // scope opted out — nothing to check
+
+    for (const node of pair.eventsCanvas.nodes || []) {
+      if ((node as any)?.type !== 'event-namespace') continue;
+      const ns = (node as any).namespace;
+      if (!ns?.name || !Array.isArray(ns.paths) || ns.paths.length === 0) continue;
+
+      for (const declared of ns.paths as string[]) {
+        const covered = ownerPaths.some((sp) => pathCovers(sp, declared));
+        if (covered) continue;
+
+        violations.push({
+          ruleId: 'scopes-namespace-paths-escape',
+          severity: 'error',
+          file: scopesCanvasPath || '.principal-views/architecture.scopes.canvas',
+          path: `nodes[scope="${pair.scope}"].paths`,
+          message: `Namespace "${ns.name}" path "${declared}" escapes the bounds of scope "${pair.scope}" (paths: ${ownerPaths.map((p) => `"${p}"`).join(', ')})`,
+          impact: 'A namespace claiming code outside its owning scope breaks the scope→namespace partition; events from that file would be attributed to the wrong scope',
+          suggestion: `Either move the namespace path under one of "${pair.scope}"'s paths, or extend the scope to cover the namespace's region. If the code genuinely belongs to a different scope, declare the namespace in that scope's events canvas instead.`,
+        });
+      }
+    }
+  }
+
+  return violations;
+}

package/src/types/canvas.ts

@@ -1014,6 +1014,21 @@ export interface OtelScopeNode extends OtelNodeBase {
   type: 'otel-scope';
   /** Short description of this instrumentation scope */
   description?: string;
+  /**
+   * Optional source paths that define this scope's code region.
+   * Each entry may be a folder (covers all descendants) or a specific file.
+   * When present, events under this scope may only originate from files
+   * covered by one of these paths, and every `event-namespace` declared in
+   * this scope's events canvas must have its own `paths` nested inside this
+   * region. Scopes without `paths` remain unenforced — enforcement is opt-in
+   * per scope.
+   *
+   * Semantics are "ownership / partition", distinct from `otel.files` on
+   * `otel-event` nodes (which lists specific emission sites). Across scopes,
+   * paths must be disjoint except for strict parent-child nesting by
+   * dotted-scope name (longest-prefix wins).
+   */
+  paths?: string[];
   /** OTEL metadata - scope name is required */
   otel: OtelMetadata & {
     /** Scope name (required - maps to getTracer('scope-name')) */