@documentation-robotics/cli 0.1.0 → 0.1.7

package/dist/core/model.js

@@ -1,138 +1,209 @@
 import { Layer } from "./layer.js";
 import { Manifest } from "./manifest.js";
 import { Element } from "./element.js";
-import { ProjectionEngine } from "./projection-engine.js";
+import { GraphModel } from "./graph-model.js";
+import { VirtualProjectionEngine } from "./virtual-projection.js";
+import { StagedChangesetStorage } from "./staged-changeset-storage.js";
 import { Relationships } from "./relationships.js";
-import { ActiveChangesetContext } from "./active-changeset.js";
+import { CANONICAL_LAYER_NAMES } from "./layers.js";
 import { ensureDir, writeFile } from "../utils/file-io.js";
-import { startSpan, endSpan } from "../telemetry/index.js";
+import { getCliVersion } from "../utils/spec-version.js";
+import { startSpan, endSpan, startActiveSpan } from "../telemetry/index.js";
 import { findProjectRoot } from "../utils/project-paths.js";
+import { getNodeType } from "../generated/node-types.js";
 import path from "node:path";
 import fs from "node:fs/promises";
+import crypto from "node:crypto";
+function deterministicUUID(path2) {
+  const hash = crypto.createHash("sha256").update(path2).digest("hex");
+  return [
+    hash.slice(0, 8),
+    hash.slice(8, 12),
+    "4" + hash.slice(13, 16),
+    // version 4 marker
+    (parseInt(hash.slice(16, 18), 16) & 63 | 128).toString(16) + hash.slice(18, 20),
+    // variant
+    hash.slice(20, 32)
+  ].join("-");
+}
+function titleToSnakeCase(title) {
+  return title.replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").replace(/([a-z\d])([A-Z])/g, "$1_$2").toLowerCase();
+}
+function typeToSnakeStem(specNodeId, type) {
+  if (specNodeId) {
+    const nodeType = getNodeType(specNodeId);
+    if (nodeType?.title)
+      return titleToSnakeCase(nodeType.title);
+  }
+  return type;
+}
 const isTelemetryEnabled = !1;
 class Model {
   rootPath;
   manifest;
+  graph;
   layers;
   relationships;
   lazyLoad;
   loadedLayers;
-  projectionEngine;
-  activeChangesetContext;
+  virtualProjectionEngine;
+  /** ID of the currently active changeset, or null if none is active. Set during load(). */
+  _activeChangesetId = null;
+  /** Layer names that exist only in staged changes (not yet committed to base model). */
+  _stagedLayerNames = /* @__PURE__ */ new Set();
   constructor(rootPath, manifest, options = {}) {
-    this.rootPath = rootPath, this.manifest = manifest, this.layers = /* @__PURE__ */ new Map(), this.relationships = new Relationships(), this.lazyLoad = options.lazyLoad ?? !1, this.loadedLayers = /* @__PURE__ */ new Set();
+    this.rootPath = rootPath, this.manifest = manifest, this.graph = new GraphModel(), this.layers = /* @__PURE__ */ new Map(), this.relationships = new Relationships(), this.lazyLoad = options.lazyLoad ?? !1, this.loadedLayers = /* @__PURE__ */ new Set();
   }
   /**
-   * Get a layer, loading it if lazy loading is enabled
+   * Get the committed base layer (no staging projection).
+   * Used internally by VirtualProjectionEngine and commit() to access the raw base model
+   * without triggering infinite recursion or double-projection.
    */
-  async getLayer(name) {
+  async getBaseLayer(name) {
     return this.lazyLoad && !this.loadedLayers.has(name) && await this.loadLayer(name), this.layers.get(name);
   }
+  /**
+   * Get a layer, transparently merging staged changes when an active changeset exists.
+   * Falls back to the committed base layer if no changeset is active or projection fails.
+   */
+  async getLayer(name) {
+    if (this.lazyLoad && !this.loadedLayers.has(name) && await this.loadLayer(name), this._activeChangesetId)
+      try {
+        return await this.getVirtualProjectionEngine().projectLayer(this, this._activeChangesetId, name);
+      } catch {
+        return this.layers.get(name);
+      }
+    return this.layers.get(name);
+  }
   /**
    * Get an element by ID across all layers
+   * Supports both UUID and semantic ID (layer.type.kebab-name) lookup
    */
   getElementById(id) {
     for (const layer of this.layers.values()) {
-      const element = layer.elements.get(id);
+      const element = layer.getElement(id);
       if (element)
         return element;
     }
   }
   /**
-   * Get projection engine (lazily initialized)
+   * Get virtual projection engine (lazily initialized)
    */
-  getProjectionEngine() {
-    return this.projectionEngine || (this.projectionEngine = new ProjectionEngine(this)), this.projectionEngine;
+  getVirtualProjectionEngine() {
+    return this.virtualProjectionEngine || (this.virtualProjectionEngine = new VirtualProjectionEngine(this.rootPath)), this.virtualProjectionEngine;
   }
   /**
-   * Get active changeset context (lazily initialized)
+   * Returns the active changeset ID, or null if no changeset is active.
+   * Used by commands that need to project the full model (e.g. validate).
    */
-  getActiveChangesetContext() {
-    return this.activeChangesetContext || (this.activeChangesetContext = new ActiveChangesetContext(this.rootPath)), this.activeChangesetContext;
+  getActiveChangesetId() {
+    return this._activeChangesetId;
   }
   /**
-   * Load a layer from disk (legacy format: model/XX_layername/*.yaml files)
-   * Supports reading layer paths from manifest for Python CLI compatibility
+   * Load a layer from disk (model/XX_layername/*.yaml files)
    */
   async loadLayer(name) {
-    const layerSpan = isTelemetryEnabled ? startSpan("layer.load", {
-      "layer.name": name
-    }) : null;
-    try {
+    await startActiveSpan("layer.load", async (layerSpan) => {
       const fs2 = await import("fs/promises"), yaml = await import("yaml");
       let layerPath = null;
-      if (this.manifest.layers && this.manifest.layers[name]) {
-        const layerConfig = this.manifest.layers[name];
-        if (layerConfig.path) {
-          const fullPath = `${this.rootPath}/${layerConfig.path.replace(/\/$/, "")}`;
-          try {
-            await fs2.access(fullPath), layerPath = fullPath;
-          } catch {
-            process.env.DEBUG && console.debug(`Manifest specifies path ${layerConfig.path} but it doesn't exist`);
-          }
-        }
-      }
-      if (!layerPath) {
-        const modelDir = `${this.rootPath}/documentation-robotics/model`;
-        try {
-          const layerDir = (await fs2.readdir(modelDir, { withFileTypes: !0 })).find((e) => e.isDirectory() && e.name.match(/^\d{2}_/) && e.name.replace(/^\d{2}_/, "") === name);
-          layerDir && (layerPath = `${modelDir}/${layerDir.name}`);
-        } catch {
-        }
+      const modelDir = `${this.rootPath}/documentation-robotics/model`;
+      try {
+        const layerDir = (await fs2.readdir(modelDir, { withFileTypes: !0 })).find((e) => e.isDirectory() && e.name.match(/^\d{2}_/) && e.name.replace(/^\d{2}_/, "") === name);
+        layerDir && (layerPath = `${modelDir}/${layerDir.name}`);
+      } catch {
       }
       if (!layerPath)
         return;
-      const layer = new Layer(name), files = await fs2.readdir(layerPath);
+      const layer = new Layer(name, this.graph);
+      let parseErrorCount = 0;
+      const files = await fs2.readdir(layerPath);
       for (const file of files)
         if (file.endsWith(".yaml") || file.endsWith(".yml")) {
-          const filePath = `${layerPath}/${file}`, yamlContent = await fs2.readFile(filePath, "utf-8"), elements = yaml.parse(yamlContent);
-          if (elements && typeof elements == "object") {
-            for (const [key, element] of Object.entries(elements))
-              if (element && typeof element == "object") {
-                const el = element, elementId = el.id || `${name}.${key}`;
-                let elementType = el.type;
-                if (!elementType) {
-                  const stem = file.replace(/\.ya?ml$/, "");
-                  elementType = stem.endsWith("s") ? stem.slice(0, -1) : stem;
+          const filePath = `${layerPath}/${file}`;
+          try {
+            const yamlContent = await fs2.readFile(filePath, "utf-8"), elements = yaml.parse(yamlContent);
+            if (elements && typeof elements == "object") {
+              for (const [key, element] of Object.entries(elements))
+                if (element && typeof element == "object") {
+                  const el = element, isSlugPattern = /^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*$/.test(el.id || ""), isUUIDPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(el.id || "");
+                  let elementId, elementPath, extractedType;
+                  if (el.path && isUUIDPattern) {
+                    elementId = el.id, elementPath = el.path;
+                    const pathParts = el.path.split(".");
+                    pathParts.length >= 3 && (extractedType = pathParts[1]);
+                  } else if (el.path && !isUUIDPattern) {
+                    elementPath = el.path, elementId = deterministicUUID(el.path);
+                    const pathParts = el.path.split(".");
+                    pathParts.length >= 3 && (extractedType = pathParts[1]);
+                  } else if (isSlugPattern) {
+                    elementPath = el.id, elementId = deterministicUUID(el.id);
+                    const parts = el.id.split(".");
+                    parts.length >= 3 && (extractedType = parts[1]);
+                  } else if (isUUIDPattern) {
+                    elementId = el.id;
+                    const layerId2 = el.layer_id || name, rawType = el.type || "", kebabName = (el.name || key).toLowerCase().replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+                    elementPath = `${layerId2}.${rawType}.${kebabName}`, extractedType = rawType || void 0;
+                  } else {
+                    const layerId2 = el.layer_id || name, rawType = el.type || (typeof el.id == "string" && el.id.includes(".") ? el.id.split(".")[1] : "") || "", kebabName = (el.name || key).toLowerCase().replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-+|-+$/g, "") || "unknown";
+                    if (elementPath = `${layerId2}.${rawType || "element"}.${kebabName}`, elementId = deterministicUUID(elementPath), rawType)
+                      extractedType = rawType;
+                    else if (typeof el.id == "string" && el.id.includes(".")) {
+                      const parts = el.id.split(".");
+                      parts.length >= 3 && (extractedType = parts[1]);
+                    }
+                  }
+                  const elementName = el.name || key, elementType = el.type || extractedType, layerId = el.layer_id || name, newElement = new Element({
+                    id: elementId,
+                    path: elementPath,
+                    spec_node_id: el.spec_node_id,
+                    layer_id: layerId,
+                    attributes: el.attributes,
+                    source_reference: el.source_reference,
+                    metadata: el.metadata,
+                    name: elementName,
+                    type: elementType,
+                    description: el.description || "",
+                    relationships: el.relationships || [],
+                    references: el.references || [],
+                    layer: layerId
+                  });
+                  layer.addElement(newElement);
                 }
-                const newElement = new Element({
-                  id: elementId,
-                  name: el.name || key,
-                  type: elementType,
-                  description: el.description || el.documentation || "",
-                  properties: el.properties || {},
-                  relationships: el.relationships || [],
-                  references: el.references || [],
-                  layer: name,
-                  // Track layer (Python CLI compatibility)
-                  filePath,
-                  // Track source file (Python CLI compatibility)
-                  rawData: el
-                  // Preserve raw YAML data (Python CLI compatibility)
-                });
-                layer.addElement(newElement);
-              }
+            }
+          } catch (fileError) {
+            const errorMsg = fileError instanceof Error ? fileError.message : String(fileError);
+            console.error(`Warning: Failed to parse ${filePath}: ${errorMsg}`), parseErrorCount++;
           }
         }
-      this.layers.set(name, layer), this.loadedLayers.add(name), isTelemetryEnabled && layerSpan && layerSpan.setAttribute("layer.element_count", layer.elements.size);
-    } finally {
-      isTelemetryEnabled && endSpan(layerSpan);
-    }
+      parseErrorCount > 0 && console.error(`Warning: Layer '${name}' loaded with ${parseErrorCount} YAML parse error(s)`), this.layers.set(name, layer), this.loadedLayers.add(name), layerSpan.setAttribute("layer.element_count", layer.elements.size);
+    }, { "layer.name": name });
   }
   /**
    * Add a layer to the model
    */
   addLayer(layer) {
-    this.layers.set(layer.name, layer), this.loadedLayers.add(layer.name);
+    if (layer.graph.getNodeCount() > 0) {
+      for (const node of layer.graph.nodes.values())
+        this.graph.addNode(node);
+      for (const edge of layer.graph.edges.values())
+        this.graph.addEdge(edge);
+    }
+    layer.graph = this.graph, this.layers.set(layer.name, layer), this.loadedLayers.add(layer.name);
   }
   /**
-   * Get all loaded layer names
+   * Get all layer names, including layers that exist only in staged changes.
+   * When an active changeset introduces elements for a layer with no committed data,
+   * that layer name is included so findElementLayer() and other callers can discover it.
    */
   getLayerNames() {
-    return Array.from(this.layers.keys());
+    const base = Array.from(this.layers.keys());
+    if (this._stagedLayerNames.size === 0)
+      return base;
+    const staged = Array.from(this._stagedLayerNames).filter((l) => !this.layers.has(l));
+    return [...base, ...staged];
   }
   /**
-   * Save a layer to disk (legacy format: model/XX_layername/*.yaml)
+   * Save a layer to disk (model/XX_layername/*.yaml)
    */
   async saveLayer(name) {
     const layer = this.layers.get(name);
@@ -140,40 +211,14 @@ class Model {
       throw new Error(`Layer ${name} not found`);
     const fs2 = await import("fs/promises"), yaml = await import("yaml");
     let layerPath = null;
-    if (this.manifest.layers && this.manifest.layers[name]) {
-      const layerConfig = this.manifest.layers[name];
-      if (layerConfig.path) {
-        const fullPath = `${this.rootPath}/${layerConfig.path.replace(/\/$/, "")}`;
-        try {
-          await fs2.access(fullPath), layerPath = fullPath;
-        } catch {
-          await ensureDir(fullPath), layerPath = fullPath;
-        }
-      }
-    }
-    if (!layerPath) {
-      const modelDir = `${this.rootPath}/documentation-robotics/model`;
-      try {
-        const layerDir = (await fs2.readdir(modelDir, { withFileTypes: !0 })).find((e) => e.isDirectory() && e.name.match(/^\d{2}_/) && e.name.replace(/^\d{2}_/, "") === name);
-        layerDir && (layerPath = `${modelDir}/${layerDir.name}`);
-      } catch {
-      }
+    const modelDir = `${this.rootPath}/documentation-robotics/model`;
+    try {
+      const layerDir = (await fs2.readdir(modelDir, { withFileTypes: !0 })).find((e) => e.isDirectory() && e.name.match(/^\d{2}_/) && e.name.replace(/^\d{2}_/, "") === name);
+      layerDir && (layerPath = `${modelDir}/${layerDir.name}`);
+    } catch {
     }
     if (!layerPath) {
-      const layerNameWithoutPrefix = name.replace(/^\d{2}-/, ""), index = [
-        "motivation",
-        "business",
-        "security",
-        "application",
-        "technology",
-        "api",
-        "data-model",
-        "datastore",
-        "ux",
-        "navigation",
-        "apm",
-        "testing"
-      ].indexOf(layerNameWithoutPrefix);
+      const layerNameWithoutPrefix = name.replace(/^\d{2}-/, ""), index = CANONICAL_LAYER_NAMES.indexOf(layerNameWithoutPrefix);
       if (index >= 0) {
         const orderNum = String(index + 1).padStart(2, "0");
         layerPath = `${this.rootPath}/documentation-robotics/model/${orderNum}_${layerNameWithoutPrefix}`, await ensureDir(layerPath);
@@ -184,24 +229,41 @@ class Model {
       const existingFiles = await fs2.readdir(layerPath);
       for (const file of existingFiles)
         (file.endsWith(".yaml") || file.endsWith(".yml")) && await fs2.unlink(`${layerPath}/${file}`);
-    } catch {
+    } catch (err) {
+      if (!(err?.code === "ENOENT"))
+        throw new Error(`Failed to clean existing YAML files: ${err instanceof Error ? err.message : String(err)}`);
     }
     const elementsByType = /* @__PURE__ */ new Map();
     for (const element of layer.elements.values()) {
-      const type = element.type + "s";
-      elementsByType.has(type) || elementsByType.set(type, []), elementsByType.get(type).push(element);
+      const typeKey = element.type;
+      if (!elementsByType.has(typeKey)) {
+        const stem = typeToSnakeStem(element.spec_node_id, element.type);
+        elementsByType.set(typeKey, { stem, elements: [] });
+      }
+      elementsByType.get(typeKey).elements.push(element);
     }
-    for (const [type, elements] of elementsByType) {
-      const filename = `${type}.yaml`, filePath = `${layerPath}/${filename}`, yamlData = {};
+    const INTERNAL_FIELDS = /* @__PURE__ */ new Set([
+      "__references__",
+      "__relationships__",
+      "source",
+      "x-source-reference"
+    ]);
+    for (const [, { stem, elements }] of elementsByType) {
+      const filename = `${stem}.yaml`, filePath = `${layerPath}/${filename}`, yamlData = {};
       for (const element of elements) {
-        const key = element.id.split(".").pop() || element.id;
+        const json = element.toJSON(), cleanAttrs = json.attributes ? Object.fromEntries(Object.entries(json.attributes).filter(([k]) => !INTERNAL_FIELDS.has(k))) : void 0, key = element.path || element.id;
         yamlData[key] = {
-          id: element.id,
-          name: element.name,
-          type: element.type,
-          ...element.description && { documentation: element.description },
-          ...Object.keys(element.properties || {}).length > 0 && { properties: element.properties },
-          ...element.references && element.references.length > 0 && { references: element.references }
+          id: json.id,
+          path: json.path,
+          spec_node_id: json.spec_node_id,
+          type: json.type,
+          layer_id: json.layer_id,
+          name: json.name,
+          ...json.description && { description: json.description },
+          ...cleanAttrs && Object.keys(cleanAttrs).length > 0 && { attributes: cleanAttrs },
+          ...json.source_reference && { source_reference: json.source_reference },
+          ...json.metadata && { metadata: json.metadata },
+          ...json.references && json.references.length > 0 && { references: json.references }
           // Relationships are now stored in centralized relationships.yaml, not inline
         };
       }
@@ -234,15 +296,14 @@ class Model {
     }
   }
   /**
-   * Save the manifest to disk (Python CLI format: documentation-robotics/model/manifest.yaml)
-   * Preserves Python CLI metadata fields for compatibility
+   * Save the manifest to disk (documentation-robotics/model/manifest.yaml)
    */
   async saveManifest() {
     this.manifest.updateModified();
     const yaml = await import("yaml"), manifestPath = `${this.rootPath}/documentation-robotics/model/manifest.yaml`, yamlData = {
       version: this.manifest.version,
       schema: "documentation-robotics-v1",
-      cli_version: this.manifest.version || "0.1.0",
+      cli_version: getCliVersion(),
       spec_version: this.manifest.specVersion,
       created: this.manifest.created,
       updated: this.manifest.modified,
@@ -252,44 +313,32 @@ class Model {
         version: this.manifest.version
       },
       documentation: ".dr/README.md",
-      layers: this.manifest.layers || {}
-    };
-    if (!this.manifest.layers || Object.keys(this.manifest.layers).length === 0) {
-      const layerOrder = [
-        "motivation",
-        "business",
-        "security",
-        "application",
-        "technology",
-        "api",
-        "data-model",
-        "datastore",
-        "ux",
-        "navigation",
-        "apm",
-        "testing"
-      ];
-      for (let i = 0; i < layerOrder.length; i++) {
-        const layerName = layerOrder[i], layer = this.layers.get(layerName), orderNum = String(i + 1).padStart(2, "0");
-        yamlData.layers[layerName] = {
-          order: i + 1,
-          name: layerName.charAt(0).toUpperCase() + layerName.slice(1).replace("-", " "),
-          path: `documentation-robotics/model/${orderNum}_${layerName}/`,
-          schema: `.dr/schemas/${orderNum}-${layerName}-layer.schema.json`,
-          enabled: !0,
-          ...layer && { elements: this.getLayerElementCounts(layer) }
-        };
-      }
-    } else
-      for (const [layerName, layerConfig] of Object.entries(yamlData.layers)) {
-        const layer = this.layers.get(layerName);
-        layer && (layerConfig.elements = this.getLayerElementCounts(layer));
-      }
-    if (this.manifest.statistics) {
-      const stats = { ...this.manifest.statistics };
-      stats.total_elements = Array.from(this.layers.values()).reduce((sum, layer) => sum + layer.elements.size, 0), yamlData.statistics = stats;
+      layers: {}
+    }, layerOrder = [
+      "motivation",
+      "business",
+      "security",
+      "application",
+      "technology",
+      "api",
+      "data-model",
+      "data-store",
+      "ux",
+      "navigation",
+      "apm",
+      "testing"
+    ];
+    for (let i = 0; i < layerOrder.length; i++) {
+      const layerName = layerOrder[i], layer = this.layers.get(layerName), orderNum = String(i + 1).padStart(2, "0");
+      yamlData.layers[layerName] = {
+        order: i + 1,
+        name: layerName.charAt(0).toUpperCase() + layerName.slice(1).replace("-", " "),
+        path: `documentation-robotics/model/${orderNum}_${layerName}/`,
+        enabled: !0,
+        ...layer && { elements: this.getLayerElementCounts(layer) }
+      };
     }
-    this.manifest.cross_references && (yamlData.cross_references = this.manifest.cross_references), this.manifest.conventions && (yamlData.conventions = this.manifest.conventions), this.manifest.upgrade_history && (yamlData.upgrade_history = this.manifest.upgrade_history), this.manifest.changeset_history && this.manifest.changeset_history.length > 0 && (yamlData.changeset_history = this.manifest.changeset_history), await ensureDir(`${this.rootPath}/documentation-robotics/model`), await writeFile(manifestPath, yaml.stringify(yamlData));
+    this.manifest.changeset_history && this.manifest.changeset_history.length > 0 && (yamlData.changeset_history = this.manifest.changeset_history), await ensureDir(`${this.rootPath}/documentation-robotics/model`), await writeFile(manifestPath, yaml.stringify(yamlData));
   }
   getLayerElementCounts(layer) {
     const counts = {};
@@ -302,11 +351,33 @@ class Model {
    */
   async loadRelationships() {
     const fs2 = await import("fs/promises"), yaml = await import("yaml"), relationshipsPath = `${this.rootPath}/documentation-robotics/model/relationships.yaml`;
+    let data;
     try {
-      const yamlContent = await fs2.readFile(relationshipsPath, "utf-8"), data = yaml.parse(yamlContent);
-      Array.isArray(data) && (this.relationships = Relationships.fromArray(data));
+      const yamlContent = await fs2.readFile(relationshipsPath, "utf-8");
+      data = yaml.parse(yamlContent);
     } catch (err) {
-      err.code !== "ENOENT" && process.env.DEBUG && console.debug(`Warning: Failed to load relationships.yaml: ${err}`);
+      if (err.code !== "ENOENT")
+        throw new Error(`Failed to load relationships.yaml: ${err instanceof Error ? err.message : String(err)}`);
+      return;
+    }
+    if (!Array.isArray(data)) {
+      console.warn(`Warning: relationships.yaml contains non-array content (received ${data === null ? "null" : typeof data}). Expected an array of relationships. Skipping relationship loading.`);
+      return;
+    }
+    this.relationships = Relationships.fromArray(data);
+    for (let i = 0; i < data.length; i++) {
+      const rel = data[i], edge = {
+        id: `rel-${i}-${crypto.randomBytes(4).toString("hex")}`,
+        source: rel.source,
+        destination: rel.target,
+        predicate: rel.predicate,
+        properties: rel.properties,
+        category: rel.category
+      };
+      try {
+        this.graph.addEdge(edge);
+      } catch {
+      }
     }
   }
   /**
@@ -366,88 +437,224 @@ Run "dr init" to create a model.`);
    * @returns Loaded Model instance
    */
   static async load(startPath, options = {}) {
-    const span = isTelemetryEnabled ? startSpan("model.load", {
-      "model.path": startPath || process.cwd(),
-      "model.type": "dr-legacy"
-    }) : null;
-    try {
-      const { projectRoot, manifestPath } = await Model.resolveModelPaths(startPath), yaml = await import("yaml"), yamlContent = await fs.readFile(manifestPath, "utf-8"), legacyData = yaml.parse(yamlContent), manifestData = {
-        name: legacyData.project?.name || "Unnamed Model",
-        description: legacyData.project?.description || "",
-        version: legacyData.project?.version || legacyData.version || "0.1.0",
-        specVersion: legacyData.spec_version || "0.6.0",
-        created: legacyData.created || (/* @__PURE__ */ new Date()).toISOString(),
-        modified: legacyData.updated || (/* @__PURE__ */ new Date()).toISOString(),
-        // Preserve Python CLI metadata fields
-        layers: legacyData.layers,
-        statistics: legacyData.statistics || {
-          total_elements: 0,
-          total_relationships: 0,
-          completeness: 0,
-          last_validation: null,
-          validation_status: "not_validated"
-        },
-        cross_references: legacyData.cross_references || {
-          total: 0,
-          by_type: {}
-        },
-        conventions: legacyData.conventions,
-        upgrade_history: legacyData.upgrade_history || []
+    return startActiveSpan("model.load", async (span) => {
+      const { projectRoot, manifestPath } = await Model.resolveModelPaths(startPath), yaml = await import("yaml"), yamlContent = await fs.readFile(manifestPath, "utf-8"), manifestYaml = yaml.parse(yamlContent), manifestData = {
+        name: manifestYaml.project?.name || "Unnamed Model",
+        description: manifestYaml.project?.description || "",
+        version: manifestYaml.project?.version || manifestYaml.version || "0.1.0",
+        specVersion: manifestYaml.spec_version || "0.6.0",
+        created: manifestYaml.created || (/* @__PURE__ */ new Date()).toISOString(),
+        modified: manifestYaml.updated || (/* @__PURE__ */ new Date()).toISOString()
       }, manifest = new Manifest(manifestData), model = new Model(projectRoot, manifest, options);
       if (!options.lazyLoad)
         try {
-          if (legacyData.layers)
-            for (const layerName of Object.keys(legacyData.layers))
-              legacyData.layers[layerName].enabled !== !1 && await model.loadLayer(layerName);
+          if (manifestYaml.layers)
+            for (const layerName of Object.keys(manifestYaml.layers))
+              manifestYaml.layers[layerName].enabled !== !1 && (!options.layers || options.layers.includes(layerName)) && await model.loadLayer(layerName);
           else {
             const modelDir = manifestPath.replace("/manifest.yaml", ""), entries = await fs.readdir(modelDir, { withFileTypes: !0 });
             for (const entry of entries)
               if (entry.isDirectory() && entry.name.match(/^\d{2}_/)) {
                 const layerName = entry.name.replace(/^\d{2}_/, "");
-                await model.loadLayer(layerName);
+                (!options.layers || options.layers.includes(layerName)) && await model.loadLayer(layerName);
               }
           }
         } catch (e) {
-          if (process.env.DEBUG) {
-            const error = e instanceof Error ? e.message : String(e);
-            error.includes("ENOENT") || console.debug(`Warning: Failed to load layers directory: ${error}`);
-          }
+          if (!(e?.code === "ENOENT"))
+            throw new Error(`Failed to load layers: ${e instanceof Error ? e.message : String(e)}`);
         }
       await model.loadRelationships();
+      const activePath = path.join(projectRoot, "documentation-robotics", "changesets", ".active");
+      try {
+        const activeId = (await fs.readFile(activePath, "utf-8")).trim();
+        if (activeId) {
+          model._activeChangesetId = activeId;
+          const changeset = await new StagedChangesetStorage(projectRoot).load(activeId);
+          if (changeset)
+            for (const change of changeset.changes) {
+              if ((change.type === "add" || change.type === "update" || change.type === "delete") && model._stagedLayerNames.add(change.layerName), change.type === "relationship-add" && change.after) {
+                const rel = change.after;
+                model.relationships.find(rel.source, rel.target, rel.predicate).length === 0 && model.relationships.add({
+                  source: rel.source,
+                  target: rel.target,
+                  predicate: rel.predicate,
+                  layer: rel.layer,
+                  ...rel.targetLayer ? { targetLayer: rel.targetLayer } : {},
+                  category: rel.category ?? "structural",
+                  ...rel.properties ? { properties: rel.properties } : {}
+                });
+              }
+              if (change.type === "relationship-delete" && change.before) {
+                const rel = change.before;
+                model.relationships.delete(rel.source, rel.target, rel.predicate);
+              }
+            }
+        }
+      } catch {
+        model._activeChangesetId = null;
+      }
       let entityCount = 0;
       for (const layer of model.layers.values())
         entityCount += layer.elements.size;
-      return isTelemetryEnabled && span && (span.setAttribute("model.entity_count", entityCount), span.setAttribute("model.layer_count", model.layers.size)), model;
-    } finally {
-      isTelemetryEnabled && endSpan(span);
-    }
+      return span.setAttribute("model.entity_count", entityCount), span.setAttribute("model.layer_count", model.layers.size), model;
+    }, {
+      "model.path": startPath || process.cwd(),
+      "model.type": "dr"
+    });
   }
   /**
-   * Initialize a new model in a directory (legacy format)
+   * Initialize a new model in a directory
    */
   static async init(rootPath, manifestData, options = {}) {
     await ensureDir(`${rootPath}/documentation-robotics/model`);
-    const layerOrder = [
-      "motivation",
-      "business",
-      "security",
-      "application",
-      "technology",
-      "api",
-      "data-model",
-      "datastore",
-      "ux",
-      "navigation",
-      "apm",
-      "testing"
-    ];
-    for (let i = 0; i < layerOrder.length; i++) {
-      const orderNum = String(i + 1).padStart(2, "0"), layerName = layerOrder[i];
+    for (let i = 0; i < CANONICAL_LAYER_NAMES.length; i++) {
+      const orderNum = String(i + 1).padStart(2, "0"), layerName = CANONICAL_LAYER_NAMES[i];
       await ensureDir(`${rootPath}/documentation-robotics/model/${orderNum}_${layerName}`);
     }
     const manifest = new Manifest(manifestData), model = new Model(rootPath, manifest, options);
     return await model.saveManifest(), model;
   }
+  /**
+   * Graph-based API methods for querying the model
+   * These methods delegate to the underlying GraphModel for efficient queries
+   */
+  /**
+   * Get a node by its UUID
+   */
+  getNode(id) {
+    return this.graph.getNode(id);
+  }
+  /**
+   * Get all nodes in a specific layer
+   */
+  getNodesByLayer(layerId) {
+    return this.graph.getNodesByLayer(layerId);
+  }
+  /**
+   * Get all nodes of a specific type
+   */
+  getNodesByType(type) {
+    return this.graph.getNodesByType(type);
+  }
+  /**
+   * Get all edges (relationships) in the model
+   */
+  getAllEdges() {
+    return this.graph.getAllEdges();
+  }
+  /**
+   * Get edges originating from a specific node
+   */
+  getEdgesFrom(nodeId, predicate) {
+    return this.graph.getEdgesFrom(nodeId, predicate);
+  }
+  /**
+   * Get edges terminating at a specific node
+   */
+  getEdgesTo(nodeId, predicate) {
+    return this.graph.getEdgesTo(nodeId, predicate);
+  }
+  /**
+   * Get edges between two specific nodes
+   */
+  getEdgesBetween(sourceId, destinationId, predicate) {
+    return this.graph.getEdgesBetween(sourceId, destinationId, predicate);
+  }
+  /**
+   * Traverse the graph starting from a node, following a specific predicate
+   */
+  async traverse(startNodeId, predicate, maxDepth = 10) {
+    return this.graph.traverse(startNodeId, predicate, maxDepth);
+  }
+  /**
+   * Create a backup of the current model state
+   * Used for rollback support in migration operations
+   *
+   * @param label Descriptive label for the backup (e.g., "pre-migration")
+   * @returns Path to the backup directory
+   */
+  async createBackup(label) {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-"), backupDir = path.join(this.rootPath, ".dr-backups", `${label}-${timestamp}`);
+    await ensureDir(backupDir);
+    const layersSource = path.join(this.rootPath, "documentation-robotics", "model"), layersBackup = path.join(backupDir, "layers");
+    await this.directoryExists(layersSource) && await this.copyDirectory(layersSource, layersBackup);
+    const manifestSource = path.join(this.rootPath, "documentation-robotics", "model", "manifest.yaml"), manifestBackup = path.join(backupDir, "manifest.yaml");
+    return await this.fileExists(manifestSource) && await fs.copyFile(manifestSource, manifestBackup), backupDir;
+  }
+  /**
+   * Restore model from a backup directory
+   * Used for rollback after failed migrations
+   *
+   * @param backupPath Path to the backup directory
+   */
+  async restoreFromBackup(backupPath) {
+    const layersBackup = path.join(backupPath, "layers"), layersTarget = path.join(this.rootPath, "documentation-robotics", "model");
+    await this.directoryExists(layersBackup) && await this.copyDirectory(layersBackup, layersTarget);
+    const manifestBackup = path.join(backupPath, "manifest.yaml"), manifestTarget = path.join(this.rootPath, "documentation-robotics", "model", "manifest.yaml");
+    await this.fileExists(manifestBackup) && await fs.copyFile(manifestBackup, manifestTarget);
+    const reloadedModel = await Model.load(this.rootPath, { lazyLoad: this.lazyLoad });
+    this.layers = reloadedModel.layers, this.manifest = reloadedModel.manifest, this.graph = reloadedModel.graph, this.relationships = reloadedModel.relationships;
+  }
+  /**
+   * Save dirty layers with atomic write semantics
+   * Writes to temporary file first, then renames on success to ensure data safety
+   *
+   * @throws Error if atomic write fails
+   */
+  async saveDirtyLayersAtomic() {
+    const tempLayerWrites = [];
+    try {
+      for (const layer of this.layers.values())
+        if (layer.isDirty()) {
+          const tempPath = `${path.join(this.rootPath, "documentation-robotics", "model", `${layer.name}_layer`)}.tmp`;
+          await ensureDir(tempPath);
+          for (const element of layer.elements.values()) {
+            const elementPath = path.join(tempPath, `${element.path || element.id}.json`), content = JSON.stringify(element.toJSON(), null, 2);
+            await writeFile(elementPath, content);
+          }
+          tempLayerWrites.push({ layer, tempPath });
+        }
+      for (const { layer, tempPath } of tempLayerWrites) {
+        const layerPath = path.join(this.rootPath, "documentation-robotics", "model", `${layer.name}_layer`);
+        await this.directoryExists(layerPath) && await fs.rm(layerPath, { recursive: !0, force: !0 }), await fs.rename(tempPath, layerPath);
+      }
+    } catch (error) {
+      for (const { tempPath } of tempLayerWrites)
+        await this.directoryExists(tempPath) && await fs.rm(tempPath, { recursive: !0, force: !0 });
+      throw error;
+    }
+  }
+  /**
+   * Helper: Check if file exists
+   */
+  async fileExists(filePath) {
+    try {
+      return await fs.access(filePath), !0;
+    } catch {
+      return !1;
+    }
+  }
+  /**
+   * Helper: Check if directory exists
+   */
+  async directoryExists(dirPath) {
+    try {
+      return (await fs.stat(dirPath)).isDirectory();
+    } catch {
+      return !1;
+    }
+  }
+  /**
+   * Helper: Recursively copy directory
+   */
+  async copyDirectory(src, dest) {
+    await ensureDir(dest);
+    const entries = await fs.readdir(src, { withFileTypes: !0 });
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry.name), destPath = path.join(dest, entry.name);
+      entry.isDirectory() ? await this.copyDirectory(srcPath, destPath) : await fs.copyFile(srcPath, destPath);
+    }
+  }
 }
 export {
   Model