@wildo-ai/framework-knowledge 1.1.5 → 1.1.6

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 (835) hide show
  1. package/dist/claude-marketplace/.claude-plugin/marketplace.json +14 -0
  2. package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +8 -0
  3. package/dist/claude-marketplace/plugins/wildo/agents/wildo-deriver.md +41 -0
  4. package/dist/claude-marketplace/plugins/wildo/hooks/hooks.json +18 -0
  5. package/dist/claude-marketplace/plugins/wildo/monitors/monitors.json +8 -0
  6. package/dist/claude-marketplace/plugins/wildo/references/acceptance.md +38 -0
  7. package/dist/{knowledge/skills/journey-run/references/framework-playbook-approval-policy.md → claude-marketplace/plugins/wildo/references/approval-and-failure-policy.md} +10 -8
  8. package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +29 -0
  9. package/dist/claude-marketplace/plugins/wildo/references/creation-state.md +61 -0
  10. package/dist/{knowledge/skills/journey-run → claude-marketplace/plugins/wildo}/references/expert-personas-and-deliberations.md +8 -8
  11. package/dist/claude-marketplace/plugins/wildo/references/runs-judges-and-questions.md +67 -0
  12. package/dist/claude-marketplace/plugins/wildo/skills/accept/SKILL.md +43 -0
  13. package/dist/claude-marketplace/plugins/wildo/skills/answer/SKILL.md +70 -0
  14. package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +38 -0
  15. package/dist/claude-marketplace/plugins/wildo/skills/doctor/SKILL.md +23 -0
  16. package/dist/claude-marketplace/plugins/wildo/skills/next/SKILL.md +39 -0
  17. package/dist/claude-marketplace/plugins/wildo/skills/run/SKILL.md +39 -0
  18. package/dist/claude-marketplace/plugins/wildo/skills/start/SKILL.md +38 -0
  19. package/dist/claude-marketplace/plugins/wildo/skills/status/SKILL.md +38 -0
  20. package/dist/claude-marketplace/plugins/wildo/skills/why/SKILL.md +37 -0
  21. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  22. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  23. package/dist/esm/framework-knowledge.definitions.js +320 -11
  24. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  25. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +1 -1
  26. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -1
  27. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +0 -3
  28. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  29. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts +12 -2
  30. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts.map +1 -1
  31. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js +33 -2
  32. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js.map +1 -1
  33. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +8 -5
  34. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -1
  35. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +55 -10
  36. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
  37. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +1 -1
  38. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
  39. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +1 -6
  40. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
  41. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +1 -1
  42. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -1
  43. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +1 -6
  44. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -1
  45. package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.d.ts +1 -1
  46. package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.d.ts.map +1 -1
  47. package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.js +0 -1
  48. package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.js.map +1 -1
  49. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts +2 -2
  50. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts.map +1 -1
  51. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js +13 -4
  52. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js.map +1 -1
  53. package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.d.ts +10 -3
  54. package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.d.ts.map +1 -1
  55. package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.js +7 -3
  56. package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.js.map +1 -1
  57. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
  58. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +8 -3
  59. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
  60. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts +1 -1
  61. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts.map +1 -1
  62. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js +0 -1
  63. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js.map +1 -1
  64. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +7 -3
  65. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
  66. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +9 -4
  67. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
  68. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts +3 -2
  69. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts.map +1 -1
  70. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js +4 -3
  71. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
  72. package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.d.ts +1 -1
  73. package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.d.ts.map +1 -1
  74. package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.js +1 -3
  75. package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.js.map +1 -1
  76. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +1 -1
  77. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
  78. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +0 -1
  79. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
  80. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts +10 -3
  81. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts.map +1 -1
  82. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js +8 -3
  83. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js.map +1 -1
  84. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts +12 -5
  85. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts.map +1 -1
  86. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.js +33 -5
  87. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.js.map +1 -1
  88. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts +1 -1
  89. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.js +1 -1
  90. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.js.map +1 -1
  91. package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.d.ts +59 -0
  92. package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.d.ts.map +1 -0
  93. package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.js +72 -0
  94. package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.js.map +1 -0
  95. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts +66 -0
  96. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts.map +1 -0
  97. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.js +115 -0
  98. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.js.map +1 -0
  99. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +1 -1
  100. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +1 -1
  101. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
  102. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts +50 -0
  103. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts.map +1 -0
  104. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.js +54 -0
  105. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.js.map +1 -0
  106. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +1 -1
  107. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +1 -1
  108. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
  109. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +1 -1
  110. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +1 -1
  111. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
  112. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +1 -1
  113. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -1
  114. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts +1 -1
  115. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js +1 -1
  116. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js.map +1 -1
  117. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +1 -1
  118. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +1 -1
  119. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -1
  120. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts +1 -1
  121. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js +1 -1
  122. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js.map +1 -1
  123. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +1 -1
  124. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +1 -1
  125. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -1
  126. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts +1 -1
  127. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js +1 -1
  128. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js.map +1 -1
  129. package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts +36 -17
  130. package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts.map +1 -1
  131. package/dist/esm/playbooks/top_down.definition/playbook.definition.js +67 -17
  132. package/dist/esm/playbooks/top_down.definition/playbook.definition.js.map +1 -1
  133. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts +1 -1
  134. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js +1 -1
  135. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js.map +1 -1
  136. package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.d.ts +45 -0
  137. package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.d.ts.map +1 -0
  138. package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.js +46 -0
  139. package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.js.map +1 -0
  140. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js +1 -1
  141. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js.map +1 -1
  142. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js +1 -1
  143. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js.map +1 -1
  144. package/dist/esm/playbooks/top_down.market-research/playbook.definition.js +1 -1
  145. package/dist/esm/playbooks/top_down.market-research/playbook.definition.js.map +1 -1
  146. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
  147. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +0 -1
  148. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
  149. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +1 -1
  150. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +1 -1
  151. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
  152. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +1 -1
  153. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +1 -1
  154. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
  155. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts +1 -1
  156. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js +1 -1
  157. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js.map +1 -1
  158. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +1 -1
  159. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +1 -1
  160. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -1
  161. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +1 -1
  162. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
  163. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +0 -1
  164. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -1
  165. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +1 -1
  166. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
  167. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +11 -3
  168. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
  169. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  170. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  171. package/dist/knowledge/manifest.json +8 -8
  172. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +0 -3
  173. package/dist/knowledge/playbooks/bottom_up.build/method.md +4 -2
  174. package/dist/knowledge/playbooks/bottom_up.build/playbook.json +31 -7
  175. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-protocol.json +1 -1
  176. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-treatment.json +1 -1
  177. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +134 -26
  178. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +7 -4
  179. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +84 -29
  180. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +2 -7
  181. package/dist/knowledge/playbooks/bottom_up.build-scale/method.md +12 -23
  182. package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +2 -7
  183. package/dist/knowledge/playbooks/bottom_up.capability-composition/method.md +12 -14
  184. package/dist/knowledge/playbooks/bottom_up.capability-composition/playbook.json +1 -2
  185. package/dist/knowledge/playbooks/bottom_up.conception/method.md +20 -2
  186. package/dist/knowledge/playbooks/bottom_up.conception/playbook.json +15 -7
  187. package/dist/knowledge/playbooks/bottom_up.documentation-plan/method.md +8 -6
  188. package/dist/knowledge/playbooks/bottom_up.documentation-plan/playbook.json +11 -4
  189. package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +2 -4
  190. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +3 -4
  191. package/dist/knowledge/playbooks/bottom_up.experience-plan/method.md +18 -2
  192. package/dist/knowledge/playbooks/bottom_up.experience-plan/playbook.json +1 -2
  193. package/dist/knowledge/playbooks/bottom_up.foundation/method.md +2 -4
  194. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +8 -5
  195. package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +16 -2
  196. package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +3 -3
  197. package/dist/knowledge/playbooks/bottom_up.maturity-reading/playbook.json +1 -3
  198. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +1 -2
  199. package/dist/knowledge/playbooks/bottom_up.website-plan/method.md +8 -7
  200. package/dist/knowledge/playbooks/bottom_up.website-plan/playbook.json +11 -4
  201. package/dist/knowledge/playbooks/cross_cutting.application-creation/playbook.json +27 -5
  202. package/dist/knowledge/playbooks/cross_cutting.compliance/playbook.json +1 -4
  203. package/dist/knowledge/playbooks/cross_cutting.feature-development/method.md +42 -0
  204. package/dist/knowledge/playbooks/cross_cutting.feature-development/playbook.json +73 -0
  205. package/dist/knowledge/playbooks/cross_cutting.refinement/method.md +46 -0
  206. package/dist/knowledge/playbooks/cross_cutting.refinement/playbook.json +108 -0
  207. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +112 -21
  208. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  209. package/dist/knowledge/playbooks/refinement.document-facts/method.md +7 -2
  210. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +2 -4
  211. package/dist/knowledge/playbooks/refinement.feature-contribution/method.md +48 -0
  212. package/dist/knowledge/playbooks/refinement.feature-contribution/playbook.json +66 -0
  213. package/dist/knowledge/playbooks/refinement.governance-document-candidate/method.md +6 -0
  214. package/dist/knowledge/playbooks/refinement.governance-document-candidate/playbook.json +1 -1
  215. package/dist/knowledge/playbooks/top_down.brand-identity/method.md +0 -4
  216. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +1 -2
  217. package/dist/knowledge/playbooks/top_down.business-model/playbook.json +1 -3
  218. package/dist/knowledge/playbooks/top_down.capability-map/method.md +2 -4
  219. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +1 -2
  220. package/dist/knowledge/playbooks/top_down.compliance-analysis/playbook.json +1 -3
  221. package/dist/knowledge/playbooks/top_down.compliance-conception/method.md +5 -3
  222. package/dist/knowledge/playbooks/top_down.compliance-conception/playbook.json +2 -4
  223. package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/playbook.json +1 -3
  224. package/dist/knowledge/playbooks/top_down.compliance-posture/method.md +0 -4
  225. package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +2 -4
  226. package/dist/knowledge/playbooks/top_down.compliance-research/playbook.json +1 -3
  227. package/dist/knowledge/playbooks/top_down.definition/method.md +7 -4
  228. package/dist/knowledge/playbooks/top_down.definition/playbook.json +52 -7
  229. package/dist/knowledge/playbooks/top_down.expert-personas/method.md +1 -1
  230. package/dist/knowledge/playbooks/top_down.expert-personas/playbook.json +2 -4
  231. package/dist/knowledge/playbooks/top_down.feature-drafts/method.md +72 -0
  232. package/dist/knowledge/playbooks/top_down.feature-drafts/playbook.json +57 -0
  233. package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +0 -1
  234. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +0 -1
  235. package/dist/knowledge/playbooks/top_down.market-research/playbook.json +0 -1
  236. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +2 -4
  237. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +1 -2
  238. package/dist/knowledge/playbooks/top_down.phase-gate/method.md +1 -1
  239. package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +2 -6
  240. package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +17 -1
  241. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +2 -5
  242. package/dist/knowledge/playbooks/top_down.risk-register/playbook.json +1 -3
  243. package/dist/knowledge/playbooks/top_down.scope-roadmap/method.md +15 -7
  244. package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +2 -4
  245. package/dist/knowledge/playbooks/top_down.value-proposition/method.md +2 -4
  246. package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +1 -2
  247. package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +7 -3
  248. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +12 -5
  249. package/dist/knowledge/references/backend.inbound-channels.handler-definition.md +212 -0
  250. package/dist/knowledge/references/backend.inbound-handlers.agents.md +45 -0
  251. package/dist/knowledge/references/backend.inbound-handlers.definition.md +218 -0
  252. package/dist/knowledge/references/build-plan.task-graph.config.md +71 -6
  253. package/dist/knowledge/references/capability-composition.config.md +20 -1
  254. package/dist/knowledge/references/cli.market.generate-command.md +18 -2
  255. package/dist/knowledge/references/engine.client-bundle.allow-list.md +7 -22
  256. package/dist/knowledge/references/engine.saas-technical-doc.provider-component.slot.md +83 -0
  257. package/dist/knowledge/references/example.authorization.service-provider-organization-wide-access.md +12 -0
  258. package/dist/knowledge/references/example.backend.addon-wiring.module.md +5 -0
  259. package/dist/knowledge/references/example.backend.custom-operation.create-postfix.md +7 -3
  260. package/dist/knowledge/references/example.config.app-shell.command-menu-items.md +7 -0
  261. package/dist/knowledge/references/example.config.app-shell.full.md +11 -0
  262. package/dist/knowledge/references/example.config.backend.billing-enable.md +14 -0
  263. package/dist/knowledge/references/example.config.backend.inbound-email.md +14 -0
  264. package/dist/knowledge/references/example.config.backend.required-floors.md +7 -0
  265. package/dist/knowledge/references/example.config.navigation.full.md +45 -2
  266. package/dist/knowledge/references/example.config.provider-usage-pricing.md +36 -0
  267. package/dist/knowledge/references/example.config.provider.backend-scope-billing.md +5 -3
  268. package/dist/knowledge/references/example.config.provider.backend-scope-inbound-email.md +16 -0
  269. package/dist/knowledge/references/example.flows-actors.autonomous-agent.md +23 -0
  270. package/dist/knowledge/references/example.flows-actors.autonomous-agent.reviewed-write.md +36 -0
  271. package/dist/knowledge/references/example.flows-actors.chat-assistant.md +26 -3
  272. package/dist/knowledge/references/example.flows-actors.llm-agent-one-shot.md +1 -1
  273. package/dist/knowledge/references/example.inbound.application-endpoint-handler.md +72 -0
  274. package/dist/knowledge/references/example.inbound.email-channel-handler.md +47 -0
  275. package/dist/knowledge/references/example.inbound.email-to-todo.md +150 -0
  276. package/dist/knowledge/references/example.infra.environment-config.local.md +14 -30
  277. package/dist/knowledge/references/example.layout-3d.own-layout.md +16 -0
  278. package/dist/knowledge/references/example.layout-3d.registration.md +15 -0
  279. package/dist/knowledge/references/example.module.companion-exports.full.md +8 -13
  280. package/dist/knowledge/references/example.module.relationships.discriminator.md +2 -2
  281. package/dist/knowledge/references/example.organizations.serves-as-provider.md +12 -0
  282. package/dist/knowledge/references/example.provider.address-lookup.adapter.md +64 -0
  283. package/dist/knowledge/references/example.provider.backend-module-shape.md +3 -0
  284. package/dist/knowledge/references/example.provider.frontend-app.module.md +9 -0
  285. package/dist/knowledge/references/example.provider.frontend-facet.package-module.md +85 -0
  286. package/dist/knowledge/references/example.provider.frontend-file-picker.contribution.md +14 -13
  287. package/dist/knowledge/references/example.provider.frontend-file-picker.module.md +18 -0
  288. package/dist/knowledge/references/example.provider.operation.backend-typed-client.md +11 -11
  289. package/dist/knowledge/references/example.rate-limit.resource-operation-surface.md +5 -0
  290. package/dist/knowledge/references/example.resource.add-resource.module-factory-map.md +2 -0
  291. package/dist/knowledge/references/example.resource.retention-binding.closure-event.md +21 -0
  292. package/dist/knowledge/references/example.resource.ui-behavior.enum-badge.md +1 -2
  293. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +24 -6
  294. package/dist/knowledge/references/example.resource.ui-behavior.surface-decision.md +36 -25
  295. package/dist/knowledge/references/example.resource.work-unit.declaration.md +13 -0
  296. package/dist/knowledge/references/example.spec.composite-view.workspace.md +0 -12
  297. package/dist/knowledge/references/example.views.app-level.composite-views-config.md +1 -1
  298. package/dist/knowledge/references/example.views.chart-view.resource-owned.md +27 -0
  299. package/dist/knowledge/references/example.views.composite-view.workspace.md +4 -1
  300. package/dist/knowledge/references/example.website.page.manifest.md +30 -0
  301. package/dist/knowledge/references/experience-plan.config.md +11 -4
  302. package/dist/knowledge/references/external-connectors.app.frontend-provider-module.md +20 -0
  303. package/dist/knowledge/references/external-connectors.backend.provider-augmentation.md +75 -0
  304. package/dist/knowledge/references/external-connectors.frontend-provider-component-declaration.md +85 -0
  305. package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +52 -0
  306. package/dist/knowledge/references/external-connectors.models.connection-rate-budgets.md +113 -0
  307. package/dist/knowledge/references/external-connectors.models.file-storage-adapter.md +165 -0
  308. package/dist/knowledge/references/external-connectors.models.oauth2-audiences.md +133 -0
  309. package/dist/knowledge/references/external-connectors.models.oauth2-incremental-consent.md +44 -0
  310. package/dist/knowledge/references/external-connectors.models.rest-operation-contract.md +21 -0
  311. package/dist/knowledge/references/external-connectors.provider-component-load-state.md +45 -0
  312. package/dist/knowledge/references/external-connectors.provider-component-loader-contribution.md +32 -0
  313. package/dist/knowledge/references/external-connectors.provider-component-registry.md +190 -0
  314. package/dist/knowledge/references/external-connectors.techdoc.frontend-provider-module.md +91 -0
  315. package/dist/knowledge/references/external-connectors.website.frontend-provider-module.md +91 -0
  316. package/dist/knowledge/references/integration-plan.config.md +34 -2
  317. package/dist/knowledge/references/market.alternative.config.md +1 -1
  318. package/dist/knowledge/references/market.buying-journey.config.md +1 -1
  319. package/dist/knowledge/references/market.category.config.md +1 -1
  320. package/dist/knowledge/references/market.channel.config.md +1 -1
  321. package/dist/knowledge/references/market.feature-benefit.config.md +1 -1
  322. package/dist/knowledge/references/market.gain.config.md +1 -1
  323. package/dist/knowledge/references/market.icp.config.md +1 -1
  324. package/dist/knowledge/references/market.job.config.md +1 -1
  325. package/dist/knowledge/references/market.message-template.config.md +1 -1
  326. package/dist/knowledge/references/market.objection.config.md +1 -1
  327. package/dist/knowledge/references/market.pain.config.md +1 -1
  328. package/dist/knowledge/references/market.persona.config.md +1 -1
  329. package/dist/knowledge/references/market.positioning.config.md +1 -1
  330. package/dist/knowledge/references/market.proof.config.md +1 -1
  331. package/dist/knowledge/references/market.references.weighted-edges.md +7 -0
  332. package/dist/knowledge/references/market.tone-of-voice.config.md +1 -1
  333. package/dist/knowledge/references/market.trigger.config.md +1 -1
  334. package/dist/knowledge/references/placement-plan.config.md +7 -1
  335. package/dist/knowledge/references/platform.config.backing-services.md +15 -15
  336. package/dist/knowledge/references/platform.config.infra-provider-resolution.md +57 -57
  337. package/dist/knowledge/references/presets.3d.frame-style-overrides.md +134 -0
  338. package/dist/knowledge/references/presets.3d.layout-contract.md +213 -0
  339. package/dist/knowledge/references/presets.3d.register-layout.md +95 -0
  340. package/dist/knowledge/references/presets.models.labelling.sections.md +5 -0
  341. package/dist/knowledge/references/presets.models.shell-region.md +47 -0
  342. package/dist/knowledge/references/requirements.functional-requirement.config.md +8 -0
  343. package/dist/knowledge/references/saas.backend.actor-execution-decision-record.md +41 -0
  344. package/dist/knowledge/references/saas.backend.application-initialization.assembly.md +1 -1
  345. package/dist/knowledge/references/saas.backend.authorization.role-ceiling.md +7 -6
  346. package/dist/knowledge/references/saas.backend.compliance.governed-documents-pdf-template.md +370 -0
  347. package/dist/knowledge/references/saas.backend.custom-operation.transactional-core.md +7 -0
  348. package/dist/knowledge/references/saas.backend.domain-module.md +93 -15
  349. package/dist/knowledge/references/saas.backend.flows-actors.autonomous-agent-declaration.md +66 -0
  350. package/dist/knowledge/references/saas.backend.flows-actors.autonomous-agent-schedule.md +31 -0
  351. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +200 -0
  352. package/dist/knowledge/references/saas.backend.flows-actors.resource-write-tool.md +2 -0
  353. package/dist/knowledge/references/saas.backend.pdf-template.collection-definition.md +73 -0
  354. package/dist/knowledge/references/saas.backend.providers.connection-target-credential-resolution.md +33 -9
  355. package/dist/knowledge/references/saas.backend.submission-challenge.md +118 -0
  356. package/dist/knowledge/references/saas.backend.system-access-service.md +98 -0
  357. package/dist/knowledge/references/saas.backend.system-of-record-action-runner.md +73 -0
  358. package/dist/knowledge/references/saas.config.providers.augmentations.md +61 -0
  359. package/dist/knowledge/references/saas.config.providers.packages.md +59 -0
  360. package/dist/knowledge/references/saas.config.providers.shared-connections.md +84 -0
  361. package/dist/knowledge/references/saas.external-data.admin-endpoints.md +56 -2
  362. package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +2 -2
  363. package/dist/knowledge/references/saas.frontend.app-shell.building-blocks.md +250 -0
  364. package/dist/knowledge/references/saas.frontend.billing-context.md +25 -2
  365. package/dist/knowledge/references/saas.frontend.chart-view.resource-chart-data.md +92 -0
  366. package/dist/knowledge/references/saas.frontend.consent-based-provider-activation.md +22 -0
  367. package/dist/knowledge/references/saas.frontend.form-field-address.lookup-slot.md +74 -0
  368. package/dist/knowledge/references/saas.frontend.linked-conversations-embed.md +60 -0
  369. package/dist/knowledge/references/saas.frontend.navigation.operation-override.md +7 -5
  370. package/dist/knowledge/references/saas.frontend.notifications.publish-badge-count.md +60 -0
  371. package/dist/knowledge/references/saas.frontend.providers.execute-operation.md +17 -2
  372. package/dist/knowledge/references/saas.frontend.related-resource-embeds.md +49 -0
  373. package/dist/knowledge/references/saas.frontend.related-resource-sections.md +8 -1
  374. package/dist/knowledge/references/saas.frontend.resource-layout-templates.md +9 -0
  375. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +100 -5
  376. package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +25 -1
  377. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +61 -0
  378. package/dist/knowledge/references/saas.market.generation-agent.md +0 -1
  379. package/dist/knowledge/references/saas.models.agent-work-capture-settings.md +34 -0
  380. package/dist/knowledge/references/saas.models.agent-work-decision-surface.md +45 -0
  381. package/dist/knowledge/references/saas.models.agent-work-decision-vocabulary.md +107 -0
  382. package/dist/knowledge/references/saas.models.agent-work-output-review.md +36 -0
  383. package/dist/knowledge/references/saas.models.agent-work-override-rate.md +50 -0
  384. package/dist/knowledge/references/saas.models.agent-work-review-config.md +24 -0
  385. package/dist/knowledge/references/saas.models.audit-trails.actor-attribution.md +97 -0
  386. package/dist/knowledge/references/saas.models.audit.trail-config.md +15 -9
  387. package/dist/knowledge/references/saas.models.auth.service-provider-client-authentication.md +169 -0
  388. package/dist/knowledge/references/saas.models.authorization.administrative-continuity-codes.md +8 -0
  389. package/dist/knowledge/references/saas.models.billing.catalog-vocabularies.md +54 -1
  390. package/dist/knowledge/references/saas.models.billing.referral-program.md +47 -0
  391. package/dist/knowledge/references/saas.models.config.organization-types.md +74 -0
  392. package/dist/knowledge/references/saas.models.config.tenant-teardown.md +31 -14
  393. package/dist/knowledge/references/saas.models.conversation-threads.md +242 -0
  394. package/dist/knowledge/references/saas.models.data-mode-read-list.md +4 -4
  395. package/dist/knowledge/references/saas.models.engine-capabilities.md +12 -0
  396. package/dist/knowledge/references/saas.models.engine-capabilities.required-provider-floor.md +5 -1
  397. package/dist/knowledge/references/saas.models.evaluation-dataset-export.md +39 -0
  398. package/dist/knowledge/references/saas.models.evaluation-export-authorization.md +38 -0
  399. package/dist/knowledge/references/saas.models.external-data-pipeline.md +667 -6
  400. package/dist/knowledge/references/saas.models.flows-actors.autonomous-agents-vocabulary.md +98 -0
  401. package/dist/knowledge/references/saas.models.flows-actors.human-decision-vocabulary.md +52 -0
  402. package/dist/knowledge/references/saas.models.flows-actors.review-calendar.md +42 -0
  403. package/dist/knowledge/references/saas.models.flows-actors.review-deadline-vocabulary.md +84 -0
  404. package/dist/knowledge/references/saas.models.flows-actors.review-deadlines-declaration.md +69 -0
  405. package/dist/knowledge/references/saas.models.frontend-provider-public-config-contract.md +72 -0
  406. package/dist/knowledge/references/saas.models.http-api-binding.md +812 -29
  407. package/dist/knowledge/references/saas.models.http-api-binding.rest-write-operations.md +81 -0
  408. package/dist/knowledge/references/saas.models.human-decision-review-marker.md +20 -0
  409. package/dist/knowledge/references/saas.models.inbound-channels.md +277 -0
  410. package/dist/knowledge/references/saas.models.inbound-email-domains.md +101 -0
  411. package/dist/knowledge/references/saas.models.inbound-email.md +111 -0
  412. package/dist/knowledge/references/saas.models.model-cost-accounting-config.md +28 -0
  413. package/dist/knowledge/references/saas.models.model-cost-summary.md +87 -0
  414. package/dist/knowledge/references/saas.models.navigation.layout.md +11 -7
  415. package/dist/knowledge/references/saas.models.navigation.surface-vocabulary.md +32 -23
  416. package/dist/knowledge/references/saas.models.navigation.transition-vocabulary.md +8 -4
  417. package/dist/knowledge/references/saas.models.navigation.zone-declaration.md +22 -20
  418. package/dist/knowledge/references/saas.models.notifications.badge-vocabularies.md +14 -0
  419. package/dist/knowledge/references/saas.models.notifications.targets.md +20 -12
  420. package/dist/knowledge/references/saas.models.notifications.user-notification-definition.md +61 -34
  421. package/dist/knowledge/references/saas.models.organization-unit-narrowing-containment.md +9 -0
  422. package/dist/knowledge/references/saas.models.organizations.service-provider-activity-feed.md +121 -0
  423. package/dist/knowledge/references/saas.models.organizations.service-provider-capability-grants.md +152 -0
  424. package/dist/knowledge/references/saas.models.organizations.service-provider-client-controls.md +49 -0
  425. package/dist/knowledge/references/saas.models.organizations.service-provider-relationships.md +567 -0
  426. package/dist/knowledge/references/saas.models.privacy.legal-holds.md +172 -0
  427. package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +104 -0
  428. package/dist/knowledge/references/saas.models.privacy.retention-binding.md +103 -0
  429. package/dist/knowledge/references/saas.models.privacy.retention-enforcement-record.md +120 -0
  430. package/dist/knowledge/references/saas.models.privacy.retention-schedule.md +147 -0
  431. package/dist/knowledge/references/saas.models.privacy.statutory-retention-ground.md +50 -0
  432. package/dist/knowledge/references/saas.models.privacy.subject-data-recipients.md +388 -0
  433. package/dist/knowledge/references/saas.models.provider-address-lookup-contract.md +139 -0
  434. package/dist/knowledge/references/saas.models.provider-address-lookup-declaration.md +61 -0
  435. package/dist/knowledge/references/saas.models.provider-capabilities.md +34 -0
  436. package/dist/knowledge/references/saas.models.provider-credential-identity.md +67 -0
  437. package/dist/knowledge/references/saas.models.provider-usage-pricing-authority.md +139 -0
  438. package/dist/knowledge/references/saas.models.providers.browser-operation-policy.md +61 -0
  439. package/dist/knowledge/references/saas.models.providers.compliance-choice.md +98 -13
  440. package/dist/knowledge/references/saas.models.providers.scope-reauthorization.md +57 -0
  441. package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +122 -28
  442. package/dist/knowledge/references/saas.models.resource-config.operation-submission-challenge.md +54 -0
  443. package/dist/knowledge/references/saas.models.resource-config.resource-configuration.md +6 -0
  444. package/dist/knowledge/references/saas.models.resource-config.resources-registry.md +8 -0
  445. package/dist/knowledge/references/saas.models.resource-config.retention-policy.md +82 -0
  446. package/dist/knowledge/references/saas.models.system-of-record-actions.md +226 -0
  447. package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +461 -0
  448. package/dist/knowledge/references/saas.models.systems-of-record.facet-augmentation.md +63 -0
  449. package/dist/knowledge/references/saas.models.systems-of-record.md +242 -7
  450. package/dist/knowledge/references/saas.models.work-attribution-vocabulary.md +109 -0
  451. package/dist/knowledge/references/saas.models.work-unit-ref.md +28 -0
  452. package/dist/knowledge/references/saas.public-runtime.contract.md +75 -7
  453. package/dist/knowledge/references/saas.specifications.assurance-document-blueprint.contract.md +20 -0
  454. package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +106 -13
  455. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.catalog-spec-shared.md +14 -13
  456. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.discriminated-union.md +36 -14
  457. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-aggregate-offer.md +4 -3
  458. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-product.md +4 -4
  459. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-software-application.md +71 -0
  460. package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +6 -4
  461. package/dist/knowledge/references/saas.specifications.compliance.retention-enforcement-state.md +32 -0
  462. package/dist/knowledge/references/saas.specifications.governed-document-release.contract.md +14 -2
  463. package/dist/knowledge/references/saas.specifications.processor-register.md +77 -0
  464. package/dist/knowledge/references/saas.specifications.recipient-disclosures.md +71 -0
  465. package/dist/knowledge/references/saas.specifications.recipient-population.md +549 -0
  466. package/dist/knowledge/references/saas.specifications.resource-operation-spec.md +112 -45
  467. package/dist/knowledge/references/saas.specifications.resource-spec-config.md +13 -1
  468. package/dist/knowledge/references/saas.specifications.resource-spec-factory.md +17 -0
  469. package/dist/knowledge/references/saas.specifications.resource-spec-frontend-prose.md +16 -0
  470. package/dist/knowledge/references/saas.specifications.subject-data-recipients.md +98 -0
  471. package/dist/knowledge/references/saas.website.astro.bridge.md +32 -9
  472. package/dist/knowledge/references/saas.website.astro.head-renderer.md +1 -1
  473. package/dist/knowledge/references/saas.website.astro.label-loader.md +7 -4
  474. package/dist/knowledge/references/saas.website.astro.robots-renderer.md +15 -15
  475. package/dist/knowledge/references/saas.website.astro.site-context.md +5 -2
  476. package/dist/knowledge/references/saas.website.blog.bridge.md +17 -4
  477. package/dist/knowledge/references/saas.website.config.pricing-catalog-loader.md +61 -0
  478. package/dist/knowledge/references/saas.website.config.site-context-loader.md +154 -0
  479. package/dist/knowledge/references/saas.website.consent.banner.md +10 -10
  480. package/dist/knowledge/references/saas.website.design-tokens.colors.md +7 -4
  481. package/dist/knowledge/references/saas.website.design-tokens.radius.md +1 -1
  482. package/dist/knowledge/references/saas.website.factories.define-section.md +3 -3
  483. package/dist/knowledge/references/saas.website.page-layout.component.md +5 -2
  484. package/dist/knowledge/references/saas.website.pricing-offer-structured-data.md +140 -0
  485. package/dist/knowledge/references/saas.website.provider-component.slot.md +99 -0
  486. package/dist/knowledge/references/saas.website.root-config.schema.md +6 -6
  487. package/dist/knowledge/references/saas.website.runtime.context.md +23 -4
  488. package/dist/knowledge/references/saas.website.sections.definition-schema.md +14 -7
  489. package/dist/knowledge/references/saas.website.seo.robots-config.md +4 -3
  490. package/dist/knowledge/references/saas.website.structured-data.payload-shape.md +7 -5
  491. package/dist/knowledge/references/saas.website.submission-challenge.md +77 -0
  492. package/dist/knowledge/references/saas.website.use-pricing-catalog.hook.md +36 -0
  493. package/dist/knowledge/references/saas.website.use-runtime.hook.md +3 -2
  494. package/dist/knowledge/references/website-plan.config.md +39 -6
  495. package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +2 -1
  496. package/dist/knowledge/references/zod.decorators.display-edit-modes.md +21 -0
  497. package/dist/knowledge/references/zod.decorators.enums.frontend-handling.md +1 -2
  498. package/dist/knowledge/references/zod.decorators.file-schema.md +11 -10
  499. package/dist/knowledge/references/zod.decorators.file-vocabularies.md +7 -4
  500. package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +8 -2
  501. package/dist/knowledge/references/zod.decorators.shared-structural-params.md +5 -1
  502. package/dist/knowledge/references/zod.decorators.structural-lifecycle-params.md +5 -1
  503. package/dist/knowledge/references/zod.factories.address.md +7 -7
  504. package/dist/knowledge/references/zod.factories.code.md +2 -2
  505. package/dist/knowledge/references/zod.factories.duration.md +4 -4
  506. package/dist/knowledge/references/zod.factories.money.md +3 -3
  507. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  508. package/dist/knowledge/registries/framework-topics.json +1238 -54
  509. package/dist/knowledge/registries/playbooks.json +81 -109
  510. package/dist/knowledge/registries/source-tags.json +3191 -1126
  511. package/dist/knowledge/rules/live-context-door.md +29 -0
  512. package/dist/knowledge/skills/INDEX.md +27 -24
  513. package/dist/knowledge/skills/agent-work-review/SKILL.md +141 -0
  514. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-capture-settings-api.md +38 -0
  515. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-output-review-api.md +40 -0
  516. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-override-rate-api.md +54 -0
  517. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-review-config-api.md +28 -0
  518. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-review-marker-api.md +108 -0
  519. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-vocabulary-api.md +111 -0
  520. package/dist/knowledge/skills/agent-work-review/references/framework-evaluation-dataset-export-api.md +43 -0
  521. package/dist/knowledge/skills/agent-work-review/references/framework-evaluation-export-authorization-api.md +42 -0
  522. package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +31 -0
  523. package/dist/knowledge/skills/application-database-migrations/SKILL.md +1 -0
  524. package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +1 -0
  525. package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-unit-narrowing-declaration-api.md +9 -0
  526. package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +6 -0
  527. package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +94 -16
  528. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +21 -8
  529. package/dist/knowledge/skills/backend-custom-operation/references/framework-transactional-core-api.md +7 -0
  530. package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +13 -5
  531. package/dist/knowledge/skills/compliance-document-authoring/SKILL.md +30 -6
  532. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +160 -32
  533. package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +20 -0
  534. package/dist/knowledge/skills/compliance-document-authoring/references/framework-governed-document-after-drafting.md +14 -2
  535. package/dist/knowledge/skills/compliance-document-authoring/references/framework-processor-register-authoring.md +88 -0
  536. package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +112 -14
  537. package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +209 -0
  538. package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-population.md +577 -0
  539. package/dist/knowledge/skills/compliance-document-authoring/references/framework-subject-data-recipients.md +549 -0
  540. package/dist/knowledge/skills/config-app-shell/SKILL.md +21 -0
  541. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +2 -2
  542. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-building-blocks-api.md +276 -0
  543. package/dist/knowledge/skills/config-app-shell/references/framework-shell-region-markers-api.md +66 -0
  544. package/dist/knowledge/skills/config-design-system/SKILL.md +1 -0
  545. package/dist/knowledge/skills/config-navigation/SKILL.md +114 -16
  546. package/dist/knowledge/skills/config-navigation/references/choosing-a-navigation-shape.md +314 -0
  547. package/dist/knowledge/skills/config-navigation/references/framework-navigation-layout-api.md +11 -7
  548. package/dist/knowledge/skills/config-navigation/references/framework-navigation-operation-override-api.md +29 -5
  549. package/dist/knowledge/skills/config-navigation/references/framework-navigation-vocabulary-api.md +40 -27
  550. package/dist/knowledge/skills/config-navigation/references/framework-navigation-zone-declaration-api.md +22 -20
  551. package/dist/knowledge/skills/config-navigation/references/how-navigation-resolves.md +112 -5
  552. package/dist/knowledge/skills/config-navigation/references/navigation-configuration-map.md +10 -10
  553. package/dist/knowledge/skills/config-navigation/references/navigation-zones.md +1 -1
  554. package/dist/knowledge/skills/config-saas/SKILL.md +3 -1
  555. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +7 -0
  556. package/dist/knowledge/skills/config-saas/references/framework-audit-trail-config-api.md +21 -11
  557. package/dist/knowledge/skills/config-saas/references/framework-capability-resolution-api.md +5 -1
  558. package/dist/knowledge/skills/config-saas/references/framework-connection-target-credentials.md +59 -9
  559. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +46 -0
  560. package/dist/knowledge/skills/config-saas/references/framework-systems-of-record-api.md +251 -12
  561. package/dist/knowledge/skills/config-saas-backend/SKILL.md +8 -0
  562. package/dist/knowledge/skills/config-saas-backend/references/framework-organization-types-api.md +81 -0
  563. package/dist/knowledge/skills/config-saas-backend/references/framework-tenant-teardown-api.md +37 -15
  564. package/dist/knowledge/skills/configure-billing/SKILL.md +64 -24
  565. package/dist/knowledge/skills/configure-billing/references/config-chain-and-failure-map.md +35 -2
  566. package/dist/knowledge/skills/configure-billing/references/example-backend-billing-enable-block.md +14 -0
  567. package/dist/knowledge/skills/configure-billing/references/example-backend-provider-module-shape.md +3 -0
  568. package/dist/knowledge/skills/configure-billing/references/framework-billing-frontend-api.md +25 -2
  569. package/dist/knowledge/skills/configure-billing/references/framework-product-catalog-api.md +73 -1
  570. package/dist/knowledge/skills/configure-billing/references/framework-referral-program.md +110 -0
  571. package/dist/knowledge/skills/configure-billing/references/framework-subscription-behavior-policy.md +27 -12
  572. package/dist/knowledge/skills/configure-coding-agent/SKILL.md +11 -2
  573. package/dist/knowledge/skills/configure-coding-agent/references/agent-selection.md +26 -2
  574. package/dist/knowledge/skills/email-add-template/SKILL.md +61 -24
  575. package/dist/knowledge/skills/email-add-template/references/framework-email-attachments-and-limits.md +5 -2
  576. package/dist/knowledge/skills/email-definition-wiring/SKILL.md +1 -0
  577. package/dist/knowledge/skills/email-labels-authoring/SKILL.md +2 -1
  578. package/dist/knowledge/skills/email-template-authoring/SKILL.md +1 -0
  579. package/dist/knowledge/skills/engine-component-registration/SKILL.md +1 -0
  580. package/dist/knowledge/skills/engine-product-definitions/SKILL.md +6 -0
  581. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +27 -3
  582. package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +180 -0
  583. package/dist/knowledge/skills/flows-actors-autonomous-agents/references/binding-and-review.md +56 -0
  584. package/dist/knowledge/skills/flows-actors-autonomous-agents/references/framework-autonomous-agent-api.md +208 -0
  585. package/dist/knowledge/skills/flows-actors-autonomous-agents/references/framework-inbound-agents-api.md +51 -0
  586. package/dist/knowledge/skills/flows-actors-autonomous-agents/references/tool-posture.md +27 -0
  587. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +31 -4
  588. package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +26 -3
  589. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-audit-agent-attribution-api.md +148 -0
  590. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-decision-deadlines-api.md +287 -0
  591. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +202 -0
  592. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +93 -15
  593. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-tool-dispatch-obligations-api.md +96 -11
  594. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +2 -1
  595. package/dist/knowledge/skills/frontend-cdn-publish/SKILL.md +1 -0
  596. package/dist/knowledge/skills/frontend-component-catalog/SKILL.md +1 -0
  597. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +2 -2
  598. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +14 -9
  599. package/dist/knowledge/skills/guidance-onboarding-authoring/SKILL.md +1 -0
  600. package/dist/knowledge/skills/i18n-label-generation/SKILL.md +1 -0
  601. package/dist/knowledge/skills/i18n-label-generation/references/framework-labelling-sections-api.md +5 -0
  602. package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +11 -9
  603. package/dist/knowledge/skills/i18n-rerun-pipeline/references/framework-labelling-sections-api.md +5 -0
  604. package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +8 -1
  605. package/dist/knowledge/skills/i18n-translation-rerun/references/framework-labelling-sections-api.md +5 -0
  606. package/dist/knowledge/skills/i18n-translation-rerun/references/translation-workflow.md +5 -0
  607. package/dist/knowledge/skills/inbound-channels/SKILL.md +301 -0
  608. package/dist/knowledge/skills/inbound-channels/references/email-channel.md +133 -0
  609. package/dist/knowledge/skills/inbound-channels/references/framework-inbound-channel-api.md +800 -0
  610. package/dist/knowledge/skills/inbound-channels/references/framework-inbound-email-api.md +222 -0
  611. package/dist/knowledge/skills/inbound-channels/references/framework-inbound-handler-api.md +231 -0
  612. package/dist/knowledge/skills/inbound-channels/references/inbound-delivery-lifecycle.md +135 -0
  613. package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +297 -0
  614. package/dist/knowledge/skills/infra-environment-config/SKILL.md +150 -44
  615. package/dist/knowledge/skills/infra-environment-config/references/framework-backing-services-api.md +83 -74
  616. package/dist/knowledge/skills/layout-3d-adoption/SKILL.md +176 -0
  617. package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-frame-style-overrides-api.md +141 -0
  618. package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-layout-contract-api.md +223 -0
  619. package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-layout-registration-api.md +103 -0
  620. package/dist/knowledge/skills/layout-3d-adoption/references/framework-shell-building-blocks-api.md +256 -0
  621. package/dist/knowledge/skills/layout-3d-adoption/references/framework-shell-region-marker-api.md +52 -0
  622. package/dist/knowledge/skills/layout-3d-adoption/references/layouts-and-transitions.md +29 -0
  623. package/dist/knowledge/skills/layout-3d-adoption/references/manual-adoption-and-removal.md +25 -0
  624. package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +32 -1
  625. package/dist/knowledge/skills/local-environment-bootstrap/references/local-environment-troubleshooting.md +2 -1
  626. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +36 -4
  627. package/dist/knowledge/skills/market-add-feature-benefit/SKILL.md +2 -1
  628. package/dist/knowledge/skills/market-add-feature-benefit/references/framework-feature-benefit-api.md +1 -1
  629. package/dist/knowledge/skills/market-alternatives/SKILL.md +3 -2
  630. package/dist/knowledge/skills/market-authoring-overview/SKILL.md +1 -0
  631. package/dist/knowledge/skills/market-authoring-overview/references/framework-market-references-api.md +7 -0
  632. package/dist/knowledge/skills/market-category/SKILL.md +2 -1
  633. package/dist/knowledge/skills/market-channels/SKILL.md +2 -1
  634. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +7 -4
  635. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +6 -4
  636. package/dist/knowledge/skills/market-generation-cli/SKILL.md +28 -13
  637. package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +18 -3
  638. package/dist/knowledge/skills/market-icp/SKILL.md +2 -1
  639. package/dist/knowledge/skills/market-jobs-pains-gains/SKILL.md +4 -3
  640. package/dist/knowledge/skills/market-message-templates-authoring/SKILL.md +2 -1
  641. package/dist/knowledge/skills/market-message-templates-authoring/references/framework-message-template-api.md +1 -1
  642. package/dist/knowledge/skills/market-persona/SKILL.md +2 -1
  643. package/dist/knowledge/skills/market-positioning-authoring/SKILL.md +2 -1
  644. package/dist/knowledge/skills/market-positioning-authoring/references/framework-positioning-api.md +1 -1
  645. package/dist/knowledge/skills/market-proof-and-objection/SKILL.md +3 -2
  646. package/dist/knowledge/skills/market-scoring-interpretation/SKILL.md +1 -0
  647. package/dist/knowledge/skills/market-snapshot-validation/SKILL.md +1 -0
  648. package/dist/knowledge/skills/market-tone-of-voice/SKILL.md +2 -1
  649. package/dist/knowledge/skills/market-triggers-and-journey/SKILL.md +3 -2
  650. package/dist/knowledge/skills/milestones-and-celebrations/SKILL.md +1 -0
  651. package/dist/knowledge/skills/minion-authoring/SKILL.md +5 -1
  652. package/dist/knowledge/skills/model-cost-attribution/SKILL.md +143 -0
  653. package/dist/knowledge/skills/model-cost-attribution/references/framework-model-cost-pricing-api.md +211 -0
  654. package/dist/knowledge/skills/model-cost-attribution/references/framework-model-cost-summary-api.md +95 -0
  655. package/dist/knowledge/skills/model-cost-attribution/references/framework-work-attribution-api.md +117 -0
  656. package/dist/knowledge/skills/model-cost-attribution/references/framework-work-unit-api.md +677 -0
  657. package/dist/knowledge/skills/module-companion-exports/SKILL.md +17 -16
  658. package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +6 -4
  659. package/dist/knowledge/skills/module-registration/SKILL.md +2 -1
  660. package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +93 -15
  661. package/dist/knowledge/skills/module-registration/references/framework-notification-badges-api.md +86 -1
  662. package/dist/knowledge/skills/module-relationships/SKILL.md +3 -2
  663. package/dist/knowledge/skills/pdf-template-authoring/SKILL.md +34 -2
  664. package/dist/knowledge/skills/pdf-template-authoring/references/framework-pdf-collection-template-api.md +447 -0
  665. package/dist/knowledge/skills/provider-address-lookup/SKILL.md +207 -0
  666. package/dist/knowledge/skills/provider-address-lookup/references/framework-address-field-lookup-slot-api.md +82 -0
  667. package/dist/knowledge/skills/provider-address-lookup/references/framework-address-lookup-contract-api.md +214 -0
  668. package/dist/knowledge/skills/provider-address-lookup/references/framework-browser-operation-policy-api.md +143 -0
  669. package/dist/knowledge/skills/provider-address-lookup/references/google-places-setup.md +73 -0
  670. package/dist/knowledge/skills/provider-backend-package/SKILL.md +272 -33
  671. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-augmentation-api.md +227 -0
  672. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-credential-identity-api.md +101 -0
  673. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-file-storage-adapter-api.md +245 -0
  674. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-incremental-consent-api.md +88 -0
  675. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-package-allow-list-api.md +111 -0
  676. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-shared-connection-api.md +309 -0
  677. package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +132 -23
  678. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +399 -0
  679. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-module-api.md +29 -0
  680. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-public-config-api.md +115 -0
  681. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-provider-component-registry-api.md +386 -0
  682. package/dist/knowledge/skills/provider-frontend-module/SKILL.md +258 -0
  683. package/dist/knowledge/skills/provider-frontend-module/references/framework-frontend-facet-contracts-api.md +463 -0
  684. package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +61 -0
  685. package/dist/knowledge/skills/provider-operation-calls/SKILL.md +75 -24
  686. package/dist/knowledge/skills/provider-operation-calls/references/browser-door-answers.md +3 -3
  687. package/dist/knowledge/skills/provider-operation-calls/references/framework-browser-operation-policy-api.md +61 -0
  688. package/dist/knowledge/skills/provider-operation-calls/references/framework-connection-rate-budgets-api.md +176 -0
  689. package/dist/knowledge/skills/provider-operation-calls/references/framework-frontend-execute-operation-api.md +17 -2
  690. package/dist/knowledge/skills/provider-operation-calls/references/framework-provider-operation-executor-api.md +15 -0
  691. package/dist/knowledge/skills/provider-operation-calls/references/framework-provider-scope-reauthorization-api.md +127 -0
  692. package/dist/knowledge/skills/provider-operation-calls/references/framework-rest-operation-contract-api.md +25 -0
  693. package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +6 -0
  694. package/dist/knowledge/skills/resource-add-field/SKILL.md +1 -0
  695. package/dist/knowledge/skills/resource-add-field/examples/add-priority-field-to-todos.example.md +1 -2
  696. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +105 -6
  697. package/dist/knowledge/skills/resource-add-module/SKILL.md +1 -0
  698. package/dist/knowledge/skills/resource-add-module/references/framework-composition-scenarios-api.md +2 -1
  699. package/dist/knowledge/skills/resource-add-resource/SKILL.md +3 -0
  700. package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +124 -30
  701. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +1 -0
  702. package/dist/knowledge/skills/resource-config-wiring/references/framework-administrative-continuity-codes-api.md +8 -0
  703. package/dist/knowledge/skills/resource-config-wiring/references/framework-authority-audit-interpretation.md +9 -0
  704. package/dist/knowledge/skills/resource-config-wiring/references/framework-collection-operation-declarations.md +17 -1
  705. package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +124 -30
  706. package/dist/knowledge/skills/resource-config-wiring/references/framework-role-ceiling-api.md +7 -6
  707. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +142 -34
  708. package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +98 -0
  709. package/dist/knowledge/skills/resource-config-wiring/references/framework-user-notifications-api.md +86 -52
  710. package/dist/knowledge/skills/resource-custom-view/SKILL.md +1 -0
  711. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +100 -5
  712. package/dist/knowledge/skills/resource-external-data/SKILL.md +1026 -28
  713. package/dist/knowledge/skills/resource-external-data/references/declared-expressions.md +144 -0
  714. package/dist/knowledge/skills/resource-external-data/references/erasure-suppression.md +68 -0
  715. package/dist/knowledge/skills/resource-external-data/references/facet-augmentations.md +154 -0
  716. package/dist/knowledge/skills/resource-external-data/references/framework-external-data-pipeline-api.md +686 -11
  717. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +904 -31
  718. package/dist/knowledge/skills/resource-external-data/references/framework-pipeline-admin-endpoints-api.md +166 -6
  719. package/dist/knowledge/skills/resource-external-data/references/incremental-extraction.md +152 -0
  720. package/dist/knowledge/skills/resource-external-data/references/odata-v2-sources.md +60 -0
  721. package/dist/knowledge/skills/resource-external-data/references/outbound-pipelines.md +179 -0
  722. package/dist/knowledge/skills/resource-external-data/references/pipeline-destination-schema.md +1 -1
  723. package/dist/knowledge/skills/resource-external-data/references/provenance-cue.md +63 -0
  724. package/dist/knowledge/skills/resource-external-data/references/rate-budgets-and-pacing.md +122 -0
  725. package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +745 -0
  726. package/dist/knowledge/skills/resource-external-data/references/remote-references.md +85 -0
  727. package/dist/knowledge/skills/resource-external-data/references/rest-keyset-sources.md +85 -0
  728. package/dist/knowledge/skills/resource-external-data/references/system-of-record-actions.md +442 -0
  729. package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +1 -0
  730. package/dist/knowledge/skills/resource-rag-source-fields/SKILL.md +1 -0
  731. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +12 -0
  732. package/dist/knowledge/skills/resource-retention-binding/SKILL.md +186 -0
  733. package/dist/knowledge/skills/resource-retention-binding/references/framework-legal-holds-api.md +200 -0
  734. package/dist/knowledge/skills/resource-retention-binding/references/framework-retention-binding-api.md +111 -0
  735. package/dist/knowledge/skills/resource-retention-binding/references/framework-retention-enforcement-records-api.md +173 -0
  736. package/dist/knowledge/skills/resource-retention-binding/references/framework-retention-schedule-api.md +155 -0
  737. package/dist/knowledge/skills/resource-retention-binding/references/framework-statutory-retention-api.md +139 -0
  738. package/dist/knowledge/skills/resource-retention-binding/references/start-point-decisions.md +55 -0
  739. package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +2 -2
  740. package/dist/knowledge/skills/resource-schema-authoring/examples/add-enum-field-with-ui.example.md +1 -2
  741. package/dist/knowledge/skills/resource-schema-authoring/references/field-type-selection.md +3 -1
  742. package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +2 -1
  743. package/dist/knowledge/skills/resource-schema-authoring/references/framework-erasure-scrub-treatments-api.md +28 -0
  744. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +5 -1
  745. package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +34 -30
  746. package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +5 -1
  747. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +101 -42
  748. package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +21 -0
  749. package/dist/knowledge/skills/resource-ui-behavior/references/framework-enum-frontend-handling-api.md +1 -2
  750. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +125 -6
  751. package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +8 -2
  752. package/dist/knowledge/skills/resource-ui-behavior/references/framework-related-resource-embeds-api.md +57 -1
  753. package/dist/knowledge/skills/resource-ui-behavior/references/framework-resource-layout-templates-api.md +61 -1
  754. package/dist/knowledge/skills/resource-ui-behavior/references/surface-decisions.md +110 -9
  755. package/dist/knowledge/skills/seeding-authoring/SKILL.md +1 -0
  756. package/dist/knowledge/skills/seeding-operations/SKILL.md +1 -0
  757. package/dist/knowledge/skills/service-provider-relationships/SKILL.md +455 -0
  758. package/dist/knowledge/skills/service-provider-relationships/references/framework-organization-types-api.md +270 -0
  759. package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-activity-feed-api.md +129 -0
  760. package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-capability-grants-api.md +161 -0
  761. package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-client-authentication-api.md +224 -0
  762. package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-relationships-api.md +576 -0
  763. package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +1 -0
  764. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +61 -0
  765. package/dist/knowledge/skills/spec-catalog-authoring/SKILL.md +43 -37
  766. package/dist/knowledge/skills/spec-catalog-authoring/references/catalog-spec-pattern-overview.md +15 -14
  767. package/dist/knowledge/skills/spec-companion-exports/SKILL.md +14 -16
  768. package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +6 -4
  769. package/dist/knowledge/skills/spec-component-update/SKILL.md +1 -0
  770. package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +20 -21
  771. package/dist/knowledge/skills/spec-family-update/SKILL.md +1 -0
  772. package/dist/knowledge/skills/spec-feature-update/SKILL.md +1 -0
  773. package/dist/knowledge/skills/spec-resource-update/SKILL.md +13 -0
  774. package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +158 -46
  775. package/dist/knowledge/skills/spec-update-after-change/SKILL.md +1 -0
  776. package/dist/knowledge/skills/spec-update-after-change/references/framework-spec-factory-api.md +17 -0
  777. package/dist/knowledge/skills/views-add-composite-view/SKILL.md +5 -1
  778. package/dist/knowledge/skills/views-add-custom-view/SKILL.md +1 -0
  779. package/dist/knowledge/skills/views-app-level/SKILL.md +2 -1
  780. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +43 -1
  781. package/dist/knowledge/skills/views-chart-authoring/references/framework-resource-chart-data-api.md +102 -0
  782. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +5 -1
  783. package/dist/knowledge/skills/views-composite-authoring/references/composite-embedding-checklist.md +3 -2
  784. package/dist/knowledge/skills/views-execution-authoring/SKILL.md +1 -0
  785. package/dist/knowledge/skills/website-anonymous-session/SKILL.md +29 -6
  786. package/dist/knowledge/skills/website-blog-authoring/SKILL.md +3 -2
  787. package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +17 -4
  788. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +23 -28
  789. package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +7 -22
  790. package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +167 -20
  791. package/dist/knowledge/skills/website-factory-advanced/SKILL.md +4 -3
  792. package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +63 -6
  793. package/dist/knowledge/skills/website-inbound-contact-forms/references/framework-submission-challenge-api.md +275 -0
  794. package/dist/knowledge/skills/website-label-pack/SKILL.md +13 -5
  795. package/dist/knowledge/skills/website-layout-overrides/SKILL.md +6 -2
  796. package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +11 -2
  797. package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +2 -1
  798. package/dist/knowledge/skills/website-page-authoring/SKILL.md +117 -33
  799. package/dist/knowledge/skills/website-page-authoring/references/framework-site-context-loader-api.md +164 -0
  800. package/dist/knowledge/skills/website-page-variants/SKILL.md +1 -0
  801. package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +1 -0
  802. package/dist/knowledge/skills/website-section-contact/SKILL.md +65 -36
  803. package/dist/knowledge/skills/website-section-contact/references/define-website-section-api.md +19 -11
  804. package/dist/knowledge/skills/website-section-cta/SKILL.md +32 -22
  805. package/dist/knowledge/skills/website-section-cta/references/define-website-section-api.md +19 -11
  806. package/dist/knowledge/skills/website-section-faq/SKILL.md +99 -63
  807. package/dist/knowledge/skills/website-section-faq/references/define-website-section-api.md +19 -11
  808. package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +27 -18
  809. package/dist/knowledge/skills/website-section-feature-benefit-summary/references/define-website-section-api.md +19 -11
  810. package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +33 -22
  811. package/dist/knowledge/skills/website-section-feature-detail/references/define-website-section-api.md +19 -11
  812. package/dist/knowledge/skills/website-section-footer-cta/SKILL.md +31 -20
  813. package/dist/knowledge/skills/website-section-footer-cta/references/define-website-section-api.md +19 -11
  814. package/dist/knowledge/skills/website-section-hero/SKILL.md +65 -44
  815. package/dist/knowledge/skills/website-section-hero/references/define-website-section-api.md +19 -11
  816. package/dist/knowledge/skills/website-section-pricing/SKILL.md +217 -200
  817. package/dist/knowledge/skills/website-section-pricing/references/define-website-section-api.md +19 -11
  818. package/dist/knowledge/skills/website-section-pricing/references/framework-pricing-catalog-api.md +248 -0
  819. package/dist/knowledge/skills/website-section-social-proof/SKILL.md +45 -34
  820. package/dist/knowledge/skills/website-section-social-proof/references/define-website-section-api.md +19 -11
  821. package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +8 -3
  822. package/dist/knowledge/skills/website-seo-aeo-geo/references/aeo-api.md +64 -34
  823. package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +30 -25
  824. package/dist/knowledge/skills/worker-authoring/SKILL.md +1 -0
  825. package/dist/knowledge/topic-index.json +5887 -1695
  826. package/dist/tsconfig.build.tsbuildinfo +1 -1
  827. package/dist/tsconfig.tsbuildinfo +1 -1
  828. package/package.json +4 -4
  829. package/dist/knowledge/skills/journey-approve/SKILL.md +0 -63
  830. package/dist/knowledge/skills/journey-bootstrap-scope/SKILL.md +0 -77
  831. package/dist/knowledge/skills/journey-next/SKILL.md +0 -82
  832. package/dist/knowledge/skills/journey-report/SKILL.md +0 -56
  833. package/dist/knowledge/skills/journey-run/SKILL.md +0 -140
  834. package/dist/knowledge/skills/journey-status/SKILL.md +0 -60
  835. /package/dist/{knowledge/skills/journey-approve → claude-marketplace/plugins/wildo}/references/specification-family-map.md +0 -0
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: resource-external-data
3
- description: Bring data that lives in another system — an enterprise Odoo, an SAP OData service, a REST API — into the application, either as a read-through virtual resource or as a synced pipeline into an ordinary local resource. Use when the user says "read our customers from Odoo", "sync suppliers from SAP", "connect to our ERP", "pull data from an external API", "mirror the CRM contacts", "our products live in another system", "show data we do not own", "keep a local copy of the supplier list", or asks whether an integration should copy data or read it live.
3
+ description: Bring data that lives in another system — an enterprise Odoo, an SAP OData service, a REST API — into the application, either as a read-through virtual resource or as a synced pipeline into an ordinary local resource. Use when the user says "read our customers from Odoo", "sync suppliers from SAP", "connect to our ERP", "pull data from an external API", "mirror the CRM contacts", "our products live in another system", "show data we do not own", "keep a local copy of the supplier list", or asks whether an integration should copy data or read it live. Also when a row must be created, updated or deleted in that system from the application ("create the partner in Odoo", "write back to our ERP"), or when records the application creates must be sent to it ("send our new leads to Odoo", "push the requests we capture into the ERP").
4
+ user-invocable: false
4
5
  ---
