@wildo-ai/framework-knowledge 1.1.11 → 1.1.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (803) hide show
  1. package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
  2. package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
  3. package/dist/claude-marketplace/plugins/wildo/references/acceptance.md +4 -0
  4. package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +25 -3
  5. package/dist/claude-marketplace/plugins/wildo/references/creation-state.md +40 -12
  6. package/dist/claude-marketplace/plugins/wildo/references/derived-artifacts.md +3 -3
  7. package/dist/claude-marketplace/plugins/wildo/references/runs-judges-and-questions.md +12 -0
  8. package/dist/claude-marketplace/plugins/wildo/skills/answer/SKILL.md +19 -2
  9. package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +33 -9
  10. package/dist/esm/framework-knowledge.definitions.d.ts +2 -3
  11. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  12. package/dist/esm/framework-knowledge.definitions.js +170 -32
  13. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  14. package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
  15. package/dist/esm/framework-knowledge.loader.js.map +1 -1
  16. package/dist/esm/framework-knowledge.research-provenance.d.ts +6 -4
  17. package/dist/esm/framework-knowledge.research-provenance.d.ts.map +1 -1
  18. package/dist/esm/framework-knowledge.research-provenance.js.map +1 -1
  19. package/dist/esm/framework-knowledge.schemas.d.ts.map +1 -1
  20. package/dist/esm/framework-knowledge.schemas.js.map +1 -1
  21. package/dist/esm/index.d.ts.map +1 -1
  22. package/dist/esm/index.js.map +1 -1
  23. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +2 -3
  24. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -1
  25. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +4 -12
  26. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  27. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts.map +1 -1
  28. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js +12 -1
  29. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js.map +1 -1
  30. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +7 -4
  31. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -1
  32. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +76 -14
  33. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
  34. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +0 -4
  35. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
  36. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +3 -15
  37. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
  38. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -1
  39. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -1
  40. package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.d.ts.map +1 -1
  41. package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.js.map +1 -1
  42. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts.map +1 -1
  43. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js.map +1 -1
  44. package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.d.ts +1 -1
  45. package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.d.ts.map +1 -1
  46. package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.js +1 -1
  47. package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.js.map +1 -1
  48. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
  49. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +35 -14
  50. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
  51. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts +16 -8
  52. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts.map +1 -1
  53. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js +19 -8
  54. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js.map +1 -1
  55. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +29 -3
  56. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
  57. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +80 -16
  58. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
  59. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts.map +1 -1
  60. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
  61. package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.d.ts +2 -2
  62. package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.d.ts.map +1 -1
  63. package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.js +2 -2
  64. package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.js.map +1 -1
  65. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +5 -1
  66. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
  67. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +3 -2
  68. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
  69. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts.map +1 -1
  70. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js.map +1 -1
  71. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts +45 -10
  72. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts.map +1 -1
  73. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.js +61 -21
  74. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.js.map +1 -1
  75. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts +4 -3
  76. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts.map +1 -1
  77. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.js +8 -5
  78. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.js.map +1 -1
  79. package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.d.ts.map +1 -1
  80. package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.js.map +1 -1
  81. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts +2 -2
  82. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts.map +1 -1
  83. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.js +3 -5
  84. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.js.map +1 -1
  85. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts +1 -1
  86. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
  87. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js +3 -3
  88. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js.map +1 -1
  89. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -1
  90. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +8 -6
  91. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
  92. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts +5 -0
  93. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts.map +1 -1
  94. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.js +8 -1
  95. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.js.map +1 -1
  96. package/dist/esm/playbooks/refinement.governance-document-candidate/playbook.definition.d.ts.map +1 -1
  97. package/dist/esm/playbooks/refinement.governance-document-candidate/playbook.definition.js.map +1 -1
  98. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +4 -1
  99. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
  100. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +11 -3
  101. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
  102. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts.map +1 -1
  103. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js +1 -1
  104. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js.map +1 -1
  105. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts.map +1 -1
  106. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js +6 -4
  107. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js.map +1 -1
  108. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts +3 -1
  109. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts.map +1 -1
  110. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js +4 -1
  111. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js.map +1 -1
  112. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +10 -1
  113. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
  114. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +36 -13
  115. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
  116. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts +8 -2
  117. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
  118. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +7 -1
  119. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -1
  120. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts +4 -1
  121. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -1
  122. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js +34 -6
  123. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js.map +1 -1
  124. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +5 -2
  125. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -1
  126. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +4 -3
  127. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -1
  128. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  129. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js +2 -2
  130. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js.map +1 -1
  131. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +22 -10
  132. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
  133. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +39 -29
  134. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -1
  135. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -1
  136. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js.map +1 -1
  137. package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts +8 -3
  138. package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts.map +1 -1
  139. package/dist/esm/playbooks/top_down.definition/playbook.definition.js +16 -7
  140. package/dist/esm/playbooks/top_down.definition/playbook.definition.js.map +1 -1
  141. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts.map +1 -1
  142. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js.map +1 -1
  143. package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.d.ts.map +1 -1
  144. package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.js.map +1 -1
  145. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
  146. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js.map +1 -1
  147. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  148. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js +2 -2
  149. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js.map +1 -1
  150. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -1
  151. package/dist/esm/playbooks/top_down.market-research/playbook.definition.js.map +1 -1
  152. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
  153. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +1 -1
  154. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
  155. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
  156. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +13 -5
  157. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
  158. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +3 -7
  159. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
  160. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +12 -14
  161. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
  162. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts +3 -0
  163. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts.map +1 -1
  164. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js +2 -1
  165. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js.map +1 -1
  166. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +3 -1
  167. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
  168. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +2 -1
  169. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -1
  170. package/dist/esm/playbooks/top_down.service-method/playbook.definition.d.ts +4 -1
  171. package/dist/esm/playbooks/top_down.service-method/playbook.definition.d.ts.map +1 -1
  172. package/dist/esm/playbooks/top_down.service-method/playbook.definition.js +14 -1
  173. package/dist/esm/playbooks/top_down.service-method/playbook.definition.js.map +1 -1
  174. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +3 -1
  175. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
  176. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +4 -2
  177. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -1
  178. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +34 -1
  179. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
  180. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +35 -17
  181. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
  182. package/dist/esm/source-anchor-grammar.d.ts.map +1 -1
  183. package/dist/esm/source-anchor-grammar.js.map +1 -1
  184. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  185. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  186. package/dist/knowledge/manifest.json +7 -7
  187. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +6 -0
  188. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +4 -4
  189. package/dist/knowledge/playbooks/bottom_up.build/method.md +12 -2
  190. package/dist/knowledge/playbooks/bottom_up.build/playbook.json +5 -3
  191. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-protocol.json +1 -1
  192. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-treatment.json +1 -1
  193. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +439 -27
  194. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +15 -4
  195. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +203 -7
  196. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +2 -5
  197. package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +1 -0
  198. package/dist/knowledge/playbooks/bottom_up.capability-composition/playbook.json +1 -0
  199. package/dist/knowledge/playbooks/bottom_up.conception/playbook.json +1 -0
  200. package/dist/knowledge/playbooks/bottom_up.documentation-plan/method.md +2 -2
  201. package/dist/knowledge/playbooks/bottom_up.documentation-plan/playbook.json +2 -1
  202. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-protocol.json +1 -1
  203. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-treatment.json +1 -1
  204. package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +104 -2
  205. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +8 -4
  206. package/dist/knowledge/playbooks/bottom_up.experience-plan/method.md +59 -4
  207. package/dist/knowledge/playbooks/bottom_up.experience-plan/playbook.json +18 -6
  208. package/dist/knowledge/playbooks/bottom_up.foundation/method.md +121 -24
  209. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +51 -7
  210. package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +15 -8
  211. package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +2 -1
  212. package/dist/knowledge/playbooks/bottom_up.maturity-reading/method.md +10 -2
  213. package/dist/knowledge/playbooks/bottom_up.maturity-reading/playbook.json +4 -3
  214. package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +34 -0
  215. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +9 -2
  216. package/dist/knowledge/playbooks/bottom_up.website-plan/playbook.json +1 -0
  217. package/dist/knowledge/playbooks/cross_cutting.application-creation/method.md +27 -12
  218. package/dist/knowledge/playbooks/cross_cutting.application-creation/playbook.json +11 -5
  219. package/dist/knowledge/playbooks/cross_cutting.compliance/method.md +4 -4
  220. package/dist/knowledge/playbooks/cross_cutting.compliance/playbook.json +7 -2
  221. package/dist/knowledge/playbooks/cross_cutting.feature-development/playbook.json +1 -0
  222. package/dist/knowledge/playbooks/cross_cutting.refinement/method.md +6 -6
  223. package/dist/knowledge/playbooks/cross_cutting.refinement/playbook.json +3 -4
  224. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/evaluation-protocol.json +1 -1
  225. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/evaluation-treatment.json +1 -1
  226. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +56 -5
  227. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +3 -2
  228. package/dist/knowledge/playbooks/refinement.document-facts/method.md +6 -4
  229. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +5 -1
  230. package/dist/knowledge/playbooks/refinement.feature-contribution/playbook.json +8 -1
  231. package/dist/knowledge/playbooks/refinement.governance-document-candidate/playbook.json +1 -0
  232. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-protocol.json +1 -1
  233. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-treatment.json +1 -1
  234. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +15 -3
  235. package/dist/knowledge/playbooks/top_down.brand-name-research/method.md +11 -4
  236. package/dist/knowledge/playbooks/top_down.brand-name-research/playbook.json +3 -2
  237. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-protocol.json +1 -1
  238. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-treatment.json +1 -1
  239. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/method.md +16 -6
  240. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/playbook.json +3 -2
  241. package/dist/knowledge/playbooks/top_down.brand-naming/playbook.json +5 -1
  242. package/dist/knowledge/playbooks/top_down.business-model/evaluation-protocol.json +1 -1
  243. package/dist/knowledge/playbooks/top_down.business-model/evaluation-treatment.json +1 -1
  244. package/dist/knowledge/playbooks/top_down.business-model/method.md +43 -11
  245. package/dist/knowledge/playbooks/top_down.business-model/playbook.json +24 -8
  246. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +6 -2
  247. package/dist/knowledge/playbooks/top_down.compliance-analysis/method.md +1 -1
  248. package/dist/knowledge/playbooks/top_down.compliance-analysis/playbook.json +49 -14
  249. package/dist/knowledge/playbooks/top_down.compliance-conception/method.md +3 -3
  250. package/dist/knowledge/playbooks/top_down.compliance-conception/playbook.json +6 -2
  251. package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/method.md +20 -0
  252. package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/playbook.json +4 -3
  253. package/dist/knowledge/playbooks/top_down.compliance-posture/evaluation-protocol.json +1 -1
  254. package/dist/knowledge/playbooks/top_down.compliance-posture/evaluation-treatment.json +1 -1
  255. package/dist/knowledge/playbooks/top_down.compliance-posture/method.md +69 -65
  256. package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +11 -7
  257. package/dist/knowledge/playbooks/top_down.compliance-research/playbook.json +1 -0
  258. package/dist/knowledge/playbooks/top_down.definition/method.md +3 -1
  259. package/dist/knowledge/playbooks/top_down.definition/playbook.json +11 -3
  260. package/dist/knowledge/playbooks/top_down.expert-personas/playbook.json +1 -0
  261. package/dist/knowledge/playbooks/top_down.feature-drafts/playbook.json +1 -0
  262. package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +1 -0
  263. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/method.md +4 -2
  264. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +4 -3
  265. package/dist/knowledge/playbooks/top_down.market-research/playbook.json +1 -0
  266. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +3 -0
  267. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +3 -2
  268. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-protocol.json +1 -1
  269. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-treatment.json +1 -1
  270. package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +1 -0
  271. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +10 -6
  272. package/dist/knowledge/playbooks/top_down.risk-register/method.md +7 -0
  273. package/dist/knowledge/playbooks/top_down.risk-register/playbook.json +5 -1
  274. package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +6 -1
  275. package/dist/knowledge/playbooks/top_down.service-method/method.md +19 -1
  276. package/dist/knowledge/playbooks/top_down.service-method/playbook.json +16 -4
  277. package/dist/knowledge/playbooks/top_down.value-proposition/method.md +5 -2
  278. package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +9 -3
  279. package/dist/knowledge/playbooks/top_down.vision-elicitation/evaluation-protocol.json +1 -1
  280. package/dist/knowledge/playbooks/top_down.vision-elicitation/evaluation-treatment.json +1 -1
  281. package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +17 -2
  282. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +59 -15
  283. package/dist/knowledge/references/application-documentation-chapters.config.md +45 -10
  284. package/dist/knowledge/references/application-documentation-plan.config.md +2 -2
  285. package/dist/knowledge/references/application-maturity.config.md +27 -1
  286. package/dist/knowledge/references/backend.inbound-channels.attachment-adoption.md +4 -2
  287. package/dist/knowledge/references/backend.inbound-channels.handler-definition.md +52 -11
  288. package/dist/knowledge/references/backend.inbound-handlers.definition.md +38 -1
  289. package/dist/knowledge/references/brand.name-screening.config.md +30 -3
  290. package/dist/knowledge/references/build-plan.task-graph.config.md +200 -4
  291. package/dist/knowledge/references/business-model.pricing-plan.config.md +12 -9
  292. package/dist/knowledge/references/business-model.snapshot.config.md +29 -2
  293. package/dist/knowledge/references/business-model.snapshot.validation.md +11 -8
  294. package/dist/knowledge/references/companion.introspection.behaviors.market.md +3 -0
  295. package/dist/knowledge/references/companion.market.generation-service.md +46 -5
  296. package/dist/knowledge/references/companion.market.prompt-renderer.md +1 -1
  297. package/dist/knowledge/references/companion.technical-doc.service.md +195 -63
  298. package/dist/knowledge/references/domain-plan.record-partition.md +105 -0
  299. package/dist/knowledge/references/engine.client-bundle.allow-list.md +3 -1
  300. package/dist/knowledge/references/engine.saas-technical-doc.config.md +69 -15
  301. package/dist/knowledge/references/example.authorization.application-roles.office-and-field.md +10 -0
  302. package/dist/knowledge/references/example.backend.addon-wiring.module.md +6 -0
  303. package/dist/knowledge/references/example.backend.custom-operation.declared-refusal-code.md +41 -0
  304. package/dist/knowledge/references/example.backend.custom-operation.external-effect-reservation.md +107 -0
  305. package/dist/knowledge/references/example.blueprint.definition.internal-tool.md +4 -2
  306. package/dist/knowledge/references/example.flows-actors.chat-assistant.md +8 -5
  307. package/dist/knowledge/references/example.infra.environment-config.local.md +13 -66
  308. package/dist/knowledge/references/example.module.companion-exports.full.md +1 -0
  309. package/dist/knowledge/references/example.module.relationships.actor-edge-back-to-scope-owner.md +35 -35
  310. package/dist/knowledge/references/example.navigation.one-entry-per-concept.md +47 -0
  311. package/dist/knowledge/references/example.organization-identity.system-of-record-partitions.md +18 -0
  312. package/dist/knowledge/references/example.provider.backend-module-shape.md +28 -4
  313. package/dist/knowledge/references/example.resource.add-resource.module-factory-map.md +0 -4
  314. package/dist/knowledge/references/example.resource.custom-view.backend-refusal.md +75 -0
  315. package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +8 -7
  316. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +37 -2
  317. package/dist/knowledge/references/example.resource.ui-behavior.record-template.md +0 -1
  318. package/dist/knowledge/references/example.resource.ui-behavior.surface-decision.md +1 -1
  319. package/dist/knowledge/references/example.resource.ui-behavior.workflow-record-page.md +212 -0
  320. package/dist/knowledge/references/example.subject-export.portability-archive.md +42 -0
  321. package/dist/knowledge/references/example.views.app-level.workflow-home.md +238 -0
  322. package/dist/knowledge/references/example.website.demo.complete-items.md +3 -3
  323. package/dist/knowledge/references/example.website.pricing.audit-payloads.md +38 -0
  324. package/dist/knowledge/references/example.website.pricing.catalog-load.md +77 -0
  325. package/dist/knowledge/references/example.website.pricing.offers.md +43 -0
  326. package/dist/knowledge/references/example.website.pricing.plans-section.md +20 -0
  327. package/dist/knowledge/references/example.website.pricing.plans.md +88 -0
  328. package/dist/knowledge/references/example.website.section.stats.md +1 -1
  329. package/dist/knowledge/references/experience-plan.config.md +111 -1
  330. package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +2 -0
  331. package/dist/knowledge/references/external-connectors.models.file-storage-adapter.md +8 -1
  332. package/dist/knowledge/references/external-connectors.models.hook-signature-algorithms.md +104 -0
  333. package/dist/knowledge/references/external-connectors.models.oauth2-audiences.md +11 -6
  334. package/dist/knowledge/references/external-connectors.models.oauth2-incremental-consent.md +165 -0
  335. package/dist/knowledge/references/external-connectors.models.rest-operation-contract.md +1035 -19
  336. package/dist/knowledge/references/external-connectors.private.provider-compliance-state-collector.md +36 -0
  337. package/dist/knowledge/references/external-connectors.private.provider-configuration-check.md +69 -0
  338. package/dist/knowledge/references/integration-plan.config.md +7 -7
  339. package/dist/knowledge/references/placement-plan.config.md +19 -0
  340. package/dist/knowledge/references/platform.config.backing-services.md +9 -11
  341. package/dist/knowledge/references/platform.config.environment.deployment.md +133 -8
  342. package/dist/knowledge/references/platform.config.infra-provider-resolution.md +3 -3
  343. package/dist/knowledge/references/platform.config.infrastructure-host.md +0 -1
  344. package/dist/knowledge/references/platform.config.platform-key-management.md +84 -8
  345. package/dist/knowledge/references/platform.config.saas.md +20 -18
  346. package/dist/knowledge/references/presets.3d.frame-style-resolution.md +65 -0
  347. package/dist/knowledge/references/presets.layouts-2d.authoring.md +1 -1
  348. package/dist/knowledge/references/presets.models.field-form-control-variant.md +32 -0
  349. package/dist/knowledge/references/presets.models.labelling.sections.md +39 -0
  350. package/dist/knowledge/references/presets.models.surface-policy.defaults.md +3 -3
  351. package/dist/knowledge/references/presets.models.surface-variant.md +5 -4
  352. package/dist/knowledge/references/presets.themes.compose-theme.md +2 -1
  353. package/dist/knowledge/references/requirements.non-functional-requirement.config.md +4 -4
  354. package/dist/knowledge/references/requirements.snapshot.config.md +2 -3
  355. package/dist/knowledge/references/saas.approval-seals.admin-endpoints.md +29 -2
  356. package/dist/knowledge/references/saas.backend.a2a.token-budget.md +11 -4
  357. package/dist/knowledge/references/saas.backend.actor-execution-continuation.md +21 -0
  358. package/dist/knowledge/references/saas.backend.app-config.backend-authored.md +5 -1
  359. package/dist/knowledge/references/saas.backend.application-initialization.assembly.md +1 -1
  360. package/dist/knowledge/references/saas.backend.authorization.role-ceiling.md +13 -1
  361. package/dist/knowledge/references/saas.backend.custom-operation.authoritative-fields.md +4 -1
  362. package/dist/knowledge/references/saas.backend.custom-operation.core-write-precondition.md +38 -0
  363. package/dist/knowledge/references/saas.backend.custom-operation.external-effect-reservation.md +109 -0
  364. package/dist/knowledge/references/saas.backend.custom-operation.hook-transaction-posture.md +43 -0
  365. package/dist/knowledge/references/saas.backend.document-sequence.issue-in-operation.md +1 -1
  366. package/dist/knowledge/references/saas.backend.document-sequence.raise-floor.md +62 -13
  367. package/dist/knowledge/references/saas.backend.domain-module.md +30 -1
  368. package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +26 -3
  369. package/dist/knowledge/references/saas.backend.flows-actors.chat-reply-handler.md +13 -1
  370. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +363 -2
  371. package/dist/knowledge/references/saas.backend.flows-actors.invoke-agent.md +5 -3
  372. package/dist/knowledge/references/saas.backend.flows-actors.resource-read-tool.md +1 -1
  373. package/dist/knowledge/references/saas.backend.flows-actors.resource-write-tool.md +9 -4
  374. package/dist/knowledge/references/saas.backend.flows.start-flow-method.md +2 -1
  375. package/dist/knowledge/references/saas.backend.privacy.subject-export-archive.md +26 -0
  376. package/dist/knowledge/references/saas.backend.providers.connection-target-credential-resolution.md +21 -19
  377. package/dist/knowledge/references/saas.backend.system-access-service.md +159 -4
  378. package/dist/knowledge/references/saas.config.content-security-policy.md +26 -9
  379. package/dist/knowledge/references/saas.data-seeding.definition-input.md +1 -1
  380. package/dist/knowledge/references/saas.data-seeding.modes.md +4 -1
  381. package/dist/knowledge/references/saas.data-seeding.row-reference.md +2 -4
  382. package/dist/knowledge/references/saas.external-providers.backend-provider-loader.md +6 -0
  383. package/dist/knowledge/references/saas.external-providers.backend-provider-registry.runtime-filter.md +2 -0
  384. package/dist/knowledge/references/saas.frontend.chart-dashboard-view.md +43 -0
  385. package/dist/knowledge/references/saas.frontend.chart-dashboard.md +130 -0
  386. package/dist/knowledge/references/saas.frontend.chart-view.resource-chart-data.md +8 -4
  387. package/dist/knowledge/references/saas.frontend.collection-filter-presets.md +76 -9
  388. package/dist/knowledge/references/saas.frontend.command-menu.search-resource.md +3 -3
  389. package/dist/knowledge/references/saas.frontend.errors.backend-refusal.md +96 -0
  390. package/dist/knowledge/references/saas.frontend.execution-view.definition.md +40 -0
  391. package/dist/knowledge/references/saas.frontend.launcher.item-refs.md +4 -0
  392. package/dist/knowledge/references/saas.frontend.linked-conversations-embed.md +3 -5
  393. package/dist/knowledge/references/saas.frontend.record-page-parts.md +117 -0
  394. package/dist/knowledge/references/saas.frontend.related-resource-embeds.md +46 -16
  395. package/dist/knowledge/references/saas.frontend.related-resource-sections.md +6 -0
  396. package/dist/knowledge/references/saas.frontend.resource-header-title.md +1 -1
  397. package/dist/knowledge/references/saas.frontend.resource-layout-templates.md +43 -9
  398. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +259 -15
  399. package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +4 -2
  400. package/dist/knowledge/references/saas.frontend.section-stages.md +63 -0
  401. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +42 -0
  402. package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +6 -9
  403. package/dist/knowledge/references/saas.frontend.viewer-may-perform-operation.md +52 -0
  404. package/dist/knowledge/references/saas.models.agent-suspension.md +8 -8
  405. package/dist/knowledge/references/saas.models.audit-trails.actor-attribution.md +21 -0
  406. package/dist/knowledge/references/saas.models.auth.relationship-grantor-authentication.md +2 -2
  407. package/dist/knowledge/references/saas.models.config.declared-type-renames.md +246 -0
  408. package/dist/knowledge/references/saas.models.config.organization-types.md +20 -0
  409. package/dist/knowledge/references/saas.models.conversation-threads.md +39 -3
  410. package/dist/knowledge/references/saas.models.crypto-keys.floors.md +10 -0
  411. package/dist/knowledge/references/saas.models.crypto-keys.local-provider.md +2 -0
  412. package/dist/knowledge/references/saas.models.crypto-keys.purpose-descriptor.md +39 -0
  413. package/dist/knowledge/references/saas.models.crypto-keys.purposes.md +7 -0
  414. package/dist/knowledge/references/saas.models.data-mode-read-list.md +0 -78
  415. package/dist/knowledge/references/saas.models.engine-capabilities.md +11 -2
  416. package/dist/knowledge/references/saas.models.engine-capabilities.required-provider-floor.md +3 -0
  417. package/dist/knowledge/references/saas.models.external-data-pipeline.md +15 -8
  418. package/dist/knowledge/references/saas.models.flows-actors.agent-behavior-report.md +13 -9
  419. package/dist/knowledge/references/saas.models.flows-actors.agent-configuration.md +29 -0
  420. package/dist/knowledge/references/saas.models.flows-actors.agent-operation-record.md +7 -0
  421. package/dist/knowledge/references/saas.models.flows-actors.human-decision-decider.md +8 -0
  422. package/dist/knowledge/references/saas.models.flows-actors.human-input-form.md +47 -12
  423. package/dist/knowledge/references/saas.models.flows-actors.operation-approval-requirement.md +31 -0
  424. package/dist/knowledge/references/saas.models.flows-actors.review-deadlines-declaration.md +3 -3
  425. package/dist/knowledge/references/saas.models.flows.runnable-model.md +21 -2
  426. package/dist/knowledge/references/saas.models.guidance-flow.md +1 -1
  427. package/dist/knowledge/references/saas.models.http-api-binding.md +19 -8
  428. package/dist/knowledge/references/saas.models.human-decision-review-marker.md +1 -1
  429. package/dist/knowledge/references/saas.models.inbound-channels.md +71 -2
  430. package/dist/knowledge/references/saas.models.model-cost-accounting-config.md +1 -1
  431. package/dist/knowledge/references/saas.models.notifications.targets.md +3 -1
  432. package/dist/knowledge/references/saas.models.notifications.user-notification-definition.md +201 -15
  433. package/dist/knowledge/references/saas.models.organization-assigned-rows-declaration.md +2 -1
  434. package/dist/knowledge/references/saas.models.organization-own-rows-declaration.md +5 -2
  435. package/dist/knowledge/references/saas.models.organizations.identity-declaration.md +201 -0
  436. package/dist/knowledge/references/saas.models.organizations.organization-relationships.md +25 -3
  437. package/dist/knowledge/references/saas.models.organizations.relationship-invitations.md +6 -2
  438. package/dist/knowledge/references/saas.models.organizations.relationship-kinds.md +14 -0
  439. package/dist/knowledge/references/saas.models.organizations.relationship-record-separation.md +1 -0
  440. package/dist/knowledge/references/saas.models.privacy.data-residency.md +676 -0
  441. package/dist/knowledge/references/saas.models.privacy.legal-holds.md +46 -2
  442. package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +6 -0
  443. package/dist/knowledge/references/saas.models.privacy.retention-binding.md +84 -1
  444. package/dist/knowledge/references/saas.models.privacy.retention-enforcement-record.md +10 -0
  445. package/dist/knowledge/references/saas.models.privacy.retention-schedule.md +5 -3
  446. package/dist/knowledge/references/saas.models.privacy.subject-data-recipients.md +2 -0
  447. package/dist/knowledge/references/saas.models.privacy.subject-export.md +134 -0
  448. package/dist/knowledge/references/saas.models.provider-capabilities.md +5 -0
  449. package/dist/knowledge/references/saas.models.providers.capability-resolution-mode.md +12 -6
  450. package/dist/knowledge/references/saas.models.providers.compliance-choice.md +15 -0
  451. package/dist/knowledge/references/saas.models.providers.processing-region-reach.md +132 -0
  452. package/dist/knowledge/references/saas.models.providers.processing-region-selection.md +139 -0
  453. package/dist/knowledge/references/saas.models.representative-activity.md +4 -0
  454. package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +107 -42
  455. package/dist/knowledge/references/saas.models.resource-config.operation-api-call.md +35 -0
  456. package/dist/knowledge/references/saas.models.resource-config.operation-auditable-event.md +4 -2
  457. package/dist/knowledge/references/saas.models.resource-config.operation-condition-parameters.md +56 -0
  458. package/dist/knowledge/references/saas.models.resource-config.operation-idempotency-key.md +16 -6
  459. package/dist/knowledge/references/saas.models.resource-config.operation-scope-admissions.md +38 -0
  460. package/dist/knowledge/references/saas.models.resource-config.resource-configuration.md +14 -16
  461. package/dist/knowledge/references/saas.models.resource-config.resources-registry.md +2 -2
  462. package/dist/knowledge/references/saas.models.resource-config.retention-policy.md +21 -0
  463. package/dist/knowledge/references/saas.models.resource-config.system-access-policy.md +32 -15
  464. package/dist/knowledge/references/saas.models.resource-operation-display-risk.md +5 -4
  465. package/dist/knowledge/references/saas.models.roles.definition.md +12 -1
  466. package/dist/knowledge/references/saas.models.roles.organization-defaults.md +6 -0
  467. package/dist/knowledge/references/saas.models.schema-family-builder.md +17 -2
  468. package/dist/knowledge/references/saas.models.system-of-record-actions.md +65 -1
  469. package/dist/knowledge/references/saas.models.system-of-record-capabilities.md +3 -1
  470. package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +16 -0
  471. package/dist/knowledge/references/saas.models.systems-of-record.md +75 -14
  472. package/dist/knowledge/references/saas.public-runtime.contract.md +41 -23
  473. package/dist/knowledge/references/saas.rag.retrieval-refusals.md +3 -2
  474. package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +12 -4
  475. package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +21 -2
  476. package/dist/knowledge/references/saas.specifications.engine-resource-sub-domain.md +105 -0
  477. package/dist/knowledge/references/saas.specifications.governed-document-release.contract.md +6 -2
  478. package/dist/knowledge/references/saas.specifications.resource-operation-spec.md +20 -3
  479. package/dist/knowledge/references/saas.specifications.resource-spec-factory.md +100 -71
  480. package/dist/knowledge/references/saas.specifications.translation-glossary.md +80 -0
  481. package/dist/knowledge/references/saas.website.astro.label-loader.md +44 -10
  482. package/dist/knowledge/references/saas.website.astro.runtime-helper.md +3 -2
  483. package/dist/knowledge/references/saas.website.blog.collection-config.md +36 -32
  484. package/dist/knowledge/references/saas.website.blog.cover-resolver.md +1 -1
  485. package/dist/knowledge/references/saas.website.blog.frontmatter.md +2 -2
  486. package/dist/knowledge/references/saas.website.blog.post-renderer.md +2 -2
  487. package/dist/knowledge/references/saas.website.blog.react-mdx-integration.md +26 -19
  488. package/dist/knowledge/references/saas.website.blog.react-mdx-query.md +1 -1
  489. package/dist/knowledge/references/saas.website.config.pricing-catalog-loader.md +3 -1
  490. package/dist/knowledge/references/saas.website.config.site-context-loader.md +6 -3
  491. package/dist/knowledge/references/saas.website.label-keys.format.md +3 -2
  492. package/dist/knowledge/references/saas.website.label-pack.validator.md +3 -1
  493. package/dist/knowledge/references/service-method.config.md +35 -2
  494. package/dist/knowledge/references/vision.constraint.config.md +4 -2
  495. package/dist/knowledge/references/zod.decorators.chainable-runtime.md +60 -0
  496. package/dist/knowledge/references/zod.decorators.data-categories.md +46 -46
  497. package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +24 -0
  498. package/dist/knowledge/references/zod.decorators.display-edit-modes.md +11 -0
  499. package/dist/knowledge/references/zod.decorators.file-schema.md +4 -3
  500. package/dist/knowledge/references/zod.decorators.rag-source.md +20 -20
  501. package/dist/knowledge/references/zod.decorators.schema-metadata.md +2 -0
  502. package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +30 -24
  503. package/dist/knowledge/references/zod.decorators.shared-structural-params.md +63 -0
  504. package/dist/knowledge/references/zod.decorators.structural-lifecycle-params.md +63 -0
  505. package/dist/knowledge/references/zod.factories.bigdecimal.md +4 -4
  506. package/dist/knowledge/references/zod.factories.code.md +4 -4
  507. package/dist/knowledge/references/zod.factories.duration.md +4 -4
  508. package/dist/knowledge/references/zod.factories.money.md +4 -4
  509. package/dist/knowledge/references/zod.factories.phone.md +4 -4
  510. package/dist/knowledge/references/zod.factories.year-month.md +79 -0
  511. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  512. package/dist/knowledge/registries/framework-topics.json +415 -2
  513. package/dist/knowledge/registries/playbooks.json +51 -39
  514. package/dist/knowledge/registries/source-tags.json +2412 -1604
  515. package/dist/knowledge/rules/database-migration-obligation.md +6 -7
  516. package/dist/knowledge/rules/live-context-door.md +1 -1
  517. package/dist/knowledge/skills/INDEX.md +3 -1
  518. package/dist/knowledge/skills/agent-work-review/references/framework-actor-execution-continuation-api.md +24 -0
  519. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-review-marker-api.md +1 -1
  520. package/dist/knowledge/skills/agent-work-review/references/framework-human-input-form-api.md +47 -12
  521. package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +30 -19
  522. package/dist/knowledge/skills/application-consumer-documentation-authoring/references/framework-documentation-chapters-api.md +48 -13
  523. package/dist/knowledge/skills/application-consumer-documentation-authoring/references/source-and-ownership-routing.md +2 -2
  524. package/dist/knowledge/skills/application-database-migrations/SKILL.md +10 -11
  525. package/dist/knowledge/skills/application-database-migrations/references/postgresql-supported-surfaces.md +64 -0
  526. package/dist/knowledge/skills/application-database-migrations/references/postgresql-vs-mongodb-obligations.md +13 -11
  527. package/dist/knowledge/skills/application-roles-authoring/SKILL.md +28 -3
  528. package/dist/knowledge/skills/application-roles-authoring/references/framework-application-roles-api.md +18 -1
  529. package/dist/knowledge/skills/application-roles-authoring/references/office-and-field-worked-example.md +22 -1
  530. package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +46 -2
  531. package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-assigned-rows-declaration-api.md +5 -3
  532. package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-organization-identity-declaration-api.md +247 -0
  533. package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-own-rows-declaration-api.md +12 -5
  534. package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +6 -0
  535. package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +31 -2
  536. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +51 -14
  537. package/dist/knowledge/skills/backend-custom-operation/references/after-the-operation.md +4 -1
  538. package/dist/knowledge/skills/backend-custom-operation/references/declared-refusal-codes.md +95 -0
  539. package/dist/knowledge/skills/backend-custom-operation/references/framework-audit-log-event-api.md +2 -2
  540. package/dist/knowledge/skills/backend-custom-operation/references/framework-core-write-precondition-api.md +73 -0
  541. package/dist/knowledge/skills/backend-custom-operation/references/framework-error-handling-api.md +5 -0
  542. package/dist/knowledge/skills/backend-custom-operation/references/framework-external-effect-reservation-api.md +276 -0
  543. package/dist/knowledge/skills/backend-custom-operation/references/framework-hook-transaction-posture-api.md +79 -0
  544. package/dist/knowledge/skills/blueprint-authoring/SKILL.md +4 -2
  545. package/dist/knowledge/skills/brand-name-screening/SKILL.md +13 -2
  546. package/dist/knowledge/skills/brand-name-screening/references/framework-brand-name-screening-api.md +30 -3
  547. package/dist/knowledge/skills/chat-agent-conversations/SKILL.md +3 -0
  548. package/dist/knowledge/skills/chat-agent-conversations/references/framework-chat-conversations-api.md +13 -1
  549. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +45 -4
  550. package/dist/knowledge/skills/compliance-document-authoring/references/framework-governed-document-after-drafting.md +17 -7
  551. package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +859 -0
  552. package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +6 -0
  553. package/dist/knowledge/skills/compliance-document-authoring/references/framework-subject-data-recipients.md +2 -0
  554. package/dist/knowledge/skills/config-app-shell/SKILL.md +5 -1
  555. package/dist/knowledge/skills/config-app-shell/references/framework-command-menu-omnibox-api.md +3 -3
  556. package/dist/knowledge/skills/config-app-shell/references/framework-launcher-items-api.md +4 -0
  557. package/dist/knowledge/skills/config-design-system/SKILL.md +1 -1
  558. package/dist/knowledge/skills/config-design-system/references/framework-surface-policy-api.md +8 -7
  559. package/dist/knowledge/skills/config-design-system/references/framework-theme-composition-api.md +44 -1
  560. package/dist/knowledge/skills/config-navigation/SKILL.md +2 -0
  561. package/dist/knowledge/skills/config-navigation/references/navigation-configuration-map.md +5 -0
  562. package/dist/knowledge/skills/config-navigation/references/one-entry-per-concept.md +101 -0
  563. package/dist/knowledge/skills/config-saas/SKILL.md +2 -2
  564. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +40 -3
  565. package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +20 -1
  566. package/dist/knowledge/skills/config-saas/references/framework-capability-resolution-api.md +75 -11
  567. package/dist/knowledge/skills/config-saas/references/framework-connection-target-credentials.md +21 -19
  568. package/dist/knowledge/skills/config-saas/references/framework-content-security-policy-api.md +26 -9
  569. package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +197 -9
  570. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +16 -2
  571. package/dist/knowledge/skills/config-saas/references/framework-systems-of-record-api.md +116 -16
  572. package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +20 -18
  573. package/dist/knowledge/skills/config-saas/references/saas-config-scope.md +1 -1
  574. package/dist/knowledge/skills/config-saas-backend/SKILL.md +11 -1
  575. package/dist/knowledge/skills/config-saas-backend/references/framework-backend-authored-config-api.md +5 -1
  576. package/dist/knowledge/skills/config-saas-backend/references/framework-declared-type-renames-api.md +261 -0
  577. package/dist/knowledge/skills/config-saas-backend/references/framework-organization-types-api.md +20 -0
  578. package/dist/knowledge/skills/config-saas-backend/references/renaming-organization-and-user-types.md +69 -0
  579. package/dist/knowledge/skills/configure-billing/SKILL.md +6 -0
  580. package/dist/knowledge/skills/configure-billing/references/example-backend-provider-module-shape.md +28 -4
  581. package/dist/knowledge/skills/configure-billing/references/framework-backend-provider-reachability-api.md +2 -0
  582. package/dist/knowledge/skills/configure-billing/references/framework-subscription-behavior-policy.md +4 -1
  583. package/dist/knowledge/skills/electronic-signature-deliverables/SKILL.md +131 -0
  584. package/dist/knowledge/skills/electronic-signature-deliverables/references/what-makes-a-request-signed.md +61 -0
  585. package/dist/knowledge/skills/email-add-template/SKILL.md +1 -1
  586. package/dist/knowledge/skills/email-add-template/references/framework-email-attachments-and-limits.md +11 -8
  587. package/dist/knowledge/skills/email-add-template/references/framework-email-send-api.md +3 -2
  588. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +31 -9
  589. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-a2a-token-budget-api.md +11 -4
  590. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +26 -3
  591. package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +1 -1
  592. package/dist/knowledge/skills/flows-actors-autonomous-agents/references/binding-and-review.md +27 -0
  593. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +18 -7
  594. package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +8 -5
  595. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-behavior-reports-api.md +13 -9
  596. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-content-guardrails-api.md +44 -4
  597. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-operation-record-api.md +7 -0
  598. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-suspension-api.md +11 -9
  599. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-audit-agent-attribution-api.md +21 -0
  600. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-decision-deadlines-api.md +3 -3
  601. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-realtime-catalog.md +7 -1
  602. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +375 -8
  603. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +30 -1
  604. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-model-spend-limits-api.md +36 -15
  605. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-tool-dispatch-obligations-api.md +8 -0
  606. package/dist/knowledge/skills/flows-actors-declared-flow/SKILL.md +1 -1
  607. package/dist/knowledge/skills/flows-actors-declared-flow/references/framework-flow-model-api.md +21 -2
  608. package/dist/knowledge/skills/flows-actors-declared-flow/references/framework-start-flow-api.md +2 -1
  609. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +1 -1
  610. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +33 -1
  611. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-invocation-api.md +5 -3
  612. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +3 -3
  613. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +37 -14
  614. package/dist/knowledge/skills/guidance-onboarding-authoring/references/framework-guidance-flow-api.md +1 -1
  615. package/dist/knowledge/skills/i18n-label-generation/references/framework-labelling-sections-api.md +39 -0
  616. package/dist/knowledge/skills/i18n-rerun-pipeline/references/framework-labelling-sections-api.md +39 -0
  617. package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +31 -2
  618. package/dist/knowledge/skills/i18n-translation-rerun/references/framework-labelling-sections-api.md +39 -0
  619. package/dist/knowledge/skills/i18n-translation-rerun/references/framework-translation-glossary-api.md +87 -0
  620. package/dist/knowledge/skills/inbound-channels/SKILL.md +31 -9
  621. package/dist/knowledge/skills/inbound-channels/references/email-channel.md +16 -4
  622. package/dist/knowledge/skills/inbound-channels/references/framework-inbound-channel-api.md +169 -23
  623. package/dist/knowledge/skills/inbound-channels/references/framework-inbound-handler-api.md +38 -1
  624. package/dist/knowledge/skills/inbound-channels/references/inbound-delivery-lifecycle.md +43 -4
  625. package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +15 -3
  626. package/dist/knowledge/skills/inbound-channels/references/sms-channel.md +93 -0
  627. package/dist/knowledge/skills/infra-environment-config/SKILL.md +125 -77
  628. package/dist/knowledge/skills/infra-environment-config/references/framework-backing-services-api.md +12 -14
  629. package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +133 -8
  630. package/dist/knowledge/skills/infra-environment-config/references/framework-infrastructure-host-api.md +0 -1
  631. package/dist/knowledge/skills/infra-environment-config/references/framework-platform-key-management-api.md +84 -8
  632. package/dist/knowledge/skills/layout-2d-adoption/references/framework-2d-layout-authoring-api.md +1 -1
  633. package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-focal-plane-settings-api.md +16 -0
  634. package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-frame-style-overrides-api.md +72 -0
  635. package/dist/knowledge/skills/layout-3d-adoption/references/manual-adoption-and-removal.md +2 -2
  636. package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +12 -9
  637. package/dist/knowledge/skills/local-environment-bootstrap/references/derived-artifact-currency.md +3 -3
  638. package/dist/knowledge/skills/local-environment-bootstrap/references/framework-upgrade-and-dependency-alignment.md +2 -2
  639. package/dist/knowledge/skills/local-environment-bootstrap/references/local-environment-troubleshooting.md +18 -10
  640. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +7 -7
  641. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +24 -2
  642. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +33 -2
  643. package/dist/knowledge/skills/market-generation-cli/SKILL.md +47 -6
  644. package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +61 -8
  645. package/dist/knowledge/skills/model-cost-attribution/SKILL.md +3 -1
  646. package/dist/knowledge/skills/model-cost-attribution/references/framework-model-cost-pricing-api.md +1 -1
  647. package/dist/knowledge/skills/model-cost-attribution/references/framework-work-unit-api.md +107 -42
  648. package/dist/knowledge/skills/module-companion-exports/SKILL.md +1 -0
  649. package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +21 -2
  650. package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +30 -1
  651. package/dist/knowledge/skills/module-relationships/SKILL.md +92 -91
  652. package/dist/knowledge/skills/organization-relationships/references/framework-organization-relationships-api.md +31 -5
  653. package/dist/knowledge/skills/organization-relationships/references/framework-relationship-grantor-authentication-api.md +2 -2
  654. package/dist/knowledge/skills/organization-relationships/references/framework-relationship-kinds-api.md +34 -0
  655. package/dist/knowledge/skills/organization-relationships/references/framework-relationship-record-separation-api.md +1 -0
  656. package/dist/knowledge/skills/organization-relationships/references/framework-representative-activity-api.md +4 -0
  657. package/dist/knowledge/skills/professional-qualifications/references/framework-operation-approval-requirement-api.md +31 -0
  658. package/dist/knowledge/skills/provider-backend-package/SKILL.md +255 -12
  659. package/dist/knowledge/skills/provider-backend-package/references/framework-optional-runtime-peers.md +4 -5
  660. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-compliance-state-collector-api.md +96 -0
  661. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-configuration-check-api.md +130 -0
  662. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-file-storage-adapter-api.md +8 -1
  663. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-inbound-endpoint-api.md +124 -3
  664. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-incremental-consent-api.md +165 -0
  665. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-loader-api.md +6 -0
  666. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-processing-region-api.md +340 -0
  667. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-shared-connection-api.md +11 -6
  668. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +2 -0
  669. package/dist/knowledge/skills/provider-frontend-module/SKILL.md +5 -2
  670. package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +1 -1
  671. package/dist/knowledge/skills/provider-operation-calls/SKILL.md +17 -3
  672. package/dist/knowledge/skills/provider-operation-calls/references/framework-rest-operation-contract-api.md +1035 -19
  673. package/dist/knowledge/skills/resource-add-field/SKILL.md +7 -0
  674. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +322 -15
  675. package/dist/knowledge/skills/resource-add-resource/SKILL.md +9 -5
  676. package/dist/knowledge/skills/resource-add-resource/references/framework-engine-api-reference-categories-api.md +119 -0
  677. package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +107 -42
  678. package/dist/knowledge/skills/resource-chat-commands/SKILL.md +2 -1
  679. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +71 -5
  680. package/dist/knowledge/skills/resource-config-wiring/references/framework-collection-operation-declarations.md +2 -2
  681. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-approval-api.md +48 -0
  682. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +33 -7
  683. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-bulk-api.md +15 -11
  684. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-idempotency-key-api.md +66 -27
  685. package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +140 -58
  686. package/dist/knowledge/skills/resource-config-wiring/references/framework-retention-policy-operations.md +7 -2
  687. package/dist/knowledge/skills/resource-config-wiring/references/framework-role-ceiling-api.md +34 -10
  688. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-operation-scope-enums-api.md +5 -4
  689. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +158 -138
  690. package/dist/knowledge/skills/resource-config-wiring/references/framework-scope-admissions-api.md +52 -0
  691. package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +205 -19
  692. package/dist/knowledge/skills/resource-config-wiring/references/framework-user-notifications-api.md +253 -25
  693. package/dist/knowledge/skills/resource-custom-view/SKILL.md +126 -1
  694. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +259 -15
  695. package/dist/knowledge/skills/resource-custom-view/references/framework-backend-refusal-api.md +110 -0
  696. package/dist/knowledge/skills/resource-external-data/SKILL.md +46 -12
  697. package/dist/knowledge/skills/resource-external-data/references/bidirectional-pipelines.md +1 -1
  698. package/dist/knowledge/skills/resource-external-data/references/framework-external-data-pipeline-api.md +15 -8
  699. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +19 -8
  700. package/dist/knowledge/skills/resource-external-data/references/framework-system-of-record-capabilities-api.md +3 -1
  701. package/dist/knowledge/skills/resource-external-data/references/local-test-doubles.md +121 -0
  702. package/dist/knowledge/skills/resource-external-data/references/outbound-pipelines.md +1 -1
  703. package/dist/knowledge/skills/resource-external-data/references/partition-from-the-domain-plan.md +230 -0
  704. package/dist/knowledge/skills/resource-external-data/references/presenting-a-copy-and-a-read-through.md +73 -0
  705. package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +26 -5
  706. package/dist/knowledge/skills/resource-external-data/references/system-of-record-actions.md +76 -6
  707. package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +8 -0
  708. package/dist/knowledge/skills/resource-rag-source-fields/SKILL.md +12 -9
  709. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +11 -2
  710. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +29 -2
  711. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-source-decorator-api.md +20 -20
  712. package/dist/knowledge/skills/resource-retention-binding/SKILL.md +18 -2
  713. package/dist/knowledge/skills/resource-retention-binding/references/framework-legal-holds-api.md +46 -2
  714. package/dist/knowledge/skills/resource-retention-binding/references/framework-retention-binding-api.md +84 -1
  715. package/dist/knowledge/skills/resource-retention-binding/references/framework-retention-enforcement-records-api.md +10 -0
  716. package/dist/knowledge/skills/resource-retention-binding/references/framework-retention-schedule-api.md +5 -3
  717. package/dist/knowledge/skills/resource-retention-binding/references/framework-statutory-retention-api.md +21 -0
  718. package/dist/knowledge/skills/resource-retention-binding/references/start-point-decisions.md +14 -2
  719. package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +1 -1
  720. package/dist/knowledge/skills/resource-schema-authoring/references/computed-totals.md +4 -1
  721. package/dist/knowledge/skills/resource-schema-authoring/references/document-numbers.md +78 -17
  722. package/dist/knowledge/skills/resource-schema-authoring/references/field-type-selection.md +2 -0
  723. package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +26 -0
  724. package/dist/knowledge/skills/resource-schema-authoring/references/framework-personal-data-category-api.md +46 -46
  725. package/dist/knowledge/skills/resource-schema-authoring/references/framework-schema-family-api.md +17 -2
  726. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +36 -24
  727. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +63 -0
  728. package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +104 -23
  729. package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +123 -0
  730. package/dist/knowledge/skills/resource-schema-authoring/references/shared-layer-decorator-checklist.md +1 -0
  731. package/dist/knowledge/skills/resource-schema-authoring/references/special-factories.md +72 -0
  732. package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +42 -2
  733. package/dist/knowledge/skills/resource-status-lifecycle/references/framework-operation-condition-parameters-api.md +67 -0
  734. package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +16 -12
  735. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +66 -3
  736. package/dist/knowledge/skills/resource-ui-behavior/references/framework-collection-filter-presets-api.md +89 -10
  737. package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +11 -0
  738. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +263 -17
  739. package/dist/knowledge/skills/resource-ui-behavior/references/framework-record-page-parts-api.md +155 -0
  740. package/dist/knowledge/skills/resource-ui-behavior/references/framework-related-resource-embeds-api.md +83 -16
  741. package/dist/knowledge/skills/resource-ui-behavior/references/framework-resource-layout-templates-api.md +44 -10
  742. package/dist/knowledge/skills/resource-ui-behavior/references/framework-section-stages-api.md +102 -0
  743. package/dist/knowledge/skills/resource-ui-behavior/references/record-page-anatomy.md +9 -2
  744. package/dist/knowledge/skills/resource-ui-behavior/references/surface-decisions.md +33 -2
  745. package/dist/knowledge/skills/resource-ui-behavior/references/visual-quality-rubric.md +19 -2
  746. package/dist/knowledge/skills/resource-ui-behavior/references/workflow-record-page.md +264 -0
  747. package/dist/knowledge/skills/seeding-authoring/SKILL.md +24 -4
  748. package/dist/knowledge/skills/seeding-authoring/references/cross-seed-row-references.md +12 -0
  749. package/dist/knowledge/skills/seeding-authoring/references/framework-data-seeding-api.md +7 -6
  750. package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +6 -0
  751. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +42 -0
  752. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +6 -9
  753. package/dist/knowledge/skills/spec-companion-exports/SKILL.md +1 -0
  754. package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +21 -2
  755. package/dist/knowledge/skills/spec-resource-update/SKILL.md +26 -0
  756. package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +121 -75
  757. package/dist/knowledge/skills/spec-resource-update/references/workflow-record-page-specification.md +237 -0
  758. package/dist/knowledge/skills/spec-update-after-change/references/framework-spec-factory-api.md +100 -71
  759. package/dist/knowledge/skills/subject-data-export/SKILL.md +176 -0
  760. package/dist/knowledge/skills/subject-data-export/references/file-content-exclusions.md +15 -0
  761. package/dist/knowledge/skills/subject-data-export/references/framework-subject-export-api.md +142 -0
  762. package/dist/knowledge/skills/subject-data-export/references/framework-subject-export-archive-api.md +33 -0
  763. package/dist/knowledge/skills/views-app-level/SKILL.md +3 -1
  764. package/dist/knowledge/skills/views-app-level/references/workflow-home.md +373 -0
  765. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +36 -5
  766. package/dist/knowledge/skills/views-chart-authoring/references/framework-resource-chart-data-api.md +9 -5
  767. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +4 -0
  768. package/dist/knowledge/skills/views-composite-authoring/references/framework-chart-dashboard-api.md +244 -0
  769. package/dist/knowledge/skills/views-execution-authoring/references/framework-execution-view-contracts-api.md +40 -0
  770. package/dist/knowledge/skills/website-blog-authoring/SKILL.md +8 -6
  771. package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +70 -59
  772. package/dist/knowledge/skills/website-building-blocks/SKILL.md +1 -1
  773. package/dist/knowledge/skills/website-building-blocks/references/framework-website-demo-examples.md +3 -3
  774. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +4 -2
  775. package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +3 -1
  776. package/dist/knowledge/skills/website-label-pack/SKILL.md +20 -5
  777. package/dist/knowledge/skills/website-page-authoring/references/framework-site-context-loader-api.md +6 -3
  778. package/dist/knowledge/skills/website-section-comparison/SKILL.md +2 -2
  779. package/dist/knowledge/skills/website-section-contact/SKILL.md +1 -1
  780. package/dist/knowledge/skills/website-section-cta/SKILL.md +1 -1
  781. package/dist/knowledge/skills/website-section-faq/SKILL.md +1 -1
  782. package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +1 -1
  783. package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +1 -1
  784. package/dist/knowledge/skills/website-section-footer-cta/SKILL.md +1 -1
  785. package/dist/knowledge/skills/website-section-hero/SKILL.md +1 -1
  786. package/dist/knowledge/skills/website-section-how-it-works/SKILL.md +1 -1
  787. package/dist/knowledge/skills/website-section-integrations/SKILL.md +3 -3
  788. package/dist/knowledge/skills/website-section-latest-posts/SKILL.md +1 -1
  789. package/dist/knowledge/skills/website-section-pricing/SKILL.md +142 -98
  790. package/dist/knowledge/skills/website-section-pricing/examples/pricing-offers.example.md +178 -66
  791. package/dist/knowledge/skills/website-section-pricing/references/framework-pricing-catalog-api.md +3 -1
  792. package/dist/knowledge/skills/website-section-problem/SKILL.md +3 -3
  793. package/dist/knowledge/skills/website-section-product-showcase/SKILL.md +1 -1
  794. package/dist/knowledge/skills/website-section-roadmap/SKILL.md +4 -4
  795. package/dist/knowledge/skills/website-section-social-proof/SKILL.md +1 -1
  796. package/dist/knowledge/skills/website-section-solution-paths/SKILL.md +2 -2
  797. package/dist/knowledge/skills/website-section-stats/SKILL.md +3 -3
  798. package/dist/knowledge/skills/website-seo-aeo-geo/references/aeo-api.md +3 -2
  799. package/dist/knowledge/skills/worker-authoring/SKILL.md +4 -2
  800. package/dist/knowledge/topic-index.json +2275 -715
  801. package/dist/tsconfig.build.tsbuildinfo +1 -1
  802. package/package.json +6 -6
  803. package/dist/tsconfig.tsbuildinfo +0 -1
