@principal-ai/subsystems-core 0.29.0

package/dist/scopes/ScopesCanvasValidator.js

@@ -0,0 +1,221 @@
+"use strict";
+/**
+ * Scopes Canvas Validator
+ *
+ * Validates that a .scopes.canvas file exists and properly documents
+ * all instrumentation scopes declared in library.yaml.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopesCanvasValidator = void 0;
+const canvas_1 = require("../types/canvas");
+const path_helpers_1 = require("../events/path-helpers");
+/**
+ * Validates scopes canvas files
+ */
+class ScopesCanvasValidator {
+    constructor(fsAdapter) {
+        this.fsAdapter = fsAdapter;
+    }
+    /**
+     * Validate a scopes canvas against library.yaml owned-scopes
+     */
+    async validate(context) {
+        const violations = [];
+        const { scopesCanvas, scopesCanvasPath, ownedScopes, basePath } = context;
+        // Initialize coverage tracking
+        const documentedScopes = [];
+        const missingScopes = [];
+        const extraScopes = [];
+        // Check if scopes canvas exists when owned-scopes are defined
+        if (ownedScopes.length > 0 && !scopesCanvas) {
+            violations.push({
+                ruleId: 'scopes-canvas-required',
+                severity: 'error',
+                file: scopesCanvasPath || '.principal-views/architecture.scopes.canvas',
+                message: 'Scopes canvas is required when library.yaml defines owned-scopes',
+                impact: 'Cannot visualize or validate instrumentation scope boundaries',
+                suggestion: `Create a scopes canvas at .principal-views/architecture.scopes.canvas with nodes for each scope:\n` +
+                    ownedScopes.map(s => `  - ${s}`).join('\n') +
+                    '\n\nUse type: "otel-scope" with otel.scope set to the scope name.',
+            });
+            return {
+                valid: false,
+                violations,
+                coverage: {
+                    totalOwnedScopes: ownedScopes.length,
+                    documentedScopes: [],
+                    missingScopes: [...ownedScopes],
+                    extraScopes: [],
+                },
+            };
+        }
+        // If no owned scopes and no canvas, that's fine
+        if (ownedScopes.length === 0) {
+            return {
+                valid: true,
+                violations,
+                coverage: {
+                    totalOwnedScopes: 0,
+                    documentedScopes: [],
+                    missingScopes: [],
+                    extraScopes: [],
+                },
+            };
+        }
+        // Extract scopes from canvas nodes
+        const canvasScopes = this.extractScopesFromCanvas(scopesCanvas);
+        const canvasScopeSet = new Set(canvasScopes.map(s => s.scope));
+        const ownedScopeSet = new Set(ownedScopes);
+        // Check which scopes are documented
+        for (const scope of ownedScopes) {
+            if (canvasScopeSet.has(scope)) {
+                documentedScopes.push(scope);
+            }
+            else {
+                missingScopes.push(scope);
+            }
+        }
+        // Check for extra scopes not in owned-scopes
+        for (const { scope, nodeId } of canvasScopes) {
+            if (!ownedScopeSet.has(scope)) {
+                extraScopes.push(scope);
+            }
+        }
+        // Report missing scopes
+        if (missingScopes.length > 0) {
+            violations.push({
+                ruleId: 'scopes-canvas-incomplete',
+                severity: 'error',
+                file: scopesCanvasPath || '.principal-views/architecture.scopes.canvas',
+                message: `Scopes canvas is missing ${missingScopes.length} scope(s) from library.yaml`,
+                impact: 'These scopes are not documented in the scope boundary map',
+                suggestion: `Add nodes for the following scopes:\n` +
+                    missingScopes.map(s => `  - ${s}: Add type: "otel-scope" node with otel.scope: "${s}"`).join('\n'),
+            });
+        }
+        // Report extra scopes (warning, not error)
+        if (extraScopes.length > 0) {
+            violations.push({
+                ruleId: 'scopes-canvas-extra-scopes',
+                severity: 'warn',
+                file: scopesCanvasPath || '.principal-views/architecture.scopes.canvas',
+                message: `Scopes canvas contains ${extraScopes.length} scope(s) not in library.yaml owned-scopes`,
+                impact: 'These scopes may be external or need to be added to library.yaml',
+                suggestion: `Either:\n` +
+                    `  - Add these scopes to owned-scopes in library.yaml: ${extraScopes.join(', ')}\n` +
+                    `  - Or remove them from the scopes canvas if they are external`,
+            });
+        }
+        // Validate scope nodes have required fields (otel-scope nodes only)
+        for (const { scope, nodeId, node } of canvasScopes) {
+            // type === 'otel-scope' with top-level description
+            const otelScopeNode = node;
+            if (!otelScopeNode.description) {
+                violations.push({
+                    ruleId: 'scopes-canvas-node-description',
+                    severity: 'warn',
+                    file: scopesCanvasPath || '.principal-views/architecture.scopes.canvas',
+                    path: `nodes[${nodeId}]`,
+                    message: `Scope node "${scope}" is missing a description`,
+                    impact: 'Scope documentation is incomplete without a description',
+                    suggestion: `Add a description field to explain what this scope covers`,
+                });
+            }
+        }
+        // Validate scope paths (optional field — enforcement is opt-in per scope).
+        // Collects declared paths across scopes to check for cross-scope overlap.
+        const declaredPaths = [];
+        for (const { scope, nodeId, node } of canvasScopes) {
+            const otelScopeNode = node;
+            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 = this.fsAdapter.join(basePath, p);
+                if (!(await this.fsAdapter.exists(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 = (0, path_helpers_1.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/subsystems-core/src" and "principal-ai.core.validation" covering "packages/subsystems-core/src/validation").',
+                    });
+                }
+            }
+        }
+        const errors = violations.filter(v => v.severity === 'error');
+        return {
+            valid: errors.length === 0,
+            violations,
+            coverage: {
+                totalOwnedScopes: ownedScopes.length,
+                documentedScopes,
+                missingScopes,
+                extraScopes,
+            },
+        };
+    }
+    /**
+     * Extract scope information from canvas nodes (otel-scope nodes only)
+     */
+    extractScopesFromCanvas(canvas) {
+        const scopes = [];
+        for (const node of canvas.nodes || []) {
+            // Only process otel-scope nodes
+            if ((0, canvas_1.isOtelScopeNode)(node)) {
+                const scope = node.otel?.scope;
+                if (scope && typeof scope === 'string') {
+                    scopes.push({
+                        scope,
+                        nodeId: node.id,
+                        node: node,
+                    });
+                }
+            }
+            // Legacy pv.otel.scope format is no longer supported
+        }
+        return scopes;
+    }
+}
+exports.ScopesCanvasValidator = ScopesCanvasValidator;
+//# sourceMappingURL=ScopesCanvasValidator.js.map

