@unified-product-graph/cloud-server 0.7.5 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to `@unified-product-graph/cloud-server` are documented in t
 
 This package co-versions with `@unified-product-graph/core` and `@unified-product-graph/mcp-server`. One version line covers the spec and both reference implementations.
 
+## 0.7.6 · 2026-05-30 · Tool UX train (mcp-server lead)
+
+This line is led by `@unified-product-graph/mcp-server` (the `start` tool, `create_node` orphan warning, authored return shapes, and the dissolved singleton tool groups). The cloud server itself is unchanged at runtime; it co-versions and picks up the shared `mcp-tooling` generator changes:
+
+- **Authored return shapes (UPG-556):** the generated tool reference now ships build-time `return_shape` / `return_notes` derived from each handler's authored `@returns`.
+- **Parity audit hardening (UPG-499 / UPG-503):** the cloud ↔ local parity audit now fails with an actionable "build the manifest first" message instead of a raw `ENOENT` when run without a prior build.
+
 ## 0.6.0 · 2026-05-22 · Launch train alignment
 
 Aligned with `@unified-product-graph/core@0.6.0`. Bumped `@unified-product-graph/core` dep to `^0.6.0`. No cloud-server surface changes; co-versioned for the launch train.

package/dist/tools-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "2",
   "package": "@unified-product-graph/cloud-server",
