@wildo-ai/framework-knowledge 1.1.8 → 1.1.10

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 (480) hide show
  1. package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
  2. package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
  3. package/dist/claude-marketplace/plugins/wildo/references/acceptance.md +11 -0
  4. package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +9 -2
  5. package/dist/claude-marketplace/plugins/wildo/references/creation-state.md +21 -0
  6. package/dist/claude-marketplace/plugins/wildo/references/derived-artifacts.md +121 -0
  7. package/dist/claude-marketplace/plugins/wildo/references/expert-personas-and-deliberations.md +26 -7
  8. package/dist/claude-marketplace/plugins/wildo/references/runs-judges-and-questions.md +31 -5
  9. package/dist/claude-marketplace/plugins/wildo/skills/accept/SKILL.md +4 -2
  10. package/dist/claude-marketplace/plugins/wildo/skills/answer/SKILL.md +29 -2
  11. package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +69 -24
  12. package/dist/claude-marketplace/plugins/wildo/skills/doctor/SKILL.md +10 -0
  13. package/dist/claude-marketplace/plugins/wildo/skills/run/SKILL.md +21 -5
  14. package/dist/claude-marketplace/plugins/wildo/skills/start/SKILL.md +31 -5
  15. package/dist/claude-marketplace/plugins/wildo/skills/status/SKILL.md +2 -0
  16. package/dist/claude-marketplace/plugins/wildo/skills/why/SKILL.md +20 -4
  17. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  18. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  19. package/dist/esm/framework-knowledge.definitions.js +95 -5
  20. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  21. package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
  22. package/dist/esm/index.d.ts.map +1 -1
  23. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +2 -2
  24. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -1
  25. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +2 -2
  26. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  27. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts +11 -11
  28. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts.map +1 -1
  29. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js +29 -22
  30. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js.map +1 -1
  31. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +41 -3
  32. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -1
  33. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +175 -14
  34. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
  35. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +1 -1
  36. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
  37. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +3 -3
  38. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
  39. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +1 -1
  40. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +1 -1
  41. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -1
  42. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts +8 -4
  43. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts.map +1 -1
  44. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js +13 -6
  45. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js.map +1 -1
  46. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +4 -2
  47. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
  48. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +90 -13
  49. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
  50. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts +4 -3
  51. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts.map +1 -1
  52. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js +4 -3
  53. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js.map +1 -1
  54. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +8 -0
  55. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
  56. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +12 -4
  57. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
  58. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +12 -3
  59. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
  60. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +8 -4
  61. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
  62. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts +4 -1
  63. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts.map +1 -1
  64. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js +2 -1
  65. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js.map +1 -1
  66. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts.map +1 -1
  67. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts.map +1 -1
  68. package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.d.ts.map +1 -1
  69. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts.map +1 -1
  70. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
  71. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +1 -1
  72. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -1
  73. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +13 -1
  74. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
  75. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts.map +1 -1
  76. package/dist/esm/playbooks/refinement.governance-document-candidate/playbook.definition.d.ts.map +1 -1
  77. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +25 -27
  78. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
  79. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +91 -43
  80. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
  81. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts +41 -0
  82. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts.map +1 -0
  83. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js +43 -0
  84. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js.map +1 -0
  85. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts +200 -0
  86. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts.map +1 -0
  87. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js +203 -0
  88. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js.map +1 -0
  89. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts +81 -0
  90. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts.map +1 -0
  91. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js +93 -0
  92. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js.map +1 -0
  93. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +3 -1
  94. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
  95. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +27 -18
  96. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
  97. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
  98. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts +11 -1
  99. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -1
  100. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js +11 -11
  101. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js.map +1 -1
  102. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +2 -0
  103. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -1
  104. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +3 -1
  105. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -1
  106. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  107. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +2 -0
  108. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
  109. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +3 -1
  110. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -1
  111. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -1
  112. package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts +5 -2
  113. package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts.map +1 -1
  114. package/dist/esm/playbooks/top_down.definition/playbook.definition.js +16 -4
  115. package/dist/esm/playbooks/top_down.definition/playbook.definition.js.map +1 -1
  116. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts +27 -6
  117. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts.map +1 -1
  118. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js +32 -12
  119. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js.map +1 -1
  120. package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.d.ts.map +1 -1
  121. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
  122. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  123. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -1
  124. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +2 -1
  125. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
  126. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +13 -5
  127. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
  128. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +7 -3
  129. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
  130. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +71 -2
  131. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
  132. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +2 -1
  133. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
  134. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +23 -8
  135. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
  136. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts +7 -1
  137. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts.map +1 -1
  138. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js +4 -2
  139. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js.map +1 -1
  140. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +9 -3
  141. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
  142. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +3 -3
  143. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -1
  144. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
  145. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +35 -2
  146. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
  147. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +41 -17
  148. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
  149. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  150. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  151. package/dist/knowledge/manifest.json +8 -8
  152. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +22 -7
  153. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +3 -3
  154. package/dist/knowledge/playbooks/bottom_up.build/method.md +17 -15
  155. package/dist/knowledge/playbooks/bottom_up.build/playbook.json +4 -3
  156. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-protocol.json +1 -1
  157. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-treatment.json +1 -1
  158. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +261 -34
  159. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +42 -4
  160. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +188 -59
  161. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +2 -2
  162. package/dist/knowledge/playbooks/bottom_up.build-scale/method.md +169 -276
  163. package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +2 -2
  164. package/dist/knowledge/playbooks/bottom_up.capability-composition/method.md +8 -1
  165. package/dist/knowledge/playbooks/bottom_up.capability-composition/playbook.json +1 -1
  166. package/dist/knowledge/playbooks/bottom_up.conception/method.md +3 -2
  167. package/dist/knowledge/playbooks/bottom_up.conception/playbook.json +11 -3
  168. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-protocol.json +1 -1
  169. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-treatment.json +1 -1
  170. package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +129 -17
  171. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +7 -4
  172. package/dist/knowledge/playbooks/bottom_up.experience-plan/method.md +28 -6
  173. package/dist/knowledge/playbooks/bottom_up.experience-plan/playbook.json +5 -4
  174. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +13 -5
  175. package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +50 -0
  176. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +16 -4
  177. package/dist/knowledge/playbooks/bottom_up.website-plan/method.md +19 -0
  178. package/dist/knowledge/playbooks/bottom_up.website-plan/playbook.json +5 -2
  179. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +7 -3
  180. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  181. package/dist/knowledge/playbooks/refinement.document-facts/method.md +8 -0
  182. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +3 -2
  183. package/dist/knowledge/playbooks/refinement.feature-contribution/method.md +5 -2
  184. package/dist/knowledge/playbooks/refinement.feature-contribution/playbook.json +1 -1
  185. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-protocol.json +1 -1
  186. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-treatment.json +1 -1
  187. package/dist/knowledge/playbooks/top_down.brand-identity/method.md +75 -37
  188. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +35 -38
  189. package/dist/knowledge/playbooks/top_down.brand-name-research/method.md +145 -0
  190. package/dist/knowledge/playbooks/top_down.brand-name-research/playbook.json +57 -0
  191. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-protocol.json +1 -0
  192. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-treatment.json +1 -0
  193. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/method.md +99 -0
  194. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/playbook.json +65 -0
  195. package/dist/knowledge/playbooks/top_down.brand-naming/method.md +56 -0
  196. package/dist/knowledge/playbooks/top_down.brand-naming/playbook.json +76 -0
  197. package/dist/knowledge/playbooks/top_down.business-model/evaluation-protocol.json +1 -1
  198. package/dist/knowledge/playbooks/top_down.business-model/evaluation-treatment.json +1 -1
  199. package/dist/knowledge/playbooks/top_down.business-model/method.md +60 -6
  200. package/dist/knowledge/playbooks/top_down.business-model/playbook.json +15 -10
  201. package/dist/knowledge/playbooks/top_down.capability-map/method.md +10 -9
  202. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +1 -1
  203. package/dist/knowledge/playbooks/top_down.compliance-analysis/playbook.json +30 -10
  204. package/dist/knowledge/playbooks/top_down.compliance-conception/playbook.json +3 -1
  205. package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +4 -1
  206. package/dist/knowledge/playbooks/top_down.definition/method.md +8 -3
  207. package/dist/knowledge/playbooks/top_down.definition/playbook.json +6 -4
  208. package/dist/knowledge/playbooks/top_down.expert-personas/playbook.json +16 -2
  209. package/dist/knowledge/playbooks/top_down.feature-drafts/method.md +5 -2
  210. package/dist/knowledge/playbooks/top_down.feature-drafts/playbook.json +1 -1
  211. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-protocol.json +1 -1
  212. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-treatment.json +1 -1
  213. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +26 -0
  214. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +4 -2
  215. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-protocol.json +1 -1
  216. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-treatment.json +1 -1
  217. package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +11 -1
  218. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-protocol.json +1 -1
  219. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-treatment.json +1 -1
  220. package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +84 -9
  221. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +6 -3
  222. package/dist/knowledge/playbooks/top_down.risk-register/method.md +21 -0
  223. package/dist/knowledge/playbooks/top_down.risk-register/playbook.json +8 -2
  224. package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +4 -2
  225. package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +29 -0
  226. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +58 -17
  227. package/dist/knowledge/references/brand.name-choice.config.md +144 -0
  228. package/dist/knowledge/references/brand.name-screening.config.md +308 -0
  229. package/dist/knowledge/references/build-plan.task-graph.config.md +119 -11
  230. package/dist/knowledge/references/business-model.pricing-plan.config.md +16 -0
  231. package/dist/knowledge/references/business-model.snapshot.config.md +64 -0
  232. package/dist/knowledge/references/business-model.snapshot.validation.md +68 -4
  233. package/dist/knowledge/references/capability-composition.config.md +67 -4
  234. package/dist/knowledge/references/companion.market.prompt-renderer.md +11 -6
  235. package/dist/knowledge/references/example.authorization.application-roles.office-and-field.md +44 -0
  236. package/dist/knowledge/references/example.backend.custom-operation.audit-event.md +81 -0
  237. package/dist/knowledge/references/example.backend.custom-operation.child-line-total.md +258 -0
  238. package/dist/knowledge/references/example.backend.custom-operation.computed-total.md +153 -0
  239. package/dist/knowledge/references/example.backend.custom-operation.create-related-resource.md +107 -0
  240. package/dist/knowledge/references/example.data-seeding.minimal.md +39 -10
  241. package/dist/knowledge/references/example.data-seeding.row-reference.md +80 -0
  242. package/dist/knowledge/references/example.email.template.minimal.md +1 -1
  243. package/dist/knowledge/references/example.resource.config-wiring.retention-policy-operations.md +74 -0
  244. package/dist/knowledge/references/example.resource.personal-data.free-text-field.md +19 -0
  245. package/dist/knowledge/references/example.resource.personal-data.person-without-account.md +27 -0
  246. package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +152 -0
  247. package/dist/knowledge/references/example.resource.ui-behavior.filter-presets.md +15 -0
  248. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -0
  249. package/dist/knowledge/references/example.views.app-level.home-definition.md +13 -0
  250. package/dist/knowledge/references/example.views.chart-definition.shared.md +83 -0
  251. package/dist/knowledge/references/experience-plan.config.md +60 -7
  252. package/dist/knowledge/references/market.context-block.builder.md +1 -1
  253. package/dist/knowledge/references/market.snapshot.validation.md +1 -1
  254. package/dist/knowledge/references/placement-plan.config.md +43 -0
  255. package/dist/knowledge/references/requirements.functional-requirement.config.md +8 -2
  256. package/dist/knowledge/references/requirements.non-functional-requirement.config.md +2 -0
  257. package/dist/knowledge/references/requirements.references.conventions.md +1 -1
  258. package/dist/knowledge/references/requirements.snapshot.config.md +57 -1
  259. package/dist/knowledge/references/requirements.snapshot.validation.md +35 -1
  260. package/dist/knowledge/references/saas.backend.audit-logs.log-event.md +63 -0
  261. package/dist/knowledge/references/saas.backend.document-sequence.issue-in-operation.md +60 -0
  262. package/dist/knowledge/references/saas.backend.document-sequence.raise-floor.md +156 -0
  263. package/dist/knowledge/references/saas.backend.email.send.md +77 -0
  264. package/dist/knowledge/references/saas.backend.notifications.operation-email-template-ref.md +60 -0
  265. package/dist/knowledge/references/saas.data-seeding.bootstrap-wiring.md +7 -1
  266. package/dist/knowledge/references/saas.data-seeding.computed-entry.md +43 -0
  267. package/dist/knowledge/references/saas.data-seeding.definition-input.md +14 -2
  268. package/dist/knowledge/references/saas.data-seeding.row-reference.md +93 -0
  269. package/dist/knowledge/references/saas.frontend.collection-filter-presets.md +124 -0
  270. package/dist/knowledge/references/saas.frontend.launcher.item-refs.md +316 -0
  271. package/dist/knowledge/references/saas.frontend.launcher.merge-rules.md +106 -0
  272. package/dist/knowledge/references/saas.frontend.launcher.runtime-availability.md +60 -0
  273. package/dist/knowledge/references/saas.frontend.resource-label-params.md +52 -0
  274. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +47 -18
  275. package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +4 -1
  276. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destination-roles.md +25 -0
  277. package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +2 -2
  278. package/dist/knowledge/references/saas.models.audit.trail-config.md +45 -0
  279. package/dist/knowledge/references/saas.models.notifications.user-notification-definition.md +5 -3
  280. package/dist/knowledge/references/saas.models.queue.scheduled-recovery.md +81 -2
  281. package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +26 -0
  282. package/dist/knowledge/references/saas.models.roles.definition.md +61 -0
  283. package/dist/knowledge/references/saas.models.roles.organization-defaults.md +97 -0
  284. package/dist/knowledge/references/saas.public-runtime.contract.md +26 -0
  285. package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +10 -0
  286. package/dist/knowledge/references/saas.website.astro.bridge.md +10 -0
  287. package/dist/knowledge/references/saas.website.astro.label-loader.md +12 -0
  288. package/dist/knowledge/references/saas.website.astro.llms-txt-server.md +14 -1
  289. package/dist/knowledge/references/saas.website.astro.site-context.md +13 -0
  290. package/dist/knowledge/references/saas.website.blog.bridge.md +4 -0
  291. package/dist/knowledge/references/saas.website.config.site-context-loader.md +3 -0
  292. package/dist/knowledge/references/saas.website.factories.define-section.md +4 -0
  293. package/dist/knowledge/references/saas.website.legal.public-document-links.md +76 -0
  294. package/dist/knowledge/references/saas.website.page-manifest.schema.md +12 -3
  295. package/dist/knowledge/references/saas.website.page-sections.component.md +72 -0
  296. package/dist/knowledge/references/saas.website.root-config.seo.md +2 -1
  297. package/dist/knowledge/references/saas.website.runtime.context.md +7 -0
  298. package/dist/knowledge/references/saas.website.sections.definition-schema.md +11 -0
  299. package/dist/knowledge/references/saas.website.seo.llms-txt-config.md +2 -0
  300. package/dist/knowledge/references/website-plan.config.md +26 -0
  301. package/dist/knowledge/references/zod.decorators.chainable-runtime.md +13 -0
  302. package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +7 -0
  303. package/dist/knowledge/references/zod.decorators.document-sequence.md +65 -0
  304. package/dist/knowledge/references/zod.decorators.schema-metadata.md +1 -0
  305. package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +21 -0
  306. package/dist/knowledge/references/zod.factories.bigdecimal.md +1 -0
  307. package/dist/knowledge/references/zod.factories.code.md +1 -0
  308. package/dist/knowledge/references/zod.factories.duration.md +1 -0
  309. package/dist/knowledge/references/zod.factories.money.md +1 -0
  310. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  311. package/dist/knowledge/registries/framework-topics.json +374 -1
  312. package/dist/knowledge/registries/playbooks.json +76 -28
  313. package/dist/knowledge/registries/source-tags.json +1513 -898
  314. package/dist/knowledge/rules/live-context-door.md +5 -2
  315. package/dist/knowledge/skills/INDEX.md +5 -2
  316. package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +16 -3
  317. package/dist/knowledge/skills/application-database-migrations/SKILL.md +14 -3
  318. package/dist/knowledge/skills/application-roles-authoring/SKILL.md +158 -0
  319. package/dist/knowledge/skills/application-roles-authoring/references/framework-application-roles-api.md +169 -0
  320. package/dist/knowledge/skills/application-roles-authoring/references/office-and-field-worked-example.md +63 -0
  321. package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +6 -1
  322. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +256 -9
  323. package/dist/knowledge/skills/backend-custom-operation/references/after-the-operation.md +42 -0
  324. package/dist/knowledge/skills/backend-custom-operation/references/framework-audit-log-event-api.md +220 -0
  325. package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +5 -0
  326. package/dist/knowledge/skills/brand-name-screening/SKILL.md +178 -0
  327. package/dist/knowledge/skills/brand-name-screening/references/framework-brand-name-screening-api.md +466 -0
  328. package/dist/knowledge/skills/brand-name-screening/references/screening-procedure.md +87 -0
  329. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +7 -3
  330. package/dist/knowledge/skills/config-app-shell/SKILL.md +58 -5
  331. package/dist/knowledge/skills/config-app-shell/references/framework-launcher-items-api.md +461 -0
  332. package/dist/knowledge/skills/config-app-shell/references/framework-launcher-visibility-api.md +80 -0
  333. package/dist/knowledge/skills/config-design-system/SKILL.md +28 -6
  334. package/dist/knowledge/skills/config-navigation/SKILL.md +14 -3
  335. package/dist/knowledge/skills/config-saas/SKILL.md +56 -15
  336. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +65 -2
  337. package/dist/knowledge/skills/config-saas/references/framework-audit-trail-config-api.md +62 -2
  338. package/dist/knowledge/skills/config-saas/references/framework-background-work-api.md +81 -2
  339. package/dist/knowledge/skills/config-saas-backend/SKILL.md +6 -1
  340. package/dist/knowledge/skills/configure-billing/SKILL.md +18 -4
  341. package/dist/knowledge/skills/email-add-template/SKILL.md +28 -6
  342. package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +1 -1
  343. package/dist/knowledge/skills/email-add-template/references/framework-email-send-api.md +128 -0
  344. package/dist/knowledge/skills/email-add-template/references/framework-operation-email-template-ref-api.md +99 -0
  345. package/dist/knowledge/skills/engine-component-registration/SKILL.md +6 -1
  346. package/dist/knowledge/skills/engine-product-definitions/SKILL.md +21 -8
  347. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +10 -2
  348. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +18 -4
  349. package/dist/knowledge/skills/frontend-component-catalog/SKILL.md +11 -3
  350. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +2 -1
  351. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +8 -0
  352. package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +19 -5
  353. package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +10 -2
  354. package/dist/knowledge/skills/inbound-channels/SKILL.md +2 -2
  355. package/dist/knowledge/skills/infra-environment-config/SKILL.md +6 -1
  356. package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +17 -2
  357. package/dist/knowledge/skills/local-environment-bootstrap/references/derived-artifact-currency.md +122 -0
  358. package/dist/knowledge/skills/local-environment-bootstrap/references/framework-upgrade-and-dependency-alignment.md +11 -0
  359. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +9 -2
  360. package/dist/knowledge/skills/market-add-feature-benefit/SKILL.md +10 -2
  361. package/dist/knowledge/skills/market-alternatives/SKILL.md +10 -2
  362. package/dist/knowledge/skills/market-authoring-overview/SKILL.md +10 -2
  363. package/dist/knowledge/skills/market-category/SKILL.md +21 -7
  364. package/dist/knowledge/skills/market-channels/SKILL.md +6 -1
  365. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +22 -4
  366. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +12 -2
  367. package/dist/knowledge/skills/market-generation-cli/SKILL.md +21 -11
  368. package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +11 -6
  369. package/dist/knowledge/skills/market-icp/SKILL.md +10 -2
  370. package/dist/knowledge/skills/market-jobs-pains-gains/SKILL.md +6 -1
  371. package/dist/knowledge/skills/market-message-templates-authoring/SKILL.md +6 -1
  372. package/dist/knowledge/skills/market-message-templates-authoring/references/framework-message-template-api.md +1 -1
  373. package/dist/knowledge/skills/market-persona/SKILL.md +14 -3
  374. package/dist/knowledge/skills/market-positioning-authoring/SKILL.md +6 -1
  375. package/dist/knowledge/skills/market-proof-and-objection/SKILL.md +10 -2
  376. package/dist/knowledge/skills/market-scoring-interpretation/SKILL.md +6 -1
  377. package/dist/knowledge/skills/market-snapshot-validation/SKILL.md +15 -4
  378. package/dist/knowledge/skills/market-snapshot-validation/references/framework-snapshot-validation-api.md +1 -1
  379. package/dist/knowledge/skills/market-tone-of-voice/SKILL.md +6 -1
  380. package/dist/knowledge/skills/model-cost-attribution/references/framework-work-unit-api.md +26 -0
  381. package/dist/knowledge/skills/module-companion-exports/SKILL.md +7 -1
  382. package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +10 -0
  383. package/dist/knowledge/skills/module-relationships/SKILL.md +37 -8
  384. package/dist/knowledge/skills/pdf-template-authoring/SKILL.md +4 -2
  385. package/dist/knowledge/skills/provider-address-lookup/SKILL.md +14 -3
  386. package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +6 -1
  387. package/dist/knowledge/skills/provider-operation-calls/SKILL.md +14 -3
  388. package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +10 -2
  389. package/dist/knowledge/skills/resource-add-field/SKILL.md +10 -2
  390. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +46 -17
  391. package/dist/knowledge/skills/resource-add-resource/SKILL.md +14 -2
  392. package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +26 -0
  393. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +29 -3
  394. package/dist/knowledge/skills/resource-config-wiring/references/framework-collection-operation-declarations.md +19 -4
  395. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +5 -2
  396. package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +103 -0
  397. package/dist/knowledge/skills/resource-config-wiring/references/framework-retention-policy-operations.md +135 -0
  398. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +26 -0
  399. package/dist/knowledge/skills/resource-config-wiring/references/framework-user-notifications-api.md +26 -7
  400. package/dist/knowledge/skills/resource-custom-view/SKILL.md +10 -2
  401. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +46 -17
  402. package/dist/knowledge/skills/resource-external-data/references/erasure-suppression.md +2 -2
  403. package/dist/knowledge/skills/resource-retention-binding/SKILL.md +5 -1
  404. package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +15 -1
  405. package/dist/knowledge/skills/resource-schema-authoring/references/computed-totals.md +569 -0
  406. package/dist/knowledge/skills/resource-schema-authoring/references/document-numbers.md +358 -0
  407. package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +8 -0
  408. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +21 -0
  409. package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +7 -2
  410. package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +13 -0
  411. package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +153 -0
  412. package/dist/knowledge/skills/resource-status-lifecycle/references/commercial-documents.md +46 -0
  413. package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +198 -0
  414. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +30 -4
  415. package/dist/knowledge/skills/resource-ui-behavior/references/framework-collection-filter-presets-api.md +157 -0
  416. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +101 -19
  417. package/dist/knowledge/skills/seeding-authoring/SKILL.md +202 -39
  418. package/dist/knowledge/skills/seeding-authoring/references/cross-seed-row-references.md +67 -0
  419. package/dist/knowledge/skills/seeding-authoring/references/framework-data-seeding-api.md +154 -4
  420. package/dist/knowledge/skills/seeding-authoring/references/seed-row-overlay.md +22 -0
  421. package/dist/knowledge/skills/seeding-operations/references/framework-data-seeding-operations-api.md +7 -1
  422. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +43 -0
  423. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +2 -2
  424. package/dist/knowledge/skills/spec-companion-exports/SKILL.md +6 -1
  425. package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +10 -0
  426. package/dist/knowledge/skills/spec-component-update/SKILL.md +10 -2
  427. package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +2 -2
  428. package/dist/knowledge/skills/spec-family-update/SKILL.md +71 -66
  429. package/dist/knowledge/skills/spec-family-update/references/family-spec-routing.md +1 -1
  430. package/dist/knowledge/skills/spec-resource-update/SKILL.md +30 -10
  431. package/dist/knowledge/skills/spec-resource-update/references/resource-spec-field-routing.md +28 -0
  432. package/dist/knowledge/skills/spec-update-after-change/SKILL.md +22 -5
  433. package/dist/knowledge/skills/views-add-composite-view/SKILL.md +6 -1
  434. package/dist/knowledge/skills/views-add-custom-view/SKILL.md +10 -2
  435. package/dist/knowledge/skills/views-app-level/SKILL.md +13 -3
  436. package/dist/knowledge/skills/views-app-level/references/application-home.md +56 -0
  437. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +221 -37
  438. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +22 -5
  439. package/dist/knowledge/skills/views-execution-authoring/SKILL.md +1 -1
  440. package/dist/knowledge/skills/website-anonymous-session/SKILL.md +32 -2
  441. package/dist/knowledge/skills/website-blog-authoring/SKILL.md +16 -3
  442. package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +4 -0
  443. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +7 -1
  444. package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +13 -1
  445. package/dist/knowledge/skills/website-factory-advanced/SKILL.md +14 -2
  446. package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +13 -1
  447. package/dist/knowledge/skills/website-layout-overrides/SKILL.md +6 -1
  448. package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +19 -1
  449. package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +55 -18
  450. package/dist/knowledge/skills/website-navigation-authoring/references/framework-public-document-links-api.md +98 -0
  451. package/dist/knowledge/skills/website-navigation-authoring/references/worked-examples-header-footer.md +8 -11
  452. package/dist/knowledge/skills/website-page-authoring/SKILL.md +100 -8
  453. package/dist/knowledge/skills/website-page-authoring/references/framework-site-context-loader-api.md +3 -0
  454. package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +6 -1
  455. package/dist/knowledge/skills/website-section-contact/SKILL.md +15 -0
  456. package/dist/knowledge/skills/website-section-contact/references/define-website-section-api.md +15 -0
  457. package/dist/knowledge/skills/website-section-cta/SKILL.md +15 -0
  458. package/dist/knowledge/skills/website-section-cta/references/define-website-section-api.md +15 -0
  459. package/dist/knowledge/skills/website-section-faq/SKILL.md +21 -1
  460. package/dist/knowledge/skills/website-section-faq/references/define-website-section-api.md +15 -0
  461. package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +21 -1
  462. package/dist/knowledge/skills/website-section-feature-benefit-summary/references/define-website-section-api.md +15 -0
  463. package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +25 -2
  464. package/dist/knowledge/skills/website-section-feature-detail/references/define-website-section-api.md +15 -0
  465. package/dist/knowledge/skills/website-section-footer-cta/SKILL.md +15 -0
  466. package/dist/knowledge/skills/website-section-footer-cta/references/define-website-section-api.md +15 -0
  467. package/dist/knowledge/skills/website-section-hero/SKILL.md +33 -10
  468. package/dist/knowledge/skills/website-section-hero/references/define-website-section-api.md +15 -0
  469. package/dist/knowledge/skills/website-section-pricing/SKILL.md +21 -1
  470. package/dist/knowledge/skills/website-section-pricing/references/define-website-section-api.md +15 -0
  471. package/dist/knowledge/skills/website-section-social-proof/SKILL.md +27 -2
  472. package/dist/knowledge/skills/website-section-social-proof/references/define-website-section-api.md +15 -0
  473. package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +16 -4
  474. package/dist/knowledge/skills/website-seo-aeo-geo/references/aeo-api.md +11 -0
  475. package/dist/knowledge/skills/website-seo-aeo-geo/references/geo-api.md +16 -1
  476. package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +2 -1
  477. package/dist/knowledge/topic-index.json +1590 -292
  478. package/dist/tsconfig.build.tsbuildinfo +1 -1
  479. package/dist/tsconfig.tsbuildinfo +1 -1
  480. package/package.json +4 -4