package/dist/scopes/ScopesCanvasValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScopesCanvasValidator.js","sourceRoot":"","sources":["../../src/scopes/ScopesCanvasValidator.ts"],"names":[],"mappings":"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"}

package/dist/scopes/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Scopes module
+ *
+ * Provides utilities and validation for instrumentation scopes:
+ * - Scope utilities for working with top-level scopes and owned-scopes references
+ * - Validation for .scopes.canvas files that document scope boundaries
+ */
+export { ScopesCanvasValidator, type ScopesCanvasValidationContext, type ScopesCanvasValidationResult, 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, getScopeNames, getScopeDefinition, getScopeColor, getScopeIcon, normalizeScopes, buildScopeColorMap, buildScopeColorMapFromCanvas, getScopeNamesFromCanvas, getScopeNodeFromCanvas, getAllScopeNames, type NormalizedScope, } from './utils';
+//# sourceMappingURL=index.d.ts.map

package/dist/scopes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scopes/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,qBAAqB,EACrB,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EACjC,KAAK,qBAAqB,GAC3B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,6BAA6B,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,kCAAkC,GACxC,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,4BAA4B,EAC5B,uBAAuB,EACvB,sBAAsB,EACtB,gBAAgB,EAChB,KAAK,eAAe,GACrB,MAAM,SAAS,CAAC"}

