@unified-product-graph/core 0.7.4 → 0.7.5

package/dist/index.cjs

@@ -49,6 +49,7 @@ __export(index_exports, {
   UPG_ANTI_PATTERNS: () => UPG_ANTI_PATTERNS,
   UPG_APPROACHES: () => UPG_APPROACHES,
   UPG_APPROACHES_BY_ID: () => UPG_APPROACHES_BY_ID,
+  UPG_CANONICAL_FORMAT_VERSION: () => UPG_CANONICAL_FORMAT_VERSION,
   UPG_CONTAINMENT_FREE_TYPES: () => UPG_CONTAINMENT_FREE_TYPES,
   UPG_COUNT_BENCHMARKS: () => UPG_COUNT_BENCHMARKS,
   UPG_CROSS_EDGE_TYPES: () => UPG_CROSS_EDGE_TYPES,
@@ -112,8 +113,10 @@ __export(index_exports, {
   coerceProductStage: () => coerceProductStage,
   collectSlugsForType: () => collectSlugsForType,
   compareVersions: () => compareVersions,
+  computeBodyChecksum: () => computeBodyChecksum,
   evaluateAntiPatterns: () => evaluateAntiPatterns,
   findInvalidStatusMigrationTargets: () => findInvalidStatusMigrationTargets,
+  formatUpgText: () => formatUpgText,
   generateSlug: () => generateSlug,
   getAnchorEntity: () => getAnchorEntity,
   getAntiPatternById: () => getAntiPatternById,
@@ -156,6 +159,7 @@ __export(index_exports, {
   getValidChildren: () => getValidChildren,
   getVisibleTypes: () => getVisibleTypes,
   hasStatusMigration: () => hasStatusMigration,
+  isCanonical: () => isCanonical,
   isCanonicalProductStage: () => isCanonicalProductStage,
   isContainmentFreeType: () => isContainmentFreeType,
   isDeprecatedType: () => isDeprecatedType,
@@ -166,6 +170,7 @@ __export(index_exports, {
   isLifecycleFreeType: () => isLifecycleFreeType,
   isLifecyclePlannedType: () => isLifecyclePlannedType,
   isPolymorphicEdge: () => isPolymorphicEdge,
+  isPortfolio: () => isPortfolio,
   isRegisteredPolymorphicEdge: () => isRegisteredPolymorphicEdge,
   isSubSequenceStep: () => isSubSequenceStep,
   isUPGDocument: () => isUPGDocument,
@@ -175,6 +180,8 @@ __export(index_exports, {
   migrateNodeProperties: () => migrateNodeProperties,
   migrateProductStage: () => migrateProductStage,
   migrateStatusValue: () => migrateStatusValue,
+  normalizeDocument: () => normalizeDocument,
+  parseUpg: () => parseUpg,
   pickCanonicalEdge: () => pickCanonicalEdge,
   resolveAllEdges: () => resolveAllEdges,
   resolveContainmentEdge: () => resolveContainmentEdge,
@@ -182,6 +189,7 @@ __export(index_exports, {
   resolveLabel: () => resolveLabel,
   resolveSlugCollision: () => resolveSlugCollision,
   rotateSlug: () => rotateSlug,
+  serializeCanonical: () => serializeCanonical,
   validateProductStageStrict: () => validateProductStageStrict,
   validateUPGDocument: () => validateUPGDocument,
   validateUPGFramework: () => validateUPGFramework,
@@ -12821,26 +12829,6 @@ var UPG_FRAMEWORKS = [
         "label": "Items to score",
         "entityTypeId": "feature",
         "description": "Features, opportunities, or solutions being evaluated"
-      },
-      {
-        "label": "Reach",
-        "entityTypeId": "feature",
-        "description": "How many users does this affect per quarter?"
-      },
-      {
-        "label": "Impact",
-        "entityTypeId": "feature",
-        "description": "How much does this move the target outcome?"
-      },
-      {
-        "label": "Confidence",
-        "entityTypeId": "feature",
-        "description": "How sure are we about these estimates?"
-      },
-      {
-        "label": "Effort",
-        "entityTypeId": "feature",
-        "description": "How many person-months to build?"
       }
     ],
     "data": {
@@ -12854,31 +12842,35 @@ var UPG_FRAMEWORKS = [
         "feature": [
           {
             "property": "reach",
-            "type": "number",
+            "type": "assessment",
+            "scale_id": "reach_5",
             "required": true,
             "label": "Reach",
             "description": "How many users will this impact per quarter?"
           },
           {
             "property": "impact",
-            "type": "number",
+            "type": "assessment",
+            "scale_id": "impact_5",
             "required": true,
             "label": "Impact",
-            "description": "How much will this impact each user? (1=minimal, 2=low, 3=medium, 4=high, 5=massive)"
+            "description": "How much will this impact each user, on the impact scale?"
           },
           {
             "property": "confidence",
-            "type": "number",
+            "type": "assessment",
+            "scale_id": "confidence_5",
             "required": true,
             "label": "Confidence",
-            "description": "How confident are you in the estimates? (0.5=low, 0.8=medium, 1.0=high)"
+            "description": "How confident are you in the reach, impact, and effort estimates?"
           },
           {
             "property": "effort",
-            "type": "number",
+            "type": "assessment",
+            "scale_id": "effort_5",
             "required": true,
             "label": "Effort",
-            "description": "Person-months of effort required"
+            "description": "How much work is required to build and ship this, on the effort scale?"
           }
         ]
       },
@@ -13072,7 +13064,7 @@ var UPG_FRAMEWORKS = [
       {
         "label": "Performance",
         "entityTypeId": "feature",
-        "description": "More is better, with linear satisfaction increase"
+        "description": "More is better: linear satisfaction increase"
       },
       {
         "label": "Delighters",
@@ -13321,24 +13313,9 @@ var UPG_FRAMEWORKS = [
     ],
     "slots": [
       {
-        "label": "Must Have",
-        "entityTypeId": "feature",
-        "description": "Non-negotiable requirements for this release"
-      },
-      {
-        "label": "Should Have",
-        "entityTypeId": "feature",
-        "description": "Important but not critical; a workaround exists"
-      },
-      {
-        "label": "Could Have",
-        "entityTypeId": "feature",
-        "description": "Nice to have; include if time permits"
-      },
-      {
-        "label": "Won't Have",
+        "label": "Requirements to categorise",
         "entityTypeId": "feature",
-        "description": "Explicitly out of scope for now"
+        "description": "Features or requirements sorted into the four MoSCoW buckets"
       }
     ],
     "data": {
@@ -13348,7 +13325,23 @@ var UPG_FRAMEWORKS = [
           "role": "scored_item"
         }
       ],
-      "required_properties": {},
+      "required_properties": {
+        "feature": [
+          {
+            "property": "moscow",
+            "type": "enum",
+            "required": true,
+            "label": "MoSCoW priority",
+            "description": "Which scope bucket this requirement falls into for the current release",
+            "enum_values": [
+              "must",
+              "should",
+              "could",
+              "wont"
+            ]
+          }
+        ]
+      },
       "computed_properties": [
         {
           "property": "must_have_ratio",
@@ -13368,28 +13361,19 @@ var UPG_FRAMEWORKS = [
         "columns": [
           {
             "property": "title",
-            "label": "Must Have",
-            "sortable": true
-          },
-          {
-            "property": "title",
-            "label": "Should Have",
-            "sortable": true
-          },
-          {
-            "property": "title",
-            "label": "Could Have",
+            "label": "Requirement",
             "sortable": true
           },
           {
-            "property": "title",
-            "label": "Won't Have",
-            "sortable": true
+            "property": "moscow",
+            "label": "Priority",
+            "sortable": true,
+            "format": "badge"
           }
         ]
       },
       "sort_by": {
-        "property": "title",
+        "property": "moscow",
         "direction": "asc"
       },
       "colour_by": "type",
@@ -13940,24 +13924,9 @@ var UPG_FRAMEWORKS = [
     ],
     "slots": [
       {
-        "label": "Deployment Frequency",
+        "label": "Delivery metric",
         "entityTypeId": "metric",
-        "description": "How often you deploy to production"
-      },
-      {
-        "label": "Lead Time for Changes",
-        "entityTypeId": "metric",
-        "description": "Time from commit to production"
-      },
-      {
-        "label": "Change Failure Rate",
-        "entityTypeId": "metric",
-        "description": "Percentage of deployments causing failures"
-      },
-      {
-        "label": "Time to Restore",
-        "entityTypeId": "metric",
-        "description": "How long to recover from a failure"
+        "description": "One of the four DORA software-delivery performance metrics"
       }
     ],
     "data": {
@@ -13967,7 +13936,36 @@ var UPG_FRAMEWORKS = [
           "role": "item"
         }
       ],
-      "required_properties": {},
+      "required_properties": {
+        "metric": [
+          {
+            "property": "dora_metric",
+            "type": "enum",
+            "required": true,
+            "label": "DORA metric",
+            "description": "Which of the four DORA metrics this measures",
+            "enum_values": [
+              "deployment_frequency",
+              "lead_time_for_changes",
+              "change_failure_rate",
+              "time_to_restore"
+            ]
+          },
+          {
+            "property": "performance_tier",
+            "type": "enum",
+            "required": false,
+            "label": "Performance tier",
+            "description": "Where this metric sits on the DORA elite-to-low benchmark",
+            "enum_values": [
+              "elite",
+              "high",
+              "medium",
+              "low"
+            ]
+          }
+        ]
+      },
       "computed_properties": [
         {
           "property": "stability_index",
@@ -14123,29 +14121,9 @@ var UPG_FRAMEWORKS = [
     ],
     "slots": [
       {
-        "label": "Acquisition",
+        "label": "Lifecycle metric",
         "entityTypeId": "metric",
-        "description": "How do users find you?"
-      },
-      {
-        "label": "Activation",
-        "entityTypeId": "metric",
-        "description": "Do users have a great first experience?"
-      },
-      {
-        "label": "Retention",
-        "entityTypeId": "metric",
-        "description": "Do users come back?"
-      },
-      {
-        "label": "Revenue",
-        "entityTypeId": "metric",
-        "description": "Can you monetise the behaviour?"
-      },
-      {
-        "label": "Referral",
-        "entityTypeId": "metric",
-        "description": "Do users tell others?"
+        "description": "A metric tracking one stage of the customer lifecycle funnel"
       }
     ],
     "data": {
@@ -14155,7 +14133,24 @@ var UPG_FRAMEWORKS = [
           "role": "item"
         }
       ],
-      "required_properties": {},
+      "required_properties": {
+        "metric": [
+          {
+            "property": "lifecycle_stage",
+            "type": "enum",
+            "required": true,
+            "label": "Lifecycle stage",
+            "description": "Which AARRR funnel stage this metric measures",
+            "enum_values": [
+              "acquisition",
+              "activation",
+              "retention",
+              "revenue",
+              "referral"
+            ]
+          }
+        ]
+      },
       "computed_properties": [
         {
           "property": "conversion_rate",
@@ -14167,7 +14162,39 @@ var UPG_FRAMEWORKS = [
       ]
     },
     "structure": {
-      "pattern": "funnel"
+      "pattern": "funnel",
+      "stages": [
+        {
+          "id": "acquisition",
+          "label": "Acquisition",
+          "order": 0,
+          "entity_type": "metric"
+        },
+        {
+          "id": "activation",
+          "label": "Activation",
+          "order": 1,
+          "entity_type": "metric"
+        },
+        {
+          "id": "retention",
+          "label": "Retention",
+          "order": 2,
+          "entity_type": "metric"
+        },
+        {
+          "id": "revenue",
+          "label": "Revenue",
+          "order": 3,
+          "entity_type": "metric"
+        },
+        {
+          "id": "referral",
+          "label": "Referral",
+          "order": 4,
+          "entity_type": "metric"
+        }
+      ]
     },
     "presentation": {
       "layout": {
@@ -14214,24 +14241,9 @@ var UPG_FRAMEWORKS = [
     ],
     "slots": [
       {
-        "label": "North Star",
-        "entityTypeId": "metric",
-        "description": "The single metric reflecting core value delivered"
-      },
-      {
-        "label": "Input Metric 1",
-        "entityTypeId": "metric",
-        "description": "A driver metric you can directly influence"
-      },
-      {
-        "label": "Input Metric 2",
-        "entityTypeId": "metric",
-        "description": "A driver metric you can directly influence"
-      },
-      {
-        "label": "Input Metric 3",
+        "label": "Metric",
         "entityTypeId": "metric",
-        "description": "A driver metric you can directly influence"
+        "description": "The North Star metric or one of its 3-5 input (driver) metrics"
       }
     ],
     "data": {
@@ -14241,7 +14253,28 @@ var UPG_FRAMEWORKS = [
           "role": "item"
         }
       ],
-      "required_properties": {},
+      "required_properties": {
+        "metric": [
+          {
+            "property": "metric_role",
+            "type": "enum",
+            "required": true,
+            "label": "Metric role",
+            "description": "Whether this is the single North Star or a driver that feeds it",
+            "enum_values": [
+              "north_star",
+              "input"
+            ]
+          },
+          {
+            "property": "leverage",
+            "type": "number",
+            "required": false,
+            "label": "Leverage",
+            "description": "How strongly this input metric moves the North Star (input metrics only)"
+          }
+        ]
+      },
       "computed_properties": [
         {
           "property": "nsm_impact",
@@ -14541,7 +14574,7 @@ var UPG_FRAMEWORKS = [
       ]
     },
     "education": {
-      "purpose": "Design the product itself as the primary growth driver (free tier, self-serve onboarding, in-product virality), reducing dependence on sales-led acquisition.",
+      "purpose": "Design the product itself as the primary growth driver (free tier, self-serve onboarding, in-product virality) to reduce dependence on sales-led acquisition.",
       "core_question": "Can our product acquire, activate, and expand users without human intervention, and where in the loop do we still need sales?",
       "when_to_use": [
         "You are launching a new product, feature, or entering a new market",
@@ -14951,7 +14984,7 @@ var UPG_FRAMEWORKS = [
       {
         "label": "Team",
         "entityTypeId": "team",
-        "description": "Team conducting the health check: all members vote anonymously on each dimension"
+        "description": "Team conducting the health check; all members vote anonymously on each dimension"
       },
       {
         "label": "Retrospective",
@@ -15040,7 +15073,7 @@ var UPG_FRAMEWORKS = [
     },
     "education": {
       "purpose": "Regularly assess team health across dimensions (psychological safety, autonomy, mission clarity, fun, speed, learning) to catch problems early and celebrate strengths.",
-      "core_question": "How is the team really doing? Where do they feel strong, where do they feel stuck, and what has changed since last check?",
+      "core_question": "How is the team really doing: where do they feel strong, where do they feel stuck, and what has changed since last check?",
       "when_to_use": [
         "You need to improve team collaboration, clarity, or effectiveness",
         "Roles and responsibilities are unclear or causing friction",
@@ -15056,7 +15089,7 @@ var UPG_FRAMEWORKS = [
     "id": "raid-log",
     "name": "RAID Log",
     "version": "1.0.0",
-    "description": "A project management register tracking Risks, Assumptions, Issues, and Dependencies: the four categories most likely to derail a project if left unmanaged.",
+    "description": "A project management register tracking Risks, Assumptions, Issues, and Dependencies, the four categories most likely to derail a project if left unmanaged.",
     "category": "program_mgmt",
     "origin": {
       "type": "practitioner",
@@ -23507,6 +23540,273 @@ function validateExpression(expr) {
   return null;
 }
 
+// src/format/canonical.ts
+var import_node_crypto = require("crypto");
+var UPG_CANONICAL_FORMAT_VERSION = "1.0.0";
+var INTEGRITY_HASH_PRIMITIVE = "sha256";
+var INTEGRITY_DIGEST_HEX = 32;
+var INTEGRITY_ALGORITHM = "sha256-128";
+function canonicalizeOpen(value) {
+  if (Array.isArray(value)) return value.map(canonicalizeOpen);
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort(byCodeUnit)) {
+      out[key] = canonicalizeOpen(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+function byCodeUnit(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function isEmpty(value) {
+  if (value === null || value === void 0) return true;
+  if (typeof value === "string") return value.length === 0;
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value === "object") return Object.keys(value).length === 0;
+  return false;
+}
+function orderedObject(source, keyOrder, opts = {}) {
+  const force = new Set(opts.forceKeys ?? []);
+  const open = new Set(opts.openKeys ?? []);
+  const out = {};
+  const emit = (key) => {
+    if (!(key in source)) return;
+    const raw = source[key];
+    if (!force.has(key) && isEmpty(raw)) return;
+    out[key] = open.has(key) ? canonicalizeOpen(raw) : raw;
+  };
+  for (const key of keyOrder) emit(key);
+  for (const key of Object.keys(source).sort(byCodeUnit)) {
+    if (!keyOrder.includes(key)) emit(key);
+  }
+  return out;
+}
+function repairNodeDrift(node) {
+  const out = { ...node };
+  if (typeof out.properties === "string") {
+    out.properties = parseDriftString(out.properties, "object", `node ${node.id}.properties`);
+  }
+  if (typeof out.tags === "string") {
+    out.tags = parseDriftString(out.tags, "array", `node ${node.id}.tags`);
+  }
+  return out;
+}
+function parseDriftString(raw, expect, where) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`[upg fmt] ${where} is a string that is not valid JSON: ${truncate(raw)}`);
+  }
+  const ok = expect === "array" ? Array.isArray(parsed) : parsed !== null && typeof parsed === "object" && !Array.isArray(parsed);
+  if (!ok) throw new Error(`[upg fmt] ${where} is a string that does not parse to a JSON ${expect}: ${truncate(raw)}`);
+  return parsed;
+}
+function truncate(s) {
+  return s.length > 60 ? s.slice(0, 57) + "..." : s;
+}
+function deriveSummary(description) {
+  if (!description) return void 0;
+  const firstLine = description.split("\n").map((l) => l.trim()).find((l) => l.length > 0);
+  if (!firstLine) return void 0;
+  return firstLine.length > 200 ? firstLine.slice(0, 197) + "..." : firstLine;
+}
+function sortNodes(nodes) {
+  return [...nodes].sort(
+    (a, b) => byCodeUnit(a.type ?? "", b.type ?? "") || byCodeUnit(a.slug ?? a.title ?? "", b.slug ?? b.title ?? "") || byCodeUnit(a.id ?? "", b.id ?? "")
+  );
+}
+function sortEdges(edges) {
+  return [...edges].sort(
+    (a, b) => byCodeUnit(a.source ?? "", b.source ?? "") || byCodeUnit(a.target ?? "", b.target ?? "") || byCodeUnit(a.type ?? "", b.type ?? "") || byCodeUnit(a.id ?? "", b.id ?? "")
+  );
+}
+var NODE_KEY_ORDER = [
+  "id",
+  "type",
+  "title",
+  "slug",
+  "aliases",
+  "description",
+  "tags",
+  "status",
+  "lifecycle_status",
+  "source_id",
+  "source_type",
+  "mapping_confidence",
+  "external_tool",
+  "external_ref",
+  "external_id",
+  "sort_order",
+  "properties"
+];
+var EDGE_KEY_ORDER = ["id", "source", "target", "type", "mapping_confidence"];
+var CROSS_EDGE_KEY_ORDER = ["id", "source", "target", "type", "source_product_id", "target_product_id", "mapping_confidence"];
+var PRODUCT_KEY_ORDER = ["id", "title", "description", "stage", "properties"];
+function canonicalNode(node) {
+  const repaired = repairNodeDrift(node);
+  if (Array.isArray(repaired.tags)) {
+    repaired.tags = [...new Set(repaired.tags)].sort(byCodeUnit);
+  }
+  return orderedObject(repaired, NODE_KEY_ORDER, { forceKeys: ["id", "type", "title"], openKeys: ["properties"] });
+}
+function canonicalEdge(edge) {
+  return orderedObject(edge, EDGE_KEY_ORDER, {
+    forceKeys: ["id", "source", "target", "type"]
+  });
+}
+function canonicalCrossEdge(edge) {
+  return orderedObject(edge, CROSS_EDGE_KEY_ORDER, {
+    forceKeys: ["id", "source", "target", "type"]
+  });
+}
+function canonicalProduct(product) {
+  return orderedObject(product, PRODUCT_KEY_ORDER, { forceKeys: ["id", "title"], openKeys: ["properties"] });
+}
+function singleBody(doc) {
+  return {
+    product: canonicalProduct(doc.product),
+    nodes: sortNodes(doc.nodes ?? []).map(canonicalNode),
+    edges: sortEdges(doc.edges ?? []).map(canonicalEdge)
+  };
+}
+function portfolioBody(doc) {
+  const products = [...doc.products ?? []].sort((a, b) => byCodeUnit(a.id ?? "", b.id ?? "")).map((p) => {
+    const { nodes, edges, ...rest } = p;
+    return {
+      ...canonicalProduct(rest),
+      nodes: sortNodes(nodes ?? []).map(canonicalNode),
+      edges: sortEdges(edges ?? []).map(canonicalEdge)
+    };
+  });
+  return {
+    organization: orderedObject(doc.organization, ["id", "title", "description", "logo_url", "industry"], { forceKeys: ["id", "title"] }),
+    product_areas: [...doc.product_areas ?? []].sort((a, b) => byCodeUnit(a.id ?? "", b.id ?? "")).map((a) => orderedObject(a, ["id", "title", "description", "parent_area_id", "strategic_priority", "products"], { forceKeys: ["id", "title"] })),
+    portfolios: [...doc.portfolios ?? []].sort((a, b) => byCodeUnit(a.id ?? "", b.id ?? "")).map((p) => orderedObject(p, ["id", "title", "description", "parent_portfolio_id", "hierarchy_model", "products"], { forceKeys: ["id", "title"] })),
+    products,
+    cross_edges: sortEdges(doc.cross_edges ?? []).map(canonicalCrossEdge)
+  };
+}
+function computeBodyChecksum(doc) {
+  const body = isPortfolio(doc) ? portfolioBody(doc) : singleBody(doc);
+  const content = JSON.stringify(body);
+  return (0, import_node_crypto.createHash)(INTEGRITY_HASH_PRIMITIVE).update(content).digest("hex").slice(0, INTEGRITY_DIGEST_HEX);
+}
+function isPortfolio(doc) {
+  return doc.type === "portfolio" || "cross_edges" in doc;
+}
+function serializeCanonical(doc, opts = {}) {
+  if (isPortfolio(doc)) return serializePortfolioWithHeader(doc, opts);
+  return serializeSingleWithHeader(doc, opts);
+}
+function buildProvenance(doc, opts) {
+  const source = opts.source ?? doc.source ?? { tool: "unknown" };
+  return orderedObject(
+    {
+      tool: source.tool,
+      tool_version: source.tool_version,
+      workspace_id: source.workspace_id,
+      exported_at: opts.exportedAt ?? doc.exported_at
+    },
+    ["tool", "tool_version", "workspace_id", "exported_at"],
+    { forceKeys: ["tool"] }
+  );
+}
+function serializeSingleWithHeader(doc, opts) {
+  const body = singleBody(doc);
+  const product = doc.product;
+  const header = {
+    format_version: UPG_CANONICAL_FORMAT_VERSION,
+    spec_version: doc.upg_version,
+    product: orderedObject(
+      { id: product.id, title: product.title, stage: product.stage },
+      ["id", "title", "stage"],
+      { forceKeys: ["id", "title"] }
+    )
+  };
+  const summary = deriveSummary(product.description);
+  if (summary) header.summary = summary;
+  header.counts = { nodes: doc.nodes?.length ?? 0, edges: doc.edges?.length ?? 0 };
+  header.provenance = buildProvenance(doc, opts);
+  header.integrity = { algorithm: INTEGRITY_ALGORITHM, body: computeBodyChecksum(doc) };
+  return JSON.stringify({ $upg: header, ...body }, null, 2) + "\n";
+}
+function serializePortfolioWithHeader(doc, opts) {
+  const body = portfolioBody(doc);
+  const org = doc.organization;
+  const header = {
+    format_version: UPG_CANONICAL_FORMAT_VERSION,
+    spec_version: doc.upg_version,
+    kind: "portfolio",
+    organization: orderedObject(
+      { id: org.id, title: org.title },
+      ["id", "title"],
+      { forceKeys: ["id", "title"] }
+    )
+  };
+  const summary = deriveSummary(org.description);
+  if (summary) header.summary = summary;
+  header.counts = {
+    products: doc.products?.length ?? 0,
+    product_areas: doc.product_areas?.length ?? 0,
+    portfolios: doc.portfolios?.length ?? 0,
+    cross_edges: doc.cross_edges?.length ?? 0
+  };
+  header.provenance = buildProvenance(doc, opts);
+  header.integrity = { algorithm: INTEGRITY_ALGORITHM, body: computeBodyChecksum(doc) };
+  return JSON.stringify({ $upg: header, ...body }, null, 2) + "\n";
+}
+function parseUpg(text) {
+  return normalizeDocument(JSON.parse(text));
+}
+function normalizeDocument(obj) {
+  const raw = obj;
+  const header = raw.$upg;
+  const upg_version = header?.spec_version ?? raw.upg_version;
+  const provenance = header?.provenance;
+  const exported_at = provenance?.exported_at ?? raw.exported_at;
+  const source = provenance ? { tool: provenance.tool, tool_version: provenance.tool_version, workspace_id: provenance.workspace_id } : raw.source;
+  const _integrity = header ? void 0 : raw._integrity;
+  const isPortfolioDoc = raw.type === "portfolio" || header?.kind === "portfolio" || "cross_edges" in raw;
+  if (isPortfolioDoc) {
+    const out2 = {
+      upg_version,
+      type: "portfolio",
+      exported_at: exported_at ?? "",
+      source: source ?? { tool: "unknown" },
+      organization: raw.organization,
+      product_areas: raw.product_areas ?? [],
+      portfolios: raw.portfolios ?? [],
+      products: (raw.products ?? []).map((p) => ({
+        ...p,
+        nodes: (p.nodes ?? []).map((n) => repairNodeDrift(n)),
+        edges: p.edges ?? []
+      })),
+      cross_edges: raw.cross_edges ?? []
+    };
+    return out2;
+  }
+  const out = {
+    upg_version,
+    exported_at: exported_at ?? "",
+    source: source ?? { tool: "unknown" },
+    product: raw.product,
+    nodes: (raw.nodes ?? []).map((n) => repairNodeDrift(n)),
+    edges: raw.edges ?? []
+  };
+  if (_integrity) out._integrity = _integrity;
+  return out;
+}
+function formatUpgText(text, opts = {}) {
+  return serializeCanonical(parseUpg(text), opts);
+}
+function isCanonical(text) {
+  const parsed = parseUpg(text);
+  return text === serializeCanonical(parsed);
+}
+
 // src/index.ts
 var UPG_VERSION = "0.7.3";
 var UPG_FORMAT_VERSION = "0.4.0";
@@ -23602,6 +23902,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   UPG_ANTI_PATTERNS,
   UPG_APPROACHES,
   UPG_APPROACHES_BY_ID,
+  UPG_CANONICAL_FORMAT_VERSION,
   UPG_CONTAINMENT_FREE_TYPES,
   UPG_COUNT_BENCHMARKS,
   UPG_CROSS_EDGE_TYPES,
@@ -23665,8 +23966,10 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   coerceProductStage,
   collectSlugsForType,
   compareVersions,
+  computeBodyChecksum,
   evaluateAntiPatterns,
   findInvalidStatusMigrationTargets,
+  formatUpgText,
   generateSlug,
   getAnchorEntity,
   getAntiPatternById,
@@ -23709,6 +24012,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   getValidChildren,
   getVisibleTypes,
   hasStatusMigration,
+  isCanonical,
   isCanonicalProductStage,
   isContainmentFreeType,
   isDeprecatedType,
@@ -23719,6 +24023,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   isLifecycleFreeType,
   isLifecyclePlannedType,
   isPolymorphicEdge,
+  isPortfolio,
   isRegisteredPolymorphicEdge,
   isSubSequenceStep,
   isUPGDocument,
@@ -23728,6 +24033,8 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   migrateNodeProperties,
   migrateProductStage,
   migrateStatusValue,
+  normalizeDocument,
+  parseUpg,
   pickCanonicalEdge,
   resolveAllEdges,
   resolveContainmentEdge,
@@ -23735,6 +24042,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   resolveLabel,
   resolveSlugCollision,
   rotateSlug,
+  serializeCanonical,
   validateProductStageStrict,
   validateUPGDocument,
   validateUPGFramework,