@@ -29,11 +29,12 @@
29
29
  * |-------------------------------|----------|--------------------------------------------------------------------------------|
30
30
  * | `INVALID_REF_FORMAT` | ERROR | A functional / non-functional ref fails its shared pattern (single source of truth with the Zod schema). Defence in depth for type-asserted fixtures. |
31
31
  * | `DUPLICATE_REF` | ERROR | Two functional (or two non-functional) requirements share a ref — the collection silently loses one entity to last-wins indexing. |
32
- * | `DUPLICATE_CROSS_REF` | WARN | The same `icpRefs` (or `jobRefs`) entry is listed more than once on ONE requirement — the repeat is noise the catalog silently dedupes (or double-counts in coverage). Intra-snapshot, so it runs UNCONDITIONALLY (no external set needed) — mirrors the assertions family's `DUPLICATE_PIN_REF`. |
32
+ * | `DUPLICATE_CROSS_REF` | WARN | The same `icpRefs` (or `jobRefs`, or `painRefs`) entry is listed more than once on ONE requirement — the repeat is noise the catalog silently dedupes (or double-counts in coverage). Intra-snapshot, so it runs UNCONDITIONALLY (no external set needed) — mirrors the assertions family's `DUPLICATE_PIN_REF`. |
33
33
  * | `NO_FUNCTIONAL_REQUIREMENTS` | WARN | `functional` empty — the requirements brief states no capability the product must provide. |