package/dist/scopes/index.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Scopes module
+ *
+ * Provides utilities and validation for instrumentation scopes:
+ * - Scope utilities for working with top-level scopes and owned-scopes references
+ * - Validation for .scopes.canvas files that document scope boundaries
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAllScopeNames = exports.getScopeNodeFromCanvas = exports.getScopeNamesFromCanvas = exports.buildScopeColorMapFromCanvas = exports.buildScopeColorMap = exports.normalizeScopes = exports.getScopeIcon = exports.getScopeColor = exports.getScopeDefinition = exports.getScopeNames = exports.DRAFT_NODE_COLOR = exports.DEFAULT_SCOPE_COLOR = exports.validateScopeNamespaceNesting = exports.ScopePathIndex = exports.ScopesCanvasValidator = void 0;
+var ScopesCanvasValidator_1 = require("./ScopesCanvasValidator");
+Object.defineProperty(exports, "ScopesCanvasValidator", { enumerable: true, get: function () { return ScopesCanvasValidator_1.ScopesCanvasValidator; } });
+var ScopePathIndex_1 = require("./ScopePathIndex");
+Object.defineProperty(exports, "ScopePathIndex", { enumerable: true, get: function () { return ScopePathIndex_1.ScopePathIndex; } });
+var validateScopeNamespaceNesting_1 = require("./validateScopeNamespaceNesting");
+Object.defineProperty(exports, "validateScopeNamespaceNesting", { enumerable: true, get: function () { return validateScopeNamespaceNesting_1.validateScopeNamespaceNesting; } });
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "DEFAULT_SCOPE_COLOR", { enumerable: true, get: function () { return utils_1.DEFAULT_SCOPE_COLOR; } });
+Object.defineProperty(exports, "DRAFT_NODE_COLOR", { enumerable: true, get: function () { return utils_1.DRAFT_NODE_COLOR; } });
+Object.defineProperty(exports, "getScopeNames", { enumerable: true, get: function () { return utils_1.getScopeNames; } });
+Object.defineProperty(exports, "getScopeDefinition", { enumerable: true, get: function () { return utils_1.getScopeDefinition; } });
+Object.defineProperty(exports, "getScopeColor", { enumerable: true, get: function () { return utils_1.getScopeColor; } });
+Object.defineProperty(exports, "getScopeIcon", { enumerable: true, get: function () { return utils_1.getScopeIcon; } });
+Object.defineProperty(exports, "normalizeScopes", { enumerable: true, get: function () { return utils_1.normalizeScopes; } });
+Object.defineProperty(exports, "buildScopeColorMap", { enumerable: true, get: function () { return utils_1.buildScopeColorMap; } });
+Object.defineProperty(exports, "buildScopeColorMapFromCanvas", { enumerable: true, get: function () { return utils_1.buildScopeColorMapFromCanvas; } });
+Object.defineProperty(exports, "getScopeNamesFromCanvas", { enumerable: true, get: function () { return utils_1.getScopeNamesFromCanvas; } });
+Object.defineProperty(exports, "getScopeNodeFromCanvas", { enumerable: true, get: function () { return utils_1.getScopeNodeFromCanvas; } });
+Object.defineProperty(exports, "getAllScopeNames", { enumerable: true, get: function () { return utils_1.getAllScopeNames; } });
+//# sourceMappingURL=index.js.map

