@unified-product-graph/sdk 0.6.0

package/dist/index.js

@@ -0,0 +1,2732 @@
+import {
+  BUSINESS_AREA_META,
+  DESCRIPTION_SOFT_LIMIT,
+  ENTITY_CLASSIFICATION,
+  InferEdgeTypeError,
+  PROPERTY_TREE_SOFT_BYTES,
+  PROPERTY_TREE_SOFT_DEPTH,
+  TIER_CLUSTER_META,
+  TIER_DESCRIPTIONS,
+  TITLE_SOFT_LIMIT,
+  UPG_ANTI_PATTERNS,
+  UPG_CROSS_EDGE_TYPES,
+  UPG_EDGE_CATALOG,
+  UPG_REGIONS,
+  UPG_TYPES,
+  UPG_VERSION,
+  UnknownEntityTypeError,
+  buildAdjacentEdges,
+  buildAlternateAnchors,
+  buildAnchorHint,
+  buildResolverHints,
+  checkLengthCaps,
+  checkPropertyTypes,
+  classifyDanglingEdges,
+  coerceProductStage,
+  collectAntiPatternInputs,
+  collectSlugsForType,
+  computeSchemaDriftSummary,
+  edgeId,
+  evaluateExpression,
+  executeInspect,
+  executePlan,
+  executePrioritise,
+  executeReflect,
+  executeTrace,
+  generateSlug,
+  getClassification,
+  getEntitiesForBusinessArea,
+  getEntitiesForCluster,
+  getEntitiesForTier,
+  getEntitiesForTierAndArea,
+  getEntitiesUpToTier,
+  getLifecycleForType,
+  getReplacementType,
+  getTierEntityCount,
+  getTierForStage,
+  inferEdgeType,
+  inferEdgeTypeWithTier,
+  isRelevantForStage,
+  migrateEdge,
+  migrateNodeProperties,
+  nodeId,
+  productId,
+  renderDanglingReport,
+  renderDriftSummary,
+  renderPropertyTypeWarning,
+  resolveEntityType,
+  resolveSlugCollision,
+  rotateSlug,
+  validateClassificationCoverage,
+  validateEdgeTypePair,
+  validateProductStageStrict,
+  validateUPGDocument
+} from "./chunk-ARDXTSGG.js";
+
+// src/store.ts
+import * as fs from "fs/promises";
+import * as path from "path";
+import { createHash } from "crypto";
+var UPGFileStore = class {
+  doc;
+  filePath;
+  dirty = false;
+  saveTimer = null;
+  selfWriteInProgress = false;
+  watcher = null;
+  // Indexes for O(1) lookups
+  nodeMap = /* @__PURE__ */ new Map();
+  edgeMap = /* @__PURE__ */ new Map();
+  edgesByNode = /* @__PURE__ */ new Map();
+  // nodeId → Set<edgeId>
+  // Session change log
+  changeLog = [];
+  // Content hash for cache-aware responses
+  contentHash = "";
+  // ── Concurrent write protection ─────────────────────────────────────────
+  // Baseline = the raw file hash at the time we loaded or last saved.
+  // If disk hash != baseline when we try to save, another process modified the file.
+  baselineFileHash = "";
+  // Snapshot of node/edge IDs at baseline — used for three-way merge
+  baselineNodeIds = /* @__PURE__ */ new Set();
+  baselineEdgeIds = /* @__PURE__ */ new Set();
+  // Last merge result (available to the server for reporting)
+  lastMergeResult = null;
+  // ── Integrity protection ───────────────────────────────────────────────
+  // Last integrity check result (available to the server for reporting)
+  lastIntegrityReport = null;
+  // Set of known UPG entity types for schema validation
+  knownTypes = new Set(UPG_TYPES);
+  // ── Dangling-edge tracking ───────────────────────────────────
+  lastDanglingReport = null;
+  lastDriftSummary = null;
+  // ── Load / Save ──────────────────────────────────────────────────────────
+  /** Hash raw file bytes — used for baseline comparison (NOT the same as contentHash) */
+  hashRawContent(raw) {
+    return createHash("sha256").update(raw).digest("hex").slice(0, 32);
+  }
+  /** Compute integrity checksum over nodes + edges content (deterministic) */
+  computeIntegrityChecksum() {
+    const sortedNodes = [...this.doc.nodes].sort((a, b) => a.id.localeCompare(b.id));
+    const sortedEdges = [...this.doc.edges].sort((a, b) => a.id.localeCompare(b.id));
+    const content = JSON.stringify({ nodes: sortedNodes, edges: sortedEdges });
+    return createHash("sha256").update(content).digest("hex").slice(0, 32);
+  }
+  /** Stamp the document with current integrity checksum */
+  stampIntegrity() {
+    this.doc._integrity = {
+      checksum: this.computeIntegrityChecksum(),
+      verified_at: (/* @__PURE__ */ new Date()).toISOString(),
+      verified_by: "upg-mcp-local"
+    };
+  }
+  /** Verify integrity and quarantine invalid entities if file was modified externally */
+  verifyIntegrity() {
+    const report = { tampered: false, quarantined: [], orphanedEdges: 0 };
+    if (!this.doc._integrity) {
+      this.stampIntegrity();
+      return report;
+    }
+    const currentChecksum = this.computeIntegrityChecksum();
+    if (currentChecksum === this.doc._integrity.checksum) {
+      return report;
+    }
+    report.tampered = true;
+    const validNodeIds = /* @__PURE__ */ new Set();
+    const quarantinedIds = /* @__PURE__ */ new Set();
+    this.doc.nodes = this.doc.nodes.filter((node) => {
+      if (!node.id || !node.type || !node.title) {
+        report.quarantined.push({
+          id: node.id || "unknown",
+          type: node.type || "unknown",
+          title: node.title || "untitled",
+          reason: "Missing required field (id, type, or title)"
+        });
+        quarantinedIds.add(node.id || "unknown");
+        return false;
+      }
+      if (!this.knownTypes.has(node.type) && node.type !== "product" && node.type !== "document") {
+        report.quarantined.push({
+          id: node.id,
+          type: node.type,
+          title: node.title,
+          reason: `Unknown entity type: "${node.type}"`
+        });
+        quarantinedIds.add(node.id);
+        return false;
+      }
+      validNodeIds.add(node.id);
+      return true;
+    });
+    const beforeEdgeCount = this.doc.edges.length;
+    this.doc.edges = this.doc.edges.filter((edge) => {
+      if (!edge.id || !edge.source || !edge.target || !edge.type) return false;
+      return validNodeIds.has(edge.source) && validNodeIds.has(edge.target);
+    });
+    report.orphanedEdges = beforeEdgeCount - this.doc.edges.length;
+    if (report.quarantined.length > 0 || report.orphanedEdges > 0) {
+      this.stampIntegrity();
+      this.dirty = true;
+    } else {
+      this.stampIntegrity();
+      this.dirty = true;
+    }
+    return report;
+  }
+  getIntegrityReport() {
+    return this.lastIntegrityReport;
+  }
+  /** Snapshot current node/edge IDs as baseline for three-way merge */
+  snapshotBaseline() {
+    this.baselineNodeIds = new Set(this.doc.nodes.map((n) => n.id));
+    this.baselineEdgeIds = new Set(this.doc.edges.map((e) => e.id));
+  }
+  getLastMergeResult() {
+    return this.lastMergeResult;
+  }
+  async load(filePath) {
+    this.filePath = path.resolve(filePath);
+    const raw = await fs.readFile(this.filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    const result = validateUPGDocument(parsed);
+    if (!result.valid) {
+      const msgs = result.errors.map((e) => `  ${e.path}: ${e.message}`).join("\n");
+      throw new Error(`Invalid UPG document:
+${msgs}`);
+    }
+    this.doc = parsed;
+    if (this.doc.product?.stage !== void 0) {
+      const coercion = coerceProductStage(this.doc.product.stage);
+      if (coercion.wasCoerced && coercion.canonical) {
+        process.stderr.write(
+          `[product-stage] Product stage ${JSON.stringify(coercion.originalValue)} is not a canonical UPGProductStage. Coerced in-memory to ${JSON.stringify(coercion.canonical)}. Run \`migrate_properties\` (or update the file) to persist the canonical value. File: ${this.filePath}
+`
+        );
+        this.doc = {
+          ...this.doc,
+          product: { ...this.doc.product, stage: coercion.canonical }
+        };
+      } else if (coercion.wasUnknown) {
+        process.stderr.write(
+          `[product-stage] Product stage ${JSON.stringify(coercion.originalValue)} is not a canonical UPGProductStage and has no documented coercion target. Treating as missing in lifecycle calculations. Set a canonical value via \`update_node\` to clear this warning. File: ${this.filePath}
+`
+        );
+      }
+    }
+    this.lastIntegrityReport = this.verifyIntegrity();
+    this.rebuildIndexes();
+    this.computeHash();
+    this.baselineFileHash = this.hashRawContent(raw);
+    this.snapshotBaseline();
+    this.lastDanglingReport = classifyDanglingEdges(
+      this.doc.edges,
+      new Set(this.doc.nodes.map((n) => n.id))
+    );
+    const rendered = renderDanglingReport(this.lastDanglingReport, this.filePath);
+    if (rendered) process.stderr.write(rendered + "\n");
+    this.lastDriftSummary = computeSchemaDriftSummary(this.doc);
+    const driftRendered = renderDriftSummary(this.lastDriftSummary, this.filePath);
+    if (driftRendered) process.stderr.write(driftRendered + "\n");
+    await this.startWatching();
+  }
+  /**
+   * Snapshot of the dangling-edge classification computed at load time.
+   * Returns null until `load()` has run.
+   */
+  getDanglingReport() {
+    return this.lastDanglingReport;
+  }
+  /**
+   * Snapshot of the schema-drift summary computed at load time.
+   * Counts only — full per-node breakdown is `validate_graph`.
+   * Returns null until `load()` has run.
+   */
+  getDriftSummary() {
+    return this.lastDriftSummary;
+  }
+  /**
+   * Drop edges matching the given dangling classes from the document. Used by
+   * the `repair_dangling_edges` tool with `dry_run: false`. Caller is
+   * responsible for choosing classes — this method does not protect
+   * `expected` cross-product edges by default; pass an empty array to no-op.
+   */
+  dropDanglingEdges(classes) {
+    if (classes.length === 0) {
+      return { dropped: 0, remaining: this.lastDanglingReport ?? { total: 0, by_class: { expected: 0, suspect: 0, corrupt: 0 }, edges: [] } };
+    }
+    const report = classifyDanglingEdges(
+      this.doc.edges,
+      new Set(this.doc.nodes.map((n) => n.id))
+    );
+    const targetClasses = new Set(classes);
+    const dropIds = new Set(
+      report.edges.filter((e) => targetClasses.has(e.class)).map((e) => e.id)
+    );
+    if (dropIds.size === 0) {
+      return { dropped: 0, remaining: report };
+    }
+    this.doc.edges = this.doc.edges.filter((e) => !dropIds.has(e.id));
+    this.rebuildIndexes();
+    this.dirty = true;
+    this.computeHash();
+    this.lastDanglingReport = classifyDanglingEdges(
+      this.doc.edges,
+      new Set(this.doc.nodes.map((n) => n.id))
+    );
+    return { dropped: dropIds.size, remaining: this.lastDanglingReport };
+  }
+  async save() {
+    if (!this.dirty) return;
+    let diskRaw;
+    try {
+      diskRaw = await fs.readFile(this.filePath, "utf-8");
+    } catch {
+      diskRaw = "";
+    }
+    const diskHash = diskRaw ? this.hashRawContent(diskRaw) : "";
+    if (diskHash && diskHash !== this.baselineFileHash) {
+      this.lastMergeResult = await this.mergeWithDisk(diskRaw);
+      if (this.lastMergeResult.conflicts.length > 0) {
+        const conflictDesc = this.lastMergeResult.conflicts.map((c) => `  Node ${c.nodeId}: field "${c.field}" \u2014 ours: ${JSON.stringify(c.ours)}, theirs: ${JSON.stringify(c.theirs)}`).join("\n");
+        throw new Error(
+          `CONFLICT: The .upg file was modified by another session.
+  Nodes added by other session: ${this.lastMergeResult.nodesFromDisk}
+  Edges added by other session: ${this.lastMergeResult.edgesFromDisk}
+  Conflicts (same node modified differently):
+${conflictDesc}
+
+Auto-merge failed. Run the save again after resolving conflicts, or reload the file.`
+        );
+      }
+      this.rebuildIndexes();
+    }
+    this.doc.exported_at = (/* @__PURE__ */ new Date()).toISOString();
+    if (!this.doc.source.tool) {
+      this.doc.source.tool = "upg-mcp-local";
+    }
+    this.stampIntegrity();
+    const output = JSON.stringify(this.doc, null, 2) + "\n";
+    const tmpPath = this.filePath + ".tmp";
+    this.selfWriteInProgress = true;
+    try {
+      await fs.writeFile(tmpPath, output, "utf-8");
+      await fs.rename(tmpPath, this.filePath);
+      this.dirty = false;
+      this.computeHash();
+      this.baselineFileHash = this.hashRawContent(output);
+      this.snapshotBaseline();
+    } finally {
+      setTimeout(() => {
+        this.selfWriteInProgress = false;
+      }, 150);
+    }
+  }
+  // ── Three-Way Merge ───────────────────────────────────────────────────────
+  //
+  // Three states:
+  //   baseline = what was on disk when we loaded (or last saved)
+  //   disk     = what's on disk now (another session wrote this)
+  //   ours     = our in-memory state
+  //
+  // Strategy:
+  //   - Nodes/edges in disk but not in baseline → added by other session → keep
+  //   - Nodes/edges in ours but not in baseline → added by this session → keep
+  //   - Nodes/edges in baseline but not in disk → deleted by other session → accept deletion
+  //   - Nodes/edges in baseline but not in ours → deleted by this session → accept deletion
+  //   - Nodes in both disk and ours with different content → CONFLICT
+  //
+  async mergeWithDisk(diskRaw) {
+    let diskDoc;
+    try {
+      const parsed = JSON.parse(diskRaw);
+      if (!validateUPGDocument(parsed).valid) {
+        return { merged: true, nodesAdded: 0, edgesAdded: 0, nodesFromDisk: 0, edgesFromDisk: 0, conflicts: [] };
+      }
+      diskDoc = parsed;
+    } catch {
+      return { merged: true, nodesAdded: 0, edgesAdded: 0, nodesFromDisk: 0, edgesFromDisk: 0, conflicts: [] };
+    }
+    const diskNodeMap = new Map(diskDoc.nodes.map((n) => [n.id, n]));
+    const diskEdgeMap = new Map(diskDoc.edges.map((e) => [e.id, e]));
+    const ourNodeMap = this.nodeMap;
+    const ourEdgeMap = this.edgeMap;
+    const conflicts = [];
+    let nodesFromDisk = 0;
+    let edgesFromDisk = 0;
+    for (const [id, diskNode] of diskNodeMap) {
+      if (!this.baselineNodeIds.has(id)) {
+        if (!ourNodeMap.has(id)) {
+          this.doc.nodes.push(diskNode);
+          nodesFromDisk++;
+        }
+      } else if (ourNodeMap.has(id)) {
+        const ourNode = ourNodeMap.get(id);
+        const ourModified = ourNode.title !== diskNode.title || ourNode.status !== diskNode.status;
+        if (ourModified) {
+          if (ourNode.title !== diskNode.title) {
+            conflicts.push({ nodeId: id, field: "title", ours: ourNode.title, theirs: diskNode.title });
+          }
+          if (ourNode.status !== diskNode.status) {
+            conflicts.push({ nodeId: id, field: "status", ours: ourNode.status, theirs: diskNode.status });
+          }
+        }
+      }
+    }
+    for (const [id, diskEdge] of diskEdgeMap) {
+      if (!this.baselineEdgeIds.has(id)) {
+        if (!ourEdgeMap.has(id)) {
+          const sourceExists = ourNodeMap.has(diskEdge.source) || diskNodeMap.has(diskEdge.source);
+          const targetExists = ourNodeMap.has(diskEdge.target) || diskNodeMap.has(diskEdge.target);
+          if (sourceExists && targetExists) {
+            this.doc.edges.push(diskEdge);
+            edgesFromDisk++;
+          }
+        }
+      }
+    }
+    for (const id of this.baselineNodeIds) {
+      if (!diskNodeMap.has(id) && ourNodeMap.has(id)) {
+        const ourNode = ourNodeMap.get(id);
+        const weModified = this.changeLog.some(
+          (c) => c.id === id && c.entity === "node" && c.action === "update"
+        );
+        if (!weModified) {
+          this.doc.nodes = this.doc.nodes.filter((n) => n.id !== id);
+          this.doc.edges = this.doc.edges.filter(
+            (e) => e.source !== id && e.target !== id
+          );
+        }
+      }
+    }
+    return {
+      merged: conflicts.length === 0,
+      nodesAdded: nodesFromDisk,
+      edgesAdded: edgesFromDisk,
+      nodesFromDisk,
+      edgesFromDisk,
+      conflicts
+    };
+  }
+  async flush() {
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+      this.saveTimer = null;
+    }
+    await this.save();
+  }
+  /**
+   * Mark the store as dirty so the next `flush()` or `save()` writes to disk.
+   * Use this when an external caller mutates the document object directly (e.g.
+   * the cross-edge migration which modifies `doc.edges` in-place via
+   * `UPGPortfolioStore.migrateCrossEdgesFromDoc`).
+   */
+  markDirty() {
+    this.dirty = true;
+  }
+  scheduleSave() {
+    this.dirty = true;
+    if (this.saveTimer) clearTimeout(this.saveTimer);
+    this.saveTimer = setTimeout(() => this.save(), 300);
+  }
+  // ── File Watching ────────────────────────────────────────────────────────
+  async startWatching() {
+    if (this.watcher) return;
+    const { watch } = await import("chokidar");
+    this.watcher = watch(this.filePath, {
+      persistent: false,
+      awaitWriteFinish: { stabilityThreshold: 200, pollInterval: 50 }
+    });
+    this.watcher.on("change", async () => {
+      if (this.selfWriteInProgress) return;
+      try {
+        const raw = await fs.readFile(this.filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!validateUPGDocument(parsed).valid) return;
+        if (this.dirty) {
+          const result = await this.mergeWithDisk(raw);
+          this.lastMergeResult = result;
+          if (result.conflicts.length === 0 && (result.nodesFromDisk > 0 || result.edgesFromDisk > 0)) {
+            this.rebuildIndexes();
+            this.computeHash();
+            this.baselineFileHash = this.hashRawContent(raw);
+          }
+        } else {
+          this.doc = parsed;
+          this.rebuildIndexes();
+          this.computeHash();
+          this.baselineFileHash = this.hashRawContent(raw);
+          this.snapshotBaseline();
+          this.dirty = false;
+        }
+      } catch {
+      }
+    });
+  }
+  stopWatching() {
+    this.watcher?.close();
+    this.watcher = null;
+  }
+  // ── Index Management ─────────────────────────────────────────────────────
+  rebuildIndexes() {
+    this.nodeMap.clear();
+    this.edgeMap.clear();
+    this.edgesByNode.clear();
+    for (const node of this.doc.nodes) {
+      this.nodeMap.set(node.id, node);
+    }
+    for (const edge of this.doc.edges) {
+      this.edgeMap.set(edge.id, edge);
+      this.indexEdgeForNode(edge);
+    }
+  }
+  indexEdgeForNode(edge) {
+    for (const nodeId2 of [edge.source, edge.target]) {
+      let set = this.edgesByNode.get(nodeId2);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        this.edgesByNode.set(nodeId2, set);
+      }
+      set.add(edge.id);
+    }
+  }
+  unindexEdgeForNode(edge) {
+    this.edgesByNode.get(edge.source)?.delete(edge.id);
+    this.edgesByNode.get(edge.target)?.delete(edge.id);
+  }
+  // ── Hash ─────────────────────────────────────────────────────────────────
+  computeHash() {
+    const content = JSON.stringify({
+      nodes: this.doc.nodes.length,
+      edges: this.doc.edges.length,
+      nodeIds: this.doc.nodes.map((n) => n.id).sort(),
+      edgeIds: this.doc.edges.map((e) => e.id).sort(),
+      lastMod: this.doc.exported_at
+    });
+    this.contentHash = createHash("sha256").update(content).digest("hex").slice(0, 16);
+  }
+  getContentHash() {
+    return this.contentHash;
+  }
+  // ── Reads ────────────────────────────────────────────────────────────────
+  getFilePath() {
+    return this.filePath;
+  }
+  getDocument() {
+    return this.doc;
+  }
+  getProduct() {
+    return this.doc.product;
+  }
+  getNode(id) {
+    return this.nodeMap.get(id);
+  }
+  getEdge(id) {
+    return this.edgeMap.get(id);
+  }
+  getAllNodes() {
+    return this.doc.nodes;
+  }
+  getAllEdges() {
+    return this.doc.edges;
+  }
+  getEdgesForNode(nodeId2) {
+    const edgeIds = this.edgesByNode.get(nodeId2);
+    if (!edgeIds) return [];
+    return [...edgeIds].map((id) => this.edgeMap.get(id)).filter(Boolean);
+  }
+  // ── Change Log ──────────────────────────────────────────────────────────
+  logChange(action, entity, id, type, title) {
+    this.changeLog.push({
+      action,
+      entity,
+      id,
+      type,
+      title,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  getChanges(since) {
+    if (!since) return [...this.changeLog];
+    return this.changeLog.filter((c) => c.timestamp >= since);
+  }
+  // ── Writes ───────────────────────────────────────────────────────────────
+  addNode(node) {
+    this.doc.nodes.push(node);
+    this.nodeMap.set(node.id, node);
+    this.logChange("create", "node", node.id, node.type, node.title);
+    this.scheduleSave();
+  }
+  updateNode(id, patch) {
+    const node = this.nodeMap.get(id);
+    if (!node) throw new Error(`Node not found: ${id}`);
+    if (patch.type !== void 0) node.type = patch.type;
+    if (patch.title !== void 0) node.title = patch.title;
+    if (patch.description !== void 0) node.description = patch.description;
+    if (patch.tags !== void 0) node.tags = patch.tags;
+    if (patch.status !== void 0) node.status = patch.status;
+    if (patch.slug !== void 0 && patch.slug !== node.slug) {
+      rotateSlug(node, patch.slug);
+    }
+    if (patch.aliases !== void 0) node.aliases = patch.aliases;
+    if (patch.properties) {
+      node.properties = { ...node.properties ?? {}, ...patch.properties };
+    }
+    this.logChange("update", "node", node.id, node.type, node.title);
+    this.scheduleSave();
+    return node;
+  }
+  removeNode(id) {
+    const node = this.nodeMap.get(id);
+    if (!node) throw new Error(`Node not found: ${id}`);
+    const edgeIds = new Set(this.edgesByNode.get(id) ?? []);
+    const removedEdgeIds = [];
+    for (const edgeId2 of edgeIds) {
+      const edge = this.edgeMap.get(edgeId2);
+      if (edge) {
+        this.unindexEdgeForNode(edge);
+        this.edgeMap.delete(edgeId2);
+        removedEdgeIds.push(edgeId2);
+      }
+    }
+    this.doc.edges = this.doc.edges.filter((e) => !edgeIds.has(e.id));
+    this.edgesByNode.delete(id);
+    this.doc.nodes = this.doc.nodes.filter((n) => n.id !== id);
+    this.nodeMap.delete(id);
+    this.logChange("delete", "node", node.id, node.type, node.title);
+    for (const eid of removedEdgeIds) {
+      this.logChange("delete", "edge", eid, "cascade", void 0);
+    }
+    this.scheduleSave();
+    return { node, removedEdgeIds };
+  }
+  addEdge(edge, skipValidation = false) {
+    if (!skipValidation) {
+      if (!this.nodeMap.has(edge.source))
+        throw new Error(`Source node not found: ${edge.source}`);
+      if (!this.nodeMap.has(edge.target))
+        throw new Error(`Target node not found: ${edge.target}`);
+    }
+    this.doc.edges.push(edge);
+    this.edgeMap.set(edge.id, edge);
+    this.indexEdgeForNode(edge);
+    this.logChange("create", "edge", edge.id, edge.type, void 0);
+    this.scheduleSave();
+  }
+  removeEdge(id) {
+    const edge = this.edgeMap.get(id);
+    if (!edge) throw new Error(`Edge not found: ${id}`);
+    this.unindexEdgeForNode(edge);
+    this.edgeMap.delete(id);
+    this.doc.edges = this.doc.edges.filter((e) => e.id !== id);
+    this.logChange("delete", "edge", edge.id, edge.type, void 0);
+    this.scheduleSave();
+    return edge;
+  }
+  migrateType(fromType, toType, defaults) {
+    let migratedNodes = 0;
+    for (const node of this.doc.nodes) {
+      if (node.type === fromType) {
+        node.type = toType;
+        if (defaults && Object.keys(defaults).length > 0) {
+          node.properties = { ...defaults, ...node.properties ?? {} };
+        }
+        migratedNodes++;
+      }
+    }
+    const edgeResult = this.applyEdgeMigrations("0.0.0", UPG_VERSION);
+    this.scheduleSave();
+    return {
+      migratedNodes,
+      edgeRenames: edgeResult.renamed,
+      edgeDrops: edgeResult.dropped
+    };
+  }
+  /**
+   * Exact-match rename of every edge whose `type === from` to `to`. Optionally
+   * flips `source`/`target` for each affected edge. The catalog is intentionally
+   * NOT consulted here — this is the low-level primitive backing
+   * `rename_edge_type`. Catalog awareness lives in the wrappers
+   * tracked separately.
+   *
+   * Returns the IDs of every edge that was actually mutated. The internal
+   * `edgesByNode` index is keyed by node id, so a flip does not require
+   * re-indexing — both endpoints are already tracked for the same edge id.
+   */
+  renameEdgeType(from, to, flip = false) {
+    const ids = [];
+    for (const edge of this.doc.edges) {
+      if (edge.type !== from) continue;
+      edge.type = to;
+      if (flip) {
+        const oldSource = edge.source;
+        edge.source = edge.target;
+        edge.target = oldSource;
+      }
+      this.logChange("update", "edge", edge.id, edge.type, void 0);
+      ids.push(edge.id);
+    }
+    if (ids.length > 0) this.scheduleSave();
+    return { renamed: ids.length, ids };
+  }
+  /**
+   * Apply every applicable rule from `UPG_EDGE_MIGRATIONS` (the v0.2.4
+   * canonical edge registry) to the loaded graph.
+   * Renames retarget the edge type; flipped renames swap source/target;
+   * dropped edges are removed entirely. Endpoint guards in the migration
+   * rules check post-migration node types — so callers should run any
+   * needed `migrateType` / `applySplit` pass on nodes BEFORE calling this.
+   *
+   * Wave 3 of the MCP edge-primitives cascade.
+   */
+  applyEdgeMigrations(fromVersion, toVersion) {
+    const renamed = [];
+    const dropped = [];
+    const edgeIds = this.doc.edges.map((e) => e.id);
+    for (const id of edgeIds) {
+      const edge = this.edgeMap.get(id);
+      if (!edge) continue;
+      const sourceNode = this.nodeMap.get(edge.source);
+      const targetNode = this.nodeMap.get(edge.target);
+      const result = migrateEdge(edge, fromVersion, toVersion, {
+        sourceType: sourceNode?.type,
+        targetType: targetNode?.type
+      });
+      if (result === null) {
+        dropped.push({ id, from: edge.type });
+        this.removeEdge(id);
+        continue;
+      }
+      if (result === edge) continue;
+      const oldType = edge.type;
+      const flipped = result.source !== edge.source;
+      edge.type = result.type;
+      if (flipped) {
+        edge.source = result.source;
+        edge.target = result.target;
+      }
+      this.logChange("update", "edge", edge.id, edge.type, void 0);
+      renamed.push({ id: edge.id, from: oldType, to: edge.type, flipped });
+    }
+    if (renamed.length > 0 || dropped.length > 0) this.scheduleSave();
+    return { renamed, dropped };
+  }
+  applyPropertyMigrations(fromVersion, toVersion) {
+    const top_level_renames = [];
+    const lifted_properties = [];
+    const dropped_props = [];
+    const dropped_self_referential = [];
+    let mutatedAny = false;
+    for (let i = 0; i < this.doc.nodes.length; i++) {
+      const original = this.doc.nodes[i];
+      const { node: migrated, changes } = migrateNodeProperties(
+        original,
+        fromVersion,
+        toVersion
+      );
+      if (changes.length === 0) continue;
+      for (const change of changes) {
+        switch (change.kind) {
+          case "dropped":
+            dropped_props.push({ id: original.id, key: change.key });
+            break;
+          case "renamed_top_level":
+            top_level_renames.push({ id: original.id, from: change.from, to: change.to, value_changed: change.value_changed });
+            break;
+          case "lifted_to_top_level":
+            lifted_properties.push({ id: original.id, from_property: change.from_property, to: change.to, value_changed: change.value_changed });
+            break;
+          case "self_ref_dropped":
+            dropped_self_referential.push({ id: original.id, field: change.field });
+            break;
+        }
+      }
+      const migratedNode = migrated;
+      this.doc.nodes[i] = migratedNode;
+      this.nodeMap.set(migratedNode.id, migratedNode);
+      this.logChange("update", "node", migratedNode.id, migratedNode.type, void 0);
+      mutatedAny = true;
+    }
+    if (mutatedAny) this.scheduleSave();
+    return { top_level_renames, lifted_properties, dropped_props, dropped_self_referential };
+  }
+};
+var UPGPortfolioStore = class {
+  doc = null;
+  filePath = null;
+  dirty = false;
+  saveTimer = null;
+  // ── Load / Save ─────────────────────────────────────────────────────────────
+  /**
+   * Load an existing portfolio document from disk, or initialise an empty one
+   * at the given path if it does not exist.
+   *
+   * @param filePath Absolute path to the `.portfolio.upg` file.
+   * @param orgTitle Organisation title for newly created portfolios.
+   */
+  async loadOrInit(filePath, orgTitle = "Portfolio") {
+    this.filePath = path.resolve(filePath);
+    let raw;
+    try {
+      raw = await fs.readFile(this.filePath, "utf-8");
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+      this.doc = this.makeEmptyPortfolio(orgTitle);
+      this.dirty = true;
+      await this.flush();
+      return {
+        cross_edge_count: 0,
+        product_count: 0,
+        file_path: this.filePath
+      };
+    }
+    const parsed = JSON.parse(raw);
+    if (parsed.type !== "portfolio") {
+      throw new Error(
+        `Expected a portfolio document (type: "portfolio") at ${this.filePath}, but found type: "${parsed.type ?? "unknown"}"`
+      );
+    }
+    this.doc = parsed;
+    return {
+      cross_edge_count: this.doc.cross_edges.length,
+      product_count: this.doc.products.length,
+      file_path: this.filePath
+    };
+  }
+  /** Create a minimal valid UPGPortfolioDocument. */
+  makeEmptyPortfolio(orgTitle) {
+    return {
+      upg_version: UPG_VERSION,
+      type: "portfolio",
+      exported_at: (/* @__PURE__ */ new Date()).toISOString(),
+      source: { tool: "upg-mcp-local" },
+      organization: {
+        id: `org_${createHash("sha256").update(orgTitle).digest("hex").slice(0, 8)}`,
+        title: orgTitle
+      },
+      product_areas: [],
+      portfolios: [],
+      products: [],
+      cross_edges: []
+    };
+  }
+  /** Return the resolved portfolio file path, or null if not loaded. */
+  getFilePath() {
+    return this.filePath;
+  }
+  /** Return the loaded portfolio document, or null if not loaded. */
+  getDocument() {
+    return this.doc;
+  }
+  /** True when a portfolio document is loaded and ready. */
+  isLoaded() {
+    return this.doc !== null && this.filePath !== null;
+  }
+  /** Flush pending writes to disk. No-op if not dirty. */
+  async flush() {
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+      this.saveTimer = null;
+    }
+    await this.writeToDisk();
+  }
+  /**
+   * Mark the portfolio store as dirty so the next `flush()` writes to disk.
+   * Use this when an external caller mutates the document object directly via
+   * `getDocument()` rather than going through `addCrossEdge` /
+   * `removeCrossEdge`. Mirrors `UPGFileStore.markDirty()`.
+   */
+  markDirty() {
+    this.dirty = true;
+  }
+  scheduleSave() {
+    this.dirty = true;
+    if (this.saveTimer) clearTimeout(this.saveTimer);
+    this.saveTimer = setTimeout(() => void this.writeToDisk(), 300);
+  }
+  async writeToDisk() {
+    if (!this.dirty || !this.doc || !this.filePath) return;
+    this.doc.exported_at = (/* @__PURE__ */ new Date()).toISOString();
+    const output = JSON.stringify(this.doc, null, 2) + "\n";
+    const tmpPath = this.filePath + ".tmp";
+    await fs.writeFile(tmpPath, output, "utf-8");
+    await fs.rename(tmpPath, this.filePath);
+    this.dirty = false;
+  }
+  // ── Cross-edge writes ────────────────────────────────────────────────────────
+  /**
+   * Add a cross-product edge to the portfolio document. Both `source` and
+   * `target` must be qualified IDs (`{product_id}/{node_id}`).
+   */
+  addCrossEdge(edge) {
+    if (!this.doc) throw new Error("Portfolio document not loaded. Call loadOrInit() first.");
+    if (!edge.id) throw new Error("Cross-edge must have an id");
+    if (!edge.source.includes("/")) {
+      throw new Error(
+        `Cross-edge source must be a qualified ID ({product_id}/{node_id}), got: "${edge.source}"`
+      );
+    }
+    if (!edge.target.includes("/")) {
+      throw new Error(
+        `Cross-edge target must be a qualified ID ({product_id}/{node_id}), got: "${edge.target}"`
+      );
+    }
+    if (!UPG_CROSS_EDGE_TYPES.includes(edge.type)) {
+      throw new Error(
+        `Invalid cross-product edge type: "${edge.type}". Valid types: ${UPG_CROSS_EDGE_TYPES.join(", ")}`
+      );
+    }
+    this.doc.cross_edges.push(edge);
+    this.scheduleSave();
+  }
+  /**
+   * Remove a cross-product edge by ID.
+   * @returns The removed edge, or null if not found.
+   */
+  removeCrossEdge(edgeId2) {
+    if (!this.doc) throw new Error("Portfolio document not loaded.");
+    const idx = this.doc.cross_edges.findIndex((e) => e.id === edgeId2);
+    if (idx === -1) return null;
+    const [removed] = this.doc.cross_edges.splice(idx, 1);
+    this.scheduleSave();
+    return removed;
+  }
+  /** Return all cross-product edges. */
+  getAllCrossEdges() {
+    return this.doc?.cross_edges ?? [];
+  }
+  /** Find a cross-product edge by ID. */
+  getCrossEdge(id) {
+    return this.doc?.cross_edges.find((e) => e.id === id);
+  }
+  // ── Migration: inline → portfolio ─────────────────────────
+  //
+  // Scans `sourceDoc` for edges whose type is in UPG_CROSS_EDGE_TYPES, converts
+  // them to UPGCrossEdge objects with qualified IDs, and either:
+  //   - dry_run: true  → reports what would change without writing anything
+  //   - dry_run: false → writes them to this portfolio document AND removes them
+  //                       from sourceDoc.edges (sourceDoc must be saved separately)
+  //
+  // `sourceProductId` is the product ID that owns the sourceDoc. When the target
+  // node is NOT in sourceDoc, the caller must supply `targetProductId`; without
+  // it, those edges are skipped (reported in `skipped`).
+  /**
+   * Migrate inline cross-product edges from a product document into this
+   * portfolio document.
+   *
+   * **Does not flush** — caller is responsible for calling `.flush()` after
+   * inspecting the result and, for non-dry-run, also saving `sourceDoc`.
+   */
+  migrateCrossEdgesFromDoc(sourceDoc, sourceProductId, targetProductId, dryRun) {
+    if (!this.doc && !dryRun) {
+      throw new Error("Portfolio document not loaded. Call loadOrInit() first.");
+    }
+    const crossEdgeTypeSet = new Set(UPG_CROSS_EDGE_TYPES);
+    const sourceNodeIds = new Set(sourceDoc.nodes.map((n) => n.id));
+    const migrated = [];
+    const skipped = [];
+    const edgeIdsToRemove = [];
+    for (const edge of sourceDoc.edges) {
+      if (!crossEdgeTypeSet.has(edge.type)) continue;
+      const qualifiedSource = `${sourceProductId}/${edge.source}`;
+      let qualifiedTarget;
+      if (sourceNodeIds.has(edge.target)) {
+        qualifiedTarget = `${sourceProductId}/${edge.target}`;
+      } else if (targetProductId) {
+        qualifiedTarget = `${targetProductId}/${edge.target}`;
+      } else {
+        skipped.push({
+          id: edge.id,
+          reason: `Target node "${edge.target}" is not in the source product and no targetProductId was provided \u2014 cannot determine qualified target ID`
+        });
+        continue;
+      }
+      migrated.push({
+        id: edge.id,
+        source: qualifiedSource,
+        target: qualifiedTarget,
+        type: edge.type,
+        source_product_id: sourceProductId
+      });
+      edgeIdsToRemove.push(edge.id);
+    }
+    if (!dryRun && migrated.length > 0) {
+      if (!this.doc) throw new Error("Portfolio document not loaded.");
+      for (const m of migrated) {
+        const crossEdge = {
+          id: m.id,
+          source: m.source,
+          target: m.target,
+          type: m.type,
+          source_product_id: sourceProductId,
+          ...m.target.split("/")[0] !== sourceProductId ? { target_product_id: m.target.split("/")[0] } : {}
+        };
+        this.doc.cross_edges.push(crossEdge);
+      }
+      this.dirty = true;
+      const removeSet = new Set(edgeIdsToRemove);
+      sourceDoc.edges = sourceDoc.edges.filter((e) => !removeSet.has(e.id));
+    }
+    return { migrated, skipped, dry_run: dryRun };
+  }
+};
+
+// src/lib/tools.ts
+function canonicalType(name) {
+  return getReplacementType(name) ?? name;
+}
+function validateStatusAgainstLifecycle(entityType, status) {
+  const lifecycle = getLifecycleForType(entityType);
+  if (!lifecycle) return void 0;
+  const validPhases = lifecycle.phases.map((p) => p.id);
+  if (!validPhases.includes(status)) {
+    return `Status "${status}" is not a valid phase for type "${entityType}". Valid phases: [${validPhases.join(", ")}]`;
+  }
+  return void 0;
+}
+function getDefaultStatus(entityType) {
+  const lifecycle = getLifecycleForType(entityType);
+  return lifecycle?.initial_phase;
+}
+function autoFillSlug(node, store) {
+  if (node.slug) return;
+  if (!node.title) return;
+  const existing = collectSlugsForType(store.getAllNodes(), node.type);
+  const base = generateSlug(node.title);
+  node.slug = resolveSlugCollision(base, existing);
+}
+function normalizeTags(tags) {
+  if (!tags) return void 0;
+  if (Array.isArray(tags)) return tags;
+  if (typeof tags === "string") {
+    try {
+      const parsed = JSON.parse(tags);
+      if (Array.isArray(parsed)) return parsed;
+    } catch {
+    }
+    return [tags];
+  }
+  return void 0;
+}
+var BUSINESS_AREAS = {
+  identity: { emoji: "\u{1F3AF}", types: ["product", "vision", "mission"] },
+  understanding: { emoji: "\u{1F464}", types: ["persona", "job", "need", "research_study", "insight"] },
+  // Surface canonical post-split types. `hypothesis` is canonical
+  // (re-promoted in v0.4.0 from hypothesis_claim). `hypothesis_evidence`
+  // is deprecated — use `evidence` + hypothesis_has_evidence edge instead.
+  // `experiment` remains canonical alongside `experiment_plan` / `experiment_run`.
+  discovery: { emoji: "\u{1F4A1}", types: ["opportunity", "solution", "competitor", "hypothesis", "experiment_plan", "experiment_run", "learning"] },
+  // `validation` overlaps `discovery` semantically but tracks the stage's
+  // characteristic artefacts (hypothesis tested, evidence captured, experiment
+  // run-throughs). Surfaced as its own region so STAGE_COVERAGE_TARGETS can
+  // gate on it at `validation` stage without re-graveling `discovery`.
+  validation: { emoji: "\u{1F9EA}", types: ["hypothesis", "experiment_plan", "experiment_run", "evidence", "learning"] },
+  reaching: { emoji: "\u{1F4E3}", types: ["ideal_customer_profile", "positioning", "messaging", "acquisition_channel", "content_strategy"] },
+  converting: { emoji: "\u{1F4B0}", types: ["value_proposition", "pricing_tier", "funnel", "funnel_step"] },
+  // (since v0.4.0) story_task collapsed into task; building area uses task for story work.
+  building: { emoji: "\u{1F4E6}", types: ["feature", "story_statement", "epic", "release", "user_journey", "user_flow"] },
+  sustaining: { emoji: "\u{1F3E6}", types: ["business_model", "revenue_stream", "cost_structure", "unit_economics", "pricing_strategy"] },
+  learning: { emoji: "\u{1F4CA}", types: ["outcome", "metric", "objective", "key_result", "retrospective"] },
+  // Operations is a maintenance-stage concern — incidents, postmortems, error
+  // budgets only become coverage-relevant once a product is in `maintenance`.
+  // Surfaced informationally at earlier stages.
+  operations: { emoji: "\u{1F6A8}", types: ["incident", "postmortem", "error_budget"] }
+};
+var STAGE_COVERAGE_TARGETS = {
+  concept: ["identity", "understanding", "discovery"],
+  validation: ["identity", "understanding", "discovery", "validation"],
+  build: ["identity", "understanding", "discovery", "validation", "building"],
+  beta: ["identity", "understanding", "discovery", "validation", "building", "reaching", "converting"],
+  launch: ["identity", "understanding", "discovery", "validation", "building", "reaching", "converting", "sustaining"],
+  growth: ["identity", "understanding", "discovery", "validation", "building", "reaching", "converting", "sustaining", "learning"],
+  mature: ["identity", "understanding", "discovery", "validation", "building", "reaching", "converting", "sustaining", "learning"],
+  maintenance: ["identity", "understanding", "discovery", "validation", "building", "reaching", "converting", "sustaining", "learning", "operations"],
+  // Sunset products are winding down — Identity stays (the product still has
+  // a name + vision) and Learning becomes the priority (capture the
+  // retrospective + reasons for sunsetting). Everything else is informational.
+  sunset: ["identity", "learning"]
+};
+function resolveCoverageStage(rawStage) {
+  if (typeof rawStage === "string") {
+    const coerced = coerceProductStage(rawStage);
+    if (coerced.canonical) return coerced.canonical;
+    if (rawStage.toLowerCase() === "idea") return "concept";
+  }
+  return "concept";
+}
+var LIFECYCLE_PHASES = {
+  strategy: ["product", "outcome", "metric", "objective", "key_result", "vision", "mission", "strategic_theme", "initiative"],
+  users: ["persona", "job", "need", "desired_outcome", "job_step"],
+  discovery: ["opportunity", "solution", "research_study", "insight", "competitor"],
+  // (since v0.4.0) hypothesis is canonical; hypothesis_claim/hypothesis_evidence
+  // are deprecated aliases. evidence replaces hypothesis_evidence in new graphs.
+  validation: ["hypothesis", "experiment_plan", "experiment_run", "learning", "evidence", "experiment", "hypothesis_claim", "hypothesis_evidence"],
+  // (since v0.4.0) story_task collapsed into task (deprecated alias).
+  execution: ["feature", "epic", "story_statement", "release", "task", "bug", "user_story", "story_task"]
+};
+var CHAINS = [
+  { name: "persona \u2192 job", from: "persona", to: "job", edgePattern: "job" },
+  { name: "job \u2192 need", from: "job", to: "need", edgePattern: "need" },
+  { name: "opportunity \u2192 solution", from: "opportunity", to: "solution", edgePattern: "solution" },
+  { name: "solution \u2192 hypothesis", from: "solution", to: "hypothesis", edgePattern: "hypothesis" },
+  { name: "hypothesis \u2192 experiment_plan", from: "hypothesis", to: "experiment_plan", edgePattern: "experiment_plan" },
+  { name: "experiment_run \u2192 learning", from: "experiment_run", to: "learning", edgePattern: "learning" },
+  { name: "objective \u2192 key_result", from: "objective", to: "key_result", edgePattern: "key_result" },
+  // (v0.2.7 split 2) features specify story_statements (the design
+  // artefact / promise). story_tasks are the delivery work, linked from
+  // story_statement via story_task_implements_story_statement.
+  { name: "feature \u2192 story_statement", from: "feature", to: "story_statement", edgePattern: "story_statement" }
+];
+var TYPE_SORT_ORDER = [
+  // Identity
+  "product",
+  "vision",
+  "mission",
+  // Users
+  "persona",
+  "job",
+  "job_step",
+  "need",
+  "desired_outcome",
+  // Discovery
+  "outcome",
+  "opportunity",
+  "solution",
+  "research_study",
+  "insight",
+  // Validation
+  "hypothesis",
+  "experiment",
+  "learning",
+  "evidence",
+  // Competition
+  "competitor",
+  "competitor_feature",
+  // Strategy
+  "strategic_theme",
+  "initiative",
+  "objective",
+  "key_result",
+  "metric",
+  // Reaching
+  "ideal_customer_profile",
+  "market_segment",
+  "positioning",
+  "messaging",
+  "acquisition_channel",
+  "content_strategy",
+  // Converting
+  "value_proposition",
+  "pricing_tier",
+  "pricing_strategy",
+  "funnel",
+  "funnel_step",
+  // Building
+  "feature",
+  "feature_area",
+  "epic",
+  "user_story",
+  "release",
+  "user_journey",
+  "user_flow",
+  "screen",
+  "screen_state",
+  // Architecture
+  "bounded_context",
+  "service",
+  "api_endpoint",
+  "database_schema",
+  "architecture_decision",
+  // Sustaining
+  "business_model",
+  "revenue_stream",
+  "cost_structure",
+  "unit_economics",
+  // Learning
+  "retrospective"
+];
+function typeSortPriority(type) {
+  const idx = TYPE_SORT_ORDER.indexOf(type);
+  return idx >= 0 ? idx : 999;
+}
+function sortByType(nodes) {
+  return [...nodes].sort((a, b) => {
+    const priorityDiff = typeSortPriority(a.type) - typeSortPriority(b.type);
+    if (priorityDiff !== 0) return priorityDiff;
+    return a.title.localeCompare(b.title);
+  });
+}
+function computeGraphDigest(store) {
+  const nodes = store.getAllNodes();
+  const edges = store.getAllEdges();
+  const product = store.getProduct();
+  const byType = {};
+  for (const n of nodes) byType[n.type] = (byType[n.type] ?? 0) + 1;
+  const byCanonicalType = {};
+  for (const n of nodes) {
+    const c = canonicalType(n.type);
+    byCanonicalType[c] = (byCanonicalType[c] ?? 0) + 1;
+  }
+  const connectedNodes = /* @__PURE__ */ new Set();
+  for (const e of edges) {
+    connectedNodes.add(e.source);
+    connectedNodes.add(e.target);
+  }
+  const orphanCount = nodes.filter((n) => !connectedNodes.has(n.id)).length;
+  const hypothesisCount = byCanonicalType["hypothesis"] ?? 0;
+  const experimentCount = (byCanonicalType["experiment_plan"] ?? 0) + (byCanonicalType["experiment_run"] ?? 0) + // `experiment` is still a canonical type for back-compat reads; count it too.
+  (byCanonicalType["experiment"] ?? 0);
+  const personaCount = byCanonicalType["persona"] ?? 0;
+  const chainStats = (parentType, edgePattern) => {
+    let withChild = 0;
+    const parents = nodes.filter((n) => canonicalType(n.type) === parentType);
+    for (const p of parents) {
+      const pEdges = store.getEdgesForNode(p.id);
+      const matches = pEdges.some(
+        (e) => e.source === p.id && (e.type.includes(edgePattern) || e.type.includes(canonicalType(edgePattern)) || // Match deprecated edge fragments by resolving each segment to canonical.
+        e.type.split("_").some((seg) => canonicalType(seg) === edgePattern))
+      );
+      if (matches) withChild++;
+    }
+    return { with_child: withChild, total: parents.length };
+  };
+  const chainStatsWithBridge = (parentType, edgePattern, bridges) => {
+    let withChild = 0;
+    const parents = nodes.filter((n) => canonicalType(n.type) === parentType);
+    for (const p of parents) {
+      const pEdges = store.getEdgesForNode(p.id);
+      const directMatch = pEdges.some(
+        (e) => e.source === p.id && (e.type.includes(edgePattern) || e.type.includes(canonicalType(edgePattern)) || e.type.split("_").some((seg) => canonicalType(seg) === edgePattern))
+      );
+      if (directMatch) {
+        withChild++;
+        continue;
+      }
+      let bridgeMatch = false;
+      for (const bridge of bridges) {
+        const incoming = pEdges.filter(
+          (e) => e.target === p.id && e.type.includes(bridge.incoming_edge_substring)
+        );
+        for (const inE of incoming) {
+          const bridgeNode = store.getNode(inE.source);
+          if (!bridgeNode || canonicalType(bridgeNode.type) !== bridge.incoming_from) continue;
+          const bridgeOut = store.getEdgesForNode(bridgeNode.id);
+          const reachesChild = bridgeOut.some((be) => {
+            if (be.source !== bridgeNode.id) return false;
+            if (!be.type.includes(bridge.bridge_outgoing_edge_substring)) return false;
+            const childNode = store.getNode(be.target);
+            return childNode != null && canonicalType(childNode.type) === bridge.bridge_to_type;
+          });
+          if (reachesChild) {
+            bridgeMatch = true;
+            break;
+          }
+        }
+        if (bridgeMatch) break;
+      }
+      if (bridgeMatch) withChild++;
+    }
+    return { with_child: withChild, total: parents.length };
+  };
+  const personaJob = chainStats("persona", "job");
+  const jobNeed = chainStatsWithBridge(
+    "job",
+    "need",
+    [
+      {
+        incoming_from: "persona",
+        incoming_edge_substring: "persona_pursues_job",
+        bridge_outgoing_edge_substring: "persona_experiences_need",
+        bridge_to_type: "need"
+      }
+    ]
+  );
+  const oppSolution = chainStats("opportunity", "solution");
+  const hypExperiment = chainStats("hypothesis", "experiment_plan");
+  const expLearning = chainStats("experiment_run", "learning");
+  const typeSet = /* @__PURE__ */ new Set();
+  for (const t of Object.keys(byType)) {
+    typeSet.add(t);
+    typeSet.add(canonicalType(t));
+  }
+  const rawStage = product.stage ?? nodes.find((n) => n.type === "product")?.properties?.stage;
+  const resolvedStage = resolveCoverageStage(rawStage);
+  const countedRegions = new Set(STAGE_COVERAGE_TARGETS[resolvedStage] ?? []);
+  const coverage = {};
+  const countedRegionStats = [];
+  for (const [area, def] of Object.entries(BUSINESS_AREAS)) {
+    const present = def.types.filter((t) => typeSet.has(t));
+    const missing = def.types.filter((t) => !typeSet.has(t));
+    const isCounted = countedRegions.has(area);
+    const region = {
+      covered: present.length,
+      total: def.types.length,
+      counted_toward_stage: isCounted,
+      types_present: present,
+      types_missing: missing
+    };
+    coverage[area] = region;
+    if (isCounted) countedRegionStats.push({ covered: region.covered, total: region.total });
+  }
+  const regionsComplete = countedRegionStats.filter((s) => s.total > 0 && s.covered === s.total).length;
+  const regionsPartial = countedRegionStats.filter((s) => s.covered > 0 && s.covered < s.total).length;
+  const perRegionPcts = countedRegionStats.map((s) => s.total === 0 ? 100 : s.covered / s.total * 100);
+  const overallPct = perRegionPcts.length === 0 ? 0 : Math.round(perRegionPcts.reduce((sum, pct) => sum + pct, 0) / perRegionPcts.length);
+  coverage.stage_summary = {
+    stage: resolvedStage,
+    regions_counted: countedRegionStats.length,
+    regions_complete: regionsComplete,
+    regions_partial: regionsPartial,
+    overall_pct: overallPct
+  };
+  const lifecycle = {};
+  for (const [phase, types] of Object.entries(LIFECYCLE_PHASES)) {
+    const canonicalSet = new Set(types.map((t) => canonicalType(t)));
+    lifecycle[phase] = [...canonicalSet].reduce(
+      (sum, t) => sum + (byCanonicalType[t] ?? 0),
+      0
+    );
+  }
+  return {
+    product: {
+      title: product.title,
+      stage: product.stage ?? nodes.find((n) => n.type === "product")?.properties?.stage ?? "unknown"
+    },
+    counts: { total_nodes: nodes.length, total_edges: edges.length, by_type: byType },
+    health: {
+      orphan_count: orphanCount,
+      orphan_rate: nodes.length > 0 ? Math.round(orphanCount / nodes.length * 100) / 100 : 0,
+      connectivity: nodes.length > 0 ? Math.round((nodes.length - orphanCount) / nodes.length * 100) / 100 : 0,
+      validation_rate: hypothesisCount > 0 ? Math.round(experimentCount / hypothesisCount * 100) / 100 : 0,
+      user_coverage: personaCount > 0 ? Math.round(personaJob.with_child / personaCount * 100) / 100 : 0
+    },
+    chains: {
+      persona_with_job: personaJob.with_child,
+      persona_total: personaJob.total,
+      job_with_need: jobNeed.with_child,
+      job_total: jobNeed.total,
+      opportunity_with_solution: oppSolution.with_child,
+      opportunity_total: oppSolution.total,
+      hypothesis_untested: hypothesisCount - hypExperiment.with_child,
+      hypothesis_total: hypothesisCount,
+      experiment_with_learning: expLearning.with_child,
+      experiment_total: experimentCount
+    },
+    coverage,
+    lifecycle
+  };
+}
+function searchNodes(store, query, options) {
+  const q = query.toLowerCase();
+  const searchFields = new Set(options?.fields ?? ["title", "description"]);
+  const limit = Math.min(options?.limit ?? 20, 100);
+  let nodes = store.getAllNodes();
+  if (options?.type) nodes = nodes.filter((n) => n.type === options.type);
+  return nodes.map((n) => {
+    let bestScore = 0;
+    let matchField = "";
+    if (searchFields.has("title") && n.title.toLowerCase().includes(q)) {
+      bestScore = 3;
+      matchField = "title";
+    }
+    if (searchFields.has("tags") && normalizeTags(n.tags)?.some((t) => t.toLowerCase().includes(q))) {
+      if (2 > bestScore) {
+        bestScore = 2;
+        matchField = "tags";
+      }
+    }
+    if (searchFields.has("description") && n.description?.toLowerCase().includes(q)) {
+      if (1 > bestScore) {
+        bestScore = 1;
+        matchField = "description";
+      }
+    }
+    if (searchFields.has("properties") && n.properties) {
+      const propsStr = JSON.stringify(n.properties).toLowerCase();
+      if (propsStr.includes(q)) {
+        if (1 > bestScore) {
+          bestScore = 1;
+          matchField = "properties";
+        }
+      }
+    }
+    if (bestScore === 0) return null;
+    return { node: n, score: bestScore, match_field: matchField };
+  }).filter((s) => s !== null).sort((a, b) => b.score - a.score).slice(0, limit);
+}
+function computeHealthScore(digest) {
+  const orphanRate = digest.health.orphan_rate;
+  const orphanScore = Math.max(0, 100 - orphanRate * 200);
+  const regions = Object.entries(digest.coverage).filter(([key]) => key !== "stage_summary").map(([, value]) => value);
+  const domainsCovered = regions.filter((c) => c.covered > 0).length;
+  const domainScore = domainsCovered / Object.keys(BUSINESS_AREAS).length * 100;
+  let chainsComplete = 0;
+  const chainPairs = [
+    [digest.chains.persona_with_job, digest.chains.persona_total],
+    [digest.chains.job_with_need, digest.chains.job_total],
+    [digest.chains.opportunity_with_solution, digest.chains.opportunity_total],
+    [digest.chains.experiment_with_learning, digest.chains.experiment_total]
+  ];
+  for (const [connected, total] of chainPairs) {
+    if (total > 0 && connected === total) chainsComplete++;
+  }
+  const chainScore = chainPairs.length > 0 ? chainsComplete / chainPairs.length * 100 : 100;
+  const validationScore = digest.health.validation_rate * 100;
+  return Math.round(
+    orphanScore * 0.25 + domainScore * 0.25 + chainScore * 0.3 + validationScore * 0.2
+  );
+}
+function getOrphans(store) {
+  const connectedNodes = /* @__PURE__ */ new Set();
+  for (const e of store.getAllEdges()) {
+    connectedNodes.add(e.source);
+    connectedNodes.add(e.target);
+  }
+  return store.getAllNodes().filter((n) => !connectedNodes.has(n.id));
+}
+function listNodes(store, options) {
+  let nodes = store.getAllNodes();
+  if (options?.type) nodes = nodes.filter((n) => n.type === options.type);
+  if (options?.status) nodes = nodes.filter((n) => n.status === options.status);
+  if (options?.tags && options.tags.length > 0) {
+    const filterTags = options.tags;
+    nodes = nodes.filter((n) => normalizeTags(n.tags)?.some((t) => filterTags.includes(t)));
+  }
+  if (options?.parentId) {
+    const parentEdges = store.getEdgesForNode(options.parentId);
+    const childIds = new Set(
+      parentEdges.filter((e) => e.source === options.parentId).map((e) => e.target)
+    );
+    nodes = nodes.filter((n) => childIds.has(n.id));
+  }
+  const total = nodes.length;
+  const offset = options?.offset ?? 0;
+  const limit = Math.min(options?.limit ?? 50, 200);
+  const page = nodes.slice(offset, offset + limit).map((n) => {
+    const entry = {
+      id: n.id,
+      type: n.type,
+      title: n.title,
+      status: n.status,
+      tags: n.tags
+    };
+    if (options?.includeEdges) {
+      entry.edges = store.getEdgesForNode(n.id).map((e) => ({
+        id: e.id,
+        type: e.type,
+        source: e.source,
+        target: e.target
+      }));
+    }
+    return entry;
+  });
+  return { nodes: page, total };
+}
+function getNode(store, args) {
+  const node = store.getNode(args.node_id);
+  if (!node) return null;
+  const compact = args.compact_edges ?? false;
+  const edges = store.getEdgesForNode(args.node_id);
+  const edgesOut = edges.filter((e) => e.source === args.node_id).map(
+    (e) => compact ? { id: e.id, type: e.type, source: e.source, target: e.target } : { ...e, target_title: store.getNode(e.target)?.title ?? "(unknown)" }
+  );
+  const edgesIn = edges.filter((e) => e.target === args.node_id).map(
+    (e) => compact ? { id: e.id, type: e.type, source: e.source, target: e.target } : { ...e, source_title: store.getNode(e.source)?.title ?? "(unknown)" }
+  );
+  return { node, edges_out: edgesOut, edges_in: edgesIn };
+}
+function getNodes(store, args) {
+  const compact = args.compact_edges ?? false;
+  const results = [];
+  const notFound = [];
+  for (const id of args.ids) {
+    const result = getNode(store, { node_id: id, compact_edges: compact });
+    if (!result) {
+      notFound.push(id);
+      continue;
+    }
+    results.push(result);
+  }
+  const response = { nodes: results, total: results.length };
+  if (notFound.length > 0) response.not_found = notFound;
+  return response;
+}
+function createNode(store, args) {
+  const resolved = resolveEntityType(args.type);
+  const canonicalNodeType = resolved.canonical;
+  const aliasWarning = resolved.alias ? `Type '${resolved.alias.from}' aliased to canonical '${resolved.alias.to}'. Update your caller to use '${resolved.alias.to}' directly.` : void 0;
+  const newNode = {
+    id: nodeId(),
+    type: canonicalNodeType,
+    title: args.title
+  };
+  if (args.description) newNode.description = args.description;
+  if (args.tags) newNode.tags = normalizeTags(args.tags) ?? [];
+  if (args.properties) newNode.properties = args.properties;
+  autoFillSlug(newNode, store);
+  let warning = aliasWarning;
+  if (args.status) {
+    newNode.status = args.status;
+    const statusWarning = validateStatusAgainstLifecycle(canonicalNodeType, args.status);
+    if (statusWarning) warning = warning ? `${warning} | ${statusWarning}` : statusWarning;
+  } else {
+    const defaultStatus = getDefaultStatus(canonicalNodeType);
+    if (defaultStatus) newNode.status = defaultStatus;
+  }
+  store.addNode(newNode);
+  let edge = null;
+  if (args.parent_id) {
+    const parent = store.getNode(args.parent_id);
+    if (!parent) {
+      return {
+        node: newNode,
+        edge: null,
+        warning: (warning ? warning + " | " : "") + `Parent node ${args.parent_id} not found. Node created without edge.`
+      };
+    }
+    const inference = inferEdgeTypeWithTier(parent.type, canonicalNodeType);
+    if (!inference.ok) {
+      const suggestion = inference.suggestions.length > 0 ? ` Suggestions: ${inference.suggestions.map((s) => `${s.source_type} \u2192 ${s.target_type} (${s.edge_type})`).join("; ")}.` : "";
+      return {
+        node: newNode,
+        edge: null,
+        warning: (warning ? warning + " | " : "") + `Parent edge not created \u2014 no canonical edge for ${parent.type} \u2192 ${canonicalNodeType}.${suggestion}`
+      };
+    }
+    edge = {
+      id: edgeId(),
+      source: args.parent_id,
+      target: newNode.id,
+      type: inference.edgeType
+    };
+    store.addEdge(edge);
+  }
+  return warning ? { node: newNode, edge, warning } : { node: newNode, edge };
+}
+function createEdge(store, args) {
+  let targetId = args.target_id;
+  if (!targetId && !args.target_title) {
+    return { error: "Provide either target_id or target_title (with target_type)" };
+  }
+  if (!targetId && args.target_title) {
+    if (!args.target_type) {
+      return { error: "target_type is required when using target_title" };
+    }
+    const candidates = store.getAllNodes().filter(
+      (n) => n.type === args.target_type && n.title.toLowerCase() === args.target_title.toLowerCase()
+    );
+    if (candidates.length === 0) {
+      return { error: `No ${args.target_type} found with title "${args.target_title}"` };
+    }
+    if (candidates.length > 1) {
+      return {
+        error: `Ambiguous: ${candidates.length} nodes match "${args.target_title}" (type: ${args.target_type}). Use target_id instead. IDs: ${candidates.map((c) => c.id).join(", ")}`
+      };
+    }
+    targetId = candidates[0].id;
+  }
+  const source = store.getNode(args.source_id);
+  const target = store.getNode(targetId);
+  if (!source) return { error: `Source not found: ${args.source_id}` };
+  if (!target) return { error: `Target not found: ${targetId}` };
+  if (args.source_id === targetId) {
+    return {
+      error: `Self-loop refused: source and target resolve to the same node "${args.source_id}". No canonical UPG edge type is self-referential. If you genuinely need a self-referential edge, file a spec proposal first.`
+    };
+  }
+  let edgeType;
+  let edgeWarning;
+  if (args.type) {
+    const pairCheck = validateEdgeTypePair(args.type, source.type, target.type);
+    if (!pairCheck.valid) {
+      return { error: pairCheck.reason };
+    }
+    edgeType = args.type;
+  } else {
+    const inference = inferEdgeTypeWithTier(source.type, target.type);
+    if (!inference.ok) {
+      const suggestion = inference.suggestions.length > 0 ? ` Try one of: ${inference.suggestions.map((s) => `${s.source_type} \u2192 ${s.target_type} (${s.edge_type})`).join("; ")}.` : "";
+      return {
+        error: `No canonical edge type for ${source.type} \u2192 ${target.type}.${suggestion} Pass an explicit \`type\` if you need a non-catalog edge.`,
+        no_canonical_edge_for: {
+          source_type: source.type,
+          target_type: target.type
+        }
+      };
+    }
+    edgeType = inference.edgeType;
+    if (inference.aliased) {
+      const parts = inference.aliased.map((a) => `${a.from} \u2192 ${a.to}`).join(", ");
+      edgeWarning = `Edge inferred from canonical (${parts}).`;
+    }
+  }
+  const edge = {
+    id: edgeId(),
+    source: args.source_id,
+    target: targetId,
+    type: edgeType
+  };
+  store.addEdge(edge);
+  const response = { edge };
+  if (edgeWarning) response.warning = edgeWarning;
+  return response;
+}
+function deleteNode(store, args) {
+  const { node, removedEdgeIds } = store.removeNode(args.node_id);
+  return {
+    deleted_node_id: node.id,
+    deleted_node_title: node.title,
+    deleted_edge_ids: removedEdgeIds
+  };
+}
+function deleteEdge(store, args) {
+  const edge = store.removeEdge(args.edge_id);
+  return { deleted_edge_id: edge.id };
+}
+function findParentEdges(store, nodeId2) {
+  const incoming = store.getEdgesForNode(nodeId2).filter((e) => e.target === nodeId2);
+  return incoming.filter((e) => {
+    const def = UPG_EDGE_CATALOG[e.type];
+    return def?.classification === "hierarchy";
+  });
+}
+function moveNode(store, args) {
+  const node = store.getNode(args.node_id);
+  if (!node) return { moved: false, error: `Node not found: ${args.node_id}` };
+  const newParent = store.getNode(args.new_parent_id);
+  if (!newParent) {
+    return { moved: false, error: `New parent not found: ${args.new_parent_id}` };
+  }
+  if (args.node_id === args.new_parent_id) {
+    return { moved: false, error: "Cannot move a node onto itself." };
+  }
+  let oldEdge = null;
+  if (args.old_edge_id) {
+    const explicit = store.getEdge(args.old_edge_id);
+    if (!explicit) {
+      return { moved: false, error: `old_edge_id not found: ${args.old_edge_id}` };
+    }
+    if (explicit.target !== args.node_id) {
+      return {
+        moved: false,
+        error: `old_edge_id ${args.old_edge_id} does not target node ${args.node_id}.`
+      };
+    }
+    oldEdge = explicit;
+  } else {
+    const parents = findParentEdges(store, args.node_id);
+    if (parents.length > 1) {
+      return {
+        moved: false,
+        error: `Node has ${parents.length} hierarchy edges; pass old_edge_id to disambiguate. Candidates: ${parents.map((e) => `${e.id} (${e.type})`).join(", ")}`
+      };
+    }
+    oldEdge = parents[0] ?? null;
+  }
+  let newEdgeType;
+  let aliasWarning;
+  if (args.new_edge_type) {
+    if (!UPG_EDGE_CATALOG[args.new_edge_type]) {
+      return {
+        moved: false,
+        error: `new_edge_type "${args.new_edge_type}" is not in UPG_EDGE_CATALOG.`
+      };
+    }
+    newEdgeType = args.new_edge_type;
+  } else {
+    const inference = inferEdgeTypeWithTier(newParent.type, node.type);
+    if (!inference.ok) {
+      const suggestion = inference.suggestions.length > 0 ? ` Suggestions: ${inference.suggestions.map((s) => `${s.source_type} \u2192 ${s.target_type} (${s.edge_type})`).join("; ")}.` : "";
+      return {
+        moved: false,
+        error: `No canonical edge for ${newParent.type} \u2192 ${node.type}.${suggestion} Pass an explicit new_edge_type.`
+      };
+    }
+    newEdgeType = inference.edgeType;
+    if (inference.aliased) {
+      const parts = inference.aliased.map((a) => `${a.from} \u2192 ${a.to}`).join(", ");
+      aliasWarning = `Edge inferred from canonical (${parts}).`;
+    }
+  }
+  const def = UPG_EDGE_CATALOG[newEdgeType];
+  if (def.source_type !== newParent.type) {
+    return {
+      moved: false,
+      error: `Edge "${newEdgeType}" requires source type "${def.source_type}", got "${newParent.type}".`
+    };
+  }
+  if (def.target_type !== node.type) {
+    return {
+      moved: false,
+      error: `Edge "${newEdgeType}" requires target type "${def.target_type}", got "${node.type}".`
+    };
+  }
+  const newEdge = {
+    id: edgeId(),
+    source: args.new_parent_id,
+    target: args.node_id,
+    type: newEdgeType
+  };
+  if (oldEdge) {
+    store.removeEdge(oldEdge.id);
+  }
+  try {
+    store.addEdge(newEdge);
+  } catch (err) {
+    if (oldEdge) {
+      store.addEdge(oldEdge, true);
+    }
+    return {
+      moved: false,
+      error: `Failed to add new edge: ${err.message}. Graph rolled back.`
+    };
+  }
+  return {
+    moved: true,
+    node_id: args.node_id,
+    new_edge: newEdge,
+    removed_edge_id: oldEdge?.id ?? null,
+    ...oldEdge ? { removed_edge: oldEdge } : {},
+    ...aliasWarning ? { warning: aliasWarning } : {}
+  };
+}
+function batchMoveNodes(store, moves) {
+  if (moves.length === 0) return { ok: false, error: "moves array is empty", failed_at_index: null };
+  if (moves.length > 50) return { ok: false, error: "Maximum 50 moves per batch", failed_at_index: null };
+  for (let i = 0; i < moves.length; i++) {
+    const m = moves[i];
+    const node = store.getNode(m.node_id);
+    if (!node) return { ok: false, error: `Move at index ${i}: node not found: ${m.node_id}`, failed_at_index: i };
+    const parent = store.getNode(m.new_parent_id);
+    if (!parent) return { ok: false, error: `Move at index ${i}: new parent not found: ${m.new_parent_id}`, failed_at_index: i };
+    if (m.node_id === m.new_parent_id) {
+      return { ok: false, error: `Move at index ${i}: cannot move a node onto itself.`, failed_at_index: i };
+    }
+    if (m.new_edge_type && !UPG_EDGE_CATALOG[m.new_edge_type]) {
+      return { ok: false, error: `Move at index ${i}: new_edge_type "${m.new_edge_type}" is not in UPG_EDGE_CATALOG.`, failed_at_index: i };
+    }
+    if (!m.new_edge_type) {
+      const inference = inferEdgeTypeWithTier(parent.type, node.type);
+      if (!inference.ok) {
+        return { ok: false, error: `Move at index ${i}: no canonical edge for ${parent.type} \u2192 ${node.type}. Pass an explicit new_edge_type.`, failed_at_index: i };
+      }
+    }
+  }
+  const applied = [];
+  for (let i = 0; i < moves.length; i++) {
+    const result = moveNode(store, moves[i]);
+    if (!result.moved) {
+      for (let j = applied.length - 1; j >= 0; j--) {
+        const a = applied[j];
+        try {
+          store.removeEdge(a.newEdge.id);
+        } catch {
+        }
+        if (a.oldEdge) {
+          try {
+            store.addEdge(a.oldEdge, true);
+          } catch {
+          }
+        }
+      }
+      return { ok: false, error: `Move at index ${i}: ${result.error}`, failed_at_index: i };
+    }
+    applied.push({
+      newEdge: result.new_edge,
+      oldEdge: result.removed_edge ?? null
+    });
+  }
+  return {
+    ok: true,
+    result: {
+      moves: applied.map((a, i) => ({
+        node_id: moves[i].node_id,
+        new_edge: a.newEdge,
+        removed_edge_id: a.oldEdge?.id ?? null
+      })),
+      count: moves.length
+    }
+  };
+}
+function batchCreateNodes(store, args) {
+  const { nodes, edges: explicitEdges = [] } = args;
+  if (!Array.isArray(nodes)) return { ok: false, error: "Missing required parameter: nodes (array)" };
+  if (nodes.length === 0) return { ok: false, error: "nodes array is empty" };
+  if (nodes.length > 50) return { ok: false, error: "Maximum 50 nodes per batch" };
+  if (nodes.length + explicitEdges.length > 50) {
+    return { ok: false, error: `Maximum 50 items per batch (got ${nodes.length} nodes + ${explicitEdges.length} edges)` };
+  }
+  const resolvedTypes = [];
+  const aliasWarnings = [];
+  for (let i = 0; i < nodes.length; i++) {
+    const n = nodes[i];
+    if (!n.type) return { ok: false, error: `Node at index ${i}: missing required field "type"` };
+    if (!n.title) return { ok: false, error: `Node at index ${i}: missing required field "title"` };
+    try {
+      const resolved = resolveEntityType(n.type);
+      resolvedTypes.push(resolved.canonical);
+      if (resolved.alias) {
+        aliasWarnings.push(
+          `Node at index ${i}: type '${resolved.alias.from}' aliased to canonical '${resolved.alias.to}'.`
+        );
+      }
+    } catch (err) {
+      if (err instanceof UnknownEntityTypeError) {
+        return { ok: false, error: `Node at index ${i}: ${err.message}` };
+      }
+      throw err;
+    }
+    if (n.parent_ref !== void 0) {
+      const match = n.parent_ref.match(/^\$(\d+)$/);
+      if (!match) return { ok: false, error: `Node at index ${i}: invalid parent_ref "${n.parent_ref}" \u2014 use "$0", "$1", etc.` };
+      const refIndex = parseInt(match[1], 10);
+      if (refIndex >= i) return { ok: false, error: `Node at index ${i}: parent_ref "${n.parent_ref}" must reference an earlier index (0\u2013${i - 1})` };
+    }
+    if (n.parent_id !== void 0 && !store.getNode(n.parent_id)) {
+      return { ok: false, error: `Node at index ${i}: parent_id "${n.parent_id}" not found in graph` };
+    }
+  }
+  const validatedEdges = [];
+  const resolveEdgeRef = (raw, label, edgeIndex) => {
+    if (typeof raw !== "string" || raw.length === 0) {
+      return { error: `Edge at index ${edgeIndex}: missing or invalid "${label}"` };
+    }
+    const refMatch = raw.match(/^\$(\d+)$/);
+    if (refMatch) {
+      const idx = parseInt(refMatch[1], 10);
+      if (idx >= nodes.length) {
+        return { error: `Edge at index ${edgeIndex}: ${label} "${raw}" out of range \u2014 only ${nodes.length} nodes in this batch.` };
+      }
+      return { kind: "ref", index: idx };
+    }
+    if (!store.getNode(raw)) {
+      return { error: `Edge at index ${edgeIndex}: ${label} "${raw}" not found in graph (and is not a $N ref into this batch).` };
+    }
+    return { kind: "id", id: raw };
+  };
+  const refSourceType = (ref) => ref.kind === "ref" ? resolvedTypes[ref.index] : store.getNode(ref.id).type;
+  for (let i = 0; i < explicitEdges.length; i++) {
+    const e = explicitEdges[i];
+    const fromResolved = resolveEdgeRef(e.from_ref, "from_ref", i);
+    if ("error" in fromResolved) return { ok: false, error: fromResolved.error };
+    const toResolved = resolveEdgeRef(e.to_ref, "to_ref", i);
+    if ("error" in toResolved) return { ok: false, error: toResolved.error };
+    const sameRef = fromResolved.kind === "ref" && toResolved.kind === "ref" && fromResolved.index === toResolved.index;
+    const sameId = fromResolved.kind === "id" && toResolved.kind === "id" && fromResolved.id === toResolved.id;
+    if (sameRef || sameId) {
+      return {
+        ok: false,
+        error: `Edge at index ${i}: self-loop refused \u2014 source and target resolve to the same node. No canonical UPG edge type is self-referential.`
+      };
+    }
+    let typeOverride;
+    if (e.type !== void 0) {
+      if (!UPG_EDGE_CATALOG[e.type]) {
+        return { ok: false, error: `Edge at index ${i}: type "${e.type}" not in UPG_EDGE_CATALOG.` };
+      }
+      const sourceType = refSourceType(fromResolved);
+      const targetType = refSourceType(toResolved);
+      const pairCheck = validateEdgeTypePair(e.type, sourceType, targetType);
+      if (!pairCheck.valid) {
+        return { ok: false, error: `Edge at index ${i}: ${pairCheck.reason}` };
+      }
+      typeOverride = e.type;
+    } else {
+      const sourceType = refSourceType(fromResolved);
+      const targetType = refSourceType(toResolved);
+      const inference = inferEdgeTypeWithTier(sourceType, targetType);
+      if (!inference.ok) {
+        const suggestion = inference.suggestions.length > 0 ? ` Suggestions: ${inference.suggestions.map((s) => `${s.source_type} \u2192 ${s.target_type} (${s.edge_type})`).join("; ")}.` : "";
+        return { ok: false, error: `Edge at index ${i}: no canonical edge for ${sourceType} \u2192 ${targetType}.${suggestion} Pass an explicit \`type\` to override.` };
+      }
+    }
+    validatedEdges.push({ from: fromResolved, to: toResolved, typeOverride });
+  }
+  const createdNodes = [];
+  const createdNodeRefs = [];
+  const createdParentEdges = [];
+  const explicitCreated = [];
+  const warnings = [...aliasWarnings];
+  const rollbackAll = () => {
+    for (const e of explicitCreated.slice().reverse()) {
+      try {
+        store.removeEdge(e.id);
+      } catch {
+      }
+    }
+    for (const e of createdParentEdges.slice().reverse()) {
+      try {
+        store.removeEdge(e.id);
+      } catch {
+      }
+    }
+    for (const n of createdNodeRefs.slice().reverse()) {
+      try {
+        store.removeNode(n.id);
+      } catch {
+      }
+    }
+  };
+  try {
+    for (let i = 0; i < nodes.length; i++) {
+      const n = nodes[i];
+      const newNode = {
+        id: nodeId(),
+        type: resolvedTypes[i],
+        title: n.title
+      };
+      if (n.description) newNode.description = n.description;
+      if (n.tags) newNode.tags = normalizeTags(n.tags) ?? [];
+      if (n.properties) newNode.properties = n.properties;
+      if (n.status) {
+        newNode.status = n.status;
+        const sw = validateStatusAgainstLifecycle(newNode.type, n.status);
+        if (sw) warnings.push(`Node "${n.title}": ${sw}`);
+      } else {
+        const ds = getDefaultStatus(newNode.type);
+        if (ds) newNode.status = ds;
+      }
+      autoFillSlug(newNode, store);
+      store.addNode(newNode);
+      createdNodes.push({ id: newNode.id, type: newNode.type, title: newNode.title, status: newNode.status });
+      createdNodeRefs.push(newNode);
+      let parentId = n.parent_id;
+      if (n.parent_ref !== void 0) {
+        const refIndex = parseInt(n.parent_ref.slice(1), 10);
+        parentId = createdNodes[refIndex].id;
+      }
+      if (parentId) {
+        const parent = store.getNode(parentId);
+        if (parent) {
+          const inference = inferEdgeTypeWithTier(parent.type, newNode.type);
+          if (inference.ok) {
+            const edge = { id: edgeId(), source: parentId, target: newNode.id, type: inference.edgeType };
+            store.addEdge(edge);
+            createdParentEdges.push(edge);
+          } else {
+            const suggestion = inference.suggestions.length > 0 ? ` Suggestions: ${inference.suggestions.map((s) => `${s.source_type} \u2192 ${s.target_type} (${s.edge_type})`).join("; ")}.` : "";
+            warnings.push(
+              `Node "${newNode.title}": parent edge not created \u2014 no canonical edge for ${parent.type} \u2192 ${newNode.type}.${suggestion}`
+            );
+          }
+        }
+      }
+    }
+    for (const v of validatedEdges) {
+      const sourceId = v.from.kind === "ref" ? createdNodes[v.from.index].id : v.from.id;
+      const targetId = v.to.kind === "ref" ? createdNodes[v.to.index].id : v.to.id;
+      let edgeType;
+      if (v.typeOverride) {
+        edgeType = v.typeOverride;
+      } else {
+        const source = store.getNode(sourceId);
+        const target = store.getNode(targetId);
+        const inference = inferEdgeTypeWithTier(source.type, target.type);
+        if (!inference.ok) {
+          throw new Error(`Edge inference unexpectedly failed for ${source.type} \u2192 ${target.type} (post-validation).`);
+        }
+        edgeType = inference.edgeType;
+      }
+      const newEdge = { id: edgeId(), source: sourceId, target: targetId, type: edgeType };
+      store.addEdge(newEdge);
+      explicitCreated.push(newEdge);
+    }
+  } catch (err) {
+    rollbackAll();
+    return {
+      ok: false,
+      error: `Atomic batch failed during apply: ${err.message}. All nodes and edges rolled back.`
+    };
+  }
+  if (createdNodes.length >= 2 && createdParentEdges.length === 0 && explicitCreated.length === 0) {
+    warnings.push(
+      `Created ${createdNodes.length} nodes with no edges \u2014 they are orphans. Use the edges[] array in this call to link them. See get_entity_schema(<type>) for canonical edges per type.`
+    );
+  }
+  const result = {
+    ok: true,
+    created: createdNodes,
+    edges: createdParentEdges,
+    count: createdNodes.length
+  };
+  if (explicitCreated.length > 0) result.explicit_edges = explicitCreated;
+  if (warnings.length > 0) result.warnings = warnings;
+  return result;
+}
+function migrateNodeType(store, args) {
+  const node = store.getNode(args.node_id);
+  if (!node) return { migrated: false, error: `Node not found: ${args.node_id}` };
+  let resolved;
+  try {
+    resolved = resolveEntityType(args.new_type);
+  } catch (err) {
+    if (err instanceof UnknownEntityTypeError) {
+      return { migrated: false, error: err.message, suggestions: err.suggestions };
+    }
+    throw err;
+  }
+  const oldType = node.type;
+  const newType = resolved.canonical;
+  const aliasWarning = resolved.alias ? `Type '${resolved.alias.from}' aliased to canonical '${resolved.alias.to}'.` : void 0;
+  if (oldType === newType) {
+    return {
+      migrated: true,
+      node_id: args.node_id,
+      from_type: oldType,
+      to_type: newType,
+      edges_rewritten: [],
+      ...aliasWarning ? { warning: aliasWarning } : {}
+    };
+  }
+  const incident = store.getEdgesForNode(args.node_id);
+  const plans = [];
+  for (const e of incident) {
+    if (e.type === args.new_type) continue;
+    const sourceType = e.source === args.node_id ? newType : store.getNode(e.source)?.type ?? "";
+    const targetType = e.target === args.node_id ? newType : store.getNode(e.target)?.type ?? "";
+    if (!sourceType || !targetType) {
+      return {
+        migrated: false,
+        error: `Edge ${e.id} references a missing node \u2014 fix graph integrity before migrating.`
+      };
+    }
+    const inference = inferEdgeTypeWithTier(sourceType, targetType);
+    if (!inference.ok) {
+      const suggestion = inference.suggestions.length > 0 ? ` Suggestions: ${inference.suggestions.map((s) => `${s.source_type} \u2192 ${s.target_type} (${s.edge_type})`).join("; ")}.` : "";
+      return {
+        migrated: false,
+        error: `Cannot re-infer edge ${e.id} (${e.type}) for ${sourceType} \u2192 ${targetType}.${suggestion} Delete the edge or pick an explicit edge type via update_node + create_edge.`
+      };
+    }
+    if (inference.edgeType !== e.type) {
+      plans.push({ oldEdge: e, newType: inference.edgeType });
+    }
+  }
+  const removed = [];
+  const added = [];
+  try {
+    for (const p of plans) {
+      const old = store.removeEdge(p.oldEdge.id);
+      removed.push(old);
+    }
+    store.updateNode(args.node_id, { type: newType });
+    for (const p of plans) {
+      const newEdge = {
+        id: edgeId(),
+        source: p.oldEdge.source,
+        target: p.oldEdge.target,
+        type: p.newType
+      };
+      store.addEdge(newEdge);
+      added.push(newEdge);
+    }
+  } catch (err) {
+    for (const a of added.slice().reverse()) {
+      try {
+        store.removeEdge(a.id);
+      } catch {
+      }
+    }
+    try {
+      store.updateNode(args.node_id, { type: oldType });
+    } catch {
+    }
+    for (const r of removed.slice().reverse()) {
+      try {
+        store.addEdge(r, true);
+      } catch {
+      }
+    }
+    return {
+      migrated: false,
+      error: `Migration failed mid-apply: ${err.message}. Graph rolled back.`
+    };
+  }
+  const edgesRewritten = plans.map((p, i) => ({
+    id: added[i].id,
+    from: p.oldEdge.type,
+    to: p.newType
+  }));
+  return {
+    migrated: true,
+    node_id: args.node_id,
+    from_type: oldType,
+    to_type: newType,
+    edges_rewritten: edgesRewritten,
+    ...aliasWarning ? { warning: aliasWarning } : {}
+  };
+}
+
+// src/client.ts
+var UPGClient = class {
+  options;
+  store = null;
+  loadPromise = null;
+  /** Node operations namespace. */
+  nodes;
+  /** Edge operations namespace. */
+  edges;
+  constructor(options) {
+    this.options = options;
+    this.nodes = new NodesAPI(this);
+    this.edges = new EdgesAPI(this);
+  }
+  /**
+   * Load the .upg file. Called automatically on first operation unless
+   * `{ lazy: true }` was set. Safe to call multiple times — repeated calls
+   * are coalesced. If load fails (transient I/O, parse error, etc.) the
+   * promise is rejected AND the cached promise is cleared, so the next
+   * call retries from scratch rather than re-throwing the stale error.
+   */
+  async load() {
+    if (this.store && !this.loadPromise) return;
+    if (this.loadPromise) return this.loadPromise;
+    this.loadPromise = (async () => {
+      try {
+        const store = new UPGFileStore();
+        await store.load(this.options.file);
+        this.store = store;
+      } catch (err) {
+        this.loadPromise = null;
+        throw err;
+      }
+    })();
+    return this.loadPromise;
+  }
+  /** Internal: get the loaded store, loading on demand. */
+  async getStore() {
+    if (!this.store) await this.load();
+    if (!this.store) throw new Error("UPGClient: store failed to load");
+    return this.store;
+  }
+  /** Persist pending changes to disk. Called automatically after mutations. */
+  async flush() {
+    const store = await this.getStore();
+    await store.flush();
+  }
+  /** Compute a health score (0–100) plus the underlying graph digest. */
+  async health() {
+    const store = await this.getStore();
+    const digest = computeGraphDigest(store);
+    return { score: computeHealthScore(digest), digest };
+  }
+  /** Search nodes by free-text query. */
+  async search(query, options = {}) {
+    const store = await this.getStore();
+    return searchNodes(store, query, {
+      limit: options.limit ?? 20,
+      ...options.type ? { type: options.type } : {}
+    });
+  }
+  /**
+   * Verify integrity of the loaded graph. Returns the integrity report from
+   * the last load + any in-memory mutation checks. `null` indicates no
+   * integrity issues were detected.
+   */
+  async verify() {
+    const store = await this.getStore();
+    return store.getIntegrityReport();
+  }
+  /**
+   * Diff against a previous version. Not yet implemented — tracked in
+   * UPG-541 follow-up. Will return a structured changeset between the
+   * current graph and the named ref (git revision or snapshot id).
+   */
+  async diff(_ref) {
+    throw new Error(
+      "UPGClient.diff() is not yet implemented. Use the CLI (`upg diff <ref>`) for now."
+    );
+  }
+  /** Release file watchers and free resources. */
+  async close() {
+    if (!this.store) return;
+    await this.store.flush();
+    this.store = null;
+    this.loadPromise = null;
+  }
+};
+var NodesAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Create a node. The `type` is validated against the UPG entity catalog —
+   * deprecated aliases are accepted with a warning, genuinely unknown types
+   * throw `UnknownEntityTypeError`.
+   */
+  async create(args) {
+    const store = await this.client.getStore();
+    const result = createNode(store, args);
+    await store.flush();
+    return result;
+  }
+  /** List nodes, optionally filtered by type / status / tag. */
+  async list(options = {}) {
+    const store = await this.client.getStore();
+    return listNodes(store, options);
+  }
+  /** Get a single node by id. Returns `undefined` if not found. */
+  async get(id) {
+    const store = await this.client.getStore();
+    const result = getNode(store, { node_id: id });
+    return result?.node;
+  }
+  /** Update a node by id. Returns the updated node. */
+  async update(id, patch) {
+    const store = await this.client.getStore();
+    const updated = store.updateNode(id, patch);
+    await store.flush();
+    return updated;
+  }
+  /** Delete a node and all incident edges. */
+  async delete(id) {
+    const store = await this.client.getStore();
+    const result = deleteNode(store, { node_id: id });
+    await store.flush();
+    return result;
+  }
+};
+var EdgesAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Connect two nodes with an edge. Edge type is inferred from source +
+   * target entity types if not provided.
+   */
+  async connect(sourceId, targetId, opts = {}) {
+    const store = await this.client.getStore();
+    const args = {
+      source_id: sourceId,
+      target_id: targetId,
+      ...opts
+    };
+    const result = createEdge(store, args);
+    await store.flush();
+    return result;
+  }
+  /** List edges, optionally filtered by source / target / type. */
+  async list(options = {}) {
+    const store = await this.client.getStore();
+    let edges = store.getAllEdges();
+    if (options.source) edges = edges.filter((e) => e.source === options.source);
+    if (options.target) edges = edges.filter((e) => e.target === options.target);
+    if (options.type) edges = edges.filter((e) => e.type === options.type);
+    return edges;
+  }
+  /** Delete an edge by id. */
+  async delete(id) {
+    const store = await this.client.getStore();
+    const result = deleteEdge(store, { edge_id: id });
+    await store.flush();
+    return result;
+  }
+};
+
+// src/lib/workspace.ts
+import * as fsp from "fs/promises";
+import * as path2 from "path";
+import { createHash as createHash2 } from "crypto";
+var WorkspaceAlreadyExistsError = class extends Error {
+  constructor() {
+    super("Workspace already exists. Use get_workspace_info to see current state.");
+    this.name = "WorkspaceAlreadyExistsError";
+  }
+};
+var WorkspaceNotInitialisedError = class extends Error {
+  constructor() {
+    super(
+      "Workspace not initialised. Run `init_workspace` first to enable multi-product management."
+    );
+    this.name = "WorkspaceNotInitialisedError";
+  }
+};
+var InvalidProductNameError = class extends Error {
+  constructor(reason) {
+    super(`Invalid product name: ${reason}`);
+    this.name = "InvalidProductNameError";
+  }
+};
+var InvalidProductStageError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidProductStageError";
+  }
+};
+async function readProductTitle(filePath, fallback) {
+  try {
+    const raw = await fsp.readFile(filePath, "utf-8");
+    const doc = JSON.parse(raw);
+    if (doc.product?.title && typeof doc.product.title === "string") {
+      return doc.product.title;
+    }
+  } catch {
+  }
+  return fallback;
+}
+async function initWorkspace({
+  cwd,
+  store,
+  moveExisting = true
+}) {
+  const resolvedCwd = path2.resolve(cwd);
+  const upgDir = path2.resolve(resolvedCwd, ".upg");
+  try {
+    await fsp.access(path2.join(upgDir, "workspace.json"));
+    throw new WorkspaceAlreadyExistsError();
+  } catch (err) {
+    if (err instanceof WorkspaceAlreadyExistsError) throw err;
+  }
+  await fsp.mkdir(upgDir, { recursive: true });
+  const rootEntries = await fsp.readdir(resolvedCwd, { withFileTypes: true });
+  const rootUpgFiles = rootEntries.filter((e) => e.isFile() && e.name.endsWith(".upg")).map((e) => e.name).sort();
+  let preExistingFiles = [];
+  try {
+    const upgDirEntries = await fsp.readdir(upgDir, { withFileTypes: true });
+    preExistingFiles = upgDirEntries.filter((e) => e.isFile() && e.name.endsWith(".upg")).map((e) => e.name).sort();
+  } catch {
+  }
+  const products = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const file of preExistingFiles) {
+    const filePath = path2.join(upgDir, file);
+    const title = await readProductTitle(filePath, path2.basename(file, ".upg"));
+    products.push({ file, title });
+    seen.add(file);
+  }
+  if (moveExisting) {
+    for (const file of rootUpgFiles) {
+      const srcPath = path2.resolve(resolvedCwd, file);
+      const destPath = path2.resolve(upgDir, file);
+      if (srcPath === destPath || path2.dirname(srcPath) === upgDir) {
+        if (!seen.has(file)) {
+          const title2 = await readProductTitle(srcPath, path2.basename(file, ".upg"));
+          products.push({ file, title: title2 });
+          seen.add(file);
+        }
+        continue;
+      }
+      const title = await readProductTitle(srcPath, path2.basename(file, ".upg"));
+      let destExists = false;
+      try {
+        await fsp.access(destPath);
+        destExists = true;
+      } catch {
+      }
+      if (!destExists) {
+        await fsp.rename(srcPath, destPath);
+      }
+      if (!seen.has(file)) {
+        products.push({ file, title });
+        seen.add(file);
+      }
+    }
+  }
+  if (products.length === 0) {
+    const currentFile = store.getFilePath();
+    const basename2 = path2.basename(currentFile);
+    const destPath = path2.resolve(upgDir, basename2);
+    try {
+      await fsp.access(destPath);
+    } catch {
+      await fsp.copyFile(currentFile, destPath);
+    }
+    const product2 = store.getProduct();
+    products.push({ file: basename2, title: product2.title });
+  }
+  const defaultProduct = products[0].file;
+  await fsp.writeFile(
+    path2.join(upgDir, "workspace.json"),
+    JSON.stringify({ version: "1.0", default_product: defaultProduct, products }, null, 2) + "\n",
+    "utf-8"
+  );
+  const newFilePath = path2.join(upgDir, defaultProduct);
+  await store.flush();
+  store.stopWatching();
+  await store.load(newFilePath);
+  const product = store.getProduct();
+  return {
+    workspace_path: ".upg/",
+    default_product: defaultProduct,
+    products,
+    current_product: { title: product.title, entities: store.getAllNodes().length }
+  };
+}
+function computeIntegrityChecksum(doc) {
+  const sortedNodes = [...doc.nodes].sort((a, b) => a.id.localeCompare(b.id));
+  const sortedEdges = [...doc.edges].sort((a, b) => a.id.localeCompare(b.id));
+  const content = JSON.stringify({ nodes: sortedNodes, edges: sortedEdges });
+  return createHash2("sha256").update(content).digest("hex").slice(0, 32);
+}
+async function createProduct(args) {
+  const { cwd, store, name, slug: slugArg, description, stage, portfolio_id } = args;
+  const upgDir = path2.resolve(cwd, ".upg");
+  try {
+    await fsp.access(path2.join(upgDir, "workspace.json"));
+  } catch {
+    throw new WorkspaceNotInitialisedError();
+  }
+  if (typeof name !== "string" || name.trim().length === 0) {
+    throw new InvalidProductNameError("name must be a non-empty string");
+  }
+  const trimmedName = name.trim();
+  if (stage !== void 0) {
+    const stageError = validateProductStageStrict(stage);
+    if (stageError !== null) {
+      throw new InvalidProductStageError(stageError);
+    }
+  }
+  const upgDirEntries = await fsp.readdir(upgDir, { withFileTypes: true });
+  const existingSlugs = new Set(
+    upgDirEntries.filter((e) => e.isFile() && e.name.endsWith(".upg")).map((e) => path2.basename(e.name, ".upg"))
+  );
+  const baseSlug = slugArg && slugArg.trim().length > 0 ? generateSlug(slugArg) : generateSlug(trimmedName);
+  const slug = resolveSlugCollision(baseSlug, existingSlugs);
+  const filename = `${slug}.upg`;
+  const destPath = path2.join(upgDir, filename);
+  const newProductId = productId();
+  const newDoc = {
+    upg_version: UPG_VERSION,
+    exported_at: (/* @__PURE__ */ new Date()).toISOString(),
+    source: { tool: "upg-mcp-local" },
+    product: {
+      id: newProductId,
+      title: trimmedName,
+      ...description ? { description } : {},
+      ...stage ? { stage } : {}
+    },
+    nodes: [],
+    edges: []
+  };
+  newDoc._integrity = {
+    checksum: computeIntegrityChecksum(newDoc),
+    verified_at: (/* @__PURE__ */ new Date()).toISOString(),
+    verified_by: "upg-mcp-local"
+  };
+  try {
+    await fsp.access(destPath);
+    throw new Error(`File already exists at ${destPath} \u2014 slug resolution failed`);
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  await fsp.writeFile(destPath, JSON.stringify(newDoc, null, 2) + "\n", "utf-8");
+  const workspacePath = path2.join(upgDir, "workspace.json");
+  const workspaceRaw = await fsp.readFile(workspacePath, "utf-8");
+  const workspace = JSON.parse(workspaceRaw);
+  workspace.products = [
+    ...workspace.products,
+    { file: filename, title: trimmedName }
+  ];
+  await fsp.writeFile(
+    workspacePath,
+    JSON.stringify(workspace, null, 2) + "\n",
+    "utf-8"
+  );
+  let portfolioAttached = false;
+  if (portfolio_id) {
+    const portfolio = store.getNode(portfolio_id);
+    if (portfolio && portfolio.type === "portfolio") {
+      store.addNode({
+        id: newProductId,
+        type: "product",
+        title: trimmedName,
+        ...description ? { description } : {}
+      });
+      store.addEdge({
+        id: edgeId(),
+        source: portfolio_id,
+        target: newProductId,
+        type: "portfolio_contains_product"
+      });
+      portfolioAttached = true;
+    }
+  }
+  return {
+    id: newProductId,
+    file: filename,
+    slug,
+    title: trimmedName,
+    workspace_path: ".upg/",
+    portfolio_attached: portfolioAttached
+  };
+}
+
+// src/lib/portfolio-routing.ts
+import * as fs2 from "fs";
+import * as path3 from "path";
+import { createHash as createHash3 } from "crypto";
+var PORTFOLIO_SCOPED_TYPES = /* @__PURE__ */ new Set([
+  "portfolio",
+  "organization",
+  "product_area"
+]);
+var PORTFOLIO_FILENAME = "portfolio.upg";
+function isPortfolioScopedType(type) {
+  return PORTFOLIO_SCOPED_TYPES.has(type);
+}
+function resolvePortfolioPath(cwd) {
+  const upgDir = path3.join(cwd, ".upg");
+  if (!fs2.existsSync(upgDir)) return null;
+  return path3.join(upgDir, PORTFOLIO_FILENAME);
+}
+function resolveOrCreatePortfolioPath(cwd) {
+  const upgDir = path3.join(cwd, ".upg");
+  if (!fs2.existsSync(upgDir)) {
+    fs2.mkdirSync(upgDir, { recursive: true });
+  }
+  return path3.join(upgDir, PORTFOLIO_FILENAME);
+}
+async function openPortfolioStore(portfolioPath) {
+  const store = new UPGPortfolioStore();
+  await store.loadOrInit(portfolioPath);
+  return store;
+}
+var PortfolioRoutingError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PortfolioRoutingError";
+  }
+};
+async function writePortfolioScopedNode(cwd, args) {
+  if (!isPortfolioScopedType(args.type)) {
+    throw new PortfolioRoutingError(
+      `writePortfolioScopedNode called with non-portfolio type "${args.type}". Valid types: ${[...PORTFOLIO_SCOPED_TYPES].join(", ")}.`
+    );
+  }
+  const portfolioPath = resolveOrCreatePortfolioPath(cwd);
+  const store = await openPortfolioStore(portfolioPath);
+  const doc = store.getDocument();
+  if (!doc) {
+    throw new PortfolioRoutingError(
+      `Failed to initialise portfolio document at ${portfolioPath}`
+    );
+  }
+  let result;
+  switch (args.type) {
+    case "portfolio":
+      result = appendPortfolio(doc, args, portfolioPath);
+      break;
+    case "product_area":
+      result = appendProductArea(doc, args, portfolioPath);
+      break;
+    case "organization":
+      result = setOrganization(doc, args, portfolioPath);
+      break;
+    default:
+      throw new PortfolioRoutingError(`Unhandled portfolio-scoped type: ${args.type}`);
+  }
+  store.markDirty();
+  await store.flush();
+  return result;
+}
+function appendPortfolio(doc, args, portfolioPath) {
+  const props = args.properties ?? {};
+  const entity = {
+    id: nodeId(),
+    title: args.title
+  };
+  if (args.description) entity.description = args.description;
+  if (typeof props.parent_portfolio_id === "string" || props.parent_portfolio_id === null) {
+    entity.parent_portfolio_id = props.parent_portfolio_id;
+  }
+  if (props.hierarchy_model === "flat" || props.hierarchy_model === "nested" || props.hierarchy_model === "matrix") {
+    entity.hierarchy_model = props.hierarchy_model;
+  }
+  if (Array.isArray(props.products)) {
+    entity.products = props.products.filter((p) => typeof p === "string");
+  }
+  doc.portfolios.push(entity);
+  return { entity, written_to: "portfolios", portfolio_file: portfolioPath };
+}
+function appendProductArea(doc, args, portfolioPath) {
+  const props = args.properties ?? {};
+  const entity = {
+    id: nodeId(),
+    title: args.title
+  };
+  if (args.description) entity.description = args.description;
+  if (typeof props.parent_area_id === "string" || props.parent_area_id === null) {
+    entity.parent_area_id = props.parent_area_id;
+  }
+  if (props.strategic_priority === "critical" || props.strategic_priority === "high" || props.strategic_priority === "medium" || props.strategic_priority === "low") {
+    entity.strategic_priority = props.strategic_priority;
+  }
+  if (Array.isArray(props.products)) {
+    entity.products = props.products.filter((p) => typeof p === "string");
+  }
+  doc.product_areas.push(entity);
+  return { entity, written_to: "product_areas", portfolio_file: portfolioPath };
+}
+function setOrganization(doc, args, portfolioPath) {
+  const props = args.properties ?? {};
+  const existing = doc.organization;
+  const isPlaceholder = isPlaceholderOrganization(existing);
+  if (existing && !isPlaceholder && !args.overwrite_organization) {
+    throw new PortfolioRoutingError(
+      `Portfolio already has an organization (id: "${existing.id}", title: "${existing.title}"). A portfolio holds exactly one organization. Pass overwrite_organization: true to replace it (e.g. create_node({type: "organization", title: "...", overwrite_organization: true})), or call update_node on the existing organization id.`
+    );
+  }
+  const entity = {
+    id: `org_${createHash3("sha256").update(args.title).digest("hex").slice(0, 8)}`,
+    title: args.title
+  };
+  if (args.description) entity.description = args.description;
+  if (typeof props.logo_url === "string") entity.logo_url = props.logo_url;
+  if (typeof props.industry === "string") entity.industry = props.industry;
+  const warning = !isPlaceholder && args.overwrite_organization ? `Replaced existing organization "${existing.title}" (id: ${existing.id}) with "${entity.title}" (id: ${entity.id}).` : void 0;
+  doc.organization = entity;
+  return {
+    entity,
+    written_to: "organization",
+    portfolio_file: portfolioPath,
+    ...warning ? { warning } : {}
+  };
+}
+function isPlaceholderOrganization(org) {
+  if (!org) return true;
+  if (org.title !== "Portfolio") return false;
+  const placeholderId = `org_${createHash3("sha256").update("Portfolio").digest("hex").slice(0, 8)}`;
+  return org.id === placeholderId;
+}
+async function openPortfolioStoreIfExists(cwd) {
+  const portfolioPath = resolvePortfolioPath(cwd);
+  if (!portfolioPath) return null;
+  if (!fs2.existsSync(portfolioPath)) return null;
+  const store = new UPGPortfolioStore();
+  await store.loadOrInit(portfolioPath);
+  return store;
+}
+function registerProductOnPortfolio(doc, ref) {
+  if (!ref.id) return false;
+  const products = doc.products;
+  if (products.some((p) => p.id === ref.id)) return false;
+  const entry = { id: ref.id };
+  if (ref.file_path) entry.file_path = ref.file_path;
+  if (ref.title) entry.title = ref.title;
+  products.push(entry);
+  return true;
+}
+function findProductFileById(cwd, productId2) {
+  const upgDir = path3.join(cwd, ".upg");
+  if (!fs2.existsSync(upgDir)) return null;
+  let entries;
+  try {
+    entries = fs2.readdirSync(upgDir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".upg")) continue;
+    if (entry.name === PORTFOLIO_FILENAME) continue;
+    const filePath = path3.join(upgDir, entry.name);
+    try {
+      const raw = fs2.readFileSync(filePath, "utf-8");
+      const doc = JSON.parse(raw);
+      if (doc.product?.id === productId2) {
+        return {
+          file_path: path3.relative(cwd, filePath),
+          title: doc.product.title ?? entry.name
+        };
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+export {
+  BUSINESS_AREAS,
+  BUSINESS_AREA_META,
+  CHAINS,
+  DESCRIPTION_SOFT_LIMIT,
+  ENTITY_CLASSIFICATION,
+  InferEdgeTypeError,
+  InvalidProductNameError,
+  InvalidProductStageError,
+  LIFECYCLE_PHASES,
+  PORTFOLIO_FILENAME,
+  PORTFOLIO_SCOPED_TYPES,
+  PROPERTY_TREE_SOFT_BYTES,
+  PROPERTY_TREE_SOFT_DEPTH,
+  PortfolioRoutingError,
+  STAGE_COVERAGE_TARGETS,
+  TIER_CLUSTER_META,
+  TIER_DESCRIPTIONS,
+  TITLE_SOFT_LIMIT,
+  UPGClient,
+  UPGFileStore,
+  UPGPortfolioStore,
+  UPG_ANTI_PATTERNS,
+  UPG_REGIONS,
+  UnknownEntityTypeError,
+  WorkspaceAlreadyExistsError,
+  WorkspaceNotInitialisedError,
+  autoFillSlug,
+  batchCreateNodes,
+  batchMoveNodes,
+  buildAdjacentEdges,
+  buildAlternateAnchors,
+  buildAnchorHint,
+  buildResolverHints,
+  checkLengthCaps,
+  checkPropertyTypes,
+  classifyDanglingEdges,
+  collectAntiPatternInputs,
+  computeGraphDigest,
+  computeHealthScore,
+  computeSchemaDriftSummary,
+  createEdge,
+  createNode,
+  createProduct,
+  deleteEdge,
+  deleteNode,
+  edgeId,
+  evaluateExpression,
+  executeInspect,
+  executePlan,
+  executePrioritise,
+  executeReflect,
+  executeTrace,
+  findProductFileById,
+  getClassification,
+  getDefaultStatus,
+  getEntitiesForBusinessArea,
+  getEntitiesForCluster,
+  getEntitiesForTier,
+  getEntitiesForTierAndArea,
+  getEntitiesUpToTier,
+  getNode,
+  getNodes,
+  getOrphans,
+  getTierEntityCount,
+  getTierForStage,
+  inferEdgeType,
+  inferEdgeTypeWithTier,
+  initWorkspace,
+  isPortfolioScopedType,
+  isRelevantForStage,
+  listNodes,
+  migrateNodeType,
+  moveNode,
+  nodeId,
+  normalizeTags,
+  openPortfolioStore,
+  openPortfolioStoreIfExists,
+  productId,
+  registerProductOnPortfolio,
+  renderDanglingReport,
+  renderDriftSummary,
+  renderPropertyTypeWarning,
+  resolveCoverageStage,
+  resolveEntityType,
+  resolveOrCreatePortfolioPath,
+  resolvePortfolioPath,
+  searchNodes,
+  sortByType,
+  typeSortPriority,
+  validateClassificationCoverage,
+  validateEdgeTypePair,
+  validateStatusAgainstLifecycle,
+  writePortfolioScopedNode
+};
+//# sourceMappingURL=index.js.map