34
34
  * | `STALE_AUTHORED` | WARN | Any entity's `authored.lastAuthoredAt + reviewCadence < now`. No check when `reviewCadence` is undefined or `AS_NEEDED`. |
35
35
  * | `UNKNOWN_ICP_REF` | ERROR | An `icpRefs` entry does not resolve in `options.availableIcpRefs`. SKIPPED (fail-soft) when no set is passed — the families are decoupled and the catalog resolves refs. |
36
36
  * | `UNKNOWN_JOB_REF` | ERROR | A `jobRefs` entry does not resolve in `options.availableJobRefs`. SKIPPED (fail-soft) when no set is passed. |
37
+ * | `UNKNOWN_PAIN_REF` | ERROR | A `painRefs` entry or an excluded pain does not resolve in `options.availablePainRefs` (#2500). SKIPPED (fail-soft) when no set is passed. |
37
38
  *
38
39
  * Severity is a TS enum (project rule — enums over literal unions). The
39
40
  * validator never mutates the snapshot. Issue ordering is detector-order
@@ -78,6 +79,11 @@ export enum RequirementsSnapshotIssueKind {
78
79
  * ERROR when a set is supplied; SKIPPED (fail-soft) when it is not.
79
80
  */
80
81
  UNKNOWN_JOB_REF = 'unknown_job_ref',
82
+ /**
83
+ * A `painRefs` entry, or an `excludedMarketPains[].painRef`, does not resolve against the supplied pain-ref set
84
+ * (#2500). ERROR when a set is supplied; SKIPPED (fail-soft) when it is not.
85
+ */
86
+ UNKNOWN_PAIN_REF = 'unknown_pain_ref',
81
87
  }
82
88
 
83
89
  export enum RequirementsSnapshotIssueSeverity {
@@ -129,6 +135,11 @@ export interface ValidateRequirementsSnapshotOptions {
129
135
  * `availableIcpRefs`, reported as `UNKNOWN_JOB_REF`.
130
136
  */
131
137
  availableJobRefs?: ReadonlySet<string>;
138
+ /**
139
+ * Resolvable market pain refs (#2500). Same skip-when-omitted semantics as `availableIcpRefs`, reported as
140
+ * `UNKNOWN_PAIN_REF`, for a requirement's `painRefs` and for an excluded pain.
141
+ */
142
+ availablePainRefs?: ReadonlySet<string>;
132
143
  }
133
144
 
134
145
  /**
@@ -259,6 +270,7 @@ function detectDuplicateCrossRefs(
259
270
  ): void => {
260
271
  checkList(entry.icpRefs, entry, `${collection}[${index}].icpRefs`);
261
272
  checkList(entry.jobRefs, entry, `${collection}[${index}].jobRefs`);
273
+ checkList(entry.painRefs, entry, `${collection}[${index}].painRefs`);
262
274
  };
263
275
 
264
276
  snapshot.functional.forEach((entry, index) => checkEntity(entry, 'functional', index));
@@ -340,9 +352,31 @@ function detectUnknownCrossRefs(
340
352
  });
341
353
  });
342
354
  }
355
+ if (options?.availablePainRefs !== undefined) {
356
+ entry.painRefs?.forEach((painRef, refIndex) => {
357
+ if (options.availablePainRefs!.has(painRef)) return;
358
+ issues.push({
359
+ kind: RequirementsSnapshotIssueKind.UNKNOWN_PAIN_REF,
360
+ path: `${collection}[${index}].painRefs[${refIndex}]`,
361
+ message: `Pain ref "${painRef}" on requirement "${entry.ref}" does not resolve in the supplied pain-ref set.`,
362
+ severity: RequirementsSnapshotIssueSeverity.ERROR,
363
+ });
364
+ });
365
+ }
343
366
  };
344
367
 
345
368
  snapshot.functional.forEach((entry, index) => checkEntity(entry, 'functional', index));
346
369
  snapshot.nonFunctional.forEach((entry, index) => checkEntity(entry, 'nonFunctional', index));
370
+ if (options?.availablePainRefs !== undefined) {
371
+ (snapshot.excludedMarketPains ?? []).forEach((excluded, index) => {
372
+ if (options.availablePainRefs!.has(excluded.painRef)) return;
373
+ issues.push({
374
+ kind: RequirementsSnapshotIssueKind.UNKNOWN_PAIN_REF,
375
+ path: `excludedMarketPains[${index}].painRef`,
376
+ message: `Excluded pain "${excluded.painRef}" does not resolve in the supplied pain-ref set.`,
377
+ severity: RequirementsSnapshotIssueSeverity.ERROR,
378
+ });
379
+ });
380
+ }
347
381
  }
348
382
  ```
@@ -0,0 +1,63 @@
1
+ # saas.backend.audit-logs.log-event
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-backend-lib`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-backend-lib`
10
+
11
+ ```typescript
12
+ /**
13
+ * What an emitter hands to the audit pipeline: the event, minus everything the pipeline derives.
14
+ *
15
+ * You supply `eventType` (your own named vocabulary), `riskLevel`, `eventData` (a flat object of the facts a reviewer
16
+ * needs — ids and states, never secrets or free personal text), and the row's subjects: `userId` (the actor) and
17
+ * `organizationId` (the tenant the event is about). The row is built from what you pass, and an organization's audit
18
+ * view lists only rows carrying its id, so take both from the request: `executionContext.initiatorIds`.
19
+ *
20
+ * Derived, never supplied: `eventId`, `eventCategory`, `severity`, the timestamps, and the principal's kind and
21
+ * delegation (person, agent, machine, through which client) — read from the execution context you pass to `logEvent`.
22
+ * Those are omitted from this type and discarded at runtime.
23
+ */
24
+ export type AuditEventEmission = Omit<AuditableEvent, '_id' | 'eventId' | 'createdAt' | 'updatedAt' | 'eventCategory' | 'severity' | AuditRowAttributionField>;
25
+ ```
26
+
27
+ ### Origin Package: `@wildo-ai/saas-backend-lib`
28
+
29
+ ```typescript
30
+ /**
31
+ * Generic audit-event emitter: how application code records an event of its own.
32
+ *
33
+ * Reach it from a custom operation through the factory's container parameter, resolved on first use:
34
+ * `container.get<AuditLogsBackendService>(SAAS_SERVICE_TYPES.AuditLogsService)` (both from
35
+ * `@wildo-ai/saas-backend-lib`).
36
+ *
37
+ * Accepts any `eventType` string. The application classifies its OWN event types in its backend configuration,
38
+ * `auditTrail.applicationEventTypes: { [eventType]: { category, severity } }`; a declared type is recorded, and
39
+ * routed to the SIEM, with that classification, and the labelling pipeline plans a word for it. An undeclared one is
40
+ * recorded as `{ category: 'data_access', severity: 'info' }`. A framework event type keeps the engine's classification.
41
+ *
42
+ * Per-org SIEM dispatch fires ONLY when an authenticated request `ExecutionContext`
43
+ * (carrying an org) is passed as `requestExecutionContext` — never on the caller-supplied
44
+ * `organizationId` field, which says which tenant the row is ABOUT (tenant segregation).
45
+ *
46
+ * Errors are caught + logged but never thrown — audit emission is
47
+ * fire-and-forget; a logging failure must not affect the request
48
+ * that triggered it.
49
+ */
50
+ public async logEvent(
51
+ auditEvent: AuditEventEmission,
52
+ requestExecutionContext?: ExecutionContext<any>,
53
+ /**
54
+ * The principal, when the caller knows it better than any context it holds (automation, a machine door).
55
+ * It REPLACES the context's principal wholesale: kind, delegating client and machine credential. So never
56
+ * pass `userAuditPrincipal(id)` while holding a delegated or machine context; pass the context instead, or
57
+ * the row will call a delegated client's action the person's own.
58
+ */
59
+ principal?: AuditPrincipalFacts,
60
+ ): Promise<void> {
61
+ return this._createAuditLog(auditEvent, requestExecutionContext, undefined, undefined, undefined, undefined, principal);
62
+ }
63
+ ```
@@ -0,0 +1,60 @@
1
+ # saas.backend.document-sequence.issue-in-operation
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-backend-lib`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-backend-lib`
10
+
11
+ ```typescript
12
+ *
13
+ * Number a row from inside the application's own operation: the EXPLICIT case, an invoice drafted without a number and
14
+ * numbered when an "issue" operation runs. It reserves the next number and writes it to the row (with any other fields
15
+ * you pass in `set`) in ONE transaction, and returns the number.
16
+ *
17
+ * Register the operation with `transactionalCore: true` and name the counters as a participant
18
+ * (`documentSequenceCounters: DOCUMENT_SEQUENCE_COUNTERS_RESOURCE_TYPE`), so the counter's increment joins the
19
+ * operation's transaction. The write only lands while the row's number is still empty: issuing an already-numbered row
20
+ * throws a CONFLICT, and the transaction rolls back, so no number is consumed. If anything else in the operation fails,
21
+ * the number is released the same way and the sequence stays gapless.
22
+ *
23
+ * Import from `@wildo-ai/saas-backend-lib`.
24
+ *
25
+ * @example
26
+ * const INVOICE_ISSUE_PARTICIPANTS = { invoices: AppResourceType.INVOICES, documentSequenceCounters: DOCUMENT_SEQUENCE_COUNTERS_RESOURCE_TYPE };
27
+ * // in the "issue" custom implementation, registered with transactionalCore: true and transactionParticipants: INVOICE_ISSUE_PARTICIPANTS
28
+ * const invoiceNumber = await issueDocumentSequenceNumberInOperation(utils, {
29
+ * resourceType: AppResourceType.INVOICES, fieldName: 'invoiceNumber', row: invoice,
30
+ * set: { status: InvoiceStatus.ISSUED, issuedAt: new Date() }, executionContext,
31
+ * });
32
+ */
33
+ export async function issueDocumentSequenceNumberInOperation(
34
+ utils: {
35
+ readonly repositoriesRegistry: RepositoriesRegistryHandlerBackendService;
36
+ readonly errorBuilder: ErrorBuilderBackendService;
37
+ readonly resourcesRegistry: { getResourceConfiguration(resourceType: string): { mainSchema: z.ZodTypeAny } };
38
+ readonly serviceOptions?: { readonly transaction?: RepositoryOptions['transaction'] };
39
+ },
40
+ input: {
41
+ readonly resourceType: string;
42
+ readonly fieldName: string;
43
+ readonly row: Record<string, unknown>;
44
+ readonly set?: Record<string, unknown>;
45
+ readonly executionContext: ExecutionContext<any>;
46
+ },
47
+ ): Promise<string> {
48
+ return issueDocumentSequenceNumber({
49
+ registry: utils.repositoriesRegistry,
50
+ errorBuilder: utils.errorBuilder,
51
+ resourceType: input.resourceType,
52
+ mainSchema: utils.resourcesRegistry.getResourceConfiguration(input.resourceType).mainSchema,
53
+ fieldName: input.fieldName,
54
+ row: input.row,
55
+ set: input.set,
56
+ executionContext: input.executionContext,
57
+ options: utils.serviceOptions?.transaction === undefined ? undefined : { transaction: utils.serviceOptions.transaction },
58
+ });
59
+ }
60
+ ```
@@ -0,0 +1,156 @@
1
+ # saas.backend.document-sequence.raise-floor
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-backend-lib`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-backend-lib`
10
+
11
+ ```typescript
12
+ *
13
+ * CONTINUE an existing numbering: set the last number one document sequence has issued, so the next document gets
14
+ * `floor + 1`. Use it when the application replaces another invoicing tool (its last invoice was INV-2026-00417, so
15
+ * pass `floor: 417` and the next is INV-2026-00418), or when a field that already held numbers gains
16
+ * `.documentSequence(...)` (see `raiseDocumentSequenceFloorsToExistingRows`).
17
+ *
18
+ * It only RAISES. A floor below the counter is refused (`document_sequence_floor_below_counter`), because lowering it
19
+ * would hand out numbers already issued; pass `whenBelowCounter: KEEP_COUNTER` to keep the counter instead. Raising
20
+ * skips numbers on purpose: the numbers between the old counter and the floor must exist in the other system or in the
21
+ * existing rows.
22
+ *
23
+ * It runs in the caller's transaction and refuses without one. It serializes with documents numbered at the same
24
+ * moment: on PostgreSQL it waits on the counter's row lock, and on MongoDB the transaction is retried. A
25
+ * compare-and-set on the counter's value backs that up (`document_sequence_counter_moved`), so a stale read can never
26
+ * overwrite a number already handed out.
27
+ *
28
+ * From an operation, call {@link raiseDocumentSequenceFloorInOperation}. The engine exposes no endpoint for it, so your
29
+ * operation is what decides who may continue a numbering, and what the audit trail keeps:
30
+ *
31
+ * - **Who**: mount the operation under the organization route for an ORGANIZATION sequence, with your organization
32
+ * administrator role, and the wrapper takes the organization from that route, never from the request body. For an
33
+ * APPLICATION sequence, restrict it to an application administrator role.
34
+ * - **Why**: put a required, bounded `justification` string in the request DTO and declare
35
+ * `auditableEvent: { reasonField: 'justification' }`, with a `HIGH` or `CRITICAL` risk level. The trail then records
36
+ * who ran it, when, and the justification.
37
+ * - **What it does NOT record**: the counter's previous and new value. No other request value is copied into the
38
+ * trail, so state the floor in the justification, and return the outcome from the operation. A dedicated event
39
+ * recording the move is planned.
40
+ *
41
+ * Import from `@wildo-ai/saas-backend-lib`.
42
+ *
43
+ * @example
44
+ * // a "continue numbering" custom operation on invoices, under /organizations/{organizationId}/…, registered with
45
+ * // transactionalCore: true and transactionParticipants: { invoices: AppResourceType.INVOICES,
46
+ * // documentSequenceCounters: DOCUMENT_SEQUENCE_COUNTERS_RESOURCE_TYPE }; request DTO { floor, periodKey, justification }
47
+ * const outcome = await raiseDocumentSequenceFloorInOperation(utils, {
48
+ * resourceType: AppResourceType.INVOICES, fieldName: 'invoiceNumber',
49
+ * periodKey: input.periodKey, floor: input.floor, executionContext,
50
+ * });
51
+ * // outcome: { previousValue, value, raised }
52
+ */
53
+ export async function raiseDocumentSequenceFloor(input: {
54
+ readonly registry: DocumentSequenceAllocationRegistry;
55
+ readonly errorBuilder: ErrorBuilderBackendService;
56
+ readonly resourceType: string;
57
+ readonly mainSchema: z.ZodTypeAny;
58
+ readonly fieldName: string;
59
+ /** The organization of an ORGANIZATION sequence. Omit it for an APPLICATION sequence. */
60
+ readonly organizationId?: string;
61
+ /**
62
+ * The counting period: `'2026'` for a yearly sequence, `'2026-10'` for a monthly one, `''` for one that never
63
+ * restarts. Defaults to the current period, read in the organization's timezone.
64
+ */
65
+ readonly periodKey?: string;
66
+ /** The last number already issued in that sequence. */
67
+ readonly floor: number;
68
+ readonly whenBelowCounter?: DocumentSequenceFloorBelowCounter;
69
+ readonly executionContext: ExecutionContext<any>;
70
+ readonly options: RepositoryOptions | undefined;
71
+ /** Only used to default `periodKey`. */
72
+ readonly now?: Date;
73
+ }): Promise<DocumentSequenceFloorRaise> {
74
+ const { registry, errorBuilder, executionContext, resourceType } = input;
75
+ const refuse = (type: ErrorType, reason: string, extra: Record<string, unknown> = {}) =>
76
+ errorBuilder.buildError(type, executionContext, { context: { reason, resourceType, fieldName: input.fieldName, ...extra } });
77
+ const field = documentSequenceFieldsOf(input.mainSchema).find((candidate) => candidate.fieldName === input.fieldName);
78
+ if (field === undefined) throw refuse(ErrorType.CONFIGURATION, 'document_sequence_field_not_declared');
79
+ if (!Number.isSafeInteger(input.floor) || input.floor < 0) throw refuse(ErrorType.VALIDATION, 'document_sequence_floor_invalid', { floor: input.floor });
80
+ const transaction = input.options?.transaction;
81
+ if (transaction === undefined) throw refuse(ErrorType.CONFIGURATION, 'document_sequence_requires_transaction');
82
+
83
+ const isOrganizationSequence = field.params.scope === DocumentSequenceScope.ORGANIZATION;
84
+ const organizationId = input.organizationId;
85
+ if (isOrganizationSequence && (typeof organizationId !== 'string' || organizationId.length === 0)) {
86
+ throw refuse(ErrorType.VALIDATION, 'document_sequence_floor_without_organization');
87
+ }
88
+ // An organization named for an APPLICATION sequence would be silently ignored, and the floor applied to everyone.
89
+ if (!isOrganizationSequence && organizationId !== undefined) throw refuse(ErrorType.VALIDATION, 'document_sequence_floor_organization_for_application_sequence');
90
+ const scopeKey = isOrganizationSequence ? organizationId! : DOCUMENT_SEQUENCE_APPLICATION_SCOPE_KEY;
91
+
92
+ const parsed = parseDocumentSequenceFormat(field.params.format);
93
+ const periodKey = input.periodKey
94
+ ?? documentSequencePeriodKey(parsed, input.now ?? new Date(), await organizationTimeZone(input, field, scopeKey, new Map()));
95
+ if (!PERIOD_KEY_SHAPE[parsed.period].test(periodKey)) throw refuse(ErrorType.VALIDATION, 'document_sequence_floor_period_invalid', { periodKey, period: parsed.period });
96
+
97
+ const _id = await ensureDocumentSequenceCounter(registry, executionContext, transaction, { resourceType, fieldName: field.fieldName, scopeKey, periodKey });
98
+ const current = await registry.readUnscopedByKey<DocumentSequenceCounter>(COUNTERS, { _id }, { transaction });
99
+ const previousValue = current?.value;
100
+ if (typeof previousValue !== 'number') throw refuse(ErrorType.INTERNAL, 'document_sequence_counter_not_advanced');
101
+ if (input.floor === previousValue) return { previousValue, value: previousValue, raised: false };
102
+ if (input.floor < previousValue) {
103
+ if ((input.whenBelowCounter ?? DocumentSequenceFloorBelowCounter.REFUSE) === DocumentSequenceFloorBelowCounter.KEEP_COUNTER) {
104
+ return { previousValue, value: previousValue, raised: false };
105
+ }
106
+ throw refuse(ErrorType.CONFLICT, 'document_sequence_floor_below_counter', { floor: input.floor, counter: previousValue, periodKey });
107
+ }
108
+ // Compare-and-set: a number allocated since the read moves the value, and this write then matches nothing.
109
+ const written = await registry.atomicGuardedMutation<DocumentSequenceCounter>(COUNTERS, { _id, value: previousValue }, { set: { value: input.floor } }, undefined, { transaction });
110
+ if (written === null) throw refuse(ErrorType.CONFLICT, 'document_sequence_counter_moved', { periodKey });
111
+ return { previousValue, value: input.floor, raised: true };
112
+ }
113
+
114
+ /**
115
+ * {@link raiseDocumentSequenceFloor} from inside the application's own operation: the schema comes from the resource
116
+ * registry, the transaction from the operation, and an ORGANIZATION sequence's organization from the operation's
117
+ * organization route (`/organizations/{organizationId}/…`), which the framework has already authorized the caller for.
118
+ * Refuses an ORGANIZATION sequence when the operation has no organization in its route, rather than accept one from the
119
+ * request, which would let one organization's administrator move another's numbering.
120
+ */
121
+ export async function raiseDocumentSequenceFloorInOperation(
122
+ utils: {
123
+ readonly repositoriesRegistry: RepositoriesRegistryHandlerBackendService;
124
+ readonly errorBuilder: ErrorBuilderBackendService;
125
+ readonly resourcesRegistry: { getResourceConfiguration(resourceType: string): { mainSchema: z.ZodTypeAny } };
126
+ readonly serviceOptions?: { readonly transaction?: RepositoryOptions['transaction'] };
127
+ },
128
+ input: {
129
+ readonly resourceType: string;
130
+ readonly fieldName: string;
131
+ readonly periodKey?: string;
132
+ readonly floor: number;
133
+ readonly whenBelowCounter?: DocumentSequenceFloorBelowCounter;
134
+ readonly executionContext: ExecutionContext<any>;
135
+ },
136
+ ): Promise<DocumentSequenceFloorRaise> {
137
+ const mainSchema = utils.resourcesRegistry.getResourceConfiguration(input.resourceType).mainSchema;
138
+ const field = documentSequenceFieldsOf(mainSchema).find((candidate) => candidate.fieldName === input.fieldName);
139
+ const routeOrganizationId = input.executionContext.getContextResourceId(coreResourceShared_FieldIdentifier[CoreResourceType.ORGANIZATIONS]);
140
+ const isOrganizationSequence = field?.params.scope === DocumentSequenceScope.ORGANIZATION;
141
+ return raiseDocumentSequenceFloor({
142
+ registry: utils.repositoriesRegistry,
143
+ errorBuilder: utils.errorBuilder,
144
+ resourceType: input.resourceType,
145
+ mainSchema,
146
+ fieldName: input.fieldName,
147
+ // Absent for an ORGANIZATION sequence when the route names no organization: the raise then refuses.
148
+ ...(isOrganizationSequence && routeOrganizationId !== undefined ? { organizationId: routeOrganizationId } : {}),
149
+ ...(input.periodKey === undefined ? {} : { periodKey: input.periodKey }),
150
+ floor: input.floor,
151
+ ...(input.whenBelowCounter === undefined ? {} : { whenBelowCounter: input.whenBelowCounter }),
152
+ executionContext: input.executionContext,
153
+ options: utils.serviceOptions?.transaction === undefined ? undefined : { transaction: utils.serviceOptions.transaction },
154
+ });
155
+ }
156
+ ```
@@ -0,0 +1,77 @@
1
+ # saas.backend.email.send
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-backend-lib`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-backend-lib`
10
+
11
+ ```typescript
12
+ /**
13
+ * What `EmailBackendService.send(request)` takes: one email, rendered from a REGISTERED template (`templateRef` is the
14
+ * scanned key, such as `email.quotes.issue.customer`) in one locale. Reach the service from a custom operation through
15
+ * the factory's container: `container.get<EmailBackendService>(SAAS_SERVICE_TYPES.EmailService)`.
16
+ *
17
+ * Unlike a `userNotifications` entry, a direct send consults no recipient preference: the caller decides that this
18
+ * person receives this email. Use it for an email the product owes regardless of preferences (a document the customer
19
+ * asked for); anything a person may switch off belongs in `userNotifications`.
20
+ */
21
+ export interface EmailSendRequest {
22
+ /**
23
+ * Stable identity of one logical provider submission. A caller that can
24
+ * retry across process/job boundaries must persist and reuse this value.
25
+ * Ephemeral callers may omit it and let the service allocate one.
26
+ */
27
+ submissionId?: string;
28
+ /** Template reference (e.g., "system.welcome_email") */
29
+ templateRef: string;
30
+ /** Locale for template selection */
31
+ locale: AvailableLanguage;
32
+ /** Email type for provider routing */
33
+ type: EmailTemplateType;
34
+ /** Primary recipient email(s) */
35
+ to: string | string[];
36
+ /** CC recipients (optional) */
37
+ cc?: string[];
38
+ /** BCC recipients (optional) */
39
+ bcc?: string[];
40
+ /** Reply-to address (optional) */
41
+ replyTo?: string;
42
+ /** From address (optional - uses provider default if not specified) */
43
+ from?: string;
44
+ /** Context for template rendering */
45
+ context: EmailTemplateContext;
46
+ /** File IDs for attachments (optional) */
47
+ attachmentFileIds?: string[];
48
+ /** Organization ID for org-scoped templates (optional) */
49
+ organizationId?: string;
50
+ /**
51
+ * Thread this email as a reply (#1630). Becomes exactly `Message-ID`, `In-Reply-To` and `References` —
52
+ * see {@link EmailThreadingHeaders} for why there is no general headers field.
53
+ */
54
+ threading?: EmailThreadingHeaders;
55
+ }
56
+
57
+ export interface EmailSendResult {
58
+ success: boolean;
59
+ /**
60
+ * Whether an at-least-once caller should retry. An acceptance-unknown retry
61
+ * can duplicate an externally visible email; provider-native idempotency is
62
+ * only an optional risk reduction.
63
+ */
64
+ retryable: boolean;
65
+ submissionId: string;
66
+ outcome: EmailSubmissionOutcome;
67
+ /** All honest provider receipts. Empty means no receipt was returned. */
68
+ providerMessageIds: string[];
69
+ /** Provider confirmed that this logical submission was already accepted. */
70
+ deduplicated?: boolean;
71
+ rejectedRecipients?: Array<{ email: string; reason?: string }>;
72
+ providerId?: string;
73
+ error?: string;
74
+ templateRef: string;
75
+ recipientCount: number;
76
+ }
77
+ ```
@@ -0,0 +1,60 @@
1
+ # saas.backend.notifications.operation-email-template-ref
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-backend-lib`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-backend-lib`
10
+
11
+ ```typescript
12
+ /**
13
+ * Canonical template identity for operation-authored email notifications: the template a `userNotifications` EMAIL
14
+ * entry renders.
15
+ *
16
+ * `email.<resource>.<operation>[.<variantKey>].<target>[_<customNotificationRef>]`, where `<target>` is the entry's
17
+ * `target` lowercased with `_` turned into `-` (an engine-internal entry without a target uses its `identifier`). The
18
+ * variant segment is present only for a variant that declares a `variantKey`, and `userNotifications` is declared on
19
+ * the OPERATION, so one entry on an operation with a keyed variant needs one template per variant.
20
+ *
21
+ * With the scanner an application ships (`keyFromPath` turns `/` into `.` under the `resources/` directory beside it), the template's
22
+ * directory is `resources/<resource>/<the rest of the ref, dotted>`: for `todos` / `change_status` / variant `admin` /
23
+ * target `USERS_CUSTOM` / custom ref `notify-assignee` it is
24
+ * `resources/todos/change_status.admin.users-custom_notify-assignee/`.
25
+ *
26
+ * Startup validation and runtime dispatch must use the same derivation;
27
+ * otherwise an application can boot against one template reference and fail
28
+ * only after a mutation commits because delivery derived another.
29
+ */
30
+ export function buildUserNotificationEmailTemplateRef(
31
+ operation: {
32
+ resourceIdentifier: string;
33
+ operationIdentifier: string;
34
+ variantKey?: string;
35
+ },
36
+ notification: {
37
+ identifier: string;
38
+ target?: string;
39
+ customNotificationRef?: string;
40
+ },
41
+ ): string {
42
+ const targetKebab =
43
+ (notification.target || notification.identifier)
44
+ .toLowerCase()
45
+ .replace(/_/g, '-');
46
+ const refParts = [
47
+ 'email',
48
+ operation.resourceIdentifier,
49
+ operation.operationIdentifier,
50
+ ];
51
+ if (operation.variantKey) {
52
+ refParts.push(operation.variantKey);
53
+ }
54
+ refParts.push(targetKebab);
55
+ const baseRef = refParts.join('.');
56
+ return notification.customNotificationRef
57
+ ? `${baseRef}_${notification.customNotificationRef}`
58
+ : baseRef;
59
+ }
60
+ ```
@@ -160,7 +160,13 @@ export function wireDataSeedingDeclarations(
160
160
  * of the collision a reader can act on.
161
161
  */
162
162
  const engineOwned = registersEngineOwnedSeeds ? ENGINE_OWNED_DATA_SEEDS : [];
163
- const seeds = [...engineOwned, ...(dataSeeds ?? [])];
163
+ /*
164
+ * Admitted over the MERGED list (#2234), so a restricted seed is withheld at registration whoever owns it — the
165
+ * promise `allowedApplicationEnvironments` makes. The application's own seeds were already admitted where
166
+ * `start-application` took them (its seeding gates read that set); re-admitting them here is idempotent, and it is
167
+ * what reaches the engine's.
168
+ */
169
+ const seeds = admitDataSeedsForApplicationEnvironment([...engineOwned, ...(dataSeeds ?? [])], readDeclaredApplicationEnvironment(process.env)).admitted;
164
170
  logDebug('🌱 Registering data-seed definitions...', {
165
171
  count: seeds.length,
166
172
  engineOwned: engineOwned.length,
@@ -0,0 +1,43 @@
1
+ # saas.data-seeding.computed-entry
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-backend-lib`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-backend-lib`
10
+
11
+ ```typescript
12
+ *
13
+ * Function shape of a **computed** seed entry — used by a seed whose payload depends on the row that triggered it
14
+ * (an `afterCreate` seed needs that row's `_id`). Declared as a type rather than in the Zod schema, because Zod cannot
15
+ * validate what a function returns.
16
+ *
17
+ * `triggeringRow` is that row as stored, untyped (`Record<string, unknown>` with its `_id`), or `null` for a
18
+ * lazy-access seed. Narrow the fields you read yourself.
19
+ *
20
+ * The context deliberately offers no way to READ other rows. A foreign key to a
21
+ * row another seed writes is returned as `referenceDataSeedRow(targetSeed, key)`
22
+ * and resolved by the engine (the target seed must be in `dependsOn`).
23
+ *
24
+ * It returns exactly ONE entry, every time it is called: there is no "skip this row" value. A seed that should
25
+ * apply to only some triggering rows is the wrong shape; put the condition in an operation (a postfix that creates
26
+ * the row when the condition holds) instead.
27
+ */
28
+ export type DataSeedComputedEntryFn = (context: {
29
+ /**
30
+ * The resource row whose lifecycle event fired the seed (Level B only).
31
+ * Always present for `triggerKind: 'resourceLifecycle'`. `null` for lazy
32
+ * access seeds where there is no triggering row.
33
+ */
34
+ triggeringRow: { _id: string } & Record<string, unknown> | null;
35
+ /**
36
+ * Who caused the run, for attribution only: the seed itself always runs as an internal request, whoever triggered
37
+ * it. `triggeredByUserId` is recorded in the row's `__seed` metadata and in the `DataSeedRun` ledger.
38
+ */
39
+ executionContext: {
40
+ triggeredByUserId: string | null;
41
+ };
42
+ }) => DataSeedStaticEntry | Promise<DataSeedStaticEntry>;
43
+ ```
@@ -46,11 +46,23 @@
46
46
  * dispatcher walks `fromVersion` from the persisted row's
47
47
  * `seedVersion` up to `version - 1`, then re-applies
48
48
  * `managedFields` from the declared entries.
49
- * - `dependsOn` — optional cross-seed dependency declarations (DAG
50
- * resolved at dispatch time).
49
+ * - `dependsOn` — seeds that run before this one. It orders and passes no
50
+ * data; to point an entry's foreign key at a row a dependency wrote, put
51
+ * `referenceDataSeedRow(dependencySeed, { …businessKey })` where the value
52
+ * goes, and the engine resolves it to that row's `_id` when this seed runs.
53
+ * Every referenced seed MUST be listed here.
54
+ * - `anchorEntriesToScopeForeignKey` — inject the scope's foreign key
55
+ * (`organizationId`, …) into every entry's business key, so static entries
56
+ * can be written once and seeded per scope row.
51
57
  * - `schedule` — optional cron-driven re-run binding; presence is the
52
58
  * sole opt-in signal for the engine cron batch. FORBIDDEN for
53
59
  * `mode === LAZY`.
60
+ * - `allowedApplicationEnvironments` — optional; omit for reference data the
61
+ * application needs everywhere. DEMONSTRATION data (sample rows that make a
62
+ * fresh application look lived-in) MUST declare it without `production`, e.g.
63
+ * `[RuntimeEnvironment.DEVELOPMENT, RuntimeEnvironment.STAGING]` (import
64
+ * `RuntimeEnvironment` from `@wildo-ai/saas-models`). A restricted seed is never
65
+ * registered elsewhere, and is withheld when the deployment declares no environment.
54
66
  */
55
67
  export interface DataSeedDefinitionInput extends DataSeedDefinitionAuthored, DataSeedDefinitionCallbacks {}
56
68