package/dist/scopes/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scopes/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEH,iEAKiC;AAJ/B,8HAAA,qBAAqB,OAAA;AAMvB,mDAI0B;AAHxB,gHAAA,cAAc,OAAA;AAKhB,iFAIyC;AAHvC,8IAAA,6BAA6B,OAAA;AAK/B,iCAciB;AAbf,4GAAA,mBAAmB,OAAA;AACnB,yGAAA,gBAAgB,OAAA;AAChB,sGAAA,aAAa,OAAA;AACb,2GAAA,kBAAkB,OAAA;AAClB,sGAAA,aAAa,OAAA;AACb,qGAAA,YAAY,OAAA;AACZ,wGAAA,eAAe,OAAA;AACf,2GAAA,kBAAkB,OAAA;AAClB,qHAAA,4BAA4B,OAAA;AAC5B,gHAAA,uBAAuB,OAAA;AACvB,+GAAA,sBAAsB,OAAA;AACtB,yGAAA,gBAAgB,OAAA"}

package/dist/scopes/utils.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Scope utility functions
+ *
+ * Helpers for working with scopes defined in the top-level `scopes` section
+ * and referenced by resources via `owned-scopes`.
+ */
+import type { OwnedScopes, ScopeDefinition } from '../types/library';
+import type { ExtendedCanvas, OtelScopeNode } from '../types/canvas';
+/** Default color for scopes without a defined color */
+export declare const DEFAULT_SCOPE_COLOR = "#6B7280";
+/** Default color for draft nodes (no scope) */
+export declare const DRAFT_NODE_COLOR = "#9CA3AF";
+/**
+ * Normalized scope entry with name and definition
+ */
+export interface NormalizedScope {
+    name: string;
+    color: string;
+    /** Icon identifier (Lucide icons) */
+    icon?: string;
+    description?: string;
+    /** Whether this scope is defined externally (in another library) */
+    external?: boolean;
+}
+/**
+ * Get all scope names from owned-scopes array
+ */
+export declare function getScopeNames(scopes: OwnedScopes | undefined): string[];
+/**
+ * Get scope definition by name from library scopes
+ */
+export declare function getScopeDefinition(libraryScopes: Record<string, ScopeDefinition> | undefined, scopeName: string): ScopeDefinition | undefined;
+/**
+ * Get scope color by name from library scopes
+ * Returns the defined color, or default color if not found
+ */
+export declare function getScopeColor(libraryScopes: Record<string, ScopeDefinition> | undefined, scopeName: string): string;
+/**
+ * Normalize scope names to NormalizedScope array using library scope definitions
+ */
+export declare function normalizeScopes(scopeNames: OwnedScopes | undefined, libraryScopes: Record<string, ScopeDefinition> | undefined): NormalizedScope[];
+/**
+ * Get scope icon by name from library scopes
+ * Returns the defined icon, or undefined if not found
+ */
+export declare function getScopeIcon(libraryScopes: Record<string, ScopeDefinition> | undefined, scopeName: string): string | undefined;
+/**
+ * Build a scope color map from .scopes.canvas
+ * Returns a simple name -> color mapping for fast lookups
+ *
+ * @deprecated The library.scopes parameter has been removed. Use scopesCanvas instead.
+ * @param scopesCanvas - Canvas containing scope definitions with colors
+ * @returns Map of scope name to color (hex format)
+ */
+export declare function buildScopeColorMap(scopesCanvas: ExtendedCanvas | undefined): Record<string, string>;
+/**
+ * Get all scope names defined in library
+ */
+export declare function getAllScopeNames(library: {
+    scopes?: Record<string, ScopeDefinition>;
+} | undefined): string[];
+/**
+ * Build scope color map from .scopes.canvas nodes
+ * Extracts color from otel-scope nodes only
+ *
+ * @param scopesCanvas - Canvas containing scope definitions
+ * @returns Map of scope name to color (hex format)
+ */
+export declare function buildScopeColorMapFromCanvas(scopesCanvas: ExtendedCanvas | undefined): Record<string, string>;
+/**
+ * Extract all scope names from a scopes canvas
+ *
+ * @param scopesCanvas - Canvas containing scope definitions
+ * @returns Array of scope names
+ */
+export declare function getScopeNamesFromCanvas(scopesCanvas: ExtendedCanvas | undefined): string[];
+/**
+ * Get scope node by scope name
+ *
+ * @param scopesCanvas - Canvas containing scope definitions
+ * @param scopeName - Name of the scope to find
+ * @returns The scope node, or undefined if not found
+ */
+export declare function getScopeNodeFromCanvas(scopesCanvas: ExtendedCanvas | undefined, scopeName: string): OtelScopeNode | undefined;
+//# sourceMappingURL=utils.d.ts.map