@@ -8,6 +8,539 @@
8
8
 
9
9
  ### Origin Package: `@wildo-ai/external-connectors-models`
10
10
 
11
+ ```typescript
12
+ /**
13
+ * The GraphQL document a provider operation sends (#3392), set as `ProviderRestOperation.graphql`.
14
+ *
15
+ * With it the operation is a GraphQL call: `method` must be `POST`, `pathTemplate` is the vendor's GraphQL endpoint
16
+ * (`/graphql`), and the operation's input IS the variables. So it may declare no `requestBody`, and no parameter fed by
17
+ * the input (a `constantValue` header or path parameter, such as a pinned API version, is allowed). `inputSchema`
18
+ * describes the variables, one top-level field per variable the document declares, and `inputOptions` work on them as on
19
+ * any input. `resultPath` and `outputSchema` read the answer's `data`, never the `{ data, errors }` envelope around it.
20
+ * `responseDecoding` stays JSON.
21
+ *
22
+ * Checked when the catalogue loads, at publish and on every call ({@link describeProviderRestOperationGraphqlDefects}).
23
+ *
24
+ * @example
25
+ * // GitHub: a repository's discussions, which GitHub serves through GraphQL only.
26
+ * {
27
+ * operationId: 'github_issues_list_discussions', domain: 'default', method: API_HttpMethod.POST, pathTemplate: '/graphql',
28
+ * classification: ExternalOperation_Classification.READ,
29
+ * graphql: {
30
+ * operationName: 'ListDiscussions',
31
+ * document: 'query ListDiscussions($owner: String!, $repo: String!, $first: Int!) { repository(owner: $owner, name: $repo) { discussions(first: $first) { nodes { number title } } } }',
32
+ * },
33
+ * inputSchema: z.strictObject({ owner: z.string(), repo: z.string(), first: z.number().int() }),
34
+ * resultPath: 'repository.discussions',
35
+ * }
36
+ */
37
+ export interface ProviderRestOperationGraphql {
38
+ /**
39
+ * The executable document, owned by the provider: exactly ONE operation (a `query` or a `mutation`, named
40
+ * {@link operationName}) and any fragments it uses. A `query` is a READ operation and a `mutation` a WRITE; a
41
+ * `subscription` is refused, since it is not answered over a single POST.
42
+ */
43
+ readonly document: string;
44
+ /** The operation's name in {@link document}, sent as `operationName`. */
45
+ readonly operationName: string;
46
+ /**
47
+ * Dot path, inside EACH error of the answer's `errors` list, to the vendor's machine-readable code (`extensions.code`
48
+ * by convention, where a vendor uses it). The specification standardizes no code, so absent, no code is read and the
49
+ * failure carries the vendor's messages only. A code is kept only when it is code-shaped, as every vendor code is.
50
+ */
51
+ readonly errorCodePath?: string;
52
+ /**
53
+ * The codes, read at {@link errorCodePath}, that mean the vendor refused the CREDENTIAL itself rather than the request
54
+ * (#3392): the stored credential is then recorded as rejected, as a REST vendor's
55
+ * `applicationOutcome.credentialRefusedErrorCodes` records it. A GraphQL vendor may name a dead or expired token inside
56
+ * a 200 (an error list beside or instead of `data`) or inside a 4xx carrying the same error list, and both are read.
57
+ * The failure itself is unchanged: the call fails with the vendor's code and is never retried.
58
+ *
59
+ * List only a code the vendor DOCUMENTS as a refused credential. A code for a resource the credential may not reach
60
+ * (`FORBIDDEN` on one repository), for a missing scope, or for a request sent with no credential at all, does not
61
+ * belong here: the credential still works, and recording it rejected would show a working connection as broken.
62
+ * Requires {@link errorCodePath}, without which no code is read and none could match.
63
+ *
64
+ * @example
65
+ * // monday.com answers a key it refuses with the error code `Unauthorized`, whose documented resolution is a valid key.
66
+ * // spec-cite: https://developer.monday.com/api-reference/docs/errors — the `Unauthorized` row (HTTP 401, resolution
67
+ * // "Input a valid API key."), fetched 2026-11-09.
68
+ * graphql: { operationName: 'CreateItem', document: CREATE_ITEM, errorCodePath: 'extensions.code', credentialRefusedErrorCodes: ['Unauthorized'] }
69
+ */
70
+ readonly credentialRefusedErrorCodes?: readonly string[];
71
+ /**
72
+ * Where a MUTATION's answer says the vendor refused it in the DATA rather than in `errors` (follow-up to #3392). Several
73
+ * GraphQL vendors answer a write they refused with a successful response whose payload carries the refusal: Shopify's
74
+ * `userErrors` list ("validation failures, such as invalid field values or business logic violations, that prevent the
75
+ * operation from completing"), Linear's `success: Boolean!`. Without it such an answer is returned as the result and a
76
+ * caller that does not read the payload takes a refused write for a done one; with it the call FAILS, carrying the
77
+ * vendor's messages, exactly as an `errors` entry does. See {@link ProviderGraphqlPayloadRefusal}.
78
+ * spec-cite: https://shopify.dev/docs/api/admin-graphql — the `UserError` description quoted above, fetched 2026-11-10.
79
+ *
80
+ * @example
81
+ * // Shopify: productCreate's userErrors, each `{ field, message }`.
82
+ * payloadRefusal: { kind: ProviderGraphqlPayloadRefusalKind.USER_ERRORS, path: 'productCreate.userErrors', messagePath: 'message', fieldPath: 'field' }
83
+ */
84
+ readonly payloadRefusal?: ProviderGraphqlPayloadRefusal;
85
+ }
86
+
87
+ /** How a mutation's payload states a refusal. See {@link ProviderRestOperationGraphql.payloadRefusal}. */
88
+ export enum ProviderGraphqlPayloadRefusalKind {
89
+ /** A list of the vendor's refusals (Shopify's `userErrors`): the write was refused when the list is not empty. */
90
+ USER_ERRORS = 'user_errors',
91
+ /** A boolean the vendor sets to `false` when it did not do the write (Linear's `success`). */
92
+ SUCCESS_FLAG = 'success_flag',
93
+ }
94
+
95
+ /**
96
+ * Where a mutation's payload states a refusal (follow-up to #3392). Every path is a dot path, `path` from the answer's
97
+ * `data` (as `resultPath` is), `messagePath`, `fieldPath` and `codePath` from inside each listed refusal.
98
+ *
99
+ * - {@link ProviderGraphqlPayloadRefusalKind.USER_ERRORS}: a non-empty list at `path` fails the call. Each entry's text at
100
+ * `messagePath` (`message` when absent) is kept, prefixed with the input field it names at `fieldPath` (a string or a
101
+ * list of path segments), and the first code-shaped value at `codePath` is the failure's code.
102
+ * - {@link ProviderGraphqlPayloadRefusalKind.SUCCESS_FLAG}: `false` at `path` fails the call.
103
+ *
104
+ * Anything else at `path` (an absent payload, `true`, an empty list) refuses nothing: the answer is read as it is.
105
+ */
106
+ export type ProviderGraphqlPayloadRefusal =
107
+ | {
108
+ readonly kind: ProviderGraphqlPayloadRefusalKind.USER_ERRORS;
109
+ readonly path: string;
110
+ readonly messagePath?: string;
111
+ readonly fieldPath?: string;
112
+ readonly codePath?: string;
113
+ }
114
+ | { readonly kind: ProviderGraphqlPayloadRefusalKind.SUCCESS_FLAG; readonly path: string };
115
+
116
+ /** What a GraphQL document's operation does. A `subscription` is not served over a single POST, so it is no member. */
117
+ export enum ProviderGraphqlOperationType {
118
+ /** Reads. The operation must be classified READ. */
119
+ QUERY = 'query',
120
+ /** Changes the vendor. The operation must be classified WRITE. */
121
+ MUTATION = 'mutation',
122
+ }
123
+
124
+ /**
125
+ * The `Accept` a GraphQL call sends: the GraphQL response media type first, `application/json` for a server that predates
126
+ * it (GraphQL over HTTP §4.2, quoted in this module's header).
127
+ * semantic-literal-boundary: the media types GraphQL over HTTP names, sent on the wire.
128
+ */
129
+ export const PROVIDER_GRAPHQL_ACCEPT_HEADER = 'application/graphql-response+json, application/json;q=0.9';
130
+
131
+ /** At most this many of the vendor's error messages are kept on a failure. */
132
+ export const PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGES = 10;
133
+ /** A kept error message is cut at this many characters. */
134
+ export const PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGE_LENGTH = 500;
135
+
136
+ /** One operation a document defines, as {@link readProviderGraphqlDocument} reads it. */
137
+ export interface ProviderGraphqlDocumentOperation {
138
+ /** `query`, `mutation` or `subscription`, as written (an anonymous `{ … }` is a query). */
139
+ readonly type: string;
140
+ /** Absent for an anonymous operation. */
141
+ readonly name?: string;
142
+ /** The variables it declares, without their `$`, in order. */
143
+ readonly variables: readonly string[];
144
+ }
145
+
146
+ /** What a document holds, or why it cannot be read. */
147
+ export interface ProviderGraphqlDocumentShape {
148
+ readonly operations: readonly ProviderGraphqlDocumentOperation[];
149
+ /** Set when the text is not a document of executable definitions. `operations` is then what was read before it. */
150
+ readonly defect?: string;
151
+ }
152
+
153
+ const GRAPHQL_NAME = /^[_A-Za-z][_0-9A-Za-z]*$/;
154
+ const GRAPHQL_PUNCTUATORS = new Set(['!', '$', '&', '(', ')', ':', '=', '@', '[', ']', '{', '|', '}']);
155
+
156
+ /**
157
+ * The tokens of a GraphQL document, with strings and comments dropped: enough to find its definitions and their
158
+ * variables. Not a validating parser: the vendor's server is the parser that decides, and this only has to see the
159
+ * document's outline. A block string (`"""…"""`) and a string (`"…"`, with `\` escapes) are skipped whole, so a brace or
160
+ * a `$` inside one is never read as structure. `undefined` for a string that never closes.
161
+ */
162
+ function tokenizeGraphqlDocument(document: string): string[] | undefined {
163
+ const tokens: string[] = [];
164
+ let index = 0;
165
+ while (index < document.length) {
166
+ const character = document[index]!;
167
+ if (character === '#') {
168
+ while (index < document.length && document[index] !== '\n' && document[index] !== '\r') index += 1;
169
+ continue;
170
+ }
171
+ if (character === '"') {
172
+ if (document.startsWith('"""', index)) {
173
+ const close = document.indexOf('"""', index + 3);
174
+ // A `\"""` inside a block string is an escaped delimiter, not its end.
175
+ let end = close;
176
+ while (end !== -1 && document[end - 1] === '\\') end = document.indexOf('"""', end + 3);
177
+ if (end === -1) return undefined;
178
+ index = end + 3;
179
+ } else {
180
+ index += 1;
181
+ while (index < document.length && document[index] !== '"') {
182
+ if (document[index] === '\n') return undefined;
183
+ index += document[index] === '\\' ? 2 : 1;
184
+ }
185
+ if (index >= document.length) return undefined;
186
+ index += 1;
187
+ }
188
+ tokens.push('"');
189
+ continue;
190
+ }
191
+ if (character === '.' && document.startsWith('...', index)) {
192
+ tokens.push('...');
193
+ index += 3;
194
+ continue;
195
+ }
196
+ if (GRAPHQL_PUNCTUATORS.has(character)) {
197
+ tokens.push(character);
198
+ index += 1;
199
+ continue;
200
+ }
201
+ if (/[_A-Za-z0-9.+-]/.test(character)) {
202
+ let end = index + 1;
203
+ while (end < document.length && /[_A-Za-z0-9.+-]/.test(document[end]!)) end += 1;
204
+ tokens.push(document.slice(index, end));
205
+ index = end;
206
+ continue;
207
+ }
208
+ // White space, commas (insignificant in GraphQL) and the byte order mark.
209
+ index += 1;
210
+ }
211
+ return tokens;
212
+ }
213
+
214
+ /**
215
+ * The executable definitions of a GraphQL document (#3392): each operation's type, name and declared variables. A
216
+ * fragment is skipped; a type-system definition (`type`, `schema`, …) is a defect, since a document sent to a server is
217
+ * executable only.
218
+ */
219
+ export function readProviderGraphqlDocument(document: string): ProviderGraphqlDocumentShape {
220
+ const tokens = tokenizeGraphqlDocument(document);
221
+ if (tokens === undefined) return { operations: [], defect: 'a string in it never closes' };
222
+ const operations: ProviderGraphqlDocumentOperation[] = [];
223
+ let index = 0;
224
+ /** Skips the balanced block opening at `index` (a `{` or a `(`), and answers the index after it, or -1. */
225
+ const skipBalanced = (open: string, close: string): number => {
226
+ let depth = 0;
227
+ for (let position = index; position < tokens.length; position += 1) {
228
+ if (tokens[position] === open) depth += 1;
229
+ else if (tokens[position] === close) {
230
+ depth -= 1;
231
+ if (depth === 0) return position + 1;
232
+ }
233
+ }
234
+ return -1;
235
+ };
236
+ while (index < tokens.length) {
237
+ const token = tokens[index]!;
238
+ if (token === '{') {
239
+ const after = skipBalanced('{', '}');
240
+ if (after === -1) return { operations, defect: 'a selection set never closes' };
241
+ operations.push({ type: 'query', variables: [] });
242
+ index = after;
243
+ continue;
244
+ }
245
+ if (token === 'query' || token === 'mutation' || token === 'subscription') {
246
+ index += 1;
247
+ const name = tokens[index] !== undefined && GRAPHQL_NAME.test(tokens[index]!) ? tokens[index] : undefined;
248
+ if (name !== undefined) index += 1;
249
+ const variables: string[] = [];
250
+ if (tokens[index] === '(') {
251
+ const after = skipBalanced('(', ')');
252
+ if (after === -1) return { operations, defect: `the variable definitions of ${name ?? 'an operation'} never close` };
253
+ // A definition is `$name :`; a default value is constant and holds no variable.
254
+ for (let position = index; position < after - 2; position += 1) {
255
+ if (tokens[position] === '$' && tokens[position + 2] === ':' && GRAPHQL_NAME.test(tokens[position + 1]!)) variables.push(tokens[position + 1]!);
256
+ }
257
+ index = after;
258
+ }
259
+ while (index < tokens.length && tokens[index] !== '{') index += 1;
260
+ if (index >= tokens.length) return { operations, defect: `${name ?? 'an operation'} has no selection set` };
261
+ const after = skipBalanced('{', '}');
262
+ if (after === -1) return { operations, defect: `the selection set of ${name ?? 'an operation'} never closes` };
263
+ operations.push({ type: token, ...(name === undefined ? {} : { name }), variables });
264
+ index = after;
265
+ continue;
266
+ }
267
+ if (token === 'fragment') {
268
+ while (index < tokens.length && tokens[index] !== '{') index += 1;
269
+ if (index >= tokens.length) return { operations, defect: 'a fragment has no selection set' };
270
+ const after = skipBalanced('{', '}');
271
+ if (after === -1) return { operations, defect: 'a fragment\'s selection set never closes' };
272
+ index = after;
273
+ continue;
274
+ }
275
+ return { operations, defect: `'${token}' begins no executable definition (an operation or a fragment)` };
276
+ }
277
+ return { operations };
278
+ }
279
+
280
+ /**
281
+ * The top-level fields an input schema declares, read through Zod's own definition (`_zod.def`) as the input-options
282
+ * check reads it, so a module built against another copy of Zod is read the same. Wrappers that keep the value's shape
283
+ * are seen through; a union declares what any of its options declares. `undefined` when the schema is not an object
284
+ * (or a union of objects), so its fields cannot be listed.
285
+ */
286
+ function inputSchemaTopLevelFields(schema: unknown): Set<string> | undefined {
287
+ let current: unknown = schema;
288
+ for (let depth = 0; depth < 64; depth += 1) {
289
+ const def = (current as { _zod?: { def?: Record<string, unknown> } } | undefined)?._zod?.def;
290
+ if (def === undefined) return undefined;
291
+ switch (def.type) {
292
+ case 'optional': case 'nullable': case 'default': case 'prefault': case 'readonly': case 'catch': case 'nonoptional':
293
+ current = def.innerType;
294
+ continue;
295
+ case 'pipe':
296
+ current = def.in;
297
+ continue;
298
+ case 'lazy':
299
+ current = typeof def.getter === 'function' ? (def.getter as () => unknown)() : undefined;
300
+ continue;
301
+ case 'object':
302
+ return new Set(Object.keys((def.shape as Record<string, unknown> | undefined) ?? {}));
303
+ case 'union': {
304
+ const fields = new Set<string>();
305
+ for (const option of Array.isArray(def.options) ? def.options : []) {
306
+ const optionFields = inputSchemaTopLevelFields(option);
307
+ if (optionFields === undefined) return undefined;
308
+ for (const field of optionFields) fields.add(field);
309
+ }
310
+ return fields;
311
+ }
312
+ default:
313
+ return undefined;
314
+ }
315
+ }
316
+ return undefined;
317
+ }
318
+
319
+ /**
320
+ * Why a GraphQL operation cannot be sent as declared, or an empty list (#3392). Empty for an operation without
321
+ * `graphql`. Checked where a catalogue loads (the operation executor, an augmentation merge), at `wildo registry publish`,
322
+ * and by the request compiler on every call, so the one rule refuses in every place:
323
+ *
324
+ * - the call is a POST with no `requestBody`, every parameter carries a `constantValue` (the input is the variables
325
+ * and nothing else), and the answer is read as JSON;
326
+ * - the document reads as exactly ONE operation, named `operationName`, beside any fragments;
327
+ * - a `query` is classified READ and a `mutation` WRITE; a `subscription` is refused;
328
+ * - each declared variable is a top-level field of `inputSchema`, and each top-level field is a declared variable, so no
329
+ * value a caller supplies is silently dropped (when `inputSchema` lists its fields; without one, the call refuses a
330
+ * value for a variable the document does not declare);
331
+ * - `errorCodePath` is a dot path;
332
+ * - each of `credentialRefusedErrorCodes` is code-shaped (a value of any other shape is never kept, so it could never
333
+ * match), and the list comes with an `errorCodePath` to read the code at;
334
+ * - a `payloadRefusal` belongs to a mutation, names a kind of its vocabulary, and reads every path as a dot path.
335
+ */
336
+ export function describeProviderRestOperationGraphqlDefects(
337
+ operation: Pick<
338
+ ProviderRestOperation,
339
+ 'operationId' | 'method' | 'classification' | 'parameters' | 'requestBody' | 'responseDecoding' | 'binaryResponse' | 'inputSchema' | 'graphql'
340
+ >,
341
+ ): string[] {
342
+ const graphql = operation.graphql;
343
+ if (graphql === undefined) return [];
344
+ const at = `GraphQL operation '${operation.operationId}'`;
345
+ const defects: string[] = [];
346
+ if (operation.method !== API_HttpMethod.POST) defects.push(`${at} is sent with ${operation.method}; a GraphQL call is a POST`);
347
+ if (operation.requestBody !== undefined) defects.push(`${at} declares a requestBody; its body is the document and its variables`);
348
+ for (const parameter of operation.parameters ?? []) {
349
+ if (parameter.constantValue === undefined) {
350
+ defects.push(`${at} declares the ${parameter.in} parameter '${parameter.name}' fed by the input; its input is the document's variables only, so a parameter must carry a constantValue`);
351
+ }
352
+ }
353
+ if (operation.responseDecoding !== undefined && operation.responseDecoding !== ProviderRestResponseDecoding.JSON) defects.push(`${at} reads its answer as ${operation.responseDecoding}; a GraphQL answer is JSON`);
354
+ if (operation.binaryResponse !== undefined) defects.push(`${at} declares binaryResponse; a GraphQL answer is JSON`);
355
+ if (!GRAPHQL_NAME.test(graphql.operationName)) defects.push(`${at} names the operation '${graphql.operationName}', which is not a GraphQL name`);
356
+ if (graphql.errorCodePath !== undefined && graphql.errorCodePath.split('.').some((segment) => segment.length === 0)) {
357
+ defects.push(`${at} reads its error code at '${graphql.errorCodePath}', which is not a dot path`);
358
+ }
359
+ const payloadRefusal = graphql.payloadRefusal;
360
+ if (payloadRefusal !== undefined) {
361
+ const kinds: readonly string[] = Object.values(ProviderGraphqlPayloadRefusalKind);
362
+ if (!kinds.includes(payloadRefusal.kind)) defects.push(`${at} declares the payload refusal kind ${JSON.stringify(payloadRefusal.kind)}, which is none of ${kinds.join(', ')}`);
363
+ const paths: [string, string | undefined][] = [['path', payloadRefusal.path]];
364
+ if (payloadRefusal.kind === ProviderGraphqlPayloadRefusalKind.USER_ERRORS) {
365
+ paths.push(['messagePath', payloadRefusal.messagePath], ['fieldPath', payloadRefusal.fieldPath], ['codePath', payloadRefusal.codePath]);
366
+ }
367
+ for (const [field, value] of paths) {
368
+ if (value === undefined && field !== 'path') continue;
369
+ if (typeof value !== 'string' || value.length === 0 || value.split('.').some((segment) => segment.length === 0)) {
370
+ defects.push(`${at} reads its payload refusal's ${field} at ${JSON.stringify(value)}, which is not a dot path`);
371
+ }
372
+ }
373
+ }
374
+ if (graphql.credentialRefusedErrorCodes !== undefined && graphql.errorCodePath === undefined) {
375
+ defects.push(`${at} lists credentialRefusedErrorCodes but no errorCodePath, so no code is read and none of them could ever match`);
376
+ }
377
+ for (const code of graphql.credentialRefusedErrorCodes ?? []) {
378
+ if (!PROVIDER_VENDOR_ERROR_CODE_SHAPE.test(code)) {
379
+ defects.push(`${at} lists the credential-refusal code '${code}', which is not code-shaped and would never match a code the transport keeps`);
380
+ }
381
+ }
382
+
383
+ const shape = readProviderGraphqlDocument(graphql.document);
384
+ if (shape.defect !== undefined) {
385
+ defects.push(`${at}: its document does not read as a GraphQL document (${shape.defect})`);
386
+ return defects;
387
+ }
388
+ const named = shape.operations.filter((candidate) => candidate.name === graphql.operationName);
389
+ if (named.length !== 1 || shape.operations.length !== 1) {
390
+ defects.push(
391
+ `${at}: its document must define exactly one operation, named '${graphql.operationName}', and it defines `
392
+ + `${shape.operations.length === 0 ? 'none' : shape.operations.map((candidate) => `${candidate.type} ${candidate.name ?? '(anonymous)'}`).join(', ')}`,
393
+ );
394
+ return defects;
395
+ }
396
+ const [definition] = named as [ProviderGraphqlDocumentOperation];
397
+ const expected = definition.type === ProviderGraphqlOperationType.QUERY ? ExternalOperation_Classification.READ
398
+ : definition.type === ProviderGraphqlOperationType.MUTATION ? ExternalOperation_Classification.WRITE
399
+ : undefined;
400
+ if (expected === undefined) defects.push(`${at} is a ${definition.type}, which is not answered over a single POST`);
401
+ // A refusal stated in a payload is a WRITE's: a query that answers data refused nothing.
402
+ if (graphql.payloadRefusal !== undefined && definition.type !== ProviderGraphqlOperationType.MUTATION) {
403
+ defects.push(`${at} is a ${definition.type} and declares a payload refusal, which only a mutation's payload states`);
404
+ }
405
+ else if (operation.classification !== expected) defects.push(`${at} is a ${definition.type} classified ${operation.classification}; a query is a READ and a mutation a WRITE`);
406
+
407
+ const fields = operation.inputSchema === undefined ? undefined : inputSchemaTopLevelFields(operation.inputSchema);
408
+ if (operation.inputSchema !== undefined && fields === undefined) {
409
+ defects.push(`${at} has an inputSchema that is not an object, and its input is the document's variables`);
410
+ }
411
+ if (fields !== undefined) {
412
+ for (const variable of definition.variables) {
413
+ if (!fields.has(variable)) defects.push(`${at} declares the variable '$${variable}', which its inputSchema does not declare`);
414
+ }
415
+ for (const field of fields) {
416
+ if (!definition.variables.includes(field)) defects.push(`${at}: its inputSchema declares '${field}', which is no variable of the document, so a value for it would never be sent`);
417
+ }
418
+ }
419
+ return defects;
420
+ }
421
+
422
+ /** The variables a GraphQL operation's document declares, or `undefined` when the document cannot be read. */
423
+ export function providerGraphqlOperationVariables(graphql: ProviderRestOperationGraphql): readonly string[] | undefined {
424
+ const shape = readProviderGraphqlDocument(graphql.document);
425
+ if (shape.defect !== undefined) return undefined;
426
+ return shape.operations.find((candidate) => candidate.name === graphql.operationName)?.variables;
427
+ }
428
+
429
+ /** What a GraphQL answer says about the call. See the table in this module's header. */
430
+ export enum ProviderGraphqlResponseOutcomeKind {
431
+ /** `data` is an object and no error was reported. */
432
+ SUCCEEDED = 'succeeded',
433
+ /** Errors, and no `data` entry: the request was refused before anything executed. Nothing was applied. */
434
+ REQUEST_ERROR = 'request_error',
435
+ /** Errors beside a `data` entry (null or partial): execution began and something failed. */
436
+ EXECUTION_ERROR = 'execution_error',
437
+ /** Neither a `data` object nor an error list: the answer does not state what happened. */
438
+ UNSTATED = 'unstated',
439
+ /**
440
+ * `data` and no `errors`, and the mutation's payload states the vendor refused it (its declared `payloadRefusal`): the
441
+ * write was not done, as the vendor says (follow-up to #3392).
442
+ */
443
+ PAYLOAD_REFUSED = 'payload_refused',
444
+ }
445
+
446
+ /** What {@link readProviderGraphqlResponse} read. */
447
+ export interface ProviderGraphqlResponseVerdict {
448
+ readonly kind: ProviderGraphqlResponseOutcomeKind;
449
+ /** On SUCCEEDED, the answer's `data` object: what the operation's `resultPath` and `outputSchema` read. */
450
+ readonly data?: Readonly<Record<string, unknown>>;
451
+ /**
452
+ * The vendor's error messages, in its order, at most {@link PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGES}, each cut at
453
+ * {@link PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGE_LENGTH} characters. Vendor prose: it may quote what the call sent, so it
454
+ * travels to the caller and is never written to a log or an audit row by the engine.
455
+ */
456
+ readonly errorMessages?: readonly string[];
457
+ /** The first code-shaped value at the operation's `errorCodePath` among the errors, when one is declared and found. */
458
+ readonly errorCode?: string;
459
+ }
460
+
461
+ /** The value at a dot path, read through own properties only (an array's index is an own property), or `undefined`. */
462
+ function readGraphqlDotPath(value: unknown, path: string): unknown {
463
+ let current: unknown = value;
464
+ for (const segment of path.split('.')) {
465
+ if (current === null || typeof current !== 'object' || !Object.hasOwn(current, segment)) return undefined;
466
+ current = (current as Record<string, unknown>)[segment];
467
+ }
468
+ return current;
469
+ }
470
+
471
+ function readGraphqlErrorCode(error: unknown, errorCodePath: string): string | undefined {
472
+ const current = readGraphqlDotPath(error, errorCodePath);
473
+ return typeof current === 'string' && PROVIDER_VENDOR_ERROR_CODE_SHAPE.test(current) ? current : undefined;
474
+ }
475
+
476
+ /** A vendor message as the verdict keeps it: cut at {@link PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGE_LENGTH}. */
477
+ function keptGraphqlMessage(message: string): string {
478
+ return message.length > PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGE_LENGTH ? `${message.slice(0, PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGE_LENGTH)}…` : message;
479
+ }
480
+
481
+ /**
482
+ * The refusal a mutation's payload states, read as its declaration says ({@link ProviderGraphqlPayloadRefusal}), or
483
+ * `undefined` when the payload refuses nothing.
484
+ */
485
+ function readGraphqlPayloadRefusal(
486
+ data: Readonly<Record<string, unknown>>,
487
+ refusal: ProviderGraphqlPayloadRefusal,
488
+ ): Pick<ProviderGraphqlResponseVerdict, 'errorMessages' | 'errorCode'> | undefined {
489
+ const stated = readGraphqlDotPath(data, refusal.path);
490
+ if (refusal.kind === ProviderGraphqlPayloadRefusalKind.SUCCESS_FLAG) {
491
+ return stated === false ? { errorMessages: [`the answer's ${refusal.path} is false: the vendor did not do the write`] } : undefined;
492
+ }
493
+ if (!Array.isArray(stated) || stated.length === 0) return undefined;
494
+ const errorMessages = stated.slice(0, PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGES).map((entry) => {
495
+ const message = readGraphqlDotPath(entry, refusal.messagePath ?? 'message');
496
+ const field = refusal.fieldPath === undefined ? undefined : readGraphqlDotPath(entry, refusal.fieldPath);
497
+ const fieldText = typeof field === 'string' ? field
498
+ : Array.isArray(field) && field.every((segment) => typeof segment === 'string' || typeof segment === 'number') ? field.join('.') : undefined;
499
+ const text = typeof message === 'string' ? message : 'the vendor refused the write without a message';
500
+ return keptGraphqlMessage(fieldText === undefined || fieldText.length === 0 ? text : `${fieldText}: ${text}`);
501
+ });
502
+ const errorCode = refusal.codePath === undefined ? undefined
503
+ : stated.map((entry) => readGraphqlErrorCode(entry, refusal.codePath!)).find((code) => code !== undefined);
504
+ return { errorMessages, ...(errorCode === undefined ? {} : { errorCode }) };
505
+ }
506
+
507
+ /**
508
+ * Reads a parsed GraphQL answer (#3392). The ONE reader: the engine's transport, for a 2xx and a non-2xx answer alike,
509
+ * and every test go through it. See the module header for the rule and its sources.
510
+ */
511
+ export function readProviderGraphqlResponse(
512
+ body: unknown,
513
+ errorCodePath?: string,
514
+ payloadRefusal?: ProviderGraphqlPayloadRefusal,
515
+ ): ProviderGraphqlResponseVerdict {
516
+ if (body === null || typeof body !== 'object' || Array.isArray(body)) return { kind: ProviderGraphqlResponseOutcomeKind.UNSTATED };
517
+ const answer = body as Record<string, unknown>;
518
+ const errors = Object.hasOwn(answer, 'errors') ? answer.errors : undefined;
519
+ if (errors !== undefined && errors !== null && !Array.isArray(errors)) return { kind: ProviderGraphqlResponseOutcomeKind.UNSTATED };
520
+ if (Array.isArray(errors) && errors.length > 0) {
521
+ const errorMessages = errors
522
+ .map((error) => (error !== null && typeof error === 'object' && typeof (error as { message?: unknown }).message === 'string' ? (error as { message: string }).message : undefined))
523
+ .filter((message): message is string => message !== undefined)
524
+ .slice(0, PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGES)
525
+ .map(keptGraphqlMessage);
526
+ const errorCode = errorCodePath === undefined ? undefined
527
+ : errors.map((error) => readGraphqlErrorCode(error, errorCodePath)).find((code) => code !== undefined);
528
+ return {
529
+ kind: Object.hasOwn(answer, 'data') ? ProviderGraphqlResponseOutcomeKind.EXECUTION_ERROR : ProviderGraphqlResponseOutcomeKind.REQUEST_ERROR,
530
+ errorMessages,
531
+ ...(errorCode === undefined ? {} : { errorCode }),
532
+ };
533
+ }
534
+ const data = Object.hasOwn(answer, 'data') ? answer.data : undefined;
535
+ if (data === null || typeof data !== 'object' || Array.isArray(data)) return { kind: ProviderGraphqlResponseOutcomeKind.UNSTATED };
536
+ const refused = payloadRefusal === undefined ? undefined : readGraphqlPayloadRefusal(data as Record<string, unknown>, payloadRefusal);
537
+ if (refused !== undefined) return { kind: ProviderGraphqlResponseOutcomeKind.PAYLOAD_REFUSED, ...refused };
538
+ return { kind: ProviderGraphqlResponseOutcomeKind.SUCCEEDED, data: data as Record<string, unknown> };
539
+ }
540
+ ```
541
+
542
+ ### Origin Package: `@wildo-ai/external-connectors-models`
543
+
11
544
  ```typescript