5
6
 
6
7
  # External Data — Workflow
@@ -55,8 +56,10 @@ run.
55
56
 
56
57
  - **The application owns the data** — that is an ordinary resource; use `resource-add-resource`.
57
58
  - **You are adding a provider or credential**, not consuming data — that is provider configuration.
58
- - **You need to PUSH data outward.** Both lanes are inbound-only today. Say so plainly rather than
59
- improvising a write path; the declaration reserves the direction, but nothing implements it.
59
+ - **The same rows must be edited on BOTH sides.** A pipeline runs one direction: INBOUND copies the
60
+ system of record's rows in, OUTBOUND sends the application's own rows out (see "When the application
61
+ is the source" below). A row changed on both sides needs a conflict policy, which is not built — say
62
+ so plainly rather than declaring two pipelines over one resource.
60
63
 
61
64
  ## Workflow
62
65
 
@@ -83,8 +86,10 @@ Both lanes name a `system`: an instance you declare under `systemsOfRecord` in
83
86
  `wildo.saas.config.ts`. An instance is a deployment — *your* company's Odoo, *your* SAP tenant — and
84
87
  it names a **vendor**.
85
88
 
86
- The vendor is not a label. It selects a **facet**: the catalogue's description of what that vendor
87
- is, as a system of record. The facet decides four things you therefore do not:
89
+ The vendor is not a label. It selects a **facet**: the systems-of-record library's description of what
90
+ that vendor is, as a system of record. The library is `@wildo-ai/systems-of-record`, an opt-in package
91
+ `wildo config sync` adds to your backend once you declare an instance; run `pnpm install` after it
92
+ does. The facet decides four things you therefore do not:
88
93
 
89
94
  | the facet says | so you do not |
90
95
  |---|---|
@@ -99,7 +104,7 @@ be inventing a dialect and an auth scheme.
99
104
 
100
105
  #### Choosing: a named vendor, or the generic `odata`
101
106
 
102
- The catalogue describes **seven** vendors — `odoo`, `microsoft-dataverse`,
107
+ The library describes **seven** vendors — `odoo`, `microsoft-dataverse`,
103
108
  `microsoft-dynamics-365-business-central`, `netsuite`, `salesforce`, `sap-s4hana`, and the generic
104
109
  `odata`.
105
110
 
@@ -112,7 +117,7 @@ The catalogue describes **seven** vendors — `odoo`, `microsoft-dataverse`,
112
117
  is the only one that parses: if the system is not OData v4, `odata` will fail at the first read,
113
118
  further from the cause.
114
119
 
115
- Two naming traps, both real: the Microsoft Web API appears in the catalogue under three connector
120
+ Two naming traps, both real: the Microsoft Web API is known under three provider
116
121
  ids, and only **`microsoft-dataverse`** has a facet — `microsoft-dynamics-365` and
117
122
  `microsoft-dynamics-crm` do not, and naming one is refused. And the SAP facet is **`sap-s4hana`**,
118
123
  not `sap-s4hana-cloud`.
@@ -123,13 +128,20 @@ Read this BEFORE you meet it as a refusal, or you will file a bug against a limi
123
128
 
124
129
  - **`sap-s4hana` — HTTP Basic only.** Its communication user prefers an X.509 client certificate,
125
130
  which is a TRANSPORT credential the outbound seam has no channel for yet.
126
- - **`sap-s4hana` — OData v4 only.** SAP's most-used API (`API_BUSINESS_PARTNER`) is **v2**, and v2 is
127
- not v4 with a different header: different envelope, paging property, count property and value
128
- encoding. A v2 service is refused at the first read, naming the version. Point the binding at an
129
- `/sap/opu/odata4/…` path where one is published.
130
- - **`salesforce`, `netsuite` — read-through only, and unsorted.** Both are REST_JSON, which the
131
- pipeline lane refuses as a source and which declares no sort translation. So they cannot feed a
132
- pipeline, and a `sortFields` declaration on them is refused at registration.
131
+ - **`sap-s4hana` — OData v4 AND v2, one instance per service root.** SAP's most-used API
132
+ (`API_BUSINESS_PARTNER`, `/sap/opu/odata/sap/…`) is **v2**; declare `dialect: ODATA_V2` on the instance
133
+ AND the binding for it, and `ODATA` for a v4 root (`/sap/opu/odata4/…`). A system reached over both is
134
+ two instances, each with its own `maxRequestsPerMinute` — their SUM must fit the vendor's allowance. A
135
+ v2 root declared as `ODATA` is refused at the first read, naming the dialect to declare. A v2 source
136
+ READS only. See `references/odata-v2-sources.md`.
137
+ - **`salesforce`, `netsuite` — unsorted, and a pipeline needs a keyset.** Both are REST_JSON, which
138
+ declares no sort translation, so a `sortFields` declaration on them is refused at registration. They
139
+ feed a pipeline only when the binding's `list` statement declares a `keyset` — offset paging is
140
+ refused for pipelines. See `references/rest-keyset-sources.md`. A DATE filter on them needs the
141
+ column's kind declared — `fieldMappings: [{ localField, remoteField, temporalKind: HttpApiRemoteTemporalKind.DATE }]`
142
+ (or `DATE_TIME`) —
143
+ because SOQL and SuiteQL spell a date and a date-time differently and never as a quoted string; an
144
+ undeclared one is refused.
133
145
  - **`microsoft-dataverse`, `salesforce` — cursor-paged.** Page N costs N requests, because a
134
146
  continuation cursor has no page number. The engine refuses past twenty pages rather than walking
135
147
  indefinitely. A caller that deep wants a filter.
@@ -153,10 +165,45 @@ them:
153
165
  organization that owns the application, so the engine's per-row gate decides — nothing about your
154
166
  tenants is pushed to a remote that has never heard of them.
155
167
  - **`erasure`** — what happens to this data when a person asks to be erased. Every stance is a real
156
- answer, including "this holds no personal data"; there is no silent option.
157
-
158
- Slice-1 reality, so you do not design against something that does not exist: **reads only.** Every
159
- write member is an honest refusal.
168
+ answer, including "this holds no personal data"; there is no silent option. That answer must agree
169
+ with your fields: `NO_SUBJECT_DATA` is refused at startup when any field that comes from the system
170
+ declares `.dataCategories()` (every field of a read-through resource; the mapped fields of a
171
+ pipeline). Settle it by fact — a company's name and contact details are data about a legal person,
172
+ not personal data, so they carry no category; a person's name does, and needs a stance that can
173
+ erase it or acknowledges it cannot.
174
+
175
+ One declaration is optional and belongs beside `erasure` whenever the rows hold personal data:
176
+ **`purposeRefs`**, the `purposeRef`s of `operatorComplianceIdentity.lawfulBases` this data is read for.
177
+ See "Which purpose the data serves" below.
178
+
179
+ **Writing rows back** — creating, updating or deleting ONE row of the remote system — is opened by
180
+ `writableVerbs` on the binding and performed by ordinary `CREATE` / `UPDATE` / `DELETE` operations.
181
+ Read `references/read-through-writes.md` before you open one: it owns the whole contract, and four
182
+ parts of it are not guessable —
183
+
184
+ - the write lands in the OWNER organization's system only, and in the caller's unit's partition;
185
+ - every write variant REQUIRES an `Idempotency-Key` (the framework sets it), and a timeout answers
186
+ `SYSTEM_OF_RECORD_WRITE_OUTCOME_UNKNOWN`, which a client must not answer by resending;
187
+ - no bulk write, no nested child writes, no queued write, no write inside a transaction;
188
+ - whether your dialect can write at all is the engine's — a binding opening a verb its dialect cannot
189
+ send is refused at startup, naming the dialect. Odoo (`ODOO_JSONRPC`), OData v4 (`ODATA`) and
190
+ REST_JSON write; OData v2 (`ODATA_V2`) reads only, and SAP S/4HANA does not write (its CSRF-token
191
+ handshake is not performed). A REST_JSON
192
+ binding DECLARES each write it opens — `operations.create` / `update` / `delete`, a method and a
193
+ path, and for a create where the vendor answers the new key (the body, or `Location`);
194
+ - a binding opening `update` must state `writeConcurrency`: `VERSION_CHECKED` on a
195
+ field mapped to the vendor's row version, or `LAST_WRITER_WINS`. On Odoo (`write_date`) the check is
196
+ BEST-EFFORT — it narrows the race and never closes it. On OData (`@odata.etag`) the version travels
197
+ as `If-Match` and the service itself refuses a stale write (412, `…_WRITE_PRECONDITION_FAILED`).
198
+
199
+ **Running an ERP action** — posting an invoice, confirming an order, an OData action — is not a row
200
+ write. Declare it on the binding under `actions`, expose it through one custom operation of the
201
+ resource that calls `utils.systemOfRecordActions.run(...)` — NAMED as its door in
202
+ `actions.<name>.operation` and borrowing `UPDATE` (a keyed `PUT`), which is what exempts it from
203
+ `writableVerbs` — and read `references/system-of-record-actions.md`:
204
+ it runs only in the system-of-record lane (never as a provider operation), for the owner organization,
205
+ by the action's declared roles, on a record read first through this resource's gates, with an
206
+ Idempotency-Key when it writes, and every attempt is audited.
160
207
 
161
208
  ### Step 3B — Pipeline: declare `externalDataPipeline` on an ORDINARY local resource
162
209
 
@@ -167,9 +214,11 @@ rows come from. Read `references/framework-external-data-pipeline-api.md` for th
167
214
  The four decisions that matter:
168
215
 
169
216
  1. **`remoteKeyLocalField`** — a `.isBusinessKey()` STRING field holding the remote row's identity.
170
- The sync merges on it, which is what makes re-running safe.
171
- 2. **`mapping`** — remote field → local field, plus constants for local fields with no remote source.
172
- It must NOT name your tenant field; see the next section.
217
+ The sync merges on it, which is what makes re-running safe. (An OUTBOUND pipeline reverses this and
218
+ the next rule — see "When the application is the source".)
219
+ 2. **`mapping`** — remote field → local field, plus constants for local fields with no remote source,
220
+ and DECLARED EXPRESSIONS for a value derived from remote fields (see "When a local value is derived"
221
+ below). It must NOT name your tenant field; see the next section.
173
222
  3. **`population`** — `CLOSED` (every row comes from the pipeline; caller CREATE is refused) or
174
223
  `OPEN` (users may also mint their own rows beside the synced ones).
175
224
  4. **`orphanPolicy`** — what happens to a local row whose remote original disappeared: `DELETE`,
@@ -231,6 +280,22 @@ pipeline instead of manually advancing its cursor.
231
280
 
232
281
  Run the verification greps below, then check that a sync produced the rows you expect.
233
282
 
283
+ ### When a pipeline misbehaves: where to look
284
+
285
+ Every run leaves a history row, so start from the pipeline's history, not the logs. From the
286
+ application root, `wildo context pipelines` lists every declared pipeline with its health, and
287
+ `wildo context pipelines --runs <resourceType>` prints one pipeline's runs; both read the admin door
288
+ (`references/framework-pipeline-admin-endpoints-api.md`), which answers each question below.
289
+
290
+ | Symptom | Read |
291
+ |---|---|
292
+ | Is it running at all, and is the copy current? | the listing's `health`: `lastRunAt`, `lastCompletedPassAt`, `lastCompletedFullPassAt` |
293
+ | It keeps failing | `health.consecutiveFailures`, then `GET …/runs`: each failed run's `failureKind` and `failureMessage` |
294
+ | The source is down | the listing's `sourceUnreachable` streak; scheduled runs back off on their own |
295
+ | Some source rows never arrive | `GET …/runs`: the run's `rejections` (remote key and reason), then fix the data at the source |
296
+ | A run refuses its stored state on every tick | `POST …/reset` with `restart-pass` |
297
+ | Rows loaded but look wrong | the run's `seedRunId`, then that load ledger's per-entry outcomes |
298
+
234
299
  ## When the instance is PARTITIONED
235
300
 
236
301
  Some systems of record hold several partitions inside one corporate — Odoo
@@ -245,6 +310,13 @@ codec, whether the value arrives as a many2one pair — comes from the vendor, n
245
310
  from you; the instance only opts in, and boot refuses if the vendor partitions by
246
311
  something that cannot be confined.
247
312
 
313
+ **When the vendor's facet declares no partition but a package does**, the package ships a facet
314
+ AUGMENTATION and the instance opts into it with `facetAugmentations: ['<package>']`. Nothing is applied
315
+ because a package is installed, and a partition declared twice is refused at boot, naming both sources.
316
+ A package discovery does not walk by name (another scope's, or yours not named `provider-*`) must also be
317
+ listed in `providers.packages`, and your backend package
318
+ must depend on it. Only a FIELD partition can be confined. Read `references/facet-augmentations.md`.
319
+
248
320
  **Who maps a partition to a unit is an operator**, through
249
321
  `systemOfRecordPartitionAssignments`. See the `authorization-unit-narrowing`
250
322
  skill for that door and for what it means to a caller.
@@ -291,6 +363,146 @@ un-assignment reversible.
291
363
  A row whose partition field is unset is **shared**: visible to every caller,
292
364
  carrying no unit, and both stamps land null on it.
293
365
 
366
+ ## When the source is large: read only what changed (`incremental`)
367
+
368
+ A pipeline with no `incremental` re-reads its whole source on every pass. For a large Odoo model that
369
+ is hundreds of runs per pass. Declare `incremental` and the pipeline runs TWO independent tracks:
370
+
371
+ - **incremental passes** on `scheduleCron` read only rows changed since a watermark — Odoo's own
372
+ own `write_date` position of the last rows loaded, never your clock — and NEVER delete;
373
+ - **full passes** on `incremental.fullPassCron` read everything and are the only thing that can find a
374
+ row deleted in the source. That is why the cadence is required.
375
+
376
+ The two never block each other, and a row an incremental pass loads while a long full pass is in
377
+ flight is never mistaken for a deletion when that full pass completes. A change to what is extracted
378
+ or how it is loaded (mapping, keys, `sourceFilter`, partition assignments, …) drops the watermark, so
379
+ the next incremental pass reads the whole source once. Refused at startup: a mode the source's
380
+ dialect or vendor does not support, and `incremental` without `scheduleCron`. Three modes exist: Odoo's
381
+ `write_date`, and for an OData v4 source a modified-at filter or the delta-link protocol (which also reads
382
+ DELETIONS); OData v2 and REST sources run full passes.
383
+
384
+ Read `references/incremental-extraction.md` before declaring it: the lookback, what re-reads the
385
+ source, and how to read a run.
386
+
387
+ ## Rate budgets: two per call, and only a pipeline waits
388
+
389
+ Every remote call spends TWO local budgets and is sent only if both have room. The instance budget and a
390
+ virtual resource's ceiling are counted in the application's Redis, once for every backend replica (a process
391
+ with no Redis counts on its own); a pipeline's ceiling stays in the process holding its lease:
392
+
393
+ - the **instance** budget, `systemsOfRecord.<name>.maxRequestsPerMinute` — one allowance shared by every
394
+ virtual resource and pipeline bound to that instance, because the vendor counts them as one caller;
395
+ - the **binding** ceiling, `remoteCallSemantics.maxRequestsPerMinute` — how much of that allowance ONE
396
+ resource or pipeline may take.
397
+
398
+ A **read-through call** (a person listing rows) refuses at once when either is full: someone is waiting,
399
+ and a wait they cannot see is worse than an error they can. A **pipeline run PACES**: it waits for its
400
+ binding ceiling to have room, backs off briefly when only the instance is full, and waits as long as a
401
+ throttling source's `Retry-After` asks. `maxRunDurationMs` (default 15 minutes) bounds the waiting; when
402
+ it comes, the run stops as a PARTIAL pass — every page it loaded is kept (a run loads each page before it
403
+ reads the next), the cursor continues the pass on the next run — never as a failure. The run report and the stored last-run summary carry `pacing`: the time
404
+ spent waiting, how many waits, and whether the run stopped at its deadline.
405
+
406
+ So when the instance declares a budget, the pipeline's binding ceiling must be **strictly below** it —
407
+ the difference is what a person's read keeps while a pass runs. Startup refuses an absent or equal
408
+ ceiling, naming both values. Read `references/rate-budgets-and-pacing.md` to choose the numbers.
409
+
410
+ ## When the source is Odoo: ARCHIVED records are not deleted records
411
+
412
+ Odoo archives a record by setting its `active` field to `false`, and hides archived records from
413
+ every search by default. A pipeline cannot inherit that default: its orphan comparison reads "absent
414
+ from a complete pass" as "deleted in the source", so a hidden archived record would be deleted,
415
+ deprecated or reported as gone by your `orphanPolicy`, taking its local fields, files and retrieval
416
+ chunks with it.
417
+
418
+ So an Odoo pipeline **always extracts archived records too**, and an archived record is **always
419
+ counted as present**. No setting can turn archiving into deletion. What you choose is only whether an
420
+ archived record is LOADED, with `archivedRecords`:
421
+
422
+ | `archivedRecords` | an archived record is | choose it when |
423
+ |---|---|---|
424
+ | absent, or `{ treatment: 'load' }` (the default) | loaded like any other row | the destination should show archival. Map Odoo's `active` onto a local boolean like any other field; an un-archive then changes exactly that one value |
425
+ | `{ treatment: 'exclude-from-load' }` | not loaded, still counted as present | archived records should never enter the destination. A row loaded while the record was live KEEPS its last loaded version until the record is un-archived. `archiveFlagRemoteField` defaults to `active`; name `x_active` for a Studio model |
426
+
427
+ Under `exclude-from-load`, a row whose archive flag is missing or not a boolean is REJECTED with that
428
+ reason (and still counted as present), because excluding or loading on a guess would both be wrong.
429
+ The run reports `excludedArchivedRows`, and the persisted last-run summary keeps it.
430
+
431
+ `archivedRecords` is refused on an OData source: OData has no protocol-level archive state. The
432
+ read-through lane keeps Odoo's default — a person listing partners does not see archived ones, as in
433
+ Odoo's own list views — while a subject erasure searches archived records too.
434
+
435
+ ## When a copied person is erased: the suppression list
436
+
437
+ Nothing to declare. An erasure that scrubs or deletes a pipeline-copied row records a SUPPRESSION of its
438
+ remote record — a keyed hash, never the key — and every later pass, full or incremental, loads nothing
439
+ under it and counts the skip as `suppressedRows`. It is released only by a completed full pass over the
440
+ whole remote entity (no `sourceFilter`) that no longer sees the record. Read
441
+ `references/erasure-suppression.md`, including the one refusal: a changed `encryptionKey` stops runs.
442
+
443
+ ## Which purpose the data serves: `purposeRefs`
444
+
445
+ Personal data read or copied from a system of record was not collected from the person, so the
446
+ application's privacy notice owes where it came from, which categories, and the purpose and legal basis
447
+ for obtaining it (GDPR Art. 14). The source and the categories are derived: the `system` you bind and the
448
+ `.dataCategories()` on your fields. The purpose is the one thing only you know, so declare it on the
449
+ binding — `httpApiBinding.purposeRefs`, or `externalDataPipeline.binding.purposeRefs` for a copy — naming
450
+ entries of `operatorComplianceIdentity.lawfulBases` in `wildo.saas.config.ts`:
451
+
452
+ - nothing refuses at startup without it; the source statement in the notice then marks its purpose as owed;
453
+ - a ref naming no declared purpose is reported (the computed fact lists it under
454
+ `purposeRefsNamingNoPurpose`), never silently dropped;
455
+ - a pipeline copy also needs a retention class on its destination resource, or the notice says the copy is
456
+ kept until erased.
457
+
458
+ The notice also owes whether the data can have come from publicly accessible sources. That is a property of
459
+ the INSTANCE — how records got into your ERP — so state it once on the instance:
460
+ `systemsOfRecord.<name>.personalDataOrigin`, `SystemOfRecordPersonalDataOrigin.NO_PUBLICLY_ACCESSIBLE_SOURCES`
461
+ or `INCLUDES_PUBLICLY_ACCESSIBLE_SOURCES` (from `@wildo-ai/saas-models`). Omitted, the notice marks that
462
+ statement owed for every resource read from the instance; it is never read as "no".
463
+
464
+ The `compliance-document-authoring` skill turns these into the notice's source statement.
465
+
466
+ ## When a remote record REFERENCES another one: `REMOTE_REFERENCE`
467
+
468
+ An Odoo `res.partner.parent_id` or an OData navigation key should not land as a bare remote id: map it
469
+ with a `REMOTE_REFERENCE` entry onto a declared relationship foreign key, and the pipeline writes the
470
+ LOCAL id of the target's copy. The foreign key is written after the load, in its own phase, so a child
471
+ extracted before its parent — and a self-reference — link without ordering anything. A target with no
472
+ local row yet leaves the key empty and PENDING, retried at the end of every later run, incremental ones
473
+ included; `pendingReferences` on the run report says how many wait. The target must be a pipeline
474
+ destination or a virtual resource on the SAME system of record. Read `references/remote-references.md`,
475
+ including the orphan-cascade refusal.
476
+
477
+ ## When a local value is DERIVED from remote fields: declared expressions
478
+
479
+ A vendor code that must become one of your enum's members, a display name built from two fields, an
480
+ amount at a declared rate, a value chosen by a flag: declare an `ENUM_MAP`, `CONCATENATION`,
481
+ `ARITHMETIC` or `CONDITIONAL` mapping entry. They are data, checked against your destination schema at
482
+ startup, and every remote field they read is requested by the extraction. There is no transform
483
+ function — an unknown key on a mapping entry is refused. A code the declaration does not map rejects
484
+ the row and the run reports it. Read `references/declared-expressions.md`.
485
+
486
+ ## What a reader sees on a synced field: the provenance note
487
+
488
+ On a read surface, every field the pipeline writes carries a note beneath its value — "Synced from Odoo ·
489
+ as of 12 minutes ago" — and your own columns carry none. It needs a READ view for the destination and the
490
+ generated instance label `systems_of_record.<name>.displayName`; you never author the words. Read
491
+ `references/provenance-cue.md`.
492
+
493
+ ## When the application is the source: `direction: OUTBOUND`
494
+
495
+ When a record is BORN in the application and the system of record must also have it — leads captured
496
+ here that belong in Odoo — declare the pipeline with `direction: ExternalDataPipelineDirection.OUTBOUND`
497
+ on the destination your users write. Every save records a change; each pass sends the row as it stands
498
+ now: a CREATE the first time (its answered key is written to `remoteKeyLocalField`), an UPDATE after.
499
+ The ownership rules reverse: the mapped fields are the application's and stay writable, the remote key is
500
+ an optional engine-written string. Only the owner organization's rows are ever sent, a local delete never
501
+ is, and an unknown-outcome CREATE waits for an operator rather than risk a duplicate. It needs
502
+ `writableVerbs` including `CREATE`, `LAST_WRITER_WINS`, `REMOTE_FIELD`/`REMOTE_REFERENCE` entries only, and
503
+ — until erasure reaches sent records — `NO_SUBJECT_DATA` with no personal-data field. Read
504
+ `references/outbound-pipelines.md`.
505
+
294
506
  ## Worked Example
295
507
 
296
508
  ## Import Origins
@@ -303,9 +515,53 @@ carrying no unit, and both stamps land null on it.
303
515
 
304
516
  ```typescript
305
517
  export enum ExternalDataPipelineDirection {
518
+ /**
519
+ * The system of record is the source: a pass reads its rows and loads them into the destination. The mapped fields
520
+ * are remote-authoritative, so callers may not write them.
521
+ */
306
522
  INBOUND = 'inbound',
523
+ /**
524
+ * The destination is the source (#1690): a row created or changed locally is sent to the system of record on the
525
+ * next pass — created there when it has no remote key yet, updated when it has one. The mapped fields are the
526
+ * application's own, so callers write them; the remote key is written by the engine, once, from the create's answer.
527
+ *
528
+ * Only rows of the organization that owns the application are ever sent (a system of record belongs to it alone),
529
+ * and on a partitioned instance only rows whose organization unit is assigned to a partition. A local DELETE is not
530
+ * sent: a system of record keeps its own records, and removing one is its operator's decision, not a side effect of
531
+ * a local edit.
532
+ */
533
+ OUTBOUND = 'outbound',
534
+ /**
535
+ * Both sides change the row (#1723): a pass LOADS what the system of record changed and SENDS what the application
536
+ * changed, field by field, as each mapping entry's `owner` declares — REMOTE fields are loaded and read-only locally,
537
+ * LOCAL fields are sent and never loaded, BOTH fields are loaded AND sent. A row whose BOTH fields changed on both
538
+ * sides since they last agreed is a CONFLICT, decided by the declared `conflictPolicy`.
539
+ *
540
+ * "Since they last agreed" is the system of record's own row version (Odoo `write_date`, an OData entity tag), kept
541
+ * per row by the engine — so the direction is legal only on an instance whose vendor declares one. A local DELETE is
542
+ * not sent, as on OUTBOUND.
543
+ */
544
+ BIDIRECTIONAL = 'bidirectional',
307
545
  }
308
546
 
547
+ /**
548
+ * Which side OWNS a mapped field of a BIDIRECTIONAL pipeline (#1723). Declared on each `REMOTE_FIELD` / `REMOTE_REFERENCE`
549
+ * entry as `owner`, and refused on any other direction (an INBOUND pipeline's fields are all the system of record's, an
550
+ * OUTBOUND pipeline's all the application's).
551
+ *
552
+ * Only BOTH fields can conflict, which keeps the common case — remote master data plus a few locally-owned fields —
553
+ * out of conflict handling entirely.
554
+ */
555
+ export enum ExternalDataFieldOwner {
556
+ /** The system of record's: loaded, read-only for callers, never sent. The default when `owner` is omitted. */
557
+ REMOTE = 'remote',
558
+ /** The application's: written by callers, sent, never loaded. */
559
+ LOCAL = 'local',
560
+ /** Both sides': written by callers AND loaded, sent AND read back — the only kind of field that can conflict. */
561
+ BOTH = 'both',
562
+ }
563
+
564
+
309
565
  /**
310
566
  * Who owns the destination's row population (D-P8, v3.1 §1).
311
567
  *
@@ -348,18 +604,164 @@ export enum ExternalDataOrphanPolicy {
348
604
  REPORT = 'report',
349
605
  }
350
606
 
351
- /** The two shapes a mapping entry can take — a closed discriminator, never inferred from keys. */
607
+ /**
608
+ * The shapes a mapping entry can take — a closed discriminator, never inferred from keys.
609
+ *
610
+ * ## The DECLARED EXPRESSIONS (#1685), and the open function slot they replace
611
+ *
612
+ * `ENUM_MAP`, `CONCATENATION`, `ARITHMETIC` and `CONDITIONAL` derive a local value from remote values. They are
613
+ * the first of the T's recorded widenings (D-P4: computed transforms, then multi-source joins, then transforms
614
+ * authored by the app-creation lane's agents) and they are DATA: every one names the remote fields it reads, the
615
+ * local field it writes, and a closed operation with declared constants. Nothing in them executes code the
616
+ * declaration does not show, so each is checked at startup against the destination schema (target type, enum
617
+ * membership, absence) and requested by the extraction like any mapped field.
618
+ *
619
+ * An open function slot (`transform: (row) => value`) is refused on purpose: it would put arbitrary code inside the
620
+ * load with no declaration anyone can review, validate or fingerprint. A derivation beyond these four stays a
621
+ * pre-load step in the application's own code, run by its own job.
622
+ */
352
623
  export enum ExternalDataMappingEntryKind {
353
624
  /** Copy (and coerce) one remote field into one local field. */
354
625
  REMOTE_FIELD = 'remote-field',
355
626
  /** Fill one local field with a declared constant (destination-required fields with no remote source). */
356
627
  CONSTANT = 'constant',
628
+ /**
629
+ * Turn a remote REFERENCE into a real local foreign key (#1684) — an Odoo many2one (`parent_id`,
630
+ * `partner_id`), an OData navigation key. The remote value names a row of ANOTHER remote entity (or of
631
+ * the same one); the pipeline writes the local foreign key to that row's LOCAL copy, never the remote
632
+ * id. See {@link ExternalDataRemoteReferenceMappingEntrySchema}.
633
+ */
634
+ REMOTE_REFERENCE = 'remote-reference',
635
+ /**
636
+ * Map a remote CODE onto a member of a local enum (#1685) — an Odoo selection (`draft`/`posted`), a vendor status
637
+ * code. Every mapped code is declared; a code the declaration does not name either rejects the row or lands a
638
+ * declared default. See {@link ExternalDataEnumMappingEntrySchema}.
639
+ */
640
+ ENUM_MAP = 'enum-map',
641
+ /**
642
+ * Join remote fields and literals into one local string (#1685) — a display name from a first and a last name.
643
+ * See {@link ExternalDataConcatenationMappingEntrySchema}.
644
+ */
645
+ CONCATENATION = 'concatenation',
646
+ /**
647
+ * `remote × factor + offset` on one numeric remote field (#1685) — a unit conversion, or a currency conversion at
648
+ * a DECLARED constant rate. See {@link ExternalDataArithmeticMappingEntrySchema}.
649
+ */
650
+ ARITHMETIC = 'arithmetic',
651
+ /**
652
+ * Choose the local value by ONE remote field's value (#1685): a list of cases, each an exact value, and an
653
+ * `otherwise`. See {@link ExternalDataConditionalMappingEntrySchema}.
654
+ */
655
+ CONDITIONAL = 'conditional',
656
+ }
657
+
658
+ /**
659
+ * The mapping entry kinds an OUTBOUND pipeline may declare (#1690): a local field sent as one remote field, and a local
660
+ * foreign key sent as the target row's REMOTE key. The declared expressions (#1685) derive one local value from remote
661
+ * ones and have no inverse — a concatenation cannot be split back into its parts — and a CONSTANT names no remote field.
662
+ */
663
+ export const EXTERNAL_DATA_OUTBOUND_MAPPING_ENTRY_KINDS: ReadonlySet<ExternalDataMappingEntryKind> = new Set([
664
+ ExternalDataMappingEntryKind.REMOTE_FIELD,
665
+ ExternalDataMappingEntryKind.REMOTE_REFERENCE,
666
+ ]);
667
+
668
+ /**
669
+ * The write verbs an OUTBOUND pipeline may open on its binding (#1690): a create for a row with no remote key yet, and
670
+ * an update for one that has one. DELETE is not among them — see {@link ExternalDataPipelineDirection.OUTBOUND}.
671
+ */
672
+ export const EXTERNAL_DATA_OUTBOUND_WRITE_VERBS: ReadonlySet<HttpApiWriteVerb> = new Set([HttpApiWriteVerb.CREATE, HttpApiWriteVerb.UPDATE]);
673
+
674
+ /**
675
+ * What an `ENUM_MAP` does with a remote code its declaration does not name (#1685).
676
+ */
677
+ export enum ExternalDataUnmappedValuePolicy {
678
+ /**
679
+ * The DEFAULT. The row is REJECTED and reported, and its previous local version survives. A vendor that adds a
680
+ * code is then visible on the next run's report instead of being folded silently into some other member.
681
+ */
682
+ REJECT_ROW = 'reject-row',
683
+ /** The row lands the declared `localValue`. Choose it only where every future code genuinely means the same thing. */
684
+ USE_DEFAULT = 'use-default',
685
+ }
686
+
687
+ /** The two things a `CONCATENATION` part can be (#1685). */
688
+ export enum ExternalDataConcatenationPartKind {
689
+ /** The value of one remote field. An absent or empty value drops the part. */
690
+ REMOTE_FIELD = 'remote-field',
691
+ /** A declared literal, written as-is. */
692
+ LITERAL = 'literal',
693
+ }
694
+
695
+ /** The two things a `CONDITIONAL` outcome can be (#1685). */
696
+ export enum ExternalDataConditionalOutcomeKind {
697
+ /** A declared constant, checked against the local field's type at startup. */
698
+ CONSTANT = 'constant',
699
+ /** Another remote field's value, copied as a `REMOTE_FIELD` entry copies it. */
700
+ REMOTE_FIELD = 'remote-field',
701
+ }
702
+
703
+ /**
704
+ * How a REMOTE_REFERENCE's remote value becomes the target's key (#1684). A closed vocabulary, one
705
+ * member per wire shape, because the shapes differ in kind and guessing between them silently resolves
706
+ * nothing.
707
+ */
708
+ export enum ExternalDataRemoteReferenceValueShape {
709
+ /**
710
+ * Odoo's many2one: `search_read` answers `[id, display_name]`, or `false` when the reference is empty.
711
+ * The key is the pair's FIRST element; the display name is ignored (it is a label, not an identity).
712
+ * spec-cite: Odoo 18.0 developer reference, External API — "Read records" / "Search and read"
713
+ * (`odoo/documentation/18.0/content/developer/reference/external_api.rst`) — a many2one reads as
714
+ * `[21, 'Belgium']`; `false` for an unset one is the ORM's null spelling (measured shape recorded on the
715
+ * provider simulator, `odoo-jsonrpc-mock.ts`).
716
+ */
717
+ ODOO_MANY2ONE = 'odoo-many2one',
718
+ /**
719
+ * The remote value IS the target's key component, as a plain scalar — an OData navigation property's
720
+ * foreign-key field (`ParentAccountID`), a REST id column. `null` or an empty string is an empty reference.
721
+ */
722
+ SCALAR = 'scalar',
723
+ }
724
+
725
+ /**
726
+ * What a run does with a reference whose target has no local row yet (#1684).
727
+ *
728
+ * Resolution happens AFTER the load, in its own phase, so a reference to a row loaded by the same run —
729
+ * including a child extracted before its parent, and a self-reference — always resolves. What remains
730
+ * "unresolved" is a target the destination does not hold at all: outside the pipeline's `sourceFilter`,
731
+ * in a partition nobody assigned, not yet loaded by the target's own pipeline.
732
+ */
733
+ export enum ExternalDataUnresolvedReferencePolicy {
734
+ /**
735
+ * The DEFAULT. The row loads with the foreign key EMPTY, and the reference is kept in the pipeline's
736
+ * pending-resolution set. The set is retried at the end of EVERY later run of the pipeline, incremental
737
+ * ones included — which is the only way such a row is ever resolved under incremental extraction (#1682),
738
+ * because a child that did not change is never re-read. Counted on every run's report and summary.
739
+ */
740
+ LEAVE_PENDING = 'leave-pending',
741
+ /**
742
+ * The row is REJECTED (reported per row; its previous local version survives) when its target is not
743
+ * already loaded and not among the rows of the same PAGE — a run loads page by page (#1689), so a target
744
+ * on a LATER page of the same run is not loaded yet. It is retried only when the row is extracted again
745
+ * — every full pass, or an incremental pass after it changes — and a pass that reads parents before their
746
+ * children never meets the case. For a self-referencing entity whose source order you do not control,
747
+ * `LEAVE_PENDING` resolves the link at the end of the same run instead. A reference to a VIRTUAL (read-through)
748
+ * target never rejects: its key is its local id, and there is nothing local to be missing.
749
+ *
750
+ * The check runs BEFORE the load, against the target as it stands then. A self-referenced target that the same
751
+ * full pass's orphan walk deletes (`orphanPolicy: DELETE`) saved the row from rejection and is then gone, so that
752
+ * row loads with its foreign key empty and pending — the one case this policy cannot rule out.
753
+ */
754
+ REJECT_ROW = 'reject-row',
357
755
  }
358
756
 
359
757
  /**
360
758
  * Built-in, closed coercion vocabulary for REMOTE_FIELD entries (v3.1 §3 / PR-8). Slice 1 ships
361
- * exactly the coercions the two generic dialects force; arbitrary transforms are the recorded
362
- * widenings (W-FK resolution, W-AGENT authored transforms) — never an open function slot here.
759
+ * exactly the coercions the two generic dialects force. A value COMPUTED from remote fields is one of
760
+ * the declared expressions (#1685 — D-P4's first widening: `ENUM_MAP`, `CONCATENATION`, `ARITHMETIC`,
761
+ * `CONDITIONAL`), and transforms authored by the app-creation lane's agents remain a recorded widening
762
+ * (W-AGENT) — never an open function slot here. Foreign-key resolution,
763
+ * once recorded as the W-FK widening beside it, is not a coercion at all: it is its own entry kind,
764
+ * {@link ExternalDataMappingEntryKind.REMOTE_REFERENCE} (#1684).
363
765
  */
364
766
  export enum ExternalDataFieldCoercion {
365
767
  /** Value lands as extracted (after the destination schema's own Zod parse). */
@@ -374,9 +776,243 @@ export enum ExternalDataFieldCoercion {
374
776
  ISO_STRING_TO_DATE = 'iso-string-to-date',
375
777
  }
376
778
 
377
- /** One declared T-step: remote field → local field with a built-in coercion, or a constant. */
779
+ /**
780
+ * What a pipeline does with a remote row its source has ARCHIVED rather than deleted (#1732).
781
+ *
782
+ * ## Why this exists: archived is not deleted, and absence reads as deletion
783
+ *
784
+ * Odoo archives a record by setting its `active` field to `false`, and an archived record is then
785
+ * "invisible in most searches and listing" — a plain `search_read` leaves it out, exactly as if it
786
+ * had been deleted.
787
+ * spec-cite: Odoo 17.0 ORM API reference, "Reserved Field names" → `Model.active`
788
+ * (https://www.odoo.com/documentation/17.0/developer/reference/backend/orm.html).
789
+ *
790
+ * A pipeline's orphan walk reads "absent from a complete pass" as "deleted remotely", so an extraction
791
+ * that inherited Odoo's default visibility turned every archive into a deletion: `REPORT` reported
792
+ * it, `DEPRECATE` deprecated it, and `DELETE` hard-deleted the local row together with its local
793
+ * extension fields, files and RAG chunks. Un-archiving later re-created a bare row.
794
+ *
795
+ * So extraction ALWAYS asks Odoo for archived rows too (the `active_test: false` context), and an
796
+ * archived row is always OBSERVED — present in the source, never an orphan. What remains a choice is
797
+ * only whether it is LOADED, and that is this vocabulary. Every member keeps the row observed; no
798
+ * member can turn an archive into a deletion.
799
+ *
800
+ * Declared on Odoo sources only (`archivedRecords`); an OData source has no protocol-level archive
801
+ * state, and the declaration coherence refuses the field there.
802
+ */
803
+ export enum ExternalDataArchivedRecordTreatment {
804
+ /**
805
+ * The DEFAULT. An archived row is loaded like any other row. Map the source's archive flag
806
+ * (`active` on most Odoo models) onto a local boolean like any other field, and the destination can
807
+ * show or filter archived rows — and an un-archive changes exactly that one value.
808
+ */
809
+ LOAD = 'load',
810
+ /**
811
+ * An archived row is NOT loaded, but still counts as observed, so it is never an orphan — the same
812
+ * treatment rows of an unassigned partition get. A local row loaded while the record was live KEEPS
813
+ * its last loaded version (it is neither updated nor deleted) until the record is un-archived.
814
+ * Choose it to keep archived records out of a destination that never held them; choose `LOAD` with
815
+ * the flag mapped when the destination must reflect archival.
816
+ */
817
+ EXCLUDE_FROM_LOAD = 'exclude-from-load',
818
+ }
819
+
820
+ /**
821
+ * A REMOTE_REFERENCE mapping entry (#1684): a remote reference field written as a real LOCAL foreign key.
822
+ *
823
+ * ## What the local field holds
824
+ *
825
+ * - a target that is another PIPELINE destination on the same system of record (or this one — a
826
+ * self-reference such as Odoo `res.partner.parent_id`): the target's local row id, found by synthesizing
827
+ * the target's key with THE TARGET BINDING's key codec and looking it up on the target's
828
+ * `remoteKeyLocalField`;
829
+ * - a target that is a VIRTUAL (read-through) resource bound to the same system of record: the synthesized
830
+ * key itself — a virtual row's `_id` IS that value, so nothing is looked up.
831
+ *
832
+ * ## When it is written
833
+ *
834
+ * After the load, in its own phase — never inside the row transform. So a child extracted before its
835
+ * parent, a self-reference, and a cycle between two pipelines all resolve without ordering anything. The
836
+ * resolution phase is the ONLY writer of the local field: the load never touches it, which is why the field
837
+ * is left out of the load's managed fields.
838
+ *
839
+ * ## What the declaration owes (checked at authoring and at startup)
840
+ *
841
+ * - `localField` is the foreign key of a declared relationship between this resource and `targetResourceType`,
842
+ * a STRING field that accepts absence (an unresolved reference leaves it empty), and — like every
843
+ * pipeline-written field — `.excludeFromCreate().excludeFromUpdate()`;
844
+ * - the target is a pipeline destination or a virtual resource on THIS pipeline's system of record, keyed by
845
+ * ONE key field (a composite target key is a recorded widening);
846
+ * - when the target's orphan policy DELETES rows and the relationship tears children down with their parent,
847
+ * `orphanCascadeAcknowledged: true` — a row vanishing from the target's source would otherwise take this
848
+ * resource's rows with it through the ordinary `onParentDelete` rules, and nothing about this declaration
849
+ * says so unless the author does.
850
+ */
851
+ export const ExternalDataRemoteReferenceMappingEntrySchema = z.strictObject({
852
+ kind: z.literal(ExternalDataMappingEntryKind.REMOTE_REFERENCE),
853
+ /** The remote field carrying the reference (`parent_id` on Odoo `res.partner`). */
854
+ remoteField: z.string().trim().min(1),
855
+ /** The local foreign-key field the resolved reference is written to. */
856
+ localField: z.string().trim().min(1),
857
+ /** The LOCAL resource the reference resolves to — a pipeline destination or a virtual resource. */
858
+ targetResourceType: z.string().trim().min(1),
859
+ /**
860
+ * How the remote value becomes the target's key. Absent = resolved at AUTHORING from the source dialect:
861
+ * `ODOO_MANY2ONE` on an Odoo source, `SCALAR` otherwise — the resource factory writes the resolved value
862
+ * into the declaration, exactly as it resolves the Odoo absent-as-false coercion.
863
+ */
864
+ valueShape: z.enum(ExternalDataRemoteReferenceValueShape).optional(),
865
+ unresolved: z.enum(ExternalDataUnresolvedReferencePolicy).default(ExternalDataUnresolvedReferencePolicy.LEAVE_PENDING),
866
+ /**
867
+ * The author has read that the target's `orphanPolicy: DELETE` will cascade into this resource's rows
868
+ * through the relationship's `onParentDelete` teardown, and wants that. Only meaningful — and only
869
+ * demanded — when both are true; see the schema's header.
870
+ */
871
+ orphanCascadeAcknowledged: z.boolean().default(false),
872
+ /** Which side owns the reference — BIDIRECTIONAL pipelines only (#1723). Absent = REMOTE. */
873
+ owner: z.enum(ExternalDataFieldOwner).optional(),
874
+ });
875
+
876
+ export type ExternalDataRemoteReferenceMappingEntry = z.infer<typeof ExternalDataRemoteReferenceMappingEntrySchema>;
877
+
878
+ /**
879
+ * A remote SCALAR a declared expression compares against or maps from (#1685) — the value shapes a remote field
880
+ * carries that can be matched exactly. An Odoo selection is a string, a status code may be a number, a flag a
881
+ * boolean. Objects and arrays (an Odoo many2one pair) cannot be matched and are not declarable.
882
+ */
883
+ const externalDataExpressionScalarSchema = z.union([z.string(), z.number().finite(), z.boolean()]);
884
+
885
+ /**
886
+ * An `ENUM_MAP` entry (#1685): one remote code → one member of the local field's enum.
887
+ *
888
+ * - the local field is an ENUM, and every declared `localValue` (and the default's) is one of its members — checked
889
+ * at startup, so a renamed member fails the boot rather than every row;
890
+ * - an ABSENT remote value (the field unset: `null`, missing, or Odoo's `false` when `false` is not itself a declared
891
+ * code) lands null, or rejects the row when `required`;
892
+ * - a PRESENT code the declaration does not name follows `unmapped`: rejected by default, or the declared member.
893
+ */
894
+ export const ExternalDataEnumMappingEntrySchema = z.strictObject({
895
+ kind: z.literal(ExternalDataMappingEntryKind.ENUM_MAP),
896
+ /** The remote field carrying the code (`state` on Odoo `account.move`). */
897
+ remoteField: z.string().trim().min(1),
898
+ localField: z.string().trim().min(1),
899
+ /** Every code the declaration maps, each to one member of the local enum. Codes are unique. */
900
+ values: z.array(z.strictObject({
901
+ remoteValue: externalDataExpressionScalarSchema,
902
+ localValue: z.union([z.string().min(1), z.number().finite()]),
903
+ })).min(1),
904
+ /** A PRESENT code no `values` entry names. Absent = reject the row. */
905
+ unmapped: z.discriminatedUnion('policy', [
906
+ z.strictObject({ policy: z.literal(ExternalDataUnmappedValuePolicy.REJECT_ROW) }),
907
+ z.strictObject({ policy: z.literal(ExternalDataUnmappedValuePolicy.USE_DEFAULT), localValue: z.union([z.string().min(1), z.number().finite()]) }),
908
+ ]).default({ policy: ExternalDataUnmappedValuePolicy.REJECT_ROW }),
909
+ /** `true`: a row whose remote code is ABSENT is rejected. `false` (default): absence lands null. */
910
+ required: z.boolean().default(false),
911
+ });
912
+
913
+ export type ExternalDataEnumMappingEntry = z.infer<typeof ExternalDataEnumMappingEntrySchema>;
914
+
915
+ /**
916
+ * A `CONCATENATION` entry (#1685): remote fields and literals joined into one local STRING.
917
+ *
918
+ * Every part with a value is written, in order, joined by `separator`; a remote part whose value is absent or empty
919
+ * (`null`, missing, `''`, or Odoo's `false`) is DROPPED with its separator, the way SQL's `concat_ws` ignores a NULL
920
+ * argument — so `first` + `last` joined by a space yields `'Ada'`, never `'Ada '`, when the last name is unset. A
921
+ * number is written as JavaScript's shortest round-trip text (`42`, `12.5`; exponent notation only beyond `1e21` or
922
+ * below `1e-6`); any other value (a boolean off Odoo, a many2one pair) rejects the row.
923
+ *
924
+ * spec-cite: PostgreSQL 17 documentation, §9.4 "String Functions and Operators", `concat_ws` — "NULL arguments are
925
+ * ignored" (https://www.postgresql.org/docs/17/functions-string.html).
926
+ *
927
+ * When NO remote part has a value, the result is ABSENT — literals alone are decoration, not data — and lands null,
928
+ * or rejects the row when `required`.
929
+ */
930
+ export const ExternalDataConcatenationMappingEntrySchema = z.strictObject({
931
+ kind: z.literal(ExternalDataMappingEntryKind.CONCATENATION),
932
+ localField: z.string().trim().min(1),
933
+ /** At least two parts, at least one of them a remote field. */
934
+ parts: z.array(z.discriminatedUnion('kind', [
935
+ z.strictObject({ kind: z.literal(ExternalDataConcatenationPartKind.REMOTE_FIELD), remoteField: z.string().trim().min(1) }),
936
+ z.strictObject({ kind: z.literal(ExternalDataConcatenationPartKind.LITERAL), literal: z.string().min(1) }),
937
+ ])).min(2),
938
+ /** Written between two parts that both have a value. Default: nothing. */
939
+ separator: z.string().default(''),
940
+ required: z.boolean().default(false),
941
+ });
942
+
943
+ export type ExternalDataConcatenationMappingEntry = z.infer<typeof ExternalDataConcatenationMappingEntrySchema>;
944
+
945
+ /**
946
+ * An `ARITHMETIC` entry (#1685): `remote × factor + offset` onto a local NUMBER.
947
+ *
948
+ * A currency conversion is legal only as a DECLARED rate (`factor`): a live exchange rate is a second source, which
949
+ * is a join, and joins are a later widening. The declaration is the rate's record, so changing it changes the
950
+ * pipeline's extraction fingerprint and an incremental pipeline re-reads every row under the new rate.
951
+ *
952
+ * The remote value is a finite number, or a string holding a plain decimal numeral (`'12.50'` — how OData v2 and
953
+ * several REST APIs serialize decimals). Anything else rejects the row. `decimalPlaces` rounds the RESULT half away
954
+ * from zero, in binary floating point: it keeps `0.1 × 3` from landing as `0.30000000000000004`, and it does not make
955
+ * the value exact — an amount that must be exact to the cent belongs in a type this expression does not produce.
956
+ */
957
+ export const ExternalDataArithmeticMappingEntrySchema = z.strictObject({
958
+ kind: z.literal(ExternalDataMappingEntryKind.ARITHMETIC),
959
+ remoteField: z.string().trim().min(1),
960
+ localField: z.string().trim().min(1),
961
+ /** Multiplier. Never 0 — a constant result is a `CONSTANT` entry. */
962
+ factor: z.number().finite().default(1),
963
+ /** Added after the multiplication. */
964
+ offset: z.number().finite().default(0),
965
+ /** Round the result to this many decimal places. Absent = no rounding. */
966
+ decimalPlaces: z.number().int().min(0).max(12).optional(),
967
+ required: z.boolean().default(false),
968
+ });
969
+
970
+ export type ExternalDataArithmeticMappingEntry = z.infer<typeof ExternalDataArithmeticMappingEntrySchema>;
971
+
972
+ /** What a `CONDITIONAL` case (or its `otherwise`) writes (#1685). */
973
+ const ExternalDataConditionalOutcomeSchema = z.discriminatedUnion('kind', [
974
+ z.strictObject({ kind: z.literal(ExternalDataConditionalOutcomeKind.CONSTANT), constant: externalDataExpressionScalarSchema }),
975
+ z.strictObject({
976
+ kind: z.literal(ExternalDataConditionalOutcomeKind.REMOTE_FIELD),
977
+ remoteField: z.string().trim().min(1),
978
+ /** As on a `REMOTE_FIELD` entry: Odoo's absent-as-false is resolved at authoring from the local field's type. */
979
+ coercion: z.enum(ExternalDataFieldCoercion).default(ExternalDataFieldCoercion.NONE),
980
+ }),
981
+ ]);
982
+
983
+ export type ExternalDataConditionalOutcome = z.infer<typeof ExternalDataConditionalOutcomeSchema>;
984
+
985
+ /**
986
+ * A `CONDITIONAL` entry (#1685): the local value chosen by ONE remote field's value.
987
+ *
988
+ * The cases are tried in order and the first whose `equals` is exactly (`===`) the remote value wins; no case
989
+ * matching — an absent value included — takes `otherwise`. On an Odoo source an unset field reads `false`, so a declared
990
+ * `equals: false` case catches it before `otherwise` does. An outcome is a constant (checked against the local
991
+ * field's type, and against its members when it is an enum) or another remote field's value. Conditions over two
992
+ * fields, ranges and patterns are not part of the set: they are exactly what makes an expression language grow into
993
+ * the open function slot this set exists to avoid.
994
+ */
995
+ export const ExternalDataConditionalMappingEntrySchema = z.strictObject({
996
+ kind: z.literal(ExternalDataMappingEntryKind.CONDITIONAL),
997
+ /** The remote field whose value decides. */
998
+ remoteField: z.string().trim().min(1),
999
+ localField: z.string().trim().min(1),
1000
+ cases: z.array(z.strictObject({ equals: externalDataExpressionScalarSchema, then: ExternalDataConditionalOutcomeSchema })).min(1),
1001
+ otherwise: ExternalDataConditionalOutcomeSchema,
1002
+ });
1003
+
1004
+ export type ExternalDataConditionalMappingEntry = z.infer<typeof ExternalDataConditionalMappingEntrySchema>;
1005
+
1006
+ /**
1007
+ * One declared T-step: remote field → local field with a built-in coercion, a constant, a resolved reference, or one
1008
+ * of the four declared expressions (#1685).
1009
+ *
1010
+ * Every entry shape is STRICT: an unknown key is refused, not dropped. That is what makes the refusal of an open
1011
+ * function slot real — `{ kind: 'remote-field', …, transform: (value) => … }` used to parse with `transform` silently
1012
+ * stripped, a declaration that reads as if it ran code and runs none.
1013
+ */
378
1014
  export const ExternalDataFieldMappingEntrySchema = z.discriminatedUnion('kind', [
379
- z.object({
1015
+ z.strictObject({
380
1016
  kind: z.literal(ExternalDataMappingEntryKind.REMOTE_FIELD),
381
1017
  remoteField: z.string().trim().min(1),
382
1018
  localField: z.string().trim().min(1),
@@ -387,19 +1023,189 @@ export const ExternalDataFieldMappingEntrySchema = z.discriminatedUnion('kind',
387
1023
  * which the declaration coherence requires the local field to accept.
388
1024
  */
389
1025
  required: z.boolean().default(false),
1026
+ /** Which side owns the field — BIDIRECTIONAL pipelines only (#1723). Absent = REMOTE. */
1027
+ owner: z.enum(ExternalDataFieldOwner).optional(),
390
1028
  }),
391
- z.object({
1029
+ z.strictObject({
392
1030
  kind: z.literal(ExternalDataMappingEntryKind.CONSTANT),
393
1031
  localField: z.string().trim().min(1),
394
1032
  constant: z.union([z.string(), z.number(), z.boolean()]),
395
1033
  }),
1034
+ ExternalDataRemoteReferenceMappingEntrySchema,
1035
+ ExternalDataEnumMappingEntrySchema,
1036
+ ExternalDataConcatenationMappingEntrySchema,
1037
+ ExternalDataArithmeticMappingEntrySchema,
1038
+ ExternalDataConditionalMappingEntrySchema,
396
1039
  ]);
1040
+
1041
+ /**
1042
+ * HOW a source says what changed — one member per remote change-tracking mechanism (#1682).
1043
+ *
1044
+ * A closed vocabulary shared by two parties: a system-of-record VENDOR FACET declares which modes its
1045
+ * deployments support (`incrementalExtractionModes`), and a pipeline declaration chooses one. A
1046
+ * pipeline asking for a mode its source's facet does not declare is refused at startup, naming both.
1047
+ *
1048
+ * Three modes: Odoo's `write_date`, and the two OData v4 mechanisms (#1722) — a modified-at filter and
1049
+ * the delta-link protocol. The incremental TRACK on the state row is mode-neutral (its watermark and
1050
+ * cursor are opaque, mode-owned text), so a new mode needed no reshape of it.
1051
+ */
1052
+ export enum ExternalDataIncrementalExtractionMode {
1053
+ /**
1054
+ * Odoo's `write_date` — the "Last Updated on" column the ORM maintains on every model that logs
1055
+ * access. Read in (SECOND, id) order from a watermark, with a declared lookback. See
1056
+ * {@link ExternalDataIncrementalExtractionDeclarationSchema}.
1057
+ */
1058
+ ODOO_WRITE_DATE = 'odoo-write-date',
1059
+ /**
1060
+ * OData v4, a MODIFIED-AT property the declaration names (`modifiedAtRemoteField` — per entity, not per
1061
+ * vendor: Dataverse's `modifiedon`, Business Central's `lastModifiedDateTime`). Rows with that property at
1062
+ * or after the watermark (less the lookback) are read in KEY order, and the watermark moves only when the
1063
+ * pass completes. Catches no deletions: full passes find those.
1064
+ */
1065
+ ODATA_MODIFIED_AT = 'odata-modified-at',
1066
+ /**
1067
+ * OData v4 CHANGE TRACKING: the first pass asks for `Prefer: odata.track-changes` and keeps the service's
1068
+ * `@odata.deltaLink`; every later pass follows it and receives changed entities AND deleted ones, so an
1069
+ * incremental pass applies the orphan policy to each deleted key. The vendor must track changes for the
1070
+ * entity set (Dataverse: per table).
1071
+ */
1072
+ ODATA_DELTA_LINK = 'odata-delta-link',
1073
+ }
1074
+
1075
+ /**
1076
+ * `incremental` — read only what changed between full passes (#1682).
1077
+ *
1078
+ * ## What an incremental pass does, and what it never does
1079
+ *
1080
+ * - It reads the rows changed since the pipeline's WATERMARK — the largest remote position a previous
1081
+ * incremental pass actually LOADED, never the local clock (a local clock and a remote clock disagree,
1082
+ * and the gap is rows nobody reads).
1083
+ * - The watermark advances only after the rows that reached it are loaded. A crash re-reads; it never
1084
+ * skips.
1085
+ * - It NEVER detects deletions. A row deleted remotely does not "change", so no incremental read can
1086
+ * see it. Deletions are found by FULL passes only, on `fullPassCron` — which is why that cadence is
1087
+ * required rather than optional: an incremental-only pipeline would keep deleted rows forever.
1088
+ * - It runs on the pipeline's `scheduleCron`, which is therefore required too.
1089
+ *
1090
+ * ## The Odoo mode — why (second, id), and why a lookback
1091
+ *
1092
+ * Odoo STORES `write_date` with microseconds (the writing transaction's `now()`) and SERVES it cut to
1093
+ * the second, while a domain compares the stored value. Two obvious designs fail on that gap:
1094
+ * `write_date > w` skips the rows that share the last row's second but did not fit on the page, and a
1095
+ * keyset on the served `(write_date, id)` re-reads its own last row forever, because a row served as
1096
+ * `10:00:00` is stored after `10:00:00`. The extraction therefore walks (SECOND, id): it finishes one
1097
+ * second by id (`s <= write_date < s+1s AND id > i`, ordered by id), then finds the next rows from the
1098
+ * following second. Every row is read once per pass, however many rows share a second.
1099
+ * spec-cite: N/A — Odoo 17.0 SOURCE, not a document: `odoo/models.py`
1100
+ * `vals.setdefault('write_date', self.env.cr.now())`, `odoo/sql_db.py` `Cursor.now`
1101
+ * (`SELECT (now() AT TIME ZONE 'UTC')`), `odoo/fields.py` `Datetime.to_string` (`strftime`), and no
1102
+ * `Datetime.convert_to_column` override (the base field stores the full value).
1103
+ *
1104
+ * The lookback re-reads the last `lookbackSeconds` of changes at the START of every incremental pass.
1105
+ * Odoo stamps `write_date` when the writing transaction runs, not when it commits, so a long
1106
+ * transaction can commit a row whose `write_date` is already older than a watermark another pass
1107
+ * advanced past in the meantime; without a lookback that row is never read — and a transaction that
1108
+ * commits later inside the watermark's own second is caught the same way. Re-reads are free where it
1109
+ * matters: the load compares content and writes nothing for an unchanged row. UNVERIFIED against a
1110
+ * live Odoo — the default is a margin, not a measurement; raise it for a deployment with long batch
1111
+ * jobs. `0` is NOT a harmless setting: without a lookback, a row written later inside a second a pass
1112
+ * has already finished is read only when it changes again (or by a full pass).
1113
+ *
1114
+ * ## Changing the declaration resets the incremental track
1115
+ *
1116
+ * An incremental pass never re-reads a row that did not change remotely, so a change to what is
1117
+ * extracted or how it is loaded — the binding, key fields, mapping, `sourceFilter`, partition fields,
1118
+ * archived-record treatment, or the operator's partition ASSIGNMENTS — would otherwise never reach the
1119
+ * rows already loaded. The run fingerprints those inputs; a different fingerprint drops the watermark,
1120
+ * and the next incremental pass reads the whole source again. The run summary says it did.
1121
+ */
1122
+ export const ExternalDataIncrementalExtractionDeclarationSchema = z.discriminatedUnion('mode', [
1123
+ z.object({
1124
+ mode: z.literal(ExternalDataIncrementalExtractionMode.ODOO_WRITE_DATE),
1125
+ /**
1126
+ * When FULL passes run (cron). The only deletion detector, so required. A full pass that takes
1127
+ * several runs continues on `scheduleCron` ticks until it completes, interleaved with incremental
1128
+ * passes; neither track waits for the other.
1129
+ */
1130
+ fullPassCron: z.string().trim().min(1),
1131
+ /** Seconds of changes re-read at the start of every incremental pass (see above). Up to one day. */
1132
+ lookbackSeconds: z.number().int().nonnegative().max(86_400).default(300),
1133
+ }),
1134
+ /*
1135
+ * ## The OData modified-at mode (#1722)
1136
+ *
1137
+ * `$filter=<modifiedAtRemoteField> ge <watermark − lookback>`, ordered by the KEY as a full pass is, paged
1138
+ * by the service. Because the pages are in key order and not in modified-at order, a page's largest
1139
+ * timestamp says nothing about the rows still to come, so the watermark moves only when the PASS completes
1140
+ * (to the largest timestamp the pass read), never per page — a per-page watermark would skip the rows of
1141
+ * a later page modified before it. `ge`, not `gt`: two rows sharing the watermark's instant are both read.
1142
+ *
1143
+ * The property must be an `Edm.DateTimeOffset` the service filters on. The lookback plays the role it
1144
+ * plays for Odoo: a row written by a transaction that commits after the pass read past its timestamp is
1145
+ * re-read by the next pass. Changing `modifiedAtRemoteField` starts the track over (the stored watermark
1146
+ * names the property it was read on).
1147
+ */
1148
+ z.object({
1149
+ mode: z.literal(ExternalDataIncrementalExtractionMode.ODATA_MODIFIED_AT),
1150
+ fullPassCron: z.string().trim().min(1),
1151
+ /** The entity's modified-at property (`Edm.DateTimeOffset`), by its REMOTE name. */
1152
+ modifiedAtRemoteField: z.string().trim().min(1),
1153
+ lookbackSeconds: z.number().int().nonnegative().max(86_400).default(300),
1154
+ }),
1155
+ /*
1156
+ * ## The OData delta-link mode (#1722)
1157
+ *
1158
+ * The first incremental pass reads the whole entity set with `Prefer: odata.track-changes` and keeps the
1159
+ * `@odata.deltaLink` the service puts on its last page; each later pass GETs that link and receives what
1160
+ * changed and what was DELETED since. A deleted entity carries only its id, so the orphan policy is applied
1161
+ * to that key — an incremental pass that finds deletions, which the other modes cannot.
1162
+ *
1163
+ * Refused at declaration: a `sourceFilter` (Dataverse refuses `$filter`, `$orderby`, `$expand` and `$top`
1164
+ * with change tracking) and a composite key (a deleted entity names one id). A delta link the service no
1165
+ * longer honours (`410 Gone`) resets the track and the same run falls back to a FULL pass, which is what
1166
+ * finds the deletions the expired link would have reported; the run summary says so.
1167
+ * spec-cite: Microsoft Learn, "Use change tracking to synchronize data with external systems"
1168
+ * (https://learn.microsoft.com/en-us/power-apps/developer/data-platform/use-change-tracking-synchronize-data-external-systems),
1169
+ * "Query options not supported in Change Tracking Web API request" — "System query options $filter,
1170
+ * $orderby, $expand, and $top aren't supported when you use the Prefer: odata.track-changes header".
1171
+ * spec-cite: OData Version 4.01 Part 1: Protocol §9.2.4 — "410 Gone indicates that the requested resource is
1172
+ * no longer available. This can happen if a client has waited too long to follow a delta link".
1173
+ *
1174
+ * No lookback: a delta link is the service's own position, not a clock.
1175
+ */
1176
+ z.object({
1177
+ mode: z.literal(ExternalDataIncrementalExtractionMode.ODATA_DELTA_LINK),
1178
+ fullPassCron: z.string().trim().min(1),
1179
+ }),
1180
+ ]);
1181
+
1182
+ export type ExternalDataIncrementalExtractionDeclaration = z.infer<typeof ExternalDataIncrementalExtractionDeclarationSchema>;
1183
+
1184
+ /**
1185
+ * The dialect each incremental mode is spoken over. A `Record` over the enum so a mode added without
1186
+ * its dialect is a compile error rather than a declaration the coherence check silently waves through.
1187
+ */
1188
+ export const EXTERNAL_DATA_INCREMENTAL_MODE_DIALECT: Readonly<Record<ExternalDataIncrementalExtractionMode, HttpApiTransportDialect>> = {
1189
+ [ExternalDataIncrementalExtractionMode.ODOO_WRITE_DATE]: HttpApiTransportDialect.ODOO_JSONRPC,
1190
+ [ExternalDataIncrementalExtractionMode.ODATA_MODIFIED_AT]: HttpApiTransportDialect.ODATA,
1191
+ [ExternalDataIncrementalExtractionMode.ODATA_DELTA_LINK]: HttpApiTransportDialect.ODATA,
1192
+ };
397
1193
  ```
398
1194
 
399
1195
  ### Origin Package: `@wildo-ai/saas-models`
400
1196
 
401
1197
  ```typescript
402
1198
  export const ExternalDataPipelineDeclarationSchema = z.object({
1199
+ /**
1200
+ * Which way rows travel — see {@link ExternalDataPipelineDirection}. `INBOUND` when omitted.
1201
+ *
1202
+ * An OUTBOUND pipeline (#1690) reuses this whole declaration with the arrows reversed: the binding opens the writes
1203
+ * it sends (`writableVerbs: [CREATE, UPDATE]`, with the same `writeConcurrency` a read-through binding states), each
1204
+ * `mapping` entry names the local field SENT and the remote field it lands on, and `remoteKeyLocalField` receives the
1205
+ * key the system of record assigns when it creates the row. The fields that only describe reading a source —
1206
+ * `sourceFilter`, `incremental`, `archivedRecords`, `partitionKeyLocalField`, `population`, `orphanPolicy` — are
1207
+ * refused on it, because nothing would read them.
1208
+ */
403
1209
  direction: z.enum(ExternalDataPipelineDirection).default(ExternalDataPipelineDirection.INBOUND),
404
1210
 
405
1211
  /**
@@ -412,6 +1218,14 @@ export const ExternalDataPipelineDeclarationSchema = z.object({
412
1218
  * different thing that no binding names), so a pipeline extracts the operator's rows and the
413
1219
  * destination's own scope declaration decides who may then read them.
414
1220
  *
1221
+ * How the source is WALKED is the dialect's, and only drift-safe walks are admitted: OData v4 follows
1222
+ * the server's `@odata.nextLink`; OData v2 (`ODATA_V2`, #1687) walks the binding's key fields and never
1223
+ * follows `__next`, because v2 promises no stability across a partial listing; Odoo walks its id keyset;
1224
+ * and a REST_JSON source walks the KEYSET its `list` statement declares
1225
+ * (`operations.list.statement.keyset: { keyRemoteField }`, #1686) — the engine builds "the next N rows
1226
+ * after the last key, in key order" and stores that key as the cursor.
1227
+ * A REST source with no keyset (offset paging only) is refused.
1228
+ *
415
1229
  * ⚠ OPERATIONAL HAZARD (PR-16): changing `keyFields` or a component CODEC after rows exist
416
1230
  * re-keys EVERY business key — the whole destination population orphans and re-creates on the
417
1231
  * next full pass, detaching local annotations (extension fields, files, chunks) from the rows
@@ -427,6 +1241,13 @@ export const ExternalDataPipelineDeclarationSchema = z.object({
427
1241
  * plain STRING business key. The factory requires it declared `.isBusinessKey()` +
428
1242
  * `excludeFromCreate/Update`: SYNC's idempotent upsert keys on it, and no caller may mint or
429
1243
  * move it.
1244
+ *
1245
+ * On an OUTBOUND pipeline (#1690) it is empty until the row is first sent: the engine writes the key the system of
1246
+ * record answers the create with, exactly once, and then updates the remote row it names. It must therefore accept
1247
+ * absence, and it is still excluded from create and update — a caller that could write it could point a local row at
1248
+ * any remote record. It must be `.isUnique()` (global, sparse — the default) and `.optional()`, never `.nullable()`:
1249
+ * one remote record, one local row, enforced by the store on every path that writes the key, while the rows not yet
1250
+ * sent (no key) stay outside the index. No business key is required there: nothing upserts on it.
430
1251
  */
431
1252
  remoteKeyLocalField: z.string().trim().min(1),
432
1253
 
@@ -476,20 +1297,72 @@ export const ExternalDataPipelineDeclarationSchema = z.object({
476
1297
 
477
1298
  population: z.enum(ExternalDataDestinationPopulation).default(ExternalDataDestinationPopulation.CLOSED),
478
1299
 
1300
+ /**
1301
+ * Odoo sources only: whether ARCHIVED remote rows are loaded (#1732). Absent = `LOAD`. Archived rows
1302
+ * are extracted and counted as observed under every treatment, so archiving a record in Odoo never
1303
+ * reaches the orphan policy — see {@link ExternalDataArchivedRecordTreatment}.
1304
+ */
1305
+ archivedRecords: ExternalDataArchivedRecordsDeclarationSchema.optional(),
1306
+
479
1307
  orphanPolicy: z.enum(ExternalDataOrphanPolicy).default(ExternalDataOrphanPolicy.REPORT),
480
1308
 
1309
+ /**
1310
+ * What a BIDIRECTIONAL pipeline (#1723) does with a row whose BOTH-owned fields changed on both sides since they last
1311
+ * agreed — see {@link ExternalDataConflictPolicy}. Absent = REFUSE_AND_REPORT: nothing is overwritten that nobody
1312
+ * decided to overwrite. Refused on any other direction, where no field has two owners.
1313
+ */
1314
+ conflictPolicy: z.enum(ExternalDataConflictPolicy).optional(),
1315
+
481
1316
  /**
482
1317
  * Cron expression for the scheduled refresh (crontabs machinery). Absent = on-demand only —
483
1318
  * legal, and honest for a manually-driven backfill.
484
1319
  */
485
1320
  scheduleCron: z.string().trim().min(1).optional(),
486
1321
 
1322
+ /**
1323
+ * Read only what changed between full passes (#1682). Absent = every pass is a FULL pass, the
1324
+ * behaviour of every pipeline before this existed. When declared, `scheduleCron` runs incremental
1325
+ * passes and `incremental.fullPassCron` runs the full passes that alone detect deletions — see
1326
+ * {@link ExternalDataIncrementalExtractionDeclarationSchema}.
1327
+ */
1328
+ incremental: ExternalDataIncrementalExtractionDeclarationSchema.optional(),
1329
+
487
1330
  /**
488
1331
  * Extraction bound per run (v3.1 §2): a big backfill progresses across runs via the ledger's
489
1332
  * resumable cursor instead of owning one unbounded run. The default matches the rate-budget
490
1333
  * era's "bounded by construction" posture.
1334
+ *
1335
+ * A run ends on a PAGE boundary, so it may carry up to one page more than this — never fewer
1336
+ * rows than the pass has left, and never a page cut short: the source's continuation follows the
1337
+ * whole page, so rows cut from it would be read by no run. An OData v4 source asks for pages of
1338
+ * `min(maxRowsPerRun, 1000)` (`Prefer: odata.maxpagesize`), which a service may honour or not
1339
+ * (#1991). Whether a pass is COMPLETE is never decided from this number — only from the source
1340
+ * answering that nothing is left.
1341
+ *
1342
+ * It bounds a run's WORK, not its memory: a run loads and checkpoints each page (up to 1 000 rows)
1343
+ * before it reads the next (#1689), so it holds one page, and a run that fails part-way keeps the
1344
+ * pages it loaded — the next run resumes after them.
491
1345
  */
492
1346
  maxRowsPerRun: z.number().int().positive().default(10_000),
1347
+
1348
+ /**
1349
+ * How long one run may spend before it stops at a page boundary (#1683) — the run's DEADLINE, in
1350
+ * milliseconds.
1351
+ *
1352
+ * A run PACES against its source's rate budget: when the binding's `remoteCallSemantics
1353
+ * .maxRequestsPerMinute` is full it waits for room instead of failing, and it waits as long as a
1354
+ * throttling source's `Retry-After` asks. This bounds that waiting. No wait that would end past the
1355
+ * deadline is taken and no page starts after it; the run then ends as a PARTIAL pass — every page it
1356
+ * loaded is kept and its cursor continues the pass on the next run — never as a failure.
1357
+ *
1358
+ * It bounds extraction and load together: each page is loaded before the next is read (#1689), so a
1359
+ * run finishes after the page it was working on, by at most one page's extraction and load.
1360
+ *
1361
+ * Fifteen minutes by default: well inside an hourly `scheduleCron`, and long enough that a pass of the
1362
+ * default `maxRowsPerRun` completes at even a small binding ceiling. Six hours at most — a run that
1363
+ * needs longer is a backfill, and resuming across runs is what the cursor is for.
1364
+ */
1365
+ maxRunDurationMs: z.number().int().min(1_000).max(21_600_000).default(900_000),
493
1366
  });
494
1367
  ```
495
1368
 
@@ -499,23 +1372,100 @@ export const ExternalDataPipelineDeclarationSchema = z.object({
499
1372
  authored vocabulary, and the coercions.
500
1373
  - `references/framework-http-api-binding-api.md` — the virtual-resource binding contract and its
501
1374
  stance vocabularies.
1375
+ - `references/read-through-writes.md` — writing rows back through a virtual resource: what to
1376
+ declare, who may write which partition, the Idempotency-Key and its one-day expiry, what an Odoo
1377
+ write sends and the limit of its best-effort version check, what an OData write sends (`POST` /
1378
+ `PATCH` / `DELETE`, `If-Match` on the entity tag) and the stable codes a client branches on.
1379
+ - `references/odata-v2-sources.md` — reading an OData v2 service (`ODATA_V2`): declaring it, why the
1380
+ engine reads the service's `$metadata`, the values it decodes and refuses, how a pipeline walks it by
1381
+ key rather than by `__next`, and what it cannot do.
1382
+ - `references/system-of-record-actions.md` — running a declared ERP action (Odoo `action_post`, an
1383
+ OData action): the declaration, who may run it on which record, its one HTTP door, and its codes.
502
1384
  - `references/lane-selection.md` — the choice in Step 1 at more depth, including what each lane
503
1385
  gives up and the industry precedent.
504
1386
  - `references/pipeline-destination-schema.md` — the destination schema rules, and what each refusal
505
1387
  message is telling you.
506
1388
  - `references/framework-pipeline-admin-endpoints-api.md` — run a pipeline on demand while authoring
507
- its mapping, and read what each one last did (`cursor`, `loadStatus`).
1389
+ its mapping, read what each one last did (`cursor`, `loadStatus`) and its health, list its run
1390
+ history with the rows each run refused (`GET …/runs`), and reset a pipeline whose run keeps
1391
+ refusing its stored state (`POST …/reset`).
1392
+ - `references/incremental-extraction.md` — reading only what changed: the two tracks, the Odoo
1393
+ `write_date` watermark and its lookback, the fingerprint that re-reads the source, and why a
1394
+ full-pass cadence is required.
1395
+ - `references/rate-budgets-and-pacing.md` — the instance budget and the binding ceiling, how a
1396
+ pipeline paces against them, `maxRunDurationMs`, how to size the numbers, and the measured load
1397
+ throughput a pass costs the store.
1398
+ - `references/erasure-suppression.md` — why an erased copied row is not re-imported, what a run counts,
1399
+ when a suppression is released, and the key-rotation refusal.
1400
+ - `references/declared-expressions.md` — `ENUM_MAP`, `CONCATENATION`, `ARITHMETIC`, `CONDITIONAL`: a
1401
+ local value derived from remote fields, what startup checks, why there is no transform function, and
1402
+ how an expression edit reaches rows an incremental pass would not re-read.
1403
+ - `references/remote-references.md` — `REMOTE_REFERENCE`: turning an Odoo many2one or an OData
1404
+ navigation key into a real local foreign key, the pending set, `REJECT_ROW`, and the orphan-cascade
1405
+ refusal.
1406
+ - `references/facet-augmentations.md` — adding a partition or a credential kind to a vendor facet a
1407
+ package does not own: the augmentation record, the per-instance `facetAugmentations` opt-in, and what
1408
+ is refused at boot.
1409
+ - `references/rest-keyset-sources.md` — a REST_JSON source (Salesforce SOQL, NetSuite SuiteQL) in a
1410
+ pipeline: the statement `keyset` you declare, the page the engine builds, why the cursor is a key and
1411
+ never a continuation link, and what is refused.
1412
+ - `references/outbound-pipelines.md` — `direction: OUTBOUND`: sending the application's own rows to a
1413
+ system of record — the declaration, the reversed field ownership, what each pass sends and never sends,
1414
+ partition placement, the unknown-outcome create that waits for an operator, and what a pass reports.
1415
+ - `references/provenance-cue.md` — the "synced from ⟨instance⟩ · as of ⟨pass⟩" note on pipeline-written
1416
+ fields: which fields carry it, what "as of" means, the read surface and instance label it needs, and
1417
+ who may read it.
508
1418
 
509
1419
  ## Verification
510
1420
 
511
1421
  - [ ] The resource declares exactly one lane, not both.
512
1422
  - [ ] Virtual: `keyFields` order is deliberate; `system` names a declared instance; `erasure` is stated.
1423
+ - [ ] A binding whose rows hold personal data names `purposeRefs` that exist in
1424
+ `operatorComplianceIdentity.lawfulBases`.
1425
+ - [ ] An instance whose resources hold personal data declares `personalDataOrigin`.
513
1426
  - [ ] Virtual: the resource is ORGANIZATIONS-scoped and its primary-scope relationship is
514
1427
  `REQUIRES_CONTEXT` with no `foreignKeyField` — the factory refuses anything else.
1428
+ - [ ] Virtual writes: every verb in `writableVerbs` has its operation, and every write operation's
1429
+ verb is in `writableVerbs`; no `*_MANY` operation, no `haveBulkOperation`, no `serviceRuntimeMode`.
1430
+ - [ ] Actions: each lives on the binding of the entity it acts on; a writing one is exposed only through a
1431
+ custom operation named in `actions.<name>.operation`, borrowing `UPDATE`, with
1432
+ `idempotencyKey: REQUIRED`, whose implementation calls `utils.systemOfRecordActions.run(...)`; no
1433
+ code reaches the ERP any other way.
1434
+ - [ ] Either lane: a binding declaring `erasure: NO_SUBJECT_DATA` brings no field that declares
1435
+ `.dataCategories()` (read-through: any field; pipeline: any mapped field).
1436
+ - [ ] Virtual writes: a field landing on the partition field is excluded from create and update.
1437
+ - [ ] Virtual writes: the client handles `SYSTEM_OF_RECORD_WRITE_OUTCOME_UNKNOWN` by reading the row,
1438
+ never by resending under a new key.
515
1439
  - [ ] Pipeline: `remoteKeyLocalField` is a `.isBusinessKey()` string field.
516
1440
  - [ ] Pipeline: every mapped local field is `.excludeFromCreate().excludeFromUpdate()`.
517
1441
  - [ ] Pipeline: every non-`required` mapped field can accept absence (optional/nullable/defaulted).
1442
+ - [ ] Odoo pipeline: decide `archivedRecords` deliberately — the default loads archived records, so map
1443
+ `active` if the destination must show archival; archived records are never orphans either way.
1444
+ - [ ] Incremental pipeline: `scheduleCron` AND `incremental.fullPassCron` are both declared, and the
1445
+ full-pass cadence bounds how long a row deleted in the source may linger locally.
1446
+ - [ ] Pipeline on an instance that declares `maxRequestsPerMinute`: the binding declares
1447
+ `remoteCallSemantics.maxRequestsPerMinute` strictly below it, and `maxRunDurationMs` fits the
1448
+ pipeline's `scheduleCron` interval.
518
1449
  - [ ] Pipeline: verify first and last batch keys remain present across a resumed pass; then remove a source row and verify the configured orphan policy. Check reconciliationStatus for skipped reconciliation and loadStatus for failed writes.
1450
+ - [ ] Pipeline holding personal data: erase one copied row, run a full pass, and confirm the row is not
1451
+ back as a live row and the run reports `suppressedRows: 1`.
1452
+ - [ ] REST_JSON pipeline source: the binding's `list` statement declares `keyset` on its single key
1453
+ field; a SOQL one declares `cursorPath`, a SuiteQL one `pagingParams` with
1454
+ `placement: 'query-string'`.
1455
+ - [ ] Pipeline with a `REMOTE_REFERENCE`: its `localField` is the `foreignKeyField` of a declared
1456
+ relationship to `targetResourceType`, optional, and excluded from create and update; after a full
1457
+ pass the child row's foreign key holds the parent's LOCAL id, and `pendingReferences` counts only
1458
+ references whose target is genuinely not loaded.
1459
+ - [ ] Pipeline with a declared expression: each `ENUM_MAP` targets a `z.enum(...)` field and maps
1460
+ every code the source sends today (a run reporting rejected rows names the field of an unmapped
1461
+ code); each `CONCATENATION` targets a string field, each `ARITHMETIC` a number field, and a
1462
+ currency conversion uses a declared `factor`.
1463
+ - [ ] OUTBOUND pipeline: `writableVerbs` includes `CREATE`; the mapped fields are caller-writable;
1464
+ `remoteKeyLocalField` is an optional (not nullable) `.isUnique()` string excluded from create and update; no sent field declares
1465
+ `.dataCategories()`; on a partitioned instance `partitionUnitLocalField` names the row's unit.
1466
+ - [ ] OUTBOUND pipeline: create a row, run a pass, and confirm the row gained its remote key and the
1467
+ record exists remotely; edit it, run again, and confirm exactly one update; a row of another
1468
+ organization is never sent (`droppedOtherOrganization`).
519
1469
  - [ ] The application starts. Every rule above is checked at startup, by name.
520
1470
 
521
1471
  ### Grep invariants
@@ -529,6 +1479,24 @@ rg -A3 'externalDataPipeline' shared-lib/src --glob '*.resources-config.ts'
529
1479
 
530
1480
  # Files or RAG declared on a virtual resource — neither can work without a local row.
531
1481
  rg -l 'persistenceAdapter.*HTTP_API' shared-lib/src | xargs rg 'z_file\(|ragSource\('
1482
+
1483
+ # Incremental pipelines — each must also carry scheduleCron and incremental.fullPassCron.
1484
+ rg -B2 -A4 'incremental:' shared-lib/src --glob '*.resources-config.ts'
1485
+
1486
+ # Remote references — each localField must be a declared relationship foreignKeyField to its target.
1487
+ rg -B1 -A4 'REMOTE_REFERENCE' shared-lib/src --glob '*.resources-config.ts'
1488
+
1489
+ # Declared expressions — each ENUM_MAP's localField must be an enum field, ARITHMETIC a number field.
1490
+ rg -B1 -A6 'ENUM_MAP|CONCATENATION|ARITHMETIC|CONDITIONAL' shared-lib/src --glob '*.resources-config.ts'
1491
+
1492
+ # Declared rate budgets — compare each pipeline's binding ceiling with its instance's (must be lower).
1493
+ rg -n 'maxRequestsPerMinute' wildo.saas.config.ts shared-lib/src
1494
+
1495
+ # OUTBOUND pipelines — each mapped field must be caller-writable and its remote key an optional string.
1496
+ rg -B2 -A12 'ExternalDataPipelineDirection.OUTBOUND' shared-lib/src --glob '*.resources-config.ts'
1497
+
1498
+ # Bulk write operations on a virtual resource — refused; a remote bulk write has no atomicity.
1499
+ rg -l 'persistenceAdapter.*HTTP_API' shared-lib/src | xargs rg '_MANY|haveBulkOperation'
532
1500
  ```
533
1501
 
534
1502
  ## Common Rationalizations
@@ -539,6 +1507,15 @@ rg -l 'persistenceAdapter.*HTTP_API' shared-lib/src | xargs rg 'z_file\(|ragSour
539
1507
  | "I'll mark the synced fields writable and let users fix bad data." | Then the next sync overwrites their edit and nobody knows why. Remote-authoritative fields are read-only *because* the remote system wins; if users must edit, that field belongs in the local half, not the mapping. |
540
1508
  | "I'll sync everything from the remote entity, just in case." | Every mapped field is personal data you now store, retain and must erase. Map what the application uses. |
541
1509
  | "The cursor is null, so orphan reconciliation succeeded." | A fresh or retried first batch also has a null cursor. Check `reconciliationStatus`: unknown source identities skip reconciliation, while failed loads keep the previous checkpoint. |
1510
+ | "A timeout on a write probably failed — the client can just retry with a fresh key." | A timeout says nothing about whether the remote applied it. Retrying under a new key is the duplicate the required Idempotency-Key exists to prevent; read the row first. |
1511
+ | "I'll open every write verb now so the resource is ready later." | An opened verb with no operation is refused at startup, and one whose dialect cannot write refuses the whole application. Open what an operation performs, when it performs it. |
1512
+ | "Incremental passes read every change, so a nightly full pass is wasted work." | A deletion is not a change: no incremental read can see it. Without full passes a row deleted in the source stays in the destination forever — `fullPassCron` is required for exactly that reason. |
1513
+ | "I'll set the watermark from our clock when the run starts." | Your clock and the source's disagree, and the gap is rows nobody reads. The watermark is a position in the source's own `write_date` order, reached by rows actually LOADED, and the framework owns it. |
1514
+ | "I'll give the pipeline the whole instance budget so the sync finishes sooner." | A pipeline takes each slot the moment it frees, so an equal ceiling refuses every person's read for as long as a pass runs — and startup refuses it. The pass already finishes: it waits instead of failing, across runs if it must. |
1515
+ | "I'll map `parent_id` as a REMOTE_FIELD and join on the remote id later." | Then nothing in the framework treats it as a link — no picker, no nested read, no cascade — and every consumer re-derives the join. A `REMOTE_REFERENCE` writes a real foreign key to the local copy. |
1516
+ | "I'll add a `transform` function to the mapping entry for this one field." | Refused at startup: an unknown key on a mapping entry is an error, not an ignored option. Declare an expression, or derive the value in a pre-load step of your own code — never in code the declaration does not show. |
1517
+ | "An unmapped vendor code can fall back to some default member." | Only if every future code genuinely means that member. The default rejection is what makes a new vendor code visible on the next run instead of folding it silently into the wrong member. |
1518
+ | "I'll send new records to the ERP from an `afterCreate` hook." | A hook runs inside the user's write, so an ERP outage fails their save, a retry creates the record twice, and nothing records who changed what. An OUTBOUND pipeline sends later, under an idempotency key, with an audit row per write. |
542
1519
  | "I'll bump the version to force a re-sync." | Unnecessary. A pipeline detects change by comparing remote values, not by a version. |
543
1520
 
544
1521
  ## Red Flags
@@ -549,9 +1526,30 @@ rg -l 'persistenceAdapter.*HTTP_API' shared-lib/src | xargs rg 'z_file\(|ragSour
549
1526
  overwrites whatever a user typed.
550
1527
  - `population: CLOSED` alongside a create-shaped custom operation — refused at startup, and the
551
1528
  message names the operation.
1529
+ - A run reporting rejected rows after the source added a selection value — an `ENUM_MAP` that does not
1530
+ map it; catch it with the declared-expressions grep above and map the code.
552
1531
  - Concurrent pipeline execution across application instances — single-instance execution is required until destination mutations have exclusive ownership. Checkpoint conflicts alone do not fence deletion.
553
1532
  - A binding whose `system` was copied from another resource without checking the instance is the one
554
1533
  you meant — two instances of one vendor differ only by that name.
1534
+ - A bulk write or a `haveBulkOperation` twin on a virtual resource — the fourth grep; refused at
1535
+ startup, because N remote writes cannot roll back as one.
1536
+ - A client that retries `SYSTEM_OF_RECORD_WRITE_OUTCOME_UNKNOWN` under a NEW key — that is exactly the
1537
+ duplicate the Idempotency-Key exists to prevent; the first write may have landed.
1538
+ - An `incremental` pipeline whose `fullPassCron` runs rarely (monthly, yearly) — the fifth grep. Rows
1539
+ deleted in the source survive locally until it runs.
1540
+ - A pipeline whose run report shows `pacing.stoppedAtDeadline: true` on every run — the ceiling is too
1541
+ low for the population, or `maxRunDurationMs` too short; the pass still progresses by cursor, only
1542
+ slower. Catch the numbers with the rate-budget grep above.
1543
+ - A mapped remote id field (`parent_id`, `*_id`) declared as `REMOTE_FIELD` into a string column — the
1544
+ remote-reference grep above; it lands the remote id, not a link to the local copy.
1545
+ - A run whose `pendingReferences` never falls — the targets sit outside the `sourceFilter` or in an
1546
+ unassigned partition; the references will wait forever until the target is loaded.
1547
+ - A run reporting `liveSuppressedRows` above zero — an erasure did not hold; erase those rows again.
1548
+ (`suppressedRows` above zero is expected; never delete a suppression to "fix" it — that re-imports.)
1549
+ - An OUTBOUND pipeline whose runs show `waiting.awaitingOperator` above zero — creates of unknown outcome that
1550
+ nobody has answered and that are never sent again on their own; look each up in the system of record and answer
1551
+ it through `POST /internal/admin/external-data/outbound-changes/resolve`. Catch the declarations with the
1552
+ OUTBOUND grep above.
555
1553
  - A `STANDALONE` primary-scope anchor on a virtual resource. It answers 403 `parent_scope_denied` to
556
1554
  an organization owner, because the execution context's organization id comes from the URL and a
557
1555
  standalone resource is not routed under its scope parent — measured, not inferred.