package/dist/scopes/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/scopes/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrE,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAE7C,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,EAAE,CAEvE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,SAAS,EAC1D,SAAS,EAAE,MAAM,GAChB,eAAe,GAAG,SAAS,CAE7B;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,SAAS,EAC1D,SAAS,EAAE,MAAM,GAChB,MAAM,CAER;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,WAAW,GAAG,SAAS,EACnC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,SAAS,GACzD,eAAe,EAAE,CAanB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,SAAS,EAC1D,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAEpB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,cAAc,GAAG,SAAS,GACvC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAExB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;CAAE,GAAG,SAAS,GAChE,MAAM,EAAE,CAGV;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,YAAY,EAAE,cAAc,GAAG,SAAS,GACvC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAuBxB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,cAAc,GAAG,SAAS,GACvC,MAAM,EAAE,CAOV;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,cAAc,GAAG,SAAS,EACxC,SAAS,EAAE,MAAM,GAChB,aAAa,GAAG,SAAS,CAM3B"}

package/dist/scopes/utils.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * Scope utility functions
+ *
+ * Helpers for working with scopes defined in the top-level `scopes` section
+ * and referenced by resources via `owned-scopes`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getScopeNodeFromCanvas = exports.getScopeNamesFromCanvas = exports.buildScopeColorMapFromCanvas = exports.getAllScopeNames = exports.buildScopeColorMap = exports.getScopeIcon = exports.normalizeScopes = exports.getScopeColor = exports.getScopeDefinition = exports.getScopeNames = exports.DRAFT_NODE_COLOR = exports.DEFAULT_SCOPE_COLOR = void 0;
+const canvas_1 = require("../types/canvas");
+/** Default color for scopes without a defined color */
+exports.DEFAULT_SCOPE_COLOR = '#6B7280'; // gray-500
+/** Default color for draft nodes (no scope) */
+exports.DRAFT_NODE_COLOR = '#9CA3AF'; // gray-400
+/**
+ * Get all scope names from owned-scopes array
+ */
+function getScopeNames(scopes) {
+    return scopes ?? [];
+}
+exports.getScopeNames = getScopeNames;
+/**
+ * Get scope definition by name from library scopes
+ */
+function getScopeDefinition(libraryScopes, scopeName) {
+    return libraryScopes?.[scopeName];
+}
+exports.getScopeDefinition = getScopeDefinition;
+/**
+ * Get scope color by name from library scopes
+ * Returns the defined color, or default color if not found
+ */
+function getScopeColor(libraryScopes, scopeName) {
+    return libraryScopes?.[scopeName]?.color ?? exports.DEFAULT_SCOPE_COLOR;
+}
+exports.getScopeColor = getScopeColor;
+/**
+ * Normalize scope names to NormalizedScope array using library scope definitions
+ */
+function normalizeScopes(scopeNames, libraryScopes) {
+    if (!scopeNames)
+        return [];
+    return scopeNames.map((name) => {
+        const definition = libraryScopes?.[name];
+        return {
+            name,
+            color: definition?.color ?? exports.DEFAULT_SCOPE_COLOR,
+            icon: definition?.icon,
+            description: definition?.description,
+            external: definition?.external,
+        };
+    });
+}
+exports.normalizeScopes = normalizeScopes;
+/**
+ * Get scope icon by name from library scopes
+ * Returns the defined icon, or undefined if not found
+ */
+function getScopeIcon(libraryScopes, scopeName) {
+    return libraryScopes?.[scopeName]?.icon;
+}
+exports.getScopeIcon = getScopeIcon;
+/**
+ * Build a scope color map from .scopes.canvas
+ * Returns a simple name -> color mapping for fast lookups
+ *
+ * @deprecated The library.scopes parameter has been removed. Use scopesCanvas instead.
+ * @param scopesCanvas - Canvas containing scope definitions with colors
+ * @returns Map of scope name to color (hex format)
+ */
+function buildScopeColorMap(scopesCanvas) {
+    return buildScopeColorMapFromCanvas(scopesCanvas);
+}
+exports.buildScopeColorMap = buildScopeColorMap;
+/**
+ * Get all scope names defined in library
+ */
+function getAllScopeNames(library) {
+    if (!library?.scopes)
+        return [];
+    return Object.keys(library.scopes);
+}
+exports.getAllScopeNames = getAllScopeNames;
+/**
+ * Build scope color map from .scopes.canvas nodes
+ * Extracts color from otel-scope nodes only
+ *
+ * @param scopesCanvas - Canvas containing scope definitions
+ * @returns Map of scope name to color (hex format)
+ */
+function buildScopeColorMapFromCanvas(scopesCanvas) {
+    const colorMap = {};
+    if (!scopesCanvas?.nodes)
+        return colorMap;
+    for (const node of scopesCanvas.nodes) {
+        // Only process otel-scope nodes
+        if (!(0, canvas_1.isOtelScopeNode)(node))
+            continue;
+        const scopeName = node.otel?.scope;
+        if (!scopeName)
+            continue;
+        // Get color from node.color field and resolve presets to hex
+        const resolvedColor = (0, canvas_1.resolveCanvasColor)(node.color);
+        if (resolvedColor) {
+            colorMap[scopeName] = resolvedColor;
+        }
+        else {
+            // Use default color if no color specified
+            colorMap[scopeName] = exports.DEFAULT_SCOPE_COLOR;
+        }
+    }
+    return colorMap;
+}
+exports.buildScopeColorMapFromCanvas = buildScopeColorMapFromCanvas;
+/**
+ * Extract all scope names from a scopes canvas
+ *
+ * @param scopesCanvas - Canvas containing scope definitions
+ * @returns Array of scope names
+ */
+function getScopeNamesFromCanvas(scopesCanvas) {
+    if (!scopesCanvas?.nodes)
+        return [];
+    return scopesCanvas.nodes
+        .filter(canvas_1.isOtelScopeNode)
+        .map(node => node.otel?.scope)
+        .filter((scope) => !!scope);
+}
+exports.getScopeNamesFromCanvas = getScopeNamesFromCanvas;
+/**
+ * Get scope node by scope name
+ *
+ * @param scopesCanvas - Canvas containing scope definitions
+ * @param scopeName - Name of the scope to find
+ * @returns The scope node, or undefined if not found
+ */
+function getScopeNodeFromCanvas(scopesCanvas, scopeName) {
+    if (!scopesCanvas?.nodes)
+        return undefined;
+    return scopesCanvas.nodes.find(node => (0, canvas_1.isOtelScopeNode)(node) && node.otel?.scope === scopeName);
+}
+exports.getScopeNodeFromCanvas = getScopeNodeFromCanvas;
+//# sourceMappingURL=utils.js.map

