@canon-protocol/sdk 8.4.0 → 8.6.0

package/README.md

@@ -0,0 +1,130 @@
+# @canon-protocol/sdk
+
+TypeScript SDK for [Canon Protocol](https://canon-protocol.org) — parse, validate, resolve, and visualize semantic ontologies.
+
+## Installation
+
+```bash
+npm install @canon-protocol/sdk
+```
+
+## Quick start
+
+### Parse a Canon document
+
+```typescript
+import { CanonParser } from '@canon-protocol/sdk';
+
+const parser = new CanonParser();
+const doc = parser.parse(yamlContent);
+
+// doc.metadata — package info, publisher, version, imports
+// doc.body — all entities (classes, properties, instances) as key-value pairs
+```
+
+### Validate
+
+```typescript
+import { CanonParser, CanonObjectValidator, InMemoryCanonDocumentRepository } from '@canon-protocol/sdk';
+
+const parser = new CanonParser();
+const repo = new InMemoryCanonDocumentRepository(parser);
+
+// Load one or more documents
+const doc = parser.parse(yamlContent);
+await repo.saveDocumentAsync(doc, 'my-ontology');
+
+// Validate
+const validator = new CanonObjectValidator(parser);
+const result = await validator.validateAsync(doc, repo);
+
+for (const error of result.errors) {
+  console.log(`${error.severity}: ${error.message}`);
+}
+```
+
+### Extract a graph for visualization
+
+Returns nodes and edges ready for D3, Cytoscape, React Flow, vis.js, or any graph library:
+
+```typescript
+import { GraphBuilder, CanonParser, InMemoryCanonDocumentRepository } from '@canon-protocol/sdk';
+
+const parser = new CanonParser();
+const repo = new InMemoryCanonDocumentRepository(parser);
+const doc = parser.parse(yamlContent);
+await repo.saveDocumentAsync(doc, 'contacts');
+
+const graph = await GraphBuilder.buildFromRepository(repo);
+
+// graph.nodes — each node has: id, label, type, namespace, properties
+//   type is one of: Class, ObjectProperty, DatatypeProperty, Instance, Datatype, Unknown
+//
+// graph.edges — each edge has: source, target, type, label
+//   type is one of: instanceOf, subClassOf, domain, range, objectRelationship, subPropertyOf
+
+// Quick single-document graph (no repository needed):
+const simpleGraph = GraphBuilder.buildFromDocument(doc);
+```
+
+### Resolve entity references across imports
+
+```typescript
+import { ResourceResolver, CanonParser, InMemoryCanonDocumentRepository } from '@canon-protocol/sdk';
+
+const parser = new CanonParser();
+const repo = new InMemoryCanonDocumentRepository(parser);
+// ... load documents into repo ...
+
+const resolver = new ResourceResolver(repo);
+const entity = await resolver.resolveEntityAsync('Person', doc);
+// entity.uri — fully qualified Canon URI
+// entity.entity — the raw entity definition
+// entity.isImported — whether it came from an imported package
+```
+
+## Browser usage
+
+For browser applications (no Node.js APIs), import from the browser entry point:
+
+```typescript
+import {
+  CanonParser,
+  GraphBuilder,
+  InMemoryCanonDocumentRepository,
+  HttpCanonDocumentRepository,
+  CanonObjectValidator,
+} from '@canon-protocol/sdk/browser';
+```
+
+This includes parsing, validation, graph building, resolution, and HTTP/in-memory repositories. It excludes filesystem access, OS credential stores, and other Node.js-specific modules.
+
+Works with Vite, webpack, esbuild, Rollup, or any browser bundler.
+
+## Document repositories
+
+```typescript
+import {
+  InMemoryCanonDocumentRepository,   // In-memory — for testing, browser, or single-document work
+  FileSystemCanonDocumentRepository,  // Filesystem — scan a directory of .can.yml files (Node.js only)
+  HttpCanonDocumentRepository,        // HTTP — fetch packages from publisher domains
+} from '@canon-protocol/sdk';
+```
+
+## Key modules
+
+| Module | Description | Browser-safe |
+|--------|-------------|:---:|
+| `CanonParser` | Parse `.can.yml` YAML into `CanonDocument` objects | Yes |
+| `CanonObjectValidator` | Validate documents against ontology rules | Yes |
+| `GraphBuilder` | Extract nodes and edges for graph visualization | Yes |
+| `ResourceResolver` | Resolve entity references across imports | Yes |
+| `InMemoryCanonDocumentRepository` | In-memory document store | Yes |
+| `HttpCanonDocumentRepository` | Fetch packages from publisher HTTP endpoints | Yes |
+| `PublisherIndex` | Discover and resolve package versions from publishers | Yes |
+| `FileSystemCanonDocumentRepository` | Read/write `.can.yml` files on disk | No |
+| `CredentialStore` | OS-native credential storage (Keychain, CredMan, etc.) | No |
+
+## License
+
+Apache-2.0

package/dist/browser.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Browser-safe entry point for the Canon Protocol SDK.
+ *
+ * Import from '@canon-protocol/sdk/browser' in browser applications.
+ * This entry point excludes Node.js-specific modules (filesystem repos,
+ * OS credential stores, child_process, node:crypto).
+ *
+ * Usage:
+ *   import { CanonParser, GraphBuilder, InMemoryCanonDocumentRepository } from '@canon-protocol/sdk/browser';
+ */
+export { CanonParser, CanonObjectParser, PropertyMetadata } from './parsing/index.js';
+export type { ICanonObjectParser } from './parsing/index.js';
+export { GraphBuilder, NodeType, EdgeType } from './graph/index.js';
+export type { GraphNode, GraphEdge, GraphData } from './graph/index.js';
+export { OntologyValidationResult, OntologyValidationError, ValidationSeverity, ValidationContext, CanonObjectValidator, NamespacePrefixRule, ResourceNamingRule, PropertyTypeSpecificityRule, SubjectCanonTypeRequiredRule, EmbeddedCanonNoExplicitTypeRule, ImportExistenceRule, UnresolvedReferenceRule, TypeAmbiguityRule, ClassHierarchyCycleRule, PropertyHierarchyCycleRule, PropertyRangeRequiredRule, SubClassOfReferenceRule, SubPropertyOfReferenceRule, NamespaceImportCycleRule, InstancePropertyReferenceRule, DefinitionPropertyReferenceRule, XsdImportRule, AmbiguousReferenceRule, PropertyRangeReferenceRule, ObjectPropertyImportRule, ObjectPropertyValueValidationRule, PropertyDomainRule, PropertyValueTypeRule, ClassDefinitionRule } from './validation/index.js';
+export type { ICanonObjectValidator, IDocumentValidationRule, IRepositoryValidationRule } from './validation/index.js';
+export { Canon, DefinedCanon, SubjectCanon, EmbeddedCanon, ReferenceCanon } from './canons/index.js';
+export type { IStatement } from './statements/index.js';
+export { Statement, ScalarStatement, StringStatement, NumberStatement, BooleanStatement, ReferenceStatement, EmbeddedStatement, ListStatement } from './statements/index.js';
+export { ResourceResolver, CanonUri, CanonUriBuilder, TypeResolver } from './resolution/index.js';
+export type { ResourceResolutionResult, ILogger } from './resolution/index.js';
+export { InMemoryCanonDocumentRepository } from './repositories/InMemoryCanonDocumentRepository.js';
+export { HttpCanonDocumentRepository } from './repositories/HttpCanonDocumentRepository.js';
+export { PublisherIndex } from './repositories/PublisherIndex.js';
+export { PublisherConfigResolver } from './repositories/PublisherConfig.js';
+export type { PublisherConfig } from './repositories/PublisherConfig.js';
+export { CtlCanonUri, CtlParser, ResourceTypeClassifier, CtlValidator, CtlGraphResolver, CtlMarkdownRenderer, CtlValidationErrorType, CtlValidationSeverity, CtlCanonUriType, PathSegmentType, ResolvedResourceType } from './ctl/index.js';
+export type { CtlDocument, CanonReference, CtlValidationResult, CtlValidationError, ResolvedResourceGraph, ResolvedResource, ResolvedProperty, UnresolvedResource } from './ctl/index.js';
+export type { ICanonDocumentRepository } from '@canon-protocol/types/document/models';
+export type { ICanonParser } from '@canon-protocol/types/document/parsing';
+export type { CanonDocument, CanonMetadata, Namespace, Import, Version, DocumentReference, ParseResult, ParseError } from '@canon-protocol/types/document/models/types';
+export type { VersionOperator } from '@canon-protocol/types/document/models/enums';

package/dist/browser.js

@@ -0,0 +1,28 @@
+/**
+ * Browser-safe entry point for the Canon Protocol SDK.
+ *
+ * Import from '@canon-protocol/sdk/browser' in browser applications.
+ * This entry point excludes Node.js-specific modules (filesystem repos,
+ * OS credential stores, child_process, node:crypto).
+ *
+ * Usage:
+ *   import { CanonParser, GraphBuilder, InMemoryCanonDocumentRepository } from '@canon-protocol/sdk/browser';
+ */
+// Parsing
+export { CanonParser, CanonObjectParser, PropertyMetadata } from './parsing/index.js';
+// Graph
+export { GraphBuilder, NodeType, EdgeType } from './graph/index.js';
+// Validation
+export { OntologyValidationResult, OntologyValidationError, ValidationSeverity, ValidationContext, CanonObjectValidator, NamespacePrefixRule, ResourceNamingRule, PropertyTypeSpecificityRule, SubjectCanonTypeRequiredRule, EmbeddedCanonNoExplicitTypeRule, ImportExistenceRule, UnresolvedReferenceRule, TypeAmbiguityRule, ClassHierarchyCycleRule, PropertyHierarchyCycleRule, PropertyRangeRequiredRule, SubClassOfReferenceRule, SubPropertyOfReferenceRule, NamespaceImportCycleRule, InstancePropertyReferenceRule, DefinitionPropertyReferenceRule, XsdImportRule, AmbiguousReferenceRule, PropertyRangeReferenceRule, ObjectPropertyImportRule, ObjectPropertyValueValidationRule, PropertyDomainRule, PropertyValueTypeRule, ClassDefinitionRule } from './validation/index.js';
+// Canons
+export { Canon, DefinedCanon, SubjectCanon, EmbeddedCanon, ReferenceCanon } from './canons/index.js';
+export { Statement, ScalarStatement, StringStatement, NumberStatement, BooleanStatement, ReferenceStatement, EmbeddedStatement, ListStatement } from './statements/index.js';
+// Resolution
+export { ResourceResolver, CanonUri, CanonUriBuilder, TypeResolver } from './resolution/index.js';
+// Repositories (browser-safe only)
+export { InMemoryCanonDocumentRepository } from './repositories/InMemoryCanonDocumentRepository.js';
+export { HttpCanonDocumentRepository } from './repositories/HttpCanonDocumentRepository.js';
+export { PublisherIndex } from './repositories/PublisherIndex.js';
+export { PublisherConfigResolver } from './repositories/PublisherConfig.js';
+// CTL
+export { CtlCanonUri, CtlParser, ResourceTypeClassifier, CtlValidator, CtlGraphResolver, CtlMarkdownRenderer, CtlValidationErrorType, CtlValidationSeverity, CtlCanonUriType, PathSegmentType, ResolvedResourceType } from './ctl/index.js';

package/dist/graph/GraphBuilder.d.ts

@@ -0,0 +1,97 @@
+import type { CanonDocument } from '@canon-protocol/types/document/models/types';
+import type { ICanonDocumentRepository } from '@canon-protocol/types/document/models';
+/**
+ * Node types in a Canon graph.
+ */
+export declare enum NodeType {
+    Class = "Class",
+    DatatypeProperty = "DatatypeProperty",
+    ObjectProperty = "ObjectProperty",
+    AnnotationProperty = "AnnotationProperty",
+    Instance = "Instance",
+    Datatype = "Datatype",
+    Unknown = "Unknown"
+}
+/**
+ * Edge types in a Canon graph.
+ */
+export declare enum EdgeType {
+    /** Instance → Class (type) */
+    InstanceOf = "instanceOf",
+    /** Class → Class (subClassOf) */
+    SubClassOf = "subClassOf",
+    /** Property → Class (domain) */
+    Domain = "domain",
+    /** Property → Class or Datatype (range) */
+    Range = "range",
+    /** Class → Class via ObjectProperty */
+    ObjectRelationship = "objectRelationship",
+    /** Property → Property (subPropertyOf) */
+    SubPropertyOf = "subPropertyOf",
+    /** Instance → value via property */
+    PropertyValue = "propertyValue"
+}
+/**
+ * A node in the Canon graph.
+ */
+export interface GraphNode {
+    /** Unique identifier: "publisher/package@version/entityName" or just "entityName" for local */
+    id: string;
+    /** Display name */
+    label: string;
+    /** Semantic type */
+    type: NodeType;
+    /** Namespace this entity belongs to (publisher/package@version) */
+    namespace: string;
+    /** All properties as key-value pairs for tooltips/detail panels */
+    properties: Record<string, unknown>;
+}
+/**
+ * An edge in the Canon graph.
+ */
+export interface GraphEdge {
+    /** Source node id */
+    source: string;
+    /** Target node id */
+    target: string;
+    /** Relationship type */
+    type: EdgeType;
+    /** Display label (e.g., property name) */
+    label: string;
+}
+/**
+ * Complete graph data ready for visualization libraries.
+ */
+export interface GraphData {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+/**
+ * Builds a visualization-ready graph from Canon documents.
+ *
+ * Usage:
+ * ```typescript
+ * import { GraphBuilder, CanonParser, InMemoryCanonDocumentRepository } from '@canon-protocol/sdk';
+ *
+ * const parser = new CanonParser();
+ * const repo = new InMemoryCanonDocumentRepository(parser);
+ * const doc = parser.parse(yamlContent);
+ * await repo.saveDocumentAsync(doc, 'my-doc');
+ *
+ * const graph = await GraphBuilder.buildFromRepository(repo);
+ * // graph.nodes = [{ id, label, type, namespace, properties }, ...]
+ * // graph.edges = [{ source, target, type, label }, ...]
+ * ```
+ */
+export declare class GraphBuilder {
+    /**
+     * Build a graph from all documents in a repository.
+     * This is the main entry point — handles imports, resolution, and classification.
+     */
+    static buildFromRepository(repository: ICanonDocumentRepository): Promise<GraphData>;
+    /**
+     * Build a graph from a single parsed document.
+     * Simpler alternative when you don't need import resolution.
+     */
+    static buildFromDocument(document: CanonDocument): GraphData;
+}

package/dist/graph/GraphBuilder.js

@@ -0,0 +1,290 @@
+/**
+ * Node types in a Canon graph.
+ */
+export var NodeType;
+(function (NodeType) {
+    NodeType["Class"] = "Class";
+    NodeType["DatatypeProperty"] = "DatatypeProperty";
+    NodeType["ObjectProperty"] = "ObjectProperty";
+    NodeType["AnnotationProperty"] = "AnnotationProperty";
+    NodeType["Instance"] = "Instance";
+    NodeType["Datatype"] = "Datatype";
+    NodeType["Unknown"] = "Unknown";
+})(NodeType || (NodeType = {}));
+/**
+ * Edge types in a Canon graph.
+ */
+export var EdgeType;
+(function (EdgeType) {
+    /** Instance → Class (type) */
+    EdgeType["InstanceOf"] = "instanceOf";
+    /** Class → Class (subClassOf) */
+    EdgeType["SubClassOf"] = "subClassOf";
+    /** Property → Class (domain) */
+    EdgeType["Domain"] = "domain";
+    /** Property → Class or Datatype (range) */
+    EdgeType["Range"] = "range";
+    /** Class → Class via ObjectProperty */
+    EdgeType["ObjectRelationship"] = "objectRelationship";
+    /** Property → Property (subPropertyOf) */
+    EdgeType["SubPropertyOf"] = "subPropertyOf";
+    /** Instance → value via property */
+    EdgeType["PropertyValue"] = "propertyValue";
+})(EdgeType || (EdgeType = {}));
+/**
+ * Builds a visualization-ready graph from Canon documents.
+ *
+ * Usage:
+ * ```typescript
+ * import { GraphBuilder, CanonParser, InMemoryCanonDocumentRepository } from '@canon-protocol/sdk';
+ *
+ * const parser = new CanonParser();
+ * const repo = new InMemoryCanonDocumentRepository(parser);
+ * const doc = parser.parse(yamlContent);
+ * await repo.saveDocumentAsync(doc, 'my-doc');
+ *
+ * const graph = await GraphBuilder.buildFromRepository(repo);
+ * // graph.nodes = [{ id, label, type, namespace, properties }, ...]
+ * // graph.edges = [{ source, target, type, label }, ...]
+ * ```
+ */
+export class GraphBuilder {
+    /**
+     * Build a graph from all documents in a repository.
+     * This is the main entry point — handles imports, resolution, and classification.
+     */
+    static async buildFromRepository(repository) {
+        const documents = await repository.getAllDocumentsAsync();
+        const nodes = [];
+        const edges = [];
+        const knownClassNames = new Set();
+        // Build a map from "publisher/packageName" to the full namespace string for alias resolution
+        const packageToNamespace = new Map();
+        for (const document of documents) {
+            const ns = document.metadata.namespace_;
+            if (ns) {
+                const namespace = ns.toString();
+                const packageKey = `${ns.publisher}/${ns.package_}`;
+                packageToNamespace.set(packageKey, namespace);
+            }
+        }
+        // First pass: identify all classes across all documents
+        for (const document of documents) {
+            for (const [name, entity] of Object.entries(document.body)) {
+                const type = entity?.type;
+                if (!type)
+                    continue;
+                if (isClassTypeName(type)) {
+                    knownClassNames.add(name);
+                }
+            }
+        }
+        // Second pass: build graph
+        for (const document of documents) {
+            const namespace = document.metadata.namespace_
+                ? document.metadata.namespace_.toString()
+                : '';
+            const aliasMap = buildAliasMap(document, packageToNamespace);
+            for (const [name, entity] of Object.entries(document.body)) {
+                if (!entity || typeof entity !== 'object')
+                    continue;
+                const typeName = entity.type;
+                const nodeType = classifyByTypeName(typeName, name, knownClassNames);
+                const nodeId = namespace ? `${namespace}/${name}` : name;
+                const properties = {};
+                for (const [key, value] of Object.entries(entity)) {
+                    if (key === 'type')
+                        continue;
+                    if (typeof value !== 'object' || value === null) {
+                        properties[key] = value;
+                    }
+                }
+                nodes.push({
+                    id: nodeId,
+                    label: entity.label ?? name,
+                    type: nodeType,
+                    namespace,
+                    properties,
+                });
+                extractEdges(nodeId, entity, nodeType, knownClassNames, edges, namespace, aliasMap);
+            }
+        }
+        return { nodes, edges };
+    }
+    /**
+     * Build a graph from a single parsed document.
+     * Simpler alternative when you don't need import resolution.
+     */
+    static buildFromDocument(document) {
+        const nodes = [];
+        const edges = [];
+        const namespace = document.metadata.namespace_
+            ? `${document.metadata.namespace_.publisher}/${document.metadata.namespace_.package_}@${document.metadata.namespace_.version}`
+            : '';
+        const knownClassNames = new Set();
+        // First pass: identify classes
+        for (const [name, entity] of Object.entries(document.body)) {
+            const type = entity?.type;
+            if (!type)
+                continue;
+            if (isClassTypeName(type)) {
+                knownClassNames.add(name);
+            }
+        }
+        // Build partial alias map from document imports
+        const aliasMap = buildAliasMap(document);
+        // Second pass: build graph
+        for (const [name, entity] of Object.entries(document.body)) {
+            if (!entity || typeof entity !== 'object')
+                continue;
+            const typeName = entity.type;
+            const nodeType = classifyByTypeName(typeName, name, knownClassNames);
+            const nodeId = namespace ? `${namespace}/${name}` : name;
+            const properties = {};
+            for (const [key, value] of Object.entries(entity)) {
+                if (key === 'type')
+                    continue;
+                if (typeof value !== 'object' || value === null) {
+                    properties[key] = value;
+                }
+            }
+            nodes.push({
+                id: nodeId,
+                label: entity.label ?? name,
+                type: nodeType,
+                namespace,
+                properties,
+            });
+            extractEdges(nodeId, entity, nodeType, knownClassNames, edges, namespace, aliasMap);
+        }
+        return { nodes, edges };
+    }
+}
+// --- Helpers ---
+function buildAliasMap(document, packageToNamespace) {
+    const aliasMap = new Map();
+    if (document.metadata?.imports) {
+        for (const [publisher, imports] of Object.entries(document.metadata.imports)) {
+            for (const import_ of imports) {
+                const alias = import_.alias ?? import_.packageName;
+                const packageKey = `${publisher}/${import_.packageName}`;
+                // Use resolved namespace from repository if available, otherwise approximate from import
+                const targetNamespace = packageToNamespace?.get(packageKey)
+                    ?? `${publisher}/${import_.packageName}@${import_.version}`;
+                aliasMap.set(alias, targetNamespace);
+            }
+        }
+    }
+    return aliasMap;
+}
+function isClassTypeName(typeName) {
+    const name = typeName.split('.').pop() ?? typeName;
+    return name === 'Class';
+}
+function classifyByTypeName(typeName, entityName, knownClassNames) {
+    if (!typeName)
+        return NodeType.Unknown;
+    const name = typeName.split('.').pop() ?? typeName;
+    switch (name) {
+        case 'Class': return NodeType.Class;
+        case 'ObjectProperty': return NodeType.ObjectProperty;
+        case 'DatatypeProperty': return NodeType.DatatypeProperty;
+        case 'AnnotationProperty': return NodeType.AnnotationProperty;
+        case 'Datatype': return NodeType.Datatype;
+        default:
+            if (knownClassNames.has(name))
+                return NodeType.Instance;
+            return NodeType.Unknown;
+    }
+}
+function extractEdges(sourceId, entity, nodeType, knownClassNames, edges, namespace, aliasMap) {
+    const type = entity.type;
+    // subClassOf → SubClassOf edge
+    if (entity.subClassOf && typeof entity.subClassOf === 'string') {
+        edges.push({
+            source: sourceId,
+            target: resolveLocalId(entity.subClassOf, namespace, aliasMap),
+            type: EdgeType.SubClassOf,
+            label: 'subClassOf',
+        });
+    }
+    // subPropertyOf → SubPropertyOf edge
+    if (entity.subPropertyOf && typeof entity.subPropertyOf === 'string') {
+        edges.push({
+            source: sourceId,
+            target: resolveLocalId(entity.subPropertyOf, namespace, aliasMap),
+            type: EdgeType.SubPropertyOf,
+            label: 'subPropertyOf',
+        });
+    }
+    // domain → Domain edge (property → class)
+    if (entity.domain && typeof entity.domain === 'string') {
+        edges.push({
+            source: sourceId,
+            target: resolveLocalId(entity.domain, namespace, aliasMap),
+            type: EdgeType.Domain,
+            label: 'domain',
+        });
+    }
+    // range → Range edge (property → class or datatype)
+    if (entity.range && typeof entity.range === 'string') {
+        edges.push({
+            source: sourceId,
+            target: resolveLocalId(entity.range, namespace, aliasMap),
+            type: EdgeType.Range,
+            label: 'range',
+        });
+    }
+    // Instance type → InstanceOf edge
+    if (nodeType === NodeType.Instance && type) {
+        const typeName = type.split('.').pop() ?? type;
+        edges.push({
+            source: sourceId,
+            target: resolveLocalId(typeName, namespace, aliasMap),
+            type: EdgeType.InstanceOf,
+            label: 'type',
+        });
+    }
+    // ObjectProperty values on instances → PropertyValue edges
+    if (nodeType === NodeType.Instance) {
+        for (const [key, value] of Object.entries(entity)) {
+            if (key === 'type' || typeof value !== 'string')
+                continue;
+            // If the value references a known class instance name, it's a relationship
+            // We can't always tell, but if it's not a scalar-looking value, treat it as a reference
+        }
+    }
+    // For ObjectProperties, create a convenience edge showing the class→class relationship
+    if (nodeType === NodeType.ObjectProperty && entity.domain && entity.range) {
+        const domainStr = typeof entity.domain === 'string' ? entity.domain : null;
+        const rangeStr = typeof entity.range === 'string' ? entity.range : null;
+        if (domainStr && rangeStr) {
+            edges.push({
+                source: resolveLocalId(domainStr, namespace, aliasMap),
+                target: resolveLocalId(rangeStr, namespace, aliasMap),
+                type: EdgeType.ObjectRelationship,
+                label: entity.label ?? sourceId.split('/').pop() ?? '',
+            });
+        }
+    }
+}
+function resolveLocalId(name, namespace, aliasMap) {
+    // Already qualified with a slash — return as-is
+    if (name.includes('/'))
+        return name;
+    // Handle aliased references (e.g., "sdg.gdpr")
+    if (name.includes('.')) {
+        const dotIndex = name.indexOf('.');
+        const alias = name.substring(0, dotIndex);
+        const entityName = name.substring(dotIndex + 1);
+        if (aliasMap) {
+            const targetNamespace = aliasMap.get(alias);
+            if (targetNamespace) {
+                return `${targetNamespace}/${entityName}`;
+            }
+        }
+        // Fallback: use entity name with local namespace
+        return namespace ? `${namespace}/${entityName}` : entityName;
+    }
+    return namespace ? `${namespace}/${name}` : name;
+}

package/dist/graph/index.d.ts

@@ -0,0 +1,3 @@
+export { GraphBuilder } from './GraphBuilder.js';
+export { NodeType, EdgeType } from './GraphBuilder.js';
+export type { GraphNode, GraphEdge, GraphData } from './GraphBuilder.js';

package/dist/graph/index.js

@@ -0,0 +1,2 @@
+export { GraphBuilder } from './GraphBuilder.js';
+export { NodeType, EdgeType } from './GraphBuilder.js';

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { InMemoryCanonDocumentRepository, FileSystemCanonDocumentRepository, CompositeCanonDocumentRepository, RepositoryFactory, DocumentLocation, HttpCanonDocumentRepository, PublisherIndex, PublisherConfigResolver, getGlobalCachePath } from './repositories/index.js';
 export type { PublisherConfig } from './repositories/index.js';
+export { GraphBuilder, NodeType, EdgeType } from './graph/index.js';
+export type { GraphNode, GraphEdge, GraphData } from './graph/index.js';
 export { GitIgnoreFilter } from './filtering/index.js';
 export type { IGitIgnoreFilter } from './filtering/index.js';
 export { CanonParser, CanonObjectParser, PropertyMetadata } from './parsing/index.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { InMemoryCanonDocumentRepository, FileSystemCanonDocumentRepository, CompositeCanonDocumentRepository, RepositoryFactory, DocumentLocation, HttpCanonDocumentRepository, PublisherIndex, PublisherConfigResolver, getGlobalCachePath } from './repositories/index.js';
+export { GraphBuilder, NodeType, EdgeType } from './graph/index.js';
 export { GitIgnoreFilter } from './filtering/index.js';
 export { CanonParser, CanonObjectParser, PropertyMetadata } from './parsing/index.js';
 export { ResourceResolver, CanonUri, CanonUriBuilder, TypeResolver } from './resolution/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canon-protocol/sdk",
-  "version": "8.4.0",
+  "version": "8.6.0",
   "description": "Canon Protocol SDK - Document repository and parsing implementations for TypeScript",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,6 +33,10 @@
     "./ctl": {
       "types": "./dist/ctl/index.d.ts",
       "default": "./dist/ctl/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
     }
   },
   "files": [
@@ -62,7 +66,7 @@
     "yaml-parser"
   ],
   "dependencies": {
-    "@canon-protocol/types": "^8.4.0",
+    "@canon-protocol/types": "^8.6.0",
     "ignore": "^7.0.5",
     "js-yaml": "^4.1.0"
   },