-  "package_version": "0.7.5",
+  "package_version": "0.8.0",
   "tool_count": 91,
   "domains": [
     "products",
@@ -59,6 +59,7 @@
       "source": "src/tools/products.ts:39",
       "symbol": "createProduct",
       "returns": "JSON: `{ product: { id, title, description?, stage? } }`.",
+      "return_shape": "{ product: { id, title, description?, stage? } }",
       "atomicity": "atomic"
     },
     {
@@ -96,6 +97,7 @@
       "source": "src/tools/products.ts:62",
       "symbol": "getAuditLog",
       "returns": "JSON: `{ entries: Array<{ ...mutation }> }`.",
+      "return_shape": "{ entries: Array<{...mutation }> }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -120,6 +122,7 @@
       "source": "src/tools/products.ts:22",
       "symbol": "listProducts",
       "returns": "JSON: `{ products: Array<{ id, title, description?, stage? }> }`.",
+      "return_shape": "{ products: Array<{ id, title, description?, stage? }> }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -161,6 +164,7 @@
       "source": "src/tools/context.ts:329",
       "symbol": "getChanges",
       "returns": "JSON: `{ changes: AuditEntry[], total }`.",
+      "return_shape": "{ changes: AuditEntry[], total }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -195,6 +199,10 @@
       "source": "src/tools/context.ts:100",
       "symbol": "getGraphDigest",
       "returns": "JSON with `product`, `counts`, `health`, `chains`, `coverage`,\n`lifecycle` keys (~500 tokens of summary). Note: chain keys still use the\nv0.1 names (`persona_with_jtbd` etc.) pending a canonical rename.",
+      "return_notes": [
+        "JSON with `product`, `counts`, `health`, `chains`, `coverage`, `lifecycle` keys (~500 tokens of summary).",
+        "Note: chain keys still use the v0.1 names (`persona_with_jtbd` etc.) pending a canonical rename."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -227,6 +235,10 @@
       "source": "src/tools/context.ts:45",
       "symbol": "getProductContext",
       "returns": "Text: `## <product title>` followed by description/stage,\ngraph stats (node/edge/type counts), and a sorted breakdown of entities\nper type. Errors with `Product not found: <id>` for unknown products.",
+      "return_notes": [
+        "Text: `## <product title>` followed by description/stage, graph stats (node/edge/type counts), and a sorted breakdown of entities per type.",
+        "Errors with `Product not found: <id>` for unknown products."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -300,6 +312,10 @@
       "source": "src/tools/context.ts:203",
       "symbol": "query",
       "returns": "JSON: `{ nodes, edges, total_nodes, total_edges,\ntruncated?, truncated_at_depth?, hint? }`. Truncates with a hint when\n`limit` is reached.",
+      "return_shape": "{ nodes, edges, total_nodes, total_edges, truncated?, truncated_at_depth?, hint? }",
+      "return_notes": [
+        "Truncates with a hint when `limit` is reached."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -368,6 +384,10 @@
       "source": "src/tools/nodes.ts:325",
       "symbol": "createNode",
       "returns": "JSON: `{ node, edge?, warning? }`. `edge` is null when no\n`parent_id` is passed; `warning` is present on lifecycle/parent issues.",
+      "return_shape": "{ node, edge?, warning? }",
+      "return_notes": [
+        "`edge` is null when no `parent_id` is passed; `warning` is present on lifecycle/parent issues."
+      ],
       "atomicity": "atomic-with-rollback"
     },
     {
@@ -419,6 +439,10 @@
       "source": "src/tools/nodes.ts:602",
       "symbol": "deduplicateNodes",
       "returns": "With `dry_run: true` (default): `{ canonical_id, duplicate_ids,\nedges_to_rebind, nodes_to_delete, dry_run }`. With `dry_run: false`:\n`{ canonical_id, merged_ids, rebound_edges, removed_self_loops,\nremoved_duplicate_edges, dry_run }`.",
+      "return_notes": [
+        "With `dry_run: true` (default): `{ canonical_id, duplicate_ids, edges_to_rebind, nodes_to_delete, dry_run }`.",
+        "With `dry_run: false`: `{ canonical_id, merged_ids, rebound_edges, removed_self_loops, removed_duplicate_edges, dry_run }`."
+      ],
       "atomicity": "atomic-with-rollback (all mutations committed or rolled back\ntogether)."
     },
     {
@@ -452,6 +476,10 @@
       "source": "src/tools/nodes.ts:506",
       "symbol": "deleteNode",
       "returns": "JSON: `{ deleted_node_id, deleted_node_title, deleted_edge_ids }`.\nErrors propagate from the store (e.g. unknown id).",
+      "return_shape": "{ deleted_node_id, deleted_node_title, deleted_edge_ids }",
+      "return_notes": [
+        "Errors propagate from the store (e.g. unknown id)."
+      ],
       "atomicity": "atomic-with-rollback"
     },
     {
@@ -493,6 +521,10 @@
       "source": "src/tools/nodes.ts:132",
       "symbol": "exportUpgDocument",
       "returns": "JSON: `{ product, nodes, edges, total_nodes, limit, next_cursor? }`.\n`next_cursor` is present when more node pages remain.",
+      "return_shape": "{ product, nodes, edges, total_nodes, limit, next_cursor? }",
+      "return_notes": [
+        "`next_cursor` is present when more node pages remain."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -525,6 +557,10 @@
       "source": "src/tools/nodes.ts:177",
       "symbol": "getNode",
       "returns": "JSON: `{ node, edges_out, edges_in }`. Errors with\n`Node not found: <id>` for unknown ids.",
+      "return_shape": "{ node, edges_out, edges_in }",
+      "return_notes": [
+        "Errors with `Node not found: <id>` for unknown ids."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -570,6 +606,10 @@
       "source": "src/tools/nodes.ts:220",
       "symbol": "getNodes",
       "returns": "JSON: `{ nodes, total, not_found? }`. `not_found` lists any\nrequested ids that did not resolve and appears only when at least one\nmiss occurred.",
+      "return_shape": "{ nodes, total, not_found? }",
+      "return_notes": [
+        "`not_found` lists any requested ids that did not resolve and appears only when at least one miss occurred."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -604,6 +644,7 @@
       "source": "src/tools/nodes.ts:667",
       "symbol": "getProductGraph",
       "returns": "JSON: `{ product, nodes, edges }`.",
+      "return_shape": "{ product, nodes, edges }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -654,6 +695,11 @@
       "source": "src/tools/nodes.ts:75",
       "symbol": "listNodes",
       "returns": "JSON: `{ nodes, total, limit, next_cursor? }`. `next_cursor` is\npresent when more results remain. `total` reflects the filtered count\nbefore pagination.",
+      "return_shape": "{ nodes, total, limit, next_cursor? }",
+      "return_notes": [
+        "`next_cursor` is present when more results remain.",
+        "`total` reflects the filtered count before pagination."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -695,6 +741,10 @@
       "source": "src/tools/nodes.ts:536",
       "symbol": "moveNode",
       "returns": "JSON: `{ node_id, old_parent_id, new_parent_id, edge_created }`.\n`old_parent_id` is `null` when the node had no prior containment edge.",
+      "return_shape": "{ node_id, old_parent_id, new_parent_id, edge_created }",
+      "return_notes": [
+        "`old_parent_id` is `null` when the node had no prior containment edge."
+      ],
       "atomicity": "atomic-with-rollback"
     },
     {
@@ -741,6 +791,7 @@
       "source": "src/tools/nodes.ts:272",
       "symbol": "searchNodes",
       "returns": "JSON: `{ results: Array<node & { match_field }>, total }`.",
+      "return_shape": "{ results: Array<node & { match_field }>, total }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -793,6 +844,10 @@
       "source": "src/tools/nodes.ts:434",
       "symbol": "updateNode",
       "returns": "JSON: `{ node: updatedNode, warning? }`. Errors propagate from\nthe store (e.g. unknown node id).",
+      "return_shape": "{ node: updatedNode, warning? }",
+      "return_notes": [
+        "Errors propagate from the store (e.g. unknown node id)."
+      ],
       "atomicity": "atomic-with-rollback"
     },
     {
@@ -834,6 +889,7 @@
       "source": "src/tools/edges.ts:57",
       "symbol": "createEdge",
       "returns": "JSON: `{ edge: { id, source, target, type }, warning? }`.",
+      "return_shape": "{ edge: { id, source, target, type }, warning? }",
       "atomicity": "atomic-with-rollback"
     },
     {
@@ -864,6 +920,7 @@
       "source": "src/tools/edges.ts:129",
       "symbol": "deleteEdge",
       "returns": "JSON: `{ deleted_edge_id }`.",
+      "return_shape": "{ deleted_edge_id }",
       "atomicity": "atomic-with-rollback"
     },
     {
@@ -902,6 +959,7 @@
       "source": "src/tools/edges.ts:151",
       "symbol": "exportEdges",
       "returns": "JSON: `{ edges: [{ id, source, target, type }], total: number }`.",
+      "return_shape": "{ edges: [{ id, source, target, type }], total: number }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -948,6 +1006,7 @@
       "source": "src/tools/edges.ts:176",
       "symbol": "renameEdgeType",
       "returns": "JSON: `{ from, to, affected: number, dry_run: boolean }`.",
+      "return_shape": "{ from, to, affected: number, dry_run: boolean }",
       "atomicity": "atomic-with-rollback (write path)"
     },
     {
@@ -987,6 +1046,7 @@
       "source": "src/tools/areas.ts:63",
       "symbol": "createArea",
       "returns": "JSON: `{ node }`.",
+      "return_shape": "{ node }",
       "atomicity": "atomic"
     },
     {
@@ -1022,6 +1082,7 @@
       "source": "src/tools/areas.ts:93",
       "symbol": "getAreaContext",
       "returns": "JSON: `{ area: { id, title, description }, entity_counts, total_entities, child_areas }`.",
+      "return_shape": "{ area: { id, title, description }, entity_counts, total_entities, child_areas }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1062,6 +1123,7 @@
       "source": "src/tools/areas.ts:38",
       "symbol": "getAreaGraph",
       "returns": "JSON: `{ area, nodes, edges }`.",
+      "return_shape": "{ area, nodes, edges }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1093,6 +1155,7 @@
       "source": "src/tools/areas.ts:20",
       "symbol": "listProductAreas",
       "returns": "JSON: `{ areas, total }`.",
+      "return_shape": "{ areas, total }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1128,6 +1191,7 @@
       "source": "src/tools/schema.ts:32",
       "symbol": "getEntitySchema",
       "returns": "JSON: `{ type, alias_of?, domain, expected_properties,\nedges_out, edges_in, phases?, initial_phase?, terminal_phases?,\ndomain_guide? }`.",
+      "return_shape": "{ type, alias_of?, domain, expected_properties, edges_out, edges_in, phases?, initial_phase?, terminal_phases?, domain_guide? }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1176,6 +1240,7 @@
       "source": "src/tools/collaboration.ts:20",
       "symbol": "addComment",
       "returns": "JSON: `{ comment: { id, product_id, node_id, user_id, body, created_at } }`.",
+      "return_shape": "{ comment: { id, product_id, node_id, user_id, body, created_at } }",
       "atomicity": "atomic"
     },
     {
@@ -1223,6 +1288,7 @@
       "source": "src/tools/collaboration.ts:63",
       "symbol": "grantAccess",
       "returns": "JSON: `{ granted: { product_id, user_id, role } }`.",
+      "return_shape": "{ granted: { product_id, user_id, role } }",
       "atomicity": "atomic"
     },
     {
@@ -1253,6 +1319,7 @@
       "source": "src/tools/collaboration.ts:92",
       "symbol": "listCollaborators",
       "returns": "JSON: `{ collaborators: Array<{ user_id, role, granted_at }> }`.",
+      "return_shape": "{ collaborators: Array<{ user_id, role, granted_at }> }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1285,6 +1352,7 @@
       "source": "src/tools/collaboration.ts:44",
       "symbol": "listComments",
       "returns": "JSON: `{ comments: Comment[] }`.",
+      "return_shape": "{ comments: Comment[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1316,6 +1384,7 @@
       "source": "src/tools/analytics.ts:21",
       "symbol": "getGraphAnalytics",
       "returns": "JSON: `{ product: { id, title }, analytics }`.",
+      "return_shape": "{ product: { id, title }, analytics }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1346,6 +1415,7 @@
       "source": "src/tools/webhooks.ts:46",
       "symbol": "listWebhooks",
       "returns": "JSON: `{ webhooks: Webhook[] }`.",
+      "return_shape": "{ webhooks: Webhook[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1390,6 +1460,7 @@
       "source": "src/tools/webhooks.ts:24",
       "symbol": "registerWebhook",
       "returns": "JSON: `{ webhook: { id, product_id, event, url, secret?, created_at } }`.",
+      "return_shape": "{ webhook: { id, product_id, event, url, secret?, created_at } }",
       "atomicity": "atomic"
     },
     {
@@ -1420,6 +1491,7 @@
       "source": "src/tools/webhooks.ts:63",
       "symbol": "removeWebhook",
       "returns": "JSON: `{ removed: <webhook_id> }`.",
+      "return_shape": "{ removed: <webhook_id> }",
       "atomicity": "atomic"
     },
     {
@@ -1451,6 +1523,9 @@
       "source": "src/tools/spec.ts:1150",
       "symbol": "getAntiPattern",
       "returns": "JSON: `UPGCuratedAntiPattern`",
+      "return_notes": [
+        "JSON: `UPGCuratedAntiPattern`"
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1492,6 +1567,9 @@
       "source": "src/tools/spec.ts:234",
       "symbol": "getApproach",
       "returns": "JSON: the full `UPGApproach` record.",
+      "return_notes": [
+        "JSON: the full `UPGApproach` record."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1523,6 +1601,9 @@
       "source": "src/tools/spec.ts:525",
       "symbol": "getDomainGuide",
       "returns": "JSON: the full `UPGDomainUsageGuide` record.",
+      "return_notes": [
+        "JSON: the full `UPGDomainUsageGuide` record."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1554,6 +1635,9 @@
       "source": "src/tools/spec.ts:1589",
       "symbol": "getDomainRing",
       "returns": "JSON: the full `UPGDomainRing` record.",
+      "return_notes": [
+        "JSON: the full `UPGDomainRing` record."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1585,6 +1669,7 @@
       "source": "src/tools/spec.ts:651",
       "symbol": "getEdgeType",
       "returns": "JSON: `{ type, forward_verb, reverse_verb, classification, source_type, target_type }`",
+      "return_shape": "{ type, forward_verb, reverse_verb, classification, source_type, target_type }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1616,6 +1701,9 @@
       "source": "src/tools/spec.ts:1069",
       "symbol": "getEntityMeta",
       "returns": "JSON: `EntityTypeMeta & { domain_id: string | null }`",
+      "return_notes": [
+        "JSON: `EntityTypeMeta & { domain_id: string | null }`"
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1648,6 +1736,9 @@
       "source": "src/tools/spec.ts:590",
       "symbol": "getFramework",
       "returns": "JSON: the full `UPGFramework` record.",
+      "return_notes": [
+        "JSON: the full `UPGFramework` record."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1680,6 +1771,7 @@
       "source": "src/tools/spec.ts:889",
       "symbol": "getLensTool",
       "returns": "JSON: `{ ...UPGLens, visible_types: string[] }`",
+      "return_shape": "{...UPGLens, visible_types: string[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1711,6 +1803,9 @@
       "source": "src/tools/spec.ts:1458",
       "symbol": "getLifecycle",
       "returns": "JSON: the full `UPGLifecycle` record, or a descriptive message.",
+      "return_notes": [
+        "JSON: the full `UPGLifecycle` record, or a descriptive message."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1743,6 +1838,9 @@
       "source": "src/tools/spec.ts:170",
       "symbol": "getPlaybook",
       "returns": "JSON: the full `UPGPlaybook` record.",
+      "return_notes": [
+        "JSON: the full `UPGPlaybook` record."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1775,6 +1873,9 @@
       "source": "src/tools/spec.ts:710",
       "symbol": "getRegion",
       "returns": "JSON: the full `UPGRegion` record.",
+      "return_notes": [
+        "JSON: the full `UPGRegion` record."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1807,6 +1908,9 @@
       "source": "src/tools/spec.ts:732",
       "symbol": "getRegionForEntity",
       "returns": "JSON: the full `UPGRegion` record.",
+      "return_notes": [
+        "JSON: the full `UPGRegion` record."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1837,6 +1941,9 @@
       "source": "src/tools/spec.ts:1505",
       "symbol": "getScale",
       "returns": "JSON: the full `UPGScaleDefinition` record including all points.",
+      "return_notes": [
+        "JSON: the full `UPGScaleDefinition` record including all points."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1858,6 +1965,7 @@
       "source": "src/tools/spec.ts:759",
       "symbol": "getSpecVersion",
       "returns": "JSON: `{ upg_version, markdown_format_version, entity_count, edge_count, domain_count, region_count }`",
+      "return_shape": "{ upg_version, markdown_format_version, entity_count, edge_count, domain_count, region_count }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1897,6 +2005,7 @@
       "source": "src/tools/spec.ts:950",
       "symbol": "getTypeLabel",
       "returns": "JSON: `{ ...UPGTypeLabel, resolved_label: string }`",
+      "return_shape": "{...UPGTypeLabel, resolved_label: string }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1929,6 +2038,7 @@
       "source": "src/tools/spec.ts:976",
       "symbol": "getValidChildrenTool",
       "returns": "JSON: `{ parent_type, valid_children: string[] }`",
+      "return_shape": "{ parent_type, valid_children: string[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1967,6 +2077,9 @@
       "source": "src/tools/spec.ts:326",
       "symbol": "inspect",
       "returns": "JSON envelope: `{ approach_id: 'inspect', scope, generated_at, approach, params }`",
+      "return_notes": [
+        "JSON envelope: `{ approach_id: 'inspect', scope, generated_at, approach, params }`"
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2022,6 +2135,7 @@
       "source": "src/tools/spec.ts:1110",
       "symbol": "listAntiPatterns",
       "returns": "JSON: `{ total, count, next_cursor?, anti_patterns: UPGCuratedAntiPattern[] }`",
+      "return_shape": "{ total, count, next_cursor?, anti_patterns: UPGCuratedAntiPattern[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2052,6 +2166,7 @@
       "source": "src/tools/spec.ts:206",
       "symbol": "listApproaches",
       "returns": "JSON: `{ count, approaches: UPGApproach[] }`",
+      "return_shape": "{ count, approaches: UPGApproach[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2109,6 +2224,7 @@
       "source": "src/tools/spec.ts:1184",
       "symbol": "listBenchmarks",
       "returns": "JSON: `{ kind, total, count, benchmarks: ... }`",
+      "return_shape": "{ kind, total, count, benchmarks:... }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2130,6 +2246,7 @@
       "source": "src/tools/spec.ts:830",
       "symbol": "listCrossEdgeTypes",
       "returns": "JSON: `{ count, types: readonly UPGCrossEdgeType[] }`",
+      "return_shape": "{ count, types: readonly UPGCrossEdgeType[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2151,6 +2268,7 @@
       "source": "src/tools/spec.ts:1568",
       "symbol": "listDomainRings",
       "returns": "JSON: `{ rings: UPGDomainRing[], total: number }`",
+      "return_shape": "{ rings: UPGDomainRing[], total: number }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2177,6 +2295,7 @@
       "source": "src/tools/spec.ts:491",
       "symbol": "listDomains",
       "returns": "JSON: `{ count, domains: Array<{ domain_id, anchor_entity, creation_sequence } | { domain_id, label, description, types, has_guide }> }`",
+      "return_shape": "{ count, domains: Array<{ domain_id, anchor_entity, creation_sequence } | { domain_id, label, description, types, has_guide }> }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2205,6 +2324,7 @@
       "source": "src/tools/spec.ts:1350",
       "symbol": "listEdgeMigrations",
       "returns": "JSON: `{ migrations: [{ kind, from, to?, since }], total: number }`",
+      "return_shape": "{ migrations: [{ kind, from, to?, since }], total: number }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2236,6 +2356,7 @@
       "source": "src/tools/spec.ts:633",
       "symbol": "listEdgeTypes",
       "returns": "JSON: `{ count, edges: Array<{ type, forward_verb, reverse_verb, classification, source_type, target_type }> }`",
+      "return_shape": "{ count, edges: Array<{ type, forward_verb, reverse_verb, classification, source_type, target_type }> }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2286,6 +2407,7 @@
       "source": "src/tools/spec.ts:1019",
       "symbol": "listEntityTypes",
       "returns": "JSON: `{ total, count, next_cursor?, types: Array<EntityTypeMeta & { domain_id: string | null }> }`",
+      "return_shape": "{ total, count, next_cursor?, types: Array<EntityTypeMeta & { domain_id: string | null }> }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2306,6 +2428,7 @@
       "source": "src/tools/spec.ts:1524",
       "symbol": "listFrameworkCategories",
       "returns": "JSON: `{ categories: string[], total: number }`",
+      "return_shape": "{ categories: string[], total: number }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2327,6 +2450,7 @@
       "source": "src/tools/spec.ts:1545",
       "symbol": "listFrameworkStructurePatterns",
       "returns": "JSON: `{ patterns: string[], total: number }`",
+      "return_shape": "{ patterns: string[], total: number }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2361,6 +2485,7 @@
       "source": "src/tools/spec.ts:554",
       "symbol": "listFrameworks",
       "returns": "JSON: `{ total, count, next_cursor?, frameworks: UPGFramework[] }`",
+      "return_shape": "{ total, count, next_cursor?, frameworks: UPGFramework[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2383,6 +2508,7 @@
       "source": "src/tools/spec.ts:856",
       "symbol": "listLenses",
       "returns": "JSON: `{ count, lenses: Array<{ id, name, description, icon, audience, perspective, framework_id?, playbook_id?, visible_domain_count, intelligence_prompt_count }> }`",
+      "return_shape": "{ count, lenses: Array<{ id, name, description, icon, audience, perspective, framework_id?, playbook_id?, visible_domain_count, intelligence_prompt_count }> }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2413,6 +2539,7 @@
       "source": "src/tools/spec.ts:1415",
       "symbol": "listLifecycles",
       "returns": "JSON: `{ lifecycles, total, free_types: string[], planned_types: string[] }`",
+      "return_shape": "{ lifecycles, total, free_types: string[], planned_types: string[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2448,6 +2575,7 @@
       "source": "src/tools/spec.ts:140",
       "symbol": "listPlaybooks",
       "returns": "JSON: `{ count, playbooks: UPGPlaybook[] }`",
+      "return_shape": "{ count, playbooks: UPGPlaybook[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2469,6 +2597,7 @@
       "source": "src/tools/spec.ts:1287",
       "symbol": "listProductStages",
       "returns": "JSON: `{ count, stages: readonly UPGProductStage[] }`",
+      "return_shape": "{ count, stages: readonly UPGProductStage[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2491,6 +2620,7 @@
       "source": "src/tools/spec.ts:678",
       "symbol": "listRegions",
       "returns": "JSON: `{ count, regions: Array<{ id, label, order, shape, mental_model, anchor_type, composes_atomic_domains, entity_count, intra_edge_count, boundary_edge_count }> }`",
+      "return_shape": "{ count, regions: Array<{ id, label, order, shape, mental_model, anchor_type, composes_atomic_domains, entity_count, intra_edge_count, boundary_edge_count }> }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2511,6 +2641,7 @@
       "source": "src/tools/spec.ts:1490",
       "symbol": "listScales",
       "returns": "JSON: `{ scales: UPGScaleDefinition[], total: number }`",
+      "return_shape": "{ scales: UPGScaleDefinition[], total: number }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2533,6 +2664,7 @@
       "source": "src/tools/spec.ts:1387",
       "symbol": "listSplitMigrations",
       "returns": "JSON: `{ splits: [...], total: number }`",
+      "return_shape": "{ splits: [...], total: number }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2563,6 +2695,7 @@
       "source": "src/tools/spec.ts:919",
       "symbol": "listTypeLabels",
       "returns": "JSON: `{ total, count, next_cursor?, labels: UPGTypeLabel[] }`",
+      "return_shape": "{ total, count, next_cursor?, labels: UPGTypeLabel[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2591,6 +2724,7 @@
       "source": "src/tools/spec.ts:1319",
       "symbol": "listTypeMigrations",
       "returns": "JSON: `{ migrations: [{ from, to, since }], total: number }`",
+      "return_shape": "{ migrations: [{ from, to, since }], total: number }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2621,6 +2755,9 @@
       "source": "src/tools/spec.ts:298",
       "symbol": "plan",
       "returns": "JSON envelope: `{ approach_id: 'plan', scope, generated_at, approach, params }`",
+      "return_notes": [
+        "JSON envelope: `{ approach_id: 'plan', scope, generated_at, approach, params }`"
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2664,6 +2801,9 @@
       "source": "src/tools/spec.ts:359",
       "symbol": "prioritise",
       "returns": "JSON envelope: `{ approach_id: 'prioritise', scope, generated_at, approach, params }`",
+      "return_notes": [
+        "JSON envelope: `{ approach_id: 'prioritise', scope, generated_at, approach, params }`"
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2708,6 +2848,9 @@
       "source": "src/tools/spec.ts:450",
       "symbol": "reflect",
       "returns": "JSON envelope: `{ approach_id: 'reflect', scope, generated_at, approach, params }`",
+      "return_notes": [
+        "JSON envelope: `{ approach_id: 'reflect', scope, generated_at, approach, params }`"
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2747,6 +2890,7 @@
       "source": "src/tools/spec.ts:800",
       "symbol": "resolveEdgeForPair",
       "returns": "JSON: `{ source_type, target_type, edge_type: string | null }`",
+      "return_shape": "{ source_type, target_type, edge_type: string | null }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2801,6 +2945,9 @@
       "source": "src/tools/spec.ts:403",
       "symbol": "trace",
       "returns": "JSON envelope: `{ approach_id: 'trace', scope, generated_at, approach, params }`",
+      "return_notes": [
+        "JSON envelope: `{ approach_id: 'trace', scope, generated_at, approach, params }`"
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2858,6 +3005,7 @@
       "source": "src/tools/portfolio.ts:84",
       "symbol": "createCrossProductEdge",
       "returns": "JSON: `{ edge: { id, source, target, type, created_by_product_id } }`",
+      "return_shape": "{ edge: { id, source, target, type, created_by_product_id } }",
       "atomicity": "atomic"
     },
     {
@@ -2891,6 +3039,7 @@
       "source": "src/tools/portfolio.ts:55",
       "symbol": "listPortfolioCrossEdges",
       "returns": "JSON: `{ edges: [{ id, source, target, type }], total: number }`",
+      "return_shape": "{ edges: [{ id, source, target, type }], total: number }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2913,6 +3062,7 @@
       "source": "src/tools/portfolio.ts:29",
       "symbol": "listPortfolios",
       "returns": "JSON: `{ portfolios: [{ id, title, products: [{ id, title, stage? }] }], total: number }`",
+      "return_shape": "{ portfolios: [{ id, title, products: [{ id, title, stage? }] }], total: number }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2957,6 +3107,7 @@
       "source": "src/tools/portfolio.ts:137",
       "symbol": "repairDanglingEdges",
       "returns": "JSON: `{ dangling: [{ id, source, target, type }], dangling_count, dry_run, dropped }`",
+      "return_shape": "{ dangling: [{ id, source, target, type }], dangling_count, dry_run, dropped }",
       "atomicity": "atomic-with-rollback (when drop is requested)"
     },
     {
@@ -3016,6 +3167,7 @@
       "source": "src/tools/batch.ts:405",
       "symbol": "batchCreateEdges",
       "returns": "JSON: `{ created: [{ id, source_id, target_id, type }], count }`.",
+      "return_shape": "{ created: [{ id, source_id, target_id, type }], count }",
       "atomicity": "atomic-with-rollback (BEGIN / COMMIT / ROLLBACK)."
     },
     {
@@ -3094,6 +3246,7 @@
       "source": "src/tools/batch.ts:63",
       "symbol": "batchCreateNodes",
       "returns": "JSON: `{ created: [{ id, type, title }], count, warnings? }`.",
+      "return_shape": "{ created: [{ id, type, title }], count, warnings? }",
       "atomicity": "atomic-with-rollback (BEGIN / COMMIT / ROLLBACK)."
     },
     {
@@ -3133,6 +3286,7 @@
       "source": "src/tools/batch.ts:502",
       "symbol": "batchDeleteEdges",
       "returns": "JSON: `{ deleted: [id], count }`.",
+      "return_shape": "{ deleted: [id], count }",
       "atomicity": "atomic-with-rollback (BEGIN / COMMIT / ROLLBACK)."
     },
     {
@@ -3174,6 +3328,7 @@
       "source": "src/tools/batch.ts:338",
       "symbol": "batchDeleteNodes",
       "returns": "JSON: `{ deleted: [id], count }`.",
+      "return_shape": "{ deleted: [id], count }",
       "atomicity": "atomic-with-rollback (BEGIN / COMMIT / ROLLBACK)."
     },
     {
@@ -3229,6 +3384,7 @@
       "source": "src/tools/batch.ts:573",
       "symbol": "batchMoveNodes",
       "returns": "JSON: `{ moved: [{ node_id, new_parent_id }], count }`.",
+      "return_shape": "{ moved: [{ node_id, new_parent_id }], count }",
       "atomicity": "atomic-with-rollback (BEGIN / COMMIT / ROLLBACK)."
     },
     {
@@ -3298,6 +3454,7 @@
       "source": "src/tools/batch.ts:216",
       "symbol": "batchUpdateNodes",
       "returns": "JSON: `{ updated: [id], count }`.",
+      "return_shape": "{ updated: [id], count }",
       "atomicity": "atomic-with-rollback (BEGIN / COMMIT / ROLLBACK)."
     },
     {
@@ -3339,6 +3496,7 @@
       "source": "src/tools/validation.ts:83",
       "symbol": "validateGraph",
       "returns": "JSON: `{ valid, product_id, summary, entity_type_drift,\nedge_type_drift, property_drift, notes }`.",
+      "return_shape": "{ valid, product_id, summary, entity_type_drift, edge_type_drift, property_drift, notes }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3377,6 +3535,7 @@
       "source": "src/tools/migrations.ts:194",
       "symbol": "migrateCrossEdges",
       "returns": "JSON: `{ product_id, migrated, count, dry_run }`.",
+      "return_shape": "{ product_id, migrated, count, dry_run }",
       "atomicity": "atomic-with-rollback (false only)"
     },
     {
@@ -3426,6 +3585,7 @@
       "source": "src/tools/migrations.ts:83",
       "symbol": "migrateType",
       "returns": "JSON: `{ from_type, to_type, affected_nodes, retyped_edges, dry_run }`.",
+      "return_shape": "{ from_type, to_type, affected_nodes, retyped_edges, dry_run }",
       "atomicity": "atomic-with-rollback (false only)"
     }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unified-product-graph/cloud-server",
-  "version": "0.7.5",
+  "version": "0.8.0",
   "description": "Postgres-backed MCP server for the Unified Product Graph, self-hostable, open source",
   "license": "MIT",
   "author": "The Product Creator <hello@theproductcreator.com>",