package/dist/scopes/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/scopes/utils.ts"],"names":[],"mappings":"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"}

package/dist/scopes/validateScopeNamespaceNesting.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 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 declare function validateScopeNamespaceNesting(input: ValidateScopeNamespaceNestingInput): ScopesCanvasViolation[];
+//# sourceMappingURL=validateScopeNamespaceNesting.d.ts.map

package/dist/scopes/validateScopeNamespaceNesting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateScopeNamespaceNesting.d.ts","sourceRoot":"","sources":["../../src/scopes/validateScopeNamespaceNesting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGtD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAErE;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,cAAc,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,kCAAkC;IACjD,YAAY,EAAE,cAAc,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAClD;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,kCAAkC,GACxC,qBAAqB,EAAE,CA2CzB"}

package/dist/scopes/validateScopeNamespaceNesting.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateScopeNamespaceNesting = void 0;
+const canvas_1 = require("../types/canvas");
+const path_helpers_1 = require("../events/path-helpers");
+/**
+ * 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.
+ */
+function validateScopeNamespaceNesting(input) {
+    const { scopesCanvas, scopesCanvasPath, eventsCanvases } = input;
+    const violations = [];
+    // Build scope → paths map from the scopes canvas.
+    const scopePaths = new Map();
+    for (const node of scopesCanvas.nodes || []) {
+        if (!(0, canvas_1.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?.type !== 'event-namespace')
+                continue;
+            const ns = node.namespace;
+            if (!ns?.name || !Array.isArray(ns.paths) || ns.paths.length === 0)
+                continue;
+            for (const declared of ns.paths) {
+                const covered = ownerPaths.some((sp) => (0, path_helpers_1.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;
+}
+exports.validateScopeNamespaceNesting = validateScopeNamespaceNesting;
+//# sourceMappingURL=validateScopeNamespaceNesting.js.map

package/dist/scopes/validateScopeNamespaceNesting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateScopeNamespaceNesting.js","sourceRoot":"","sources":["../../src/scopes/validateScopeNamespaceNesting.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAGH,4CAAkD;AAClD,yDAAoD;AAqBpD;;;;;GAKG;AACH,SAAgB,6BAA6B,CAC3C,KAAyC;IAEzC,MAAM,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,GAAG,KAAK,CAAC;IACjE,MAAM,UAAU,GAA4B,EAAE,CAAC;IAE/C,kDAAkD;IAClD,MAAM,UAAU,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC/C,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,KAAK,IAAI,EAAE,EAAE;QAC3C,IAAI,CAAC,IAAA,wBAAe,EAAC,IAAI,CAAC;YAAE,SAAS;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC;QAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACrD,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;KAC9B;IAED,wEAAwE;IACxE,oEAAoE;IACpE,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE;QACjC,MAAM,UAAU,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9C,IAAI,CAAC,UAAU;YAAE,SAAS,CAAC,qCAAqC;QAEhE,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE,EAAE;YAChD,IAAK,IAAY,EAAE,IAAI,KAAK,iBAAiB;gBAAE,SAAS;YACxD,MAAM,EAAE,GAAI,IAAY,CAAC,SAAS,CAAC;YACnC,IAAI,CAAC,EAAE,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAE7E,KAAK,MAAM,QAAQ,IAAI,EAAE,CAAC,KAAiB,EAAE;gBAC3C,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAA,yBAAU,EAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC;gBAClE,IAAI,OAAO;oBAAE,SAAS;gBAEtB,UAAU,CAAC,IAAI,CAAC;oBACd,MAAM,EAAE,+BAA+B;oBACvC,QAAQ,EAAE,OAAO;oBACjB,IAAI,EAAE,gBAAgB,IAAI,6CAA6C;oBACvE,IAAI,EAAE,gBAAgB,IAAI,CAAC,KAAK,UAAU;oBAC1C,OAAO,EAAE,cAAc,EAAE,CAAC,IAAI,WAAW,QAAQ,kCAAkC,IAAI,CAAC,KAAK,aAAa,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;oBACvJ,MAAM,EAAE,uJAAuJ;oBAC/J,UAAU,EAAE,gDAAgD,IAAI,CAAC,KAAK,kLAAkL;iBACzP,CAAC,CAAC;aACJ;SACF;KACF;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AA7CD,sEA6CC"}