12
545
  /** Where a declared parameter rides on the wire. */
13
546
  export enum ProviderRestParameterLocation {
@@ -106,6 +639,19 @@ export interface ProviderRestOperationParameter {
106
639
  * above it; the origin itself cannot move, as for every path value.
107
640
  */
108
641
  readonly multiSegment?: true;
642
+ /**
643
+ * PATH only (#3397): the value is the CONNECTION's vendor-reported fact of this name, never the caller's input. Every
644
+ * QuickBooks path is `/v3/company/{realmId}/…`, and the company is the one the person connected, so asking each caller
645
+ * for it would let a call name a company its connection was not made for and leave every application re-typing it.
646
+ *
647
+ * The fact must be declared on the connection's OAuth2 contract with a
648
+ * {@link ProviderOAuth2ReportedAccountFact.pathSegmentPattern}; the access resolver re-admits the stored value on every
649
+ * call and hands it to the request compiler, which fills nothing else from it. A caller value under the same input
650
+ * name is refused rather than ignored, and the operation's `inputSchema` must not declare one
651
+ * ({@link describeProviderRestOperationConnectionFactDefects}). Exclusive with `from`, `constantValue` and
652
+ * `multiSegment`.
653
+ */
654
+ readonly connectionFact?: string;
109
655
  readonly description?: string;
110
656
  }
111
657
 
@@ -177,11 +723,146 @@ export interface ProviderRestOperationInputOptions {
177
723
  /** Dot-path, inside each listed item, to the text a person reads (`name`). Vendor content, never derived from the value. */
178
724
  readonly labelPath: string;
179
725
  /**
180
- * Inputs the options depend on: `{ <options-operation input field>: <this operation's input field> }`.
726
+ * Inputs the options depend on: `{ <options-operation input field>: <this operation's input field PATH> }`.
727
+ * The value side is a dot path into this operation's input, like the `inputOptions` key (#3399): Jira's issue
728
+ * types depend on `project.key`. The key side is a top-level field of the options operation's own input.
181
729
  * A choice that is not yet made is REFUSED by name rather than listed as empty — "no projects" and
182
730
  * "choose a workspace first" are different answers, and only one of them is true.
183
731
  */
184
732
  readonly dependsOn?: Readonly<Record<string, string>>;
733
+ /**
734
+ * Fixed values the options operation is called with, beside what `dependsOn` forwards (#3399): Jira lists only the
735
+ * projects a person may create in (`action: 'create'`), Box lists the root folder (`folder_id: '0'`). A field may
736
+ * not be both fixed and forwarded.
737
+ */
738
+ readonly input?: Readonly<Record<string, string | number | boolean>>;
739
+ /**
740
+ * Dot path, inside the options operation's output, to the listed items, when that output is an object rather than the
741
+ * list itself (#3399): QuickBooks answers a query as `{ Customer: [...] }`, Box a folder as `{ entries: [...] }`. An
742
+ * object without that path lists nothing, which is how QuickBooks answers a query with no rows; anything else at the
743
+ * path that is not a list is an unreadable answer. Absent, the output itself must be the list.
744
+ */
745
+ readonly itemsPath?: string;
746
+ /**
747
+ * Keeps only the listed items whose value at each dot path equals the given text (#3399): a folder's items are files,
748
+ * folders and web links, and only a folder can be a parent (`{ type: 'folder' }`). Absent, every item is a choice.
749
+ */
750
+ readonly itemWhere?: Readonly<Record<string, string>>;
751
+ }
752
+
753
+ /**
754
+ * The schema a dot path into an operation's input names, or `undefined` when a segment names no declared field (#3399).
755
+ *
756
+ * Walked through Zod's own definition (`_zod.def`), not `instanceof`: a provider module may be built against another
757
+ * copy of Zod than the host's. Wrappers that leave the value's shape alone (optional, nullable, default, prefault,
758
+ * readonly, catch, nonoptional, a pipe's input, a lazy getter) are seen through. A union names the field when any of its
759
+ * options declares it, as a discriminated body does. Only an object's DECLARED fields count: a loose object admits other
760
+ * keys at runtime, and a picker for a key nobody declared is the typo this check exists to refuse.
761
+ */
762
+ function providerRestInputSchemaAtPath(schema: unknown, segments: readonly string[]): unknown {
763
+ let current: unknown = schema;
764
+ for (let depth = 0; depth < 64; depth += 1) {
765
+ const def = (current as { _zod?: { def?: Record<string, unknown> } } | undefined)?._zod?.def;
766
+ if (def === undefined) return undefined;
767
+ switch (def.type) {
768
+ case 'optional': case 'nullable': case 'default': case 'prefault': case 'readonly': case 'catch': case 'nonoptional':
769
+ current = def.innerType;
770
+ continue;
771
+ case 'pipe':
772
+ current = def.in;
773
+ continue;
774
+ case 'lazy':
775
+ current = typeof def.getter === 'function' ? (def.getter as () => unknown)() : undefined;
776
+ continue;
777
+ case 'union': {
778
+ if (segments.length === 0) return current;
779
+ const options = Array.isArray(def.options) ? def.options : [];
780
+ return options.map((option) => providerRestInputSchemaAtPath(option, segments)).find((found) => found !== undefined);
781
+ }
782
+ case 'object': {
783
+ if (segments.length === 0) return current;
784
+ const shape = def.shape as Record<string, unknown> | undefined;
785
+ const [head, ...rest] = segments;
786
+ if (shape === undefined || head === undefined || !Object.hasOwn(shape, head)) return undefined;
787
+ return providerRestInputSchemaAtPath(shape[head], rest);
788
+ }
789
+ default:
790
+ return segments.length === 0 ? current : undefined;
791
+ }
792
+ }
793
+ return undefined;
794
+ }
795
+
796
+ /**
797
+ * Why an operation's `inputOptions` cannot be honoured, or an empty list (#3399). Each key, and each `dependsOn` value,
798
+ * is a dot path into the operation's input (`project.key`, `CustomerRef.value`; a top-level field is a one-segment
799
+ * path), and must name a field the operation's `inputSchema` declares. Checked where a catalogue loads (the operation
800
+ * executor, an augmentation or supplement merge) and at publish, so a mistyped path is refused once, by name, instead of
801
+ * offering a picker that fills nothing. An operation without an `inputSchema` passes its input through unvalidated and
802
+ * declares no fields, so there is nothing to check its paths against; only their shape is.
803
+ */
804
+ export function describeProviderRestOperationInputOptionsDefects(operation: Pick<ProviderRestOperation, 'operationId' | 'inputSchema' | 'inputOptions'>): string[] {
805
+ const defects: string[] = [];
806
+ const check = (path: string, role: string) => {
807
+ const segments = path.split('.');
808
+ if (segments.some((segment) => segment.length === 0)) {
809
+ defects.push(`operation '${operation.operationId}': ${role} '${path}' is not a dot path of field names`);
810
+ return;
811
+ }
812
+ if (operation.inputSchema !== undefined && providerRestInputSchemaAtPath(operation.inputSchema, segments) === undefined) {
813
+ defects.push(`operation '${operation.operationId}': ${role} '${path}' names no field of its inputSchema`);
814
+ }
815
+ };
816
+ for (const [inputPath, declaration] of Object.entries(operation.inputOptions ?? {})) {
817
+ check(inputPath, 'the inputOptions key');
818
+ for (const sourcePath of Object.values(declaration.dependsOn ?? {})) check(sourcePath, `the dependsOn of '${inputPath}'`);
819
+ for (const fixed of Object.keys(declaration.input ?? {})) {
820
+ if (Object.hasOwn(declaration.dependsOn ?? {}, fixed)) {
821
+ defects.push(`operation '${operation.operationId}': the options of '${inputPath}' both fix and forward '${fixed}'`);
822
+ }
823
+ }
824
+ for (const listPath of [declaration.itemsPath, ...Object.keys(declaration.itemWhere ?? {})]) {
825
+ if (listPath !== undefined && listPath.split('.').some((segment) => segment.length === 0)) {
826
+ defects.push(`operation '${operation.operationId}': the options of '${inputPath}' name '${listPath}', which is not a dot path`);
827
+ }
828
+ }
829
+ }
830
+ return defects;
831
+ }
832
+
833
+ /**
834
+ * Why an operation's {@link ProviderRestOperationParameter.connectionFact} parameters cannot be honoured, or an empty
835
+ * list (#3397). Each must be a PATH parameter the path template uses, fed by nothing else (no `from`, `constantValue` or
836
+ * `multiSegment`), and the operation's `inputSchema` must not declare a field of its name: a caller is never asked for a
837
+ * value the connection supplies, and one it sends anyway is refused at the call. With `reportedAccountFacts` (the
838
+ * connection's OAuth2 declaration), each named fact must also be declared there with a `pathSegmentPattern`; without
839
+ * it the request compiler refuses the call, so a module walk passes them to catch it before any call.
840
+ */
841
+ export function describeProviderRestOperationConnectionFactDefects(
842
+ operation: Pick<ProviderRestOperation, 'operationId' | 'pathTemplate' | 'parameters' | 'inputSchema'>,
843
+ reportedAccountFacts?: Readonly<Record<string, ProviderOAuth2ReportedAccountFact>>,
844
+ ): string[] {
845
+ const defects: string[] = [];
846
+ for (const parameter of operation.parameters ?? []) {
847
+ const factName = parameter.connectionFact;
848
+ if (factName === undefined) continue;
849
+ const at = `operation '${operation.operationId}': the parameter '${parameter.name}' filled from the connection fact '${factName}'`;
850
+ if (parameter.in !== ProviderRestParameterLocation.PATH) defects.push(`${at} is a ${parameter.in} parameter; only a PATH value may come from a connection fact`);
851
+ if (parameter.from !== undefined || parameter.constantValue !== undefined || parameter.multiSegment !== undefined) {
852
+ defects.push(`${at} also declares from, constantValue or multiSegment; its value comes from the connection alone`);
853
+ }
854
+ if (!operation.pathTemplate.includes(`{${parameter.name}}`)) defects.push(`${at} fills no '{${parameter.name}}' token of the path template`);
855
+ if (operation.inputSchema !== undefined && providerRestInputSchemaAtPath(operation.inputSchema, [parameter.name]) !== undefined) {
856
+ defects.push(`${at} is also declared by the inputSchema, which would ask callers for a value the connection supplies`);
857
+ }
858
+ if (reportedAccountFacts !== undefined) {
859
+ const fact = Object.hasOwn(reportedAccountFacts, factName) ? reportedAccountFacts[factName] : undefined;
860
+ if (fact?.pathSegmentPattern === undefined) {
861
+ defects.push(`${at}: the connection's OAuth2 contract declares no reported fact '${factName}' with a pathSegmentPattern`);
862
+ }
863
+ }
864
+ }
865
+ return defects;
185
866
  }
186
867
 
187
868
  /**
@@ -285,10 +966,19 @@ export interface ProviderRestOperation {
285
966
  /** Narrows the provider's semantics for this one operation (a slow export, a tight endpoint). */
286
967
  readonly remoteCallSemantics?: Partial<ProviderRestCallSemantics>;
287
968
  /**
288
- * Where each input's choices come from, keyed by INPUT field name. Absent for an input a caller types.
289
- * See {@link ProviderRestOperationInputOptions}.
969
+ * Where each input's choices come from, keyed by a dot PATH into the input (#3399): `workspace` for a top-level
970
+ * field, `project.key` or `CustomerRef.value` for the value a vendor nests inside a reference object. Absent for an
971
+ * input a caller types. Every path must name a field of `inputSchema`
972
+ * ({@link describeProviderRestOperationInputOptionsDefects}). See {@link ProviderRestOperationInputOptions}.
290
973
  */
291
974
  readonly inputOptions?: Readonly<Record<string, ProviderRestOperationInputOptions>>;
975
+ /**
976
+ * Present for a GraphQL operation (#3392): the provider-owned document the call sends to `pathTemplate` (the vendor's
977
+ * GraphQL endpoint), with the operation's input as its variables. A 2xx answer carrying `errors` fails the call; the
978
+ * output is read from the answer's `data`. See {@link ProviderRestOperationGraphql} for what such an operation may and
979
+ * may not declare beside it.
980
+ */
981
+ readonly graphql?: ProviderRestOperationGraphql;
292
982
  /** Set when the vendor has deprecated it; the executor logs once per operation, never refuses. */
293
983
  readonly deprecated?: {
294
984
  readonly reason: string;
@@ -407,6 +1097,23 @@ export const PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER = '{tenant}';
407
1097
  /** A tenant value the token URL admits: a GUID or a DNS name. Nothing that can leave the URL's path segment. */
408
1098
  export const PROVIDER_CLIENT_CREDENTIALS_TENANT_SHAPE = /^[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?$/;
409
1099
 
1100
+ /**
1101
+ * The placeholder that BEGINS a client-credentials token URL whose token endpoint is on the deployment's own vendor
1102
+ * instance (#3402): `{deploymentOrigin}/oauth2/v1/token`. Filled with the ORIGIN of the base URL the engine resolved for
1103
+ * the REST contract (from `baseUrlHostEnvVarName` or `baseUrlEnvVarName`), never from a connection or a request.
1104
+ *
1105
+ * Okta is the case: every org has its own host (`<org>.okta.com`, or a custom domain), and its org authorization server's
1106
+ * token endpoint is on that host. A fixed {@link ProviderRestClientCredentials.tokenHosts} list cannot admit a host only
1107
+ * the operator knows, and a `{tenant}` value would be a second, separately typed copy of the host the operations already
1108
+ * go to, which could disagree with it. Filling the token endpoint from the SAME resolved origin keeps them one value: the
1109
+ * client's assertion is sent to the host the operator named, and to nothing a person connecting could choose.
1110
+ *
1111
+ * spec-cite: Okta Developer, "Implement OAuth for Okta with a service app"
1112
+ * (https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/, fetched 2026-11-10) — the token
1113
+ * request is `POST https://{yourOktaDomain}/oauth2/v1/token`, and the assertion's `aud` is that URL.
1114
+ */
1115
+ export const PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER = '{deploymentOrigin}';
1116
+
410
1117
  /** What a {@link ProviderClientCredentialsVerifiedFact} records: a value the person typed and the vendor accepted. */
411
1118
  export enum ProviderClientCredentialsFactSource {
412
1119
  /** The client id the token endpoint issued a token for: Microsoft's bot App ID. */
@@ -440,9 +1147,14 @@ export interface ProviderClientCredentialsVerifiedFact {
440
1147
  * secret the connection holds (#2663). The Bot Framework is the first: a Teams bot's App ID and secret, and for a
441
1148
  * single-tenant bot the tenant it is registered in, mint a token for `https://api.botframework.com/.default`.
442
1149
  *
1150
+ * Declared beside `oauth2` (#3398), it is the APPLICATION's own connection: Box's client-credentials grant and Zoom's
1151
+ * server-to-server OAuth renew the application's token while people and organizations connect through the exchange.
1152
+ * {@link providerClientCredentialsServesOwnerScope} says which door a connection takes.
1153
+ *
443
1154
  * The token is minted per call when no unexpired one is cached, never stored, and attached where
444
- * {@link ProviderProtocolRuntimeContract}'s `apiKey` says, so `apiKey.secretRef` names the client SECRET (the slot
445
- * whose absence means "not configured"). The client id, secret and tenant are read from the connection: the
1155
+ * {@link ProviderProtocolRuntimeContract}'s `apiKey` says, so (with no `oauth2` beside it) `apiKey.secretRef` names the
1156
+ * client's credential, its SECRET or its private key (#3402), the slot whose absence means "not configured". The
1157
+ * client id, credential and tenant are read from the connection: the
446
1158
  * application's own environment for an APPLICATION connection, the organization's typed credential for an
447
1159
  * ORGANIZATION one.
448
1160
  *
@@ -457,16 +1169,62 @@ export interface ProviderClientCredentialsVerifiedFact {
457
1169
  * `https://api.botframework.com/.default`, fetched 2026-10-06.
458
1170
  */
459
1171
  export interface ProviderRestClientCredentials {
460
- /** The https token endpoint. May carry {@link PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}. */
1172
+ /**
1173
+ * The https token endpoint. May carry {@link PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}, or BEGIN with
1174
+ * {@link PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} when the token endpoint is on the deployment's own
1175
+ * vendor instance (Okta's org, #3402).
1176
+ */
461
1177
  readonly tokenUrl: string;
462
- /** The hosts the token endpoint may be on once filled. The client secret is sent nowhere else. */
1178
+ /**
1179
+ * The hosts the token endpoint may be on once filled. The client secret is sent nowhere else. EMPTY exactly when the
1180
+ * token URL begins with {@link PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}: its host is the one the
1181
+ * operator named for the operations, and no fixed list can name it.
1182
+ */
463
1183
  readonly tokenHosts: readonly string[];
464
- /** The `scope` parameter, sent as written. */
465
- readonly scope: string;
1184
+ /**
1185
+ * The `scope` parameter, sent as written. Omitted, no `scope` is sent: RFC 6749 makes it optional, and Box, Zoom and
1186
+ * Salesforce grant the scopes configured on the app instead (#3398).
1187
+ * spec-cite: RFC 6749 §4.4.2 — `scope`: "OPTIONAL. The scope of the access request as described by Section 3.3."
1188
+ * Fetched 2026-10-06.
1189
+ */
1190
+ readonly scope?: string;
1191
+ /**
1192
+ * The `grant_type` sent. Omitted, `client_credentials` (RFC 6749 §4.4). See {@link ProviderClientCredentialsGrantType}.
1193
+ */
1194
+ readonly grantType?: ProviderClientCredentialsGrantType;
1195
+ /**
1196
+ * Further parameters of the token request a vendor requires, by name: a fixed value, or one read from a slot of the
1197
+ * connection (#3398). Box's client-credentials grant names the subject it authenticates as (`box_subject_type`,
1198
+ * `box_subject_id`); Zoom's server-to-server grant names the account (`account_id`). A parameter the grant itself
1199
+ * defines (`grant_type`, `client_id`, `client_secret`, `scope`, the client assertion) is refused here: each has its own
1200
+ * field. See {@link ProviderClientCredentialsTokenRequestParameter}.
1201
+ */
1202
+ readonly tokenRequestParameters?: Readonly<Record<string, ProviderClientCredentialsTokenRequestParameter>>;
1203
+ /**
1204
+ * How the client authenticates to the token endpoint. Omitted,
1205
+ * {@link ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_POST} with a client secret: the id and secret in the
1206
+ * body, as Microsoft's identity platform documents. {@link ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_BASIC}
1207
+ * sends them in the Basic header only (Zoom's server-to-server OAuth documents nothing else). With
1208
+ * {@link privateKeyJwt} the method is {@link ProviderOAuth2ClientAuthenticationMethod.PRIVATE_KEY_JWT}, implied when
1209
+ * omitted (#3402).
1210
+ */
1211
+ readonly tokenEndpointAuthMethod?: ProviderOAuth2ClientAuthenticationMethod;
466
1212
  /** The slot holding the client id. */
467
1213
  readonly clientIdSecretRef: string;
468
- /** The slot holding the client secret. Equal to the contract's `apiKey.secretRef`. */
469
- readonly clientSecretSecretRef: string;
1214
+ /**
1215
+ * The slot holding the client secret. Exactly one of this and {@link privateKeyJwt} (#3402): a client authenticates
1216
+ * with a shared secret or with a key it alone holds, never both. The client's CREDENTIAL slot (this one, or the
1217
+ * private key's) equals the contract's `apiKey.secretRef` when the contract declares no `oauth2` (the slot whose
1218
+ * absence means "not configured"); beside `oauth2`, `apiKey.secretRef` is the slot of the people's and organizations'
1219
+ * minted tokens and this one serves the application alone.
1220
+ */
1221
+ readonly clientSecretSecretRef?: string;
1222
+ /**
1223
+ * The client authenticates with a JWT it signs with its own private key (`private_key_jwt`, #3402) instead of a
1224
+ * secret: Okta's OAuth service apps accept nothing else for the Management API. See
1225
+ * {@link ProviderClientCredentialsPrivateKeyJwt}.
1226
+ */
1227
+ readonly privateKeyJwt?: ProviderClientCredentialsPrivateKeyJwt;
470
1228
  /** The slot filling {@link PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}. Required exactly when the token URL carries it. */
471
1229
  readonly tenantSecretRef?: string;
472
1230
  /** Facts an ORGANIZATION connection records once the vendor accepted its credential, keyed by fact name. */
@@ -475,6 +1233,152 @@ export interface ProviderRestClientCredentials {
475
1233
  readonly tokenLifetimeFallbackSeconds?: number;
476
1234
  }
477
1235
 
1236
+ /**
1237
+ * The `grant_type` a client-credentials token request sends. Narrower than `OAuth2_GrantType` on purpose: these are the
1238
+ * grants the client-credentials minter performs, each with nothing but the client's own credential and the declared
1239
+ * parameters, and a member joins in the change that implements it.
1240
+ */
1241
+ export enum ProviderClientCredentialsGrantType {
1242
+ /**
1243
+ * The OAuth 2.0 client-credentials grant: the default.
1244
+ * spec-cite: RFC 6749 §4.4.2 — `grant_type`: "REQUIRED. Value MUST be set to "client_credentials"." Fetched 2026-10-06.
1245
+ */
1246
+ CLIENT_CREDENTIALS = 'client_credentials',
1247
+ /**
1248
+ * Zoom's server-to-server OAuth: the same exchange (a client authenticated with Basic, one token back, no refresh
1249
+ * token) under Zoom's own grant name, with the account named in `account_id`.
1250
+ * spec-cite: https://developers.zoom.us/docs/internal-apps/s2s-oauth/ — "Use the `account_credentials` grant type to
1251
+ * generate an access token."; "Set up the body of the access token request using the `account_credentials`
1252
+ * `grant_type` and your `account_id`." Fetched 2026-11-09.
1253
+ */
1254
+ ACCOUNT_CREDENTIALS = 'account_credentials',
1255
+ }
1256
+
1257
+ /**
1258
+ * One further parameter of a client-credentials token request ({@link ProviderRestClientCredentials.tokenRequestParameters}):
1259
+ * a fixed `value` the module states (`box_subject_type: enterprise`), or a `secretRef` naming the connection slot that
1260
+ * holds it (Box's enterprise id, Zoom's account id), read like the client id: from the application's environment for
1261
+ * the application's connection, from the organization's credential for an organization's.
1262
+ */
1263
+ export type ProviderClientCredentialsTokenRequestParameter =
1264
+ | { readonly value: string; readonly secretRef?: never }
1265
+ | { readonly secretRef: string; readonly value?: never };
1266
+
1267
+ /**
1268
+ * The algorithms a client assertion is signed with (#3402). The JWS names (RFC 7518 §3.1) of the two asymmetric
1269
+ * families every vendor measured accepts: Okta lists "RS256, RS384, RS512, ES256, ES384, and ES512" for a service app's
1270
+ * key. A member joins when a vendor needs it.
1271
+ * spec-cite: RFC 7518 §3.1 — "RS256 | RSASSA-PKCS1-v1_5 using SHA-256" and "ES256 | ECDSA using P-256 and SHA-256";
1272
+ * https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/ — the supported algorithms. Both
1273
+ * fetched 2026-11-09.
1274
+ */
1275
+ export enum ProviderClientAssertionSigningAlgorithm {
1276
+ /** ECDSA on P-256 with SHA-256: a short key and signature, and the default to choose for a new key. */
1277
+ ES256 = 'ES256',
1278
+ /** RSASSA-PKCS1-v1_5 with SHA-256, for a vendor or key store that issues RSA keys. */
1279
+ RS256 = 'RS256',
1280
+ }
1281
+
1282
+ /** The longest a client assertion may live: Okta refuses one whose `exp` is more than an hour away. */
1283
+ export const PROVIDER_CLIENT_ASSERTION_MAXIMUM_LIFETIME_SECONDS = 3600;
1284
+
1285
+ /** How long a client assertion lives when the declaration says nothing: long enough for one request, and no more. */
1286
+ export const PROVIDER_CLIENT_ASSERTION_DEFAULT_LIFETIME_SECONDS = 300;
1287
+
1288
+ /**
1289
+ * `private_key_jwt` client authentication for a client-credentials token request (#3402). The client signs, per token
1290
+ * request, a JWT whose `iss` and `sub` are its client id, whose `aud` is the token endpoint it is sent to, with a short
1291
+ * `exp` and a fresh `jti`, and sends it as `client_assertion`.
1292
+ *
1293
+ * The private key is read from a slot of the connection, as an unencrypted PEM (PKCS#8, or an RSA PKCS#1 / EC key the
1294
+ * signer re-wraps), like a secret: the application's configured provider secrets for its own connection, an organization's sealed
1295
+ * credential row for an organization's.
1296
+ *
1297
+ * ## Why the platform keyring does not hold this key (decided 2026-11-10, #3402)
1298
+ *
1299
+ * The key layer (#2916) holds keys by PURPOSE, each signing the platform's own claims under its own `typ` and verified
1300
+ * from public halves the platform publishes. A client key is the opposite: its public half is REGISTERED BY THE OPERATOR
1301
+ * at the vendor (Okta's app, a Google service account), the vendor is its only verifier, and the vendor fixes the
1302
+ * algorithm (Okta's console and Google's uploaded keys are RSA, while the keyring signs ES256 only). A keyring rotation
1303
+ * would also silently break every connection whose vendor still holds the old public half. So custody signing for vendor
1304
+ * clients is a key purpose of its own (RS256 across the keyring providers, a public half handed to the operator, rotation
1305
+ * coordinated with the vendor registration), recorded on #2916, and not a missing step of this declaration.
1306
+ *
1307
+ * spec-cite: RFC 7523 §2.2 — "The value of the "client_assertion_type" is
1308
+ * "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"."; §3 — the JWT "MUST contain an "iss" (issuer) claim", for
1309
+ * client authentication "the subject MUST be the "client_id" of the OAuth client", an "aud" (audience) claim "containing
1310
+ * a value that identifies the authorization server", and an "exp" (expiration time) claim; OpenID Connect Core 1.0 §9,
1311
+ * `private_key_jwt` — `iss` and `sub` "MUST contain the client_id of the OAuth Client", "The Audience SHOULD be the URL
1312
+ * of the Authorization Server's Token Endpoint", `jti` REQUIRED: "These tokens MUST only be used once". Fetched
1313
+ * 2026-11-09 from https://www.rfc-editor.org/rfc/rfc7523 and https://openid.net/specs/openid-connect-core-1_0.html.
1314
+ */
1315
+ export interface ProviderClientCredentialsPrivateKeyJwt {
1316
+ /** The slot holding the client's private key: an unencrypted PEM, PKCS#8 (`-----BEGIN PRIVATE KEY-----`) or PKCS#1 / EC. */
1317
+ readonly privateKeySecretRef: string;
1318
+ /** The JWS algorithm the key signs with. Must match the key: an EC P-256 key for ES256, an RSA key for RS256. */
1319
+ readonly algorithm: ProviderClientAssertionSigningAlgorithm;
1320
+ /**
1321
+ * The slot holding the key id sent as the assertion's `kid` header, when the vendor locates the key by it (Okta
1322
+ * requires a `kid` on every key registered with the app). Omitted, no `kid` is sent.
1323
+ */
1324
+ readonly keyIdSecretRef?: string;
1325
+ /** Seconds until the assertion's `exp`. Omitted, {@link PROVIDER_CLIENT_ASSERTION_DEFAULT_LIFETIME_SECONDS}. */
1326
+ readonly assertionLifetimeSeconds?: number;
1327
+ }
1328
+
1329
+ /**
1330
+ * The slot of a client-credentials declaration's own CREDENTIAL: the client secret, or the private key (#3402).
1331
+ * `undefined` only for a declaration {@link describeProviderRestClientCredentialsDefects} refuses.
1332
+ */
1333
+ export function providerClientCredentialsCredentialSlot(credentials: ProviderRestClientCredentials): string | undefined {
1334
+ return credentials.clientSecretSecretRef ?? credentials.privateKeyJwt?.privateKeySecretRef;
1335
+ }
1336
+
1337
+ /**
1338
+ * The parameter names {@link ProviderRestClientCredentials.tokenRequestParameters} may not declare: each is written by
1339
+ * the grant itself (the grant type, the client's credential, the scope, a client assertion), so a second value would
1340
+ * either be ignored or override the declared one.
1341
+ */
1342
+ export const PROVIDER_CLIENT_CREDENTIALS_RESERVED_PARAMETER_NAMES: readonly string[] = [
1343
+ 'grant_type', 'client_id', 'client_secret', 'scope', 'client_assertion', 'client_assertion_type',
1344
+ ];
1345
+
1346
+ /**
1347
+ * Whether the client-credentials door of a REST contract serves a connection of this owner scope (#3398).
1348
+ *
1349
+ * Alone, it serves every admitted connection: the application's own (from its environment) and an organization's (from
1350
+ * the credential the organization typed, as a Teams bot). Beside `oauth2`, a person or an organization connects through
1351
+ * the authorization-code exchange, and the client-credentials grant serves the APPLICATION's own account only, so that
1352
+ * account renews itself instead of resting on a pasted token that expires within the hour.
1353
+ */
1354
+ export function providerClientCredentialsServesOwnerScope(
1355
+ contract: { readonly clientCredentials?: ProviderRestClientCredentials; readonly oauth2?: unknown },
1356
+ ownerScope: ExternalProvider_Connection_OwnerScope,
1357
+ ): boolean {
1358
+ if (contract.clientCredentials === undefined) return false;
1359
+ return contract.oauth2 === undefined || ownerScope === ExternalProvider_Connection_OwnerScope.APPLICATION;
1360
+ }
1361
+
1362
+ /**
1363
+ * The slot a connection of this owner scope AUTHENTICATES with, as the engine's REST access resolver reads it: the
1364
+ * client-credentials grant's own credential (its client secret or private key) when that door serves the owner scope
1365
+ * ({@link providerClientCredentialsServesOwnerScope}), else `apiKey.secretRef`, the stored or pasted token itself.
1366
+ *
1367
+ * For a contract declaring `clientCredentials` beside `oauth2` (Box, Zoom, #3398) the two differ by owner: the
1368
+ * application's own account mints from the server app's secret, while a person's connection reads its exchanged token
1369
+ * from `apiKey.secretRef`. A tool standing in for one connection (`wildo providers probe`, `connect`, the doctor's
1370
+ * configuration checks, all APPLICATION-owned) asks this instead of reading `apiKey.secretRef`, so it reads the slot the
1371
+ * engine would. `undefined` when the contract names neither.
1372
+ */
1373
+ export function providerRestConnectionCredentialSlot(
1374
+ contract: { readonly clientCredentials?: ProviderRestClientCredentials; readonly oauth2?: unknown; readonly apiKey?: { readonly secretRef?: string } },
1375
+ ownerScope: ExternalProvider_Connection_OwnerScope,
1376
+ ): string | undefined {
1377
+ return providerClientCredentialsServesOwnerScope(contract, ownerScope)
1378
+ ? providerClientCredentialsCredentialSlot(contract.clientCredentials!)
1379
+ : contract.apiKey?.secretRef;
1380
+ }
1381
+
478
1382
  /**
479
1383
  * Why a client-credentials declaration cannot be honoured, or an empty list. Checked where a provider is composed:
480
1384
  * a token URL that is not https, a token host that is not a DNS name or that the URL is not on, a tenant placeholder
@@ -483,20 +1387,70 @@ export interface ProviderRestClientCredentials {
483
1387
  export function describeProviderRestClientCredentialsDefects(credentials: ProviderRestClientCredentials): string[] {
484
1388
  const defects: string[] = [];
485
1389
  const hasTenant = credentials.tokenUrl.includes(PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER);
486
- const filled = credentials.tokenUrl.split(PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER).join('tenant.example');
487
- if (/[{}]/.test(filled)) defects.push(`clientCredentials.tokenUrl '${credentials.tokenUrl}' carries a placeholder other than ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}`);
1390
+ // The deployment's origin forms the WHOLE origin or nothing (#3402): text before it, or anything but a path after it,
1391
+ // would compose a host the operator never named.
1392
+ const onDeploymentOrigin = credentials.tokenUrl.includes(PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER);
1393
+ if (onDeploymentOrigin && !credentials.tokenUrl.startsWith(`${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}/`)) {
1394
+ defects.push(`clientCredentials.tokenUrl carries ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} other than as its whole origin, followed by a path`);
1395
+ }
1396
+ if (onDeploymentOrigin && hasTenant) defects.push(`clientCredentials.tokenUrl carries both ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} and ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}; the token endpoint has one source`);
1397
+ const filled = credentials.tokenUrl
1398
+ .split(PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER).join('tenant.example')
1399
+ .split(PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER).join('https://deployment.example');
1400
+ if (/[{}]/.test(filled)) defects.push(`clientCredentials.tokenUrl '${credentials.tokenUrl}' carries a placeholder other than ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER} and ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}`);
488
1401
  if (hasTenant && credentials.tenantSecretRef === undefined) defects.push(`clientCredentials.tokenUrl carries ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER} and no tenantSecretRef fills it`);
489
1402
  if (!hasTenant && credentials.tenantSecretRef !== undefined) defects.push(`clientCredentials.tenantSecretRef '${credentials.tenantSecretRef}' fills nothing: the token URL carries no ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}`);
490
1403
  const host = /^https:\/\/([^/:?#]+)(?::\d+)?\//.exec(filled)?.[1]?.toLowerCase();
491
1404
  if (host === undefined) defects.push(`clientCredentials.tokenUrl '${credentials.tokenUrl}' is not an https URL with a path`);
492
- if (credentials.tokenHosts.length === 0) defects.push('clientCredentials.tokenHosts admits no host');
493
- for (const tokenHost of credentials.tokenHosts) {
494
- if (!PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(tokenHost.toLowerCase())) defects.push(`clientCredentials.tokenHosts names '${tokenHost}', which is not a DNS name`);
1405
+ if (onDeploymentOrigin) {
1406
+ // The host is the deployment's, admitted where the engine resolves the operations' base URL; a fixed list would be
1407
+ // a second, unchecked statement of it.
1408
+ if (credentials.tokenHosts.length > 0) defects.push(`clientCredentials.tokenHosts names hosts beside ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}; the token host is the deployment's, so declare none`);
1409
+ } else {
1410
+ if (credentials.tokenHosts.length === 0) defects.push('clientCredentials.tokenHosts admits no host');
1411
+ for (const tokenHost of credentials.tokenHosts) {
1412
+ if (!PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(tokenHost.toLowerCase())) defects.push(`clientCredentials.tokenHosts names '${tokenHost}', which is not a DNS name`);
1413
+ }
1414
+ if (host !== undefined && !credentials.tokenHosts.some((tokenHost) => tokenHost.toLowerCase() === host)) {
1415
+ defects.push(`clientCredentials.tokenUrl is on '${host}', which tokenHosts does not admit`);
1416
+ }
1417
+ }
1418
+ if (credentials.scope !== undefined && credentials.scope.trim() === '') defects.push('clientCredentials.scope is empty; omit it to send none');
1419
+ const grantTypes: readonly string[] = Object.values(ProviderClientCredentialsGrantType);
1420
+ if (credentials.grantType !== undefined && !grantTypes.includes(credentials.grantType)) {
1421
+ defects.push(`clientCredentials.grantType ${JSON.stringify(credentials.grantType)} is none of ${grantTypes.join(', ')}`);
1422
+ }
1423
+ // One credential: a secret or a private key (#3402), and the method agrees with which.
1424
+ if ((credentials.clientSecretSecretRef === undefined) === (credentials.privateKeyJwt === undefined)) {
1425
+ defects.push('clientCredentials declares exactly one of clientSecretSecretRef and privateKeyJwt');
495
1426
  }
496
- if (host !== undefined && !credentials.tokenHosts.some((tokenHost) => tokenHost.toLowerCase() === host)) {
497
- defects.push(`clientCredentials.tokenUrl is on '${host}', which tokenHosts does not admit`);
1427
+ const methods: readonly string[] = credentials.privateKeyJwt !== undefined
1428
+ ? [ProviderOAuth2ClientAuthenticationMethod.PRIVATE_KEY_JWT]
1429
+ : [ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_POST, ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_BASIC];
1430
+ if (credentials.tokenEndpointAuthMethod !== undefined && !methods.includes(credentials.tokenEndpointAuthMethod)) {
1431
+ defects.push(`clientCredentials.tokenEndpointAuthMethod ${JSON.stringify(credentials.tokenEndpointAuthMethod)} is none of ${methods.join(', ')} for ${credentials.privateKeyJwt !== undefined ? 'a private key' : 'a client secret'}`);
1432
+ }
1433
+ if (credentials.privateKeyJwt !== undefined) {
1434
+ const { privateKeySecretRef, algorithm, keyIdSecretRef, assertionLifetimeSeconds } = credentials.privateKeyJwt;
1435
+ const algorithms: readonly string[] = Object.values(ProviderClientAssertionSigningAlgorithm);
1436
+ if (privateKeySecretRef.trim() === '') defects.push('clientCredentials.privateKeyJwt.privateKeySecretRef names no slot');
1437
+ if (!algorithms.includes(algorithm)) defects.push(`clientCredentials.privateKeyJwt.algorithm ${JSON.stringify(algorithm)} is none of ${algorithms.join(', ')}`);
1438
+ if (keyIdSecretRef !== undefined && keyIdSecretRef.trim() === '') defects.push('clientCredentials.privateKeyJwt.keyIdSecretRef names no slot');
1439
+ if (assertionLifetimeSeconds !== undefined
1440
+ && !(Number.isInteger(assertionLifetimeSeconds) && assertionLifetimeSeconds > 0 && assertionLifetimeSeconds <= PROVIDER_CLIENT_ASSERTION_MAXIMUM_LIFETIME_SECONDS)) {
1441
+ defects.push(`clientCredentials.privateKeyJwt.assertionLifetimeSeconds is not a whole number of seconds from 1 to ${PROVIDER_CLIENT_ASSERTION_MAXIMUM_LIFETIME_SECONDS}`);
1442
+ }
1443
+ }
1444
+ for (const [name, parameter] of Object.entries(credentials.tokenRequestParameters ?? {})) {
1445
+ if (!/^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(name)) defects.push(`clientCredentials.tokenRequestParameters names '${name}', which is not a parameter name`);
1446
+ if (PROVIDER_CLIENT_CREDENTIALS_RESERVED_PARAMETER_NAMES.includes(name)) {
1447
+ defects.push(`clientCredentials.tokenRequestParameters names '${name}', which the grant itself sends; declare it in its own field`);
1448
+ }
1449
+ const hasValue = typeof parameter.value === 'string';
1450
+ const hasSlot = typeof parameter.secretRef === 'string';
1451
+ if (hasValue === hasSlot) defects.push(`clientCredentials.tokenRequestParameters '${name}' must declare exactly one of value and secretRef`);
1452
+ else if ((parameter.value ?? parameter.secretRef ?? '').trim() === '') defects.push(`clientCredentials.tokenRequestParameters '${name}' is empty`);
498
1453
  }
499
- if (credentials.scope.trim() === '') defects.push('clientCredentials.scope is empty');
500
1454
  for (const [name, fact] of Object.entries(credentials.verifiedAccountFacts ?? {})) {
501
1455
  if (!/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(name)) defects.push(`clientCredentials.verifiedAccountFacts names '${name}', which is not a fact name`);
502
1456
  if (fact.source === ProviderClientCredentialsFactSource.TENANT && credentials.tenantSecretRef === undefined) {
@@ -509,6 +1463,68 @@ export function describeProviderRestClientCredentialsDefects(credentials: Provid
509
1463
  return defects;
510
1464
  }
511
1465
 
1466
+ /**
1467
+ * Why a REST contract's `clientCredentials` sits wrongly beside the contract's other authentication fields, or an empty
1468
+ * list (#2663, #3398). Checked where a provider is composed, beside {@link describeProviderRestClientCredentialsDefects}.
1469
+ *
1470
+ * - beside `requestSigning`: two ways to authenticate one call;
1471
+ * - alone, `apiKey.secretRef` must be the client secret's slot, the one whose absence means "not configured";
1472
+ * - beside `oauth2` the grant serves the APPLICATION's own account only ({@link providerClientCredentialsServesOwnerScope}),
1473
+ * so the module must admit that connection; `apiKey.secretRef` names the exchanged tokens' slot and may not be the
1474
+ * client secret's (a person's token would be read from it); and `verifiedAccountFacts`, which only an organization's
1475
+ * connection records, would record nothing.
1476
+ * - a token URL on {@link PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} (#3402) needs a base URL the
1477
+ * DEPLOYMENT names (`baseUrlHostEnvVarName` or `baseUrlEnvVarName`), and may serve the APPLICATION's connection only:
1478
+ * the deployment's instance is the application's own (its Okta org), so an organization minting there would
1479
+ * authenticate against the application's vendor tenant, never its own.
1480
+ */
1481
+ export function describeProviderRestClientCredentialsPlacementDefects(
1482
+ contract: {
1483
+ readonly clientCredentials?: ProviderRestClientCredentials;
1484
+ readonly oauth2?: unknown;
1485
+ readonly requestSigning?: unknown;
1486
+ readonly apiKey: { readonly secretRef: string };
1487
+ readonly baseUrlHostEnvVarName?: string;
1488
+ readonly baseUrlEnvVarName?: string;
1489
+ },
1490
+ admitsApplicationConnection: boolean,
1491
+ /** Whether the module admits an ORGANIZATION or USER connection. Omitted, `false`. */
1492
+ admitsNonApplicationConnection = false,
1493
+ ): string[] {
1494
+ const credentials = contract.clientCredentials;
1495
+ if (credentials === undefined) return [];
1496
+ const defects: string[] = [];
1497
+ if (contract.requestSigning !== undefined) {
1498
+ defects.push('declares clientCredentials beside requestSigning; a call authenticates one way');
1499
+ }
1500
+ if (credentials.tokenUrl.includes(PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER)) {
1501
+ if (contract.baseUrlHostEnvVarName === undefined && contract.baseUrlEnvVarName === undefined) {
1502
+ defects.push(`clientCredentials.tokenUrl is on ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}, and the contract's base URL is not one the deployment names (baseUrlHostEnvVarName or baseUrlEnvVarName)`);
1503
+ }
1504
+ if (!admitsApplicationConnection) {
1505
+ defects.push(`clientCredentials.tokenUrl is on ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}, which serves the application's own connection only, and the module admits none`);
1506
+ }
1507
+ if (contract.oauth2 === undefined && admitsNonApplicationConnection) {
1508
+ defects.push(`clientCredentials.tokenUrl is on ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}, the application's own vendor instance, and the module admits an organization or user connection that would mint there`);
1509
+ }
1510
+ }
1511
+ const credentialSlot = providerClientCredentialsCredentialSlot(credentials);
1512
+ if (contract.oauth2 === undefined) {
1513
+ if (contract.apiKey.secretRef !== credentialSlot) {
1514
+ defects.push(`apiKey.secretRef '${contract.apiKey.secretRef}' is not the client's credential slot '${credentialSlot}' (its secret or private key); that is the slot whose absence means not configured`);
1515
+ }
1516
+ return defects;
1517
+ }
1518
+ if (!admitsApplicationConnection) defects.push('declares clientCredentials beside oauth2 and admits no APPLICATION connection, the only one that grant serves');
1519
+ if (contract.apiKey.secretRef === credentialSlot) {
1520
+ defects.push(`apiKey.secretRef '${contract.apiKey.secretRef}' is the client-credentials secret or key; beside oauth2 it names the slot of the exchanged access tokens`);
1521
+ }
1522
+ if (credentials.verifiedAccountFacts !== undefined) {
1523
+ defects.push('declares clientCredentials.verifiedAccountFacts beside oauth2; an organization connects through oauth2, so no client-credentials fact is ever recorded');
1524
+ }
1525
+ return defects;
1526
+ }
1527
+
512
1528
  function readDotPath(body: unknown, path: string): unknown {
513
1529
  let current: unknown = body;
514
1530
  for (const segment of path.split('.')) {