@wildo-ai/framework-knowledge 1.1.0

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 (922) hide show
  1. package/LICENSE +34 -0
  2. package/dist/esm/.builder.pid +9 -0
  3. package/dist/esm/framework-knowledge.definitions.d.ts +51 -0
  4. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -0
  5. package/dist/esm/framework-knowledge.definitions.js +1571 -0
  6. package/dist/esm/framework-knowledge.definitions.js.map +1 -0
  7. package/dist/esm/framework-knowledge.loader.d.ts +72 -0
  8. package/dist/esm/framework-knowledge.loader.d.ts.map +1 -0
  9. package/dist/esm/framework-knowledge.loader.js +258 -0
  10. package/dist/esm/framework-knowledge.loader.js.map +1 -0
  11. package/dist/esm/framework-knowledge.schemas.d.ts +236 -0
  12. package/dist/esm/framework-knowledge.schemas.d.ts.map +1 -0
  13. package/dist/esm/framework-knowledge.schemas.js +23 -0
  14. package/dist/esm/framework-knowledge.schemas.js.map +1 -0
  15. package/dist/esm/index.d.ts +4 -0
  16. package/dist/esm/index.d.ts.map +1 -0
  17. package/dist/esm/index.js +4 -0
  18. package/dist/esm/index.js.map +1 -0
  19. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +53 -0
  20. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -0
  21. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +56 -0
  22. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -0
  23. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +200 -0
  24. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -0
  25. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +228 -0
  26. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -0
  27. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +39 -0
  28. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -0
  29. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +39 -0
  30. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -0
  31. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +261 -0
  32. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -0
  33. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +412 -0
  34. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -0
  35. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +61 -0
  36. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -0
  37. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +65 -0
  38. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -0
  39. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +53 -0
  40. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -0
  41. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +54 -0
  42. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -0
  43. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts +43 -0
  44. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -0
  45. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js +73 -0
  46. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js.map +1 -0
  47. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +53 -0
  48. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -0
  49. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +114 -0
  50. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -0
  51. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +95 -0
  52. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -0
  53. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +102 -0
  54. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -0
  55. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +258 -0
  56. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -0
  57. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +241 -0
  58. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -0
  59. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts +241 -0
  60. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -0
  61. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +202 -0
  62. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -0
  63. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +82 -0
  64. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -0
  65. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +89 -0
  66. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -0
  67. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts +56 -0
  68. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -0
  69. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js +76 -0
  70. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js.map +1 -0
  71. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts +30 -0
  72. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -0
  73. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js +27 -0
  74. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js.map +1 -0
  75. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts +31 -0
  76. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -0
  77. package/dist/esm/playbooks/top_down.market-research/playbook.definition.js +26 -0
  78. package/dist/esm/playbooks/top_down.market-research/playbook.definition.js.map +1 -0
  79. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +254 -0
  80. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -0
  81. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +219 -0
  82. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -0
  83. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +180 -0
  84. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -0
  85. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +302 -0
  86. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -0
  87. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +249 -0
  88. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -0
  89. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +286 -0
  90. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -0
  91. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +248 -0
  92. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -0
  93. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +227 -0
  94. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -0
  95. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +45 -0
  96. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -0
  97. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +48 -0
  98. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -0
  99. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +250 -0
  100. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -0
  101. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +218 -0
  102. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -0
  103. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -0
  104. package/dist/knowledge/manifest.json +45 -0
  105. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +407 -0
  106. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +69 -0
  107. package/dist/knowledge/playbooks/bottom_up.build-dispatch/evaluation-protocol.json +1 -0
  108. package/dist/knowledge/playbooks/bottom_up.build-dispatch/evaluation-treatment.json +1 -0
  109. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +556 -0
  110. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +47 -0
  111. package/dist/knowledge/playbooks/bottom_up.build-scale/method.md +344 -0
  112. package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +43 -0
  113. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-protocol.json +1 -0
  114. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-treatment.json +1 -0
  115. package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +259 -0
  116. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +83 -0
  117. package/dist/knowledge/playbooks/bottom_up.domain-plan/structured-artifact-action.json +1 -0
  118. package/dist/knowledge/playbooks/bottom_up.foundation/method.md +321 -0
  119. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +79 -0
  120. package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +185 -0
  121. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +66 -0
  122. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +737 -0
  123. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +44 -0
  124. package/dist/knowledge/playbooks/refinement.document-facts/method.md +261 -0
  125. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +57 -0
  126. package/dist/knowledge/playbooks/top_down.brand-identity/method.md +151 -0
  127. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +124 -0
  128. package/dist/knowledge/playbooks/top_down.business-model/evaluation-protocol.json +1 -0
  129. package/dist/knowledge/playbooks/top_down.business-model/evaluation-treatment.json +1 -0
  130. package/dist/knowledge/playbooks/top_down.business-model/method.md +128 -0
  131. package/dist/knowledge/playbooks/top_down.business-model/playbook.json +102 -0
  132. package/dist/knowledge/playbooks/top_down.business-model/structured-artifact-action.json +1 -0
  133. package/dist/knowledge/playbooks/top_down.capability-map/evaluation-protocol.json +1 -0
  134. package/dist/knowledge/playbooks/top_down.capability-map/evaluation-treatment.json +1 -0
  135. package/dist/knowledge/playbooks/top_down.capability-map/method.md +239 -0
  136. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +73 -0
  137. package/dist/knowledge/playbooks/top_down.capability-map/structured-artifact-action.json +1 -0
  138. package/dist/knowledge/playbooks/top_down.compliance-posture/method.md +177 -0
  139. package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +95 -0
  140. package/dist/knowledge/playbooks/top_down.market-analysis/method.md +64 -0
  141. package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +49 -0
  142. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/method.md +56 -0
  143. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +40 -0
  144. package/dist/knowledge/playbooks/top_down.market-research/method.md +68 -0
  145. package/dist/knowledge/playbooks/top_down.market-research/playbook.json +42 -0
  146. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-protocol.json +1 -0
  147. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-treatment.json +1 -0
  148. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +239 -0
  149. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +69 -0
  150. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/structured-artifact-action.json +1 -0
  151. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-protocol.json +1 -0
  152. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-treatment.json +1 -0
  153. package/dist/knowledge/playbooks/top_down.phase-gate/method.md +96 -0
  154. package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +77 -0
  155. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-protocol.json +1 -0
  156. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-treatment.json +1 -0
  157. package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +53 -0
  158. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +61 -0
  159. package/dist/knowledge/playbooks/top_down.requirements-definition/structured-artifact-action.json +1 -0
  160. package/dist/knowledge/playbooks/top_down.scope-roadmap/evaluation-protocol.json +1 -0
  161. package/dist/knowledge/playbooks/top_down.scope-roadmap/evaluation-treatment.json +1 -0
  162. package/dist/knowledge/playbooks/top_down.scope-roadmap/method.md +280 -0
  163. package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +87 -0
  164. package/dist/knowledge/playbooks/top_down.scope-roadmap/structured-artifact-action.json +1 -0
  165. package/dist/knowledge/playbooks/top_down.value-proposition/method.md +204 -0
  166. package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +54 -0
  167. package/dist/knowledge/playbooks/top_down.vision-elicitation/evaluation-protocol.json +1 -0
  168. package/dist/knowledge/playbooks/top_down.vision-elicitation/evaluation-treatment.json +1 -0
  169. package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +146 -0
  170. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +120 -0
  171. package/dist/knowledge/playbooks/top_down.vision-elicitation/structured-artifact-action.json +1 -0
  172. package/dist/knowledge/references/application.database.migration-change-risk.md +28 -0
  173. package/dist/knowledge/references/assertions.authored-metadata.config.md +90 -0
  174. package/dist/knowledge/references/assertions.behaviors.wire-contracts.md +223 -0
  175. package/dist/knowledge/references/assertions.references.conventions.md +92 -0
  176. package/dist/knowledge/references/assertions.snapshot.validation.md +317 -0
  177. package/dist/knowledge/references/assertions.specification.config.md +287 -0
  178. package/dist/knowledge/references/brand.asset.config.md +167 -0
  179. package/dist/knowledge/references/brand.authored-metadata.config.md +51 -0
  180. package/dist/knowledge/references/brand.logo-direction.config.md +88 -0
  181. package/dist/knowledge/references/brand.name.config.md +46 -0
  182. package/dist/knowledge/references/brand.snapshot.config.md +76 -0
  183. package/dist/knowledge/references/brand.snapshot.validation.md +446 -0
  184. package/dist/knowledge/references/brand.visual-tone.config.md +56 -0
  185. package/dist/knowledge/references/build-plan.task-graph.config.md +198 -0
  186. package/dist/knowledge/references/business-model.authored-metadata.config.md +65 -0
  187. package/dist/knowledge/references/business-model.pricing-plan.config.md +122 -0
  188. package/dist/knowledge/references/business-model.references.conventions.md +99 -0
  189. package/dist/knowledge/references/business-model.snapshot.config.md +121 -0
  190. package/dist/knowledge/references/business-model.snapshot.validation.md +325 -0
  191. package/dist/knowledge/references/cli.market.generate-command.md +230 -0
  192. package/dist/knowledge/references/cli.market.utils.md +147 -0
  193. package/dist/knowledge/references/companion.introspection.behaviors.market.md +90 -0
  194. package/dist/knowledge/references/companion.introspection.handlers.market.md +42 -0
  195. package/dist/knowledge/references/companion.market.generation-service.md +270 -0
  196. package/dist/knowledge/references/companion.market.prompt-renderer.md +244 -0
  197. package/dist/knowledge/references/companion.technical-doc.service.md +809 -0
  198. package/dist/knowledge/references/engine.client-bundle.allow-list.md +125 -0
  199. package/dist/knowledge/references/engine.client-bundle.discipline.md +130 -0
  200. package/dist/knowledge/references/engine.client-bundle.external-connectors-public.discipline.md +55 -0
  201. package/dist/knowledge/references/engine.saas-technical-doc.config.md +215 -0
  202. package/dist/knowledge/references/engine.saas-website.config.md +331 -0
  203. package/dist/knowledge/references/example.authorization.unit-narrowing.declaration.md +24 -0
  204. package/dist/knowledge/references/example.backend.addon-wiring.module.md +55 -0
  205. package/dist/knowledge/references/example.backend.custom-operation.create-postfix.md +35 -0
  206. package/dist/knowledge/references/example.backend.operation.error-throw.md +17 -0
  207. package/dist/knowledge/references/example.config.app-shell.command-menu-items.md +63 -0
  208. package/dist/knowledge/references/example.config.app-shell.full.md +147 -0
  209. package/dist/knowledge/references/example.config.app-shell.hosted-components.md +45 -0
  210. package/dist/knowledge/references/example.config.app-shell.quick-switcher-fields.md +37 -0
  211. package/dist/knowledge/references/example.config.backend.billing-enable.md +20 -0
  212. package/dist/knowledge/references/example.config.backend.required-floors.md +46 -0
  213. package/dist/knowledge/references/example.config.design-system.full.md +162 -0
  214. package/dist/knowledge/references/example.config.navigation.full.md +71 -0
  215. package/dist/knowledge/references/example.config.provider.backend-scope-billing.md +27 -0
  216. package/dist/knowledge/references/example.data-seeding.minimal.md +114 -0
  217. package/dist/knowledge/references/example.email.template.minimal.md +54 -0
  218. package/dist/knowledge/references/example.engine.component-registration.lazy-load.md +16 -0
  219. package/dist/knowledge/references/example.engine.product-definitions.feature-and-profiles.md +146 -0
  220. package/dist/knowledge/references/example.flows-actors.chat-assistant.md +196 -0
  221. package/dist/knowledge/references/example.flows-actors.llm-agent-one-shot.md +174 -0
  222. package/dist/knowledge/references/example.i18n.label-generation.engine-barrel.md +15 -0
  223. package/dist/knowledge/references/example.infra.cdn.cloudflare.md +23 -0
  224. package/dist/knowledge/references/example.infra.cdn.generic.md +17 -0
  225. package/dist/knowledge/references/example.infra.environment-config.local.md +250 -0
  226. package/dist/knowledge/references/example.market.alternative.in-house-build.md +49 -0
  227. package/dist/knowledge/references/example.market.authored-metadata.md +32 -0
  228. package/dist/knowledge/references/example.market.buying-journey.core-icp.md +140 -0
  229. package/dist/knowledge/references/example.market.category.config.md +71 -0
  230. package/dist/knowledge/references/example.market.channel.community.md +39 -0
  231. package/dist/knowledge/references/example.market.feature-benefit.kano-threshold.md +67 -0
  232. package/dist/knowledge/references/example.market.feature-benefit.pain-reliever.md +65 -0
  233. package/dist/knowledge/references/example.market.icp.anti-target.md +47 -0
  234. package/dist/knowledge/references/example.market.icp.individual.md +82 -0
  235. package/dist/knowledge/references/example.market.icp.legal-entity-with-geographies.md +95 -0
  236. package/dist/knowledge/references/example.market.is-benefit-available.composition.md +40 -0
  237. package/dist/knowledge/references/example.market.job.emotional.md +27 -0
  238. package/dist/knowledge/references/example.market.job.functional.md +28 -0
  239. package/dist/knowledge/references/example.market.message-template.seeds.md +106 -0
  240. package/dist/knowledge/references/example.market.objection.pricing.md +39 -0
  241. package/dist/knowledge/references/example.market.persona.dmu-with-inheritance.md +62 -0
  242. package/dist/knowledge/references/example.market.persona.individual-self.md +51 -0
  243. package/dist/knowledge/references/example.market.positioning.per-icp.md +103 -0
  244. package/dist/knowledge/references/example.market.proof.metric.md +39 -0
  245. package/dist/knowledge/references/example.market.scoring.golden-case.md +46 -0
  246. package/dist/knowledge/references/example.market.scoring.no-coverage-zero.md +40 -0
  247. package/dist/knowledge/references/example.market.snapshot-validation.duplicate-journey-stage.md +36 -0
  248. package/dist/knowledge/references/example.market.snapshot-validation.errors-by-kind.md +55 -0
  249. package/dist/knowledge/references/example.market.snapshot-validation.objection-proof-benefit-mismatch.md +74 -0
  250. package/dist/knowledge/references/example.market.snapshot-validation.proof-without-support.md +32 -0
  251. package/dist/knowledge/references/example.market.snapshot-validation.threshold-without-job.md +44 -0
  252. package/dist/knowledge/references/example.market.snapshot.assembled.md +49 -0
  253. package/dist/knowledge/references/example.market.tone-of-voice.config.md +41 -0
  254. package/dist/knowledge/references/example.market.trigger.growth-milestone.md +43 -0
  255. package/dist/knowledge/references/example.module.companion-exports.full.md +142 -0
  256. package/dist/knowledge/references/example.module.registration.shared.md +16 -0
  257. package/dist/knowledge/references/example.module.relationships.actor-edge-back-to-scope-owner.md +47 -0
  258. package/dist/knowledge/references/example.module.relationships.discriminator.md +25 -0
  259. package/dist/knowledge/references/example.module.relationships.scope-membership-junction.md +25 -0
  260. package/dist/knowledge/references/example.provider.backend-module-shape.md +110 -0
  261. package/dist/knowledge/references/example.provider.contribution.backend-billing.md +12 -0
  262. package/dist/knowledge/references/example.provider.frontend-file-picker.contribution.md +30 -0
  263. package/dist/knowledge/references/example.provider.frontend-file-picker.module.md +21 -0
  264. package/dist/knowledge/references/example.rag.source-fields.declaration.md +83 -0
  265. package/dist/knowledge/references/example.rate-limit.custom-controller-surface.md +25 -0
  266. package/dist/knowledge/references/example.rate-limit.resource-operation-surface.md +24 -0
  267. package/dist/knowledge/references/example.resource.add-field.priority-enum.md +19 -0
  268. package/dist/knowledge/references/example.resource.add-resource.module-factory-map.md +21 -0
  269. package/dist/knowledge/references/example.resource.config-wiring.fk-relationship.md +33 -0
  270. package/dist/knowledge/references/example.resource.custom-view.read-host.md +28 -0
  271. package/dist/knowledge/references/example.resource.mcp-exposure.md +65 -0
  272. package/dist/knowledge/references/example.resource.reference-constraints.role-constrained.md +27 -0
  273. package/dist/knowledge/references/example.resource.ui-behavior.enum-badge.md +22 -0
  274. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +43 -0
  275. package/dist/knowledge/references/example.spec.composite-view.workspace.md +72 -0
  276. package/dist/knowledge/references/example.spec.feature.flag-with-codehandling.md +64 -0
  277. package/dist/knowledge/references/example.spec.frontend-component.prop-vocabulary.md +88 -0
  278. package/dist/knowledge/references/example.spec.resource.semantic-field.md +23 -0
  279. package/dist/knowledge/references/example.views.app-level.composite-views-config.md +19 -0
  280. package/dist/knowledge/references/example.views.chart-view.resource-owned.md +69 -0
  281. package/dist/knowledge/references/example.views.composite-view.host-embeds.md +31 -0
  282. package/dist/knowledge/references/example.views.composite-view.workspace.md +65 -0
  283. package/dist/knowledge/references/example.views.custom-view.execution-host.md +41 -0
  284. package/dist/knowledge/references/example.views.execution-view.resource-owned.md +25 -0
  285. package/dist/knowledge/references/external-connectors.app.frontend-provider-module.md +42 -0
  286. package/dist/knowledge/references/market.alternative.config.md +68 -0
  287. package/dist/knowledge/references/market.alternative.kind.md +32 -0
  288. package/dist/knowledge/references/market.authored-metadata.config.md +64 -0
  289. package/dist/knowledge/references/market.buying-journey.config.md +43 -0
  290. package/dist/knowledge/references/market.buying-journey.stage.md +33 -0
  291. package/dist/knowledge/references/market.category.config.md +63 -0
  292. package/dist/knowledge/references/market.channel.config.md +59 -0
  293. package/dist/knowledge/references/market.channel.kind.md +49 -0
  294. package/dist/knowledge/references/market.context-block.builder.md +544 -0
  295. package/dist/knowledge/references/market.context-block.response.md +57 -0
  296. package/dist/knowledge/references/market.feature-benefit.config.md +84 -0
  297. package/dist/knowledge/references/market.feature-benefit.kano.md +41 -0
  298. package/dist/knowledge/references/market.gain.config.md +50 -0
  299. package/dist/knowledge/references/market.generation.response.md +108 -0
  300. package/dist/knowledge/references/market.icp.config.md +162 -0
  301. package/dist/knowledge/references/market.icp.geographic-targeting.md +57 -0
  302. package/dist/knowledge/references/market.inherit-from.md +74 -0
  303. package/dist/knowledge/references/market.is-benefit-available.md +58 -0
  304. package/dist/knowledge/references/market.job.config.md +48 -0
  305. package/dist/knowledge/references/market.message-template.config.md +86 -0
  306. package/dist/knowledge/references/market.objection.config.md +56 -0
  307. package/dist/knowledge/references/market.objection.kind.md +34 -0
  308. package/dist/knowledge/references/market.pain.config.md +50 -0
  309. package/dist/knowledge/references/market.persona.config.md +64 -0
  310. package/dist/knowledge/references/market.positioning.config.md +84 -0
  311. package/dist/knowledge/references/market.proof.config.md +48 -0
  312. package/dist/knowledge/references/market.proof.kind.md +34 -0
  313. package/dist/knowledge/references/market.references.weighted-edges.md +105 -0
  314. package/dist/knowledge/references/market.scoring.fit.md +215 -0
  315. package/dist/knowledge/references/market.snapshot.config.md +34 -0
  316. package/dist/knowledge/references/market.snapshot.validation.md +1171 -0
  317. package/dist/knowledge/references/market.tone-of-voice.config.md +80 -0
  318. package/dist/knowledge/references/market.trigger.config.md +45 -0
  319. package/dist/knowledge/references/market.trigger.kind.md +35 -0
  320. package/dist/knowledge/references/placement-plan.config.md +330 -0
  321. package/dist/knowledge/references/platform.config.application-database.md +74 -0
  322. package/dist/knowledge/references/platform.config.application-modules.md +30 -0
  323. package/dist/knowledge/references/platform.config.backing-services.md +266 -0
  324. package/dist/knowledge/references/platform.config.cdn.md +167 -0
  325. package/dist/knowledge/references/platform.config.environment.deployment.md +263 -0
  326. package/dist/knowledge/references/platform.config.saas.md +405 -0
  327. package/dist/knowledge/references/presets.models.design-system.configuration.md +59 -0
  328. package/dist/knowledge/references/presets.models.design-system.source-config.md +72 -0
  329. package/dist/knowledge/references/presets.models.labelling.sections.md +64 -0
  330. package/dist/knowledge/references/presets.models.material.profile-contract.md +192 -0
  331. package/dist/knowledge/references/presets.models.material.runtime-policy.md +60 -0
  332. package/dist/knowledge/references/presets.models.surface-policy.defaults.md +613 -0
  333. package/dist/knowledge/references/presets.models.surface-policy.md +534 -0
  334. package/dist/knowledge/references/presets.models.surface-variant.md +56 -0
  335. package/dist/knowledge/references/requirements.authored-metadata.config.md +64 -0
  336. package/dist/knowledge/references/requirements.functional-requirement.config.md +68 -0
  337. package/dist/knowledge/references/requirements.non-functional-requirement.config.md +100 -0
  338. package/dist/knowledge/references/requirements.references.conventions.md +125 -0
  339. package/dist/knowledge/references/requirements.snapshot.config.md +73 -0
  340. package/dist/knowledge/references/requirements.snapshot.validation.md +333 -0
  341. package/dist/knowledge/references/roadmap.authored-metadata.config.md +64 -0
  342. package/dist/knowledge/references/roadmap.phase.config.md +149 -0
  343. package/dist/knowledge/references/roadmap.references.conventions.md +89 -0
  344. package/dist/knowledge/references/roadmap.snapshot.config.md +65 -0
  345. package/dist/knowledge/references/roadmap.snapshot.validation.md +325 -0
  346. package/dist/knowledge/references/saas.backend.app-config.backend-authored.md +32 -0
  347. package/dist/knowledge/references/saas.backend.application-initialization.assembly.md +38 -0
  348. package/dist/knowledge/references/saas.backend.billing.resolution-failure-reasons.md +45 -0
  349. package/dist/knowledge/references/saas.backend.custom-operation.authoritative-fields.md +53 -0
  350. package/dist/knowledge/references/saas.backend.custom-operation.transactional-core.md +120 -0
  351. package/dist/knowledge/references/saas.backend.domain-module.md +237 -0
  352. package/dist/knowledge/references/saas.backend.email-template.definition.md +69 -0
  353. package/dist/knowledge/references/saas.backend.flows-actors.a2a-agent-card.md +89 -0
  354. package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +118 -0
  355. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +82 -0
  356. package/dist/knowledge/references/saas.backend.flows-actors.invoke-agent.md +48 -0
  357. package/dist/knowledge/references/saas.backend.flows-actors.resource-read-tool.md +39 -0
  358. package/dist/knowledge/references/saas.backend.flows-actors.resource-write-tool.md +67 -0
  359. package/dist/knowledge/references/saas.backend.pdf-template.bindings.md +52 -0
  360. package/dist/knowledge/references/saas.backend.pdf-template.definition.md +113 -0
  361. package/dist/knowledge/references/saas.backend.rate-limit-service.check-policy.md +75 -0
  362. package/dist/knowledge/references/saas.backend.system-access-service.md +994 -0
  363. package/dist/knowledge/references/saas.data-seeding.admin-endpoints.md +59 -0
  364. package/dist/knowledge/references/saas.data-seeding.bootstrap-wiring.md +184 -0
  365. package/dist/knowledge/references/saas.data-seeding.definition-input.md +95 -0
  366. package/dist/knowledge/references/saas.data-seeding.modes.md +72 -0
  367. package/dist/knowledge/references/saas.data-seeding.run-ledger.md +198 -0
  368. package/dist/knowledge/references/saas.data-seeding.run-status.md +35 -0
  369. package/dist/knowledge/references/saas.data-seeding.schedule.md +91 -0
  370. package/dist/knowledge/references/saas.data-seeding.scope-iteration-strategy.md +46 -0
  371. package/dist/knowledge/references/saas.external-providers.backend-provider-registry.runtime-filter.md +55 -0
  372. package/dist/knowledge/references/saas.external-providers.document-extraction.applicability.md +26 -0
  373. package/dist/knowledge/references/saas.external-providers.embeddings.applicability.md +30 -0
  374. package/dist/knowledge/references/saas.external-providers.llm.model-configuration.md +124 -0
  375. package/dist/knowledge/references/saas.external-providers.llm.operation-key.md +49 -0
  376. package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +265 -0
  377. package/dist/knowledge/references/saas.frontend.app-level-component.vocabulary.md +148 -0
  378. package/dist/knowledge/references/saas.frontend.app-shell.hosted-components.md +145 -0
  379. package/dist/knowledge/references/saas.frontend.chart-view.inserted-declaration.md +80 -0
  380. package/dist/knowledge/references/saas.frontend.command-menu.omnibox.md +88 -0
  381. package/dist/knowledge/references/saas.frontend.command-menu.search-resource.md +109 -0
  382. package/dist/knowledge/references/saas.frontend.component-registration.entry.md +21 -0
  383. package/dist/knowledge/references/saas.frontend.composite-view.authoring.md +102 -0
  384. package/dist/knowledge/references/saas.frontend.composite-view.define-helper.md +31 -0
  385. package/dist/knowledge/references/saas.frontend.domain-module.md +31 -0
  386. package/dist/knowledge/references/saas.frontend.embedded-resource-descent.md +37 -0
  387. package/dist/knowledge/references/saas.frontend.execution-view.action-status-contract.md +172 -0
  388. package/dist/knowledge/references/saas.frontend.execution-view.action-status-contract.per-action-retry-loop.md +115 -0
  389. package/dist/knowledge/references/saas.frontend.execution-view.definition.md +172 -0
  390. package/dist/knowledge/references/saas.frontend.execution-view.dirty-bridge-contract.local-pane.md +109 -0
  391. package/dist/knowledge/references/saas.frontend.execution-view.dirty-bridge-contract.md +55 -0
  392. package/dist/knowledge/references/saas.frontend.execution-view.dirty-state-contract.md +151 -0
  393. package/dist/knowledge/references/saas.frontend.execution-view.failure-handling-contract.md +302 -0
  394. package/dist/knowledge/references/saas.frontend.execution-view.loading-aggregation.md +89 -0
  395. package/dist/knowledge/references/saas.frontend.execution-view.loading-aggregation.participation-prefetch.md +231 -0
  396. package/dist/knowledge/references/saas.frontend.execution-view.loading-aggregation.participation-prefetch.shell-data-hydrator.md +174 -0
  397. package/dist/knowledge/references/saas.frontend.execution-view.navigation-handling-and-embedding.md +96 -0
  398. package/dist/knowledge/references/saas.frontend.execution-view.navigation-handling-and-embedding.resolution.md +45 -0
  399. package/dist/knowledge/references/saas.frontend.execution-view.outcome-emission-contract.md +71 -0
  400. package/dist/knowledge/references/saas.frontend.execution-view.participation-and-anchor.md +80 -0
  401. package/dist/knowledge/references/saas.frontend.execution-view.three-zone-contract.md +147 -0
  402. package/dist/knowledge/references/saas.frontend.flows-actors-view.md +40 -0
  403. package/dist/knowledge/references/saas.frontend.form-fields.file-provider-constraints.md +80 -0
  404. package/dist/knowledge/references/saas.frontend.full-custom-view.definition.md +64 -0
  405. package/dist/knowledge/references/saas.frontend.inserted-view.identity-bindings-descriptor.md +149 -0
  406. package/dist/knowledge/references/saas.frontend.operation-key-and-resource-config-like.md +63 -0
  407. package/dist/knowledge/references/saas.frontend.quick-switcher.scope-field.md +102 -0
  408. package/dist/knowledge/references/saas.frontend.related-resource-embeds.md +86 -0
  409. package/dist/knowledge/references/saas.frontend.related-resource-preview.md +23 -0
  410. package/dist/knowledge/references/saas.frontend.related-resource-sections.md +28 -0
  411. package/dist/knowledge/references/saas.frontend.resource-header-title.md +43 -0
  412. package/dist/knowledge/references/saas.frontend.resource-layout-templates.md +215 -0
  413. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +531 -0
  414. package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +210 -0
  415. package/dist/knowledge/references/saas.frontend.resource-ui-behavior-preset-map.md +39 -0
  416. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +58 -0
  417. package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +118 -0
  418. package/dist/knowledge/references/saas.frontend.view-definition-scope.md +42 -0
  419. package/dist/knowledge/references/saas.market.generation-agent.md +104 -0
  420. package/dist/knowledge/references/saas.models.core-resource-operation.md +86 -0
  421. package/dist/knowledge/references/saas.models.data-mode-read-list.md +395 -0
  422. package/dist/knowledge/references/saas.models.engine-capabilities.md +114 -0
  423. package/dist/knowledge/references/saas.models.error-type.md +45 -0
  424. package/dist/knowledge/references/saas.models.external-data-pipeline.md +162 -0
  425. package/dist/knowledge/references/saas.models.feature-limit-semantic.md +51 -0
  426. package/dist/knowledge/references/saas.models.flows-actors.agent-configuration.md +127 -0
  427. package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +115 -0
  428. package/dist/knowledge/references/saas.models.flows-actors.agent-invocation.md +52 -0
  429. package/dist/knowledge/references/saas.models.flows-actors.agent-prompt-spec.md +188 -0
  430. package/dist/knowledge/references/saas.models.http-api-binding.md +237 -0
  431. package/dist/knowledge/references/saas.models.navigation.layout.md +149 -0
  432. package/dist/knowledge/references/saas.models.organization-unit-narrowing-containment.md +22 -0
  433. package/dist/knowledge/references/saas.models.organization-unit-narrowing-declaration.md +42 -0
  434. package/dist/knowledge/references/saas.models.polymorphism.optout-business-key.md +62 -0
  435. package/dist/knowledge/references/saas.models.polymorphism.variant-definition.md +74 -0
  436. package/dist/knowledge/references/saas.models.provider-capabilities.md +97 -0
  437. package/dist/knowledge/references/saas.models.rate-limit-configuration.md +67 -0
  438. package/dist/knowledge/references/saas.models.relationship-handling-contract.md +30 -0
  439. package/dist/knowledge/references/saas.models.relationship-handling-settings.md +62 -0
  440. package/dist/knowledge/references/saas.models.relationship-nature-and-models.md +112 -0
  441. package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +431 -0
  442. package/dist/knowledge/references/saas.models.resource-config.forwarded-label.md +88 -0
  443. package/dist/knowledge/references/saas.models.resource-config.operation-api-call.md +89 -0
  444. package/dist/knowledge/references/saas.models.resource-config.operation-base.md +79 -0
  445. package/dist/knowledge/references/saas.models.resource-config.operation-mcp-exposure.md +49 -0
  446. package/dist/knowledge/references/saas.models.resource-config.operation-path.md +27 -0
  447. package/dist/knowledge/references/saas.models.resource-config.operation-union.md +26 -0
  448. package/dist/knowledge/references/saas.models.resource-config.operation-variant-for-key.md +62 -0
  449. package/dist/knowledge/references/saas.models.resource-config.resource-configuration.md +124 -0
  450. package/dist/knowledge/references/saas.models.resource-config.resource-relationships-buckets.md +38 -0
  451. package/dist/knowledge/references/saas.models.resource-config.resources-registry.md +69 -0
  452. package/dist/knowledge/references/saas.models.resource-config.searchable-relation.md +89 -0
  453. package/dist/knowledge/references/saas.models.resource-config.system-access-policy.md +121 -0
  454. package/dist/knowledge/references/saas.models.resource-config.token-generation.md +145 -0
  455. package/dist/knowledge/references/saas.models.resource-field-identifier.md +25 -0
  456. package/dist/knowledge/references/saas.models.resource-operation-display-risk.md +77 -0
  457. package/dist/knowledge/references/saas.models.resource-operation-variant-runtime.md +58 -0
  458. package/dist/knowledge/references/saas.models.resource-primary-scope.md +36 -0
  459. package/dist/knowledge/references/saas.models.resource-relationship-access-scope.md +26 -0
  460. package/dist/knowledge/references/saas.models.resource-relationship-builder-parameters.md +100 -0
  461. package/dist/knowledge/references/saas.models.resource-relationship-cardinality.md +57 -0
  462. package/dist/knowledge/references/saas.models.resource-relationship-declaration.md +69 -0
  463. package/dist/knowledge/references/saas.models.resource-relationship-resolved-semantics.md +60 -0
  464. package/dist/knowledge/references/saas.models.resource-relationship-schema.md +172 -0
  465. package/dist/knowledge/references/saas.models.resource-server-instance.md +109 -0
  466. package/dist/knowledge/references/saas.models.resource-type.md +24 -0
  467. package/dist/knowledge/references/saas.models.schema-family-builder.md +242 -0
  468. package/dist/knowledge/references/saas.models.scope-membership.md +143 -0
  469. package/dist/knowledge/references/saas.models.shared-domain-module.md +36 -0
  470. package/dist/knowledge/references/saas.models.shared-saas-module.md +36 -0
  471. package/dist/knowledge/references/saas.public-runtime.contract.md +229 -0
  472. package/dist/knowledge/references/saas.rag.retrieval-bounds.md +106 -0
  473. package/dist/knowledge/references/saas.rag.retrieval-refusals.md +89 -0
  474. package/dist/knowledge/references/saas.rag.retrieval-request.md +130 -0
  475. package/dist/knowledge/references/saas.rag.retrieval-result.md +147 -0
  476. package/dist/knowledge/references/saas.rag.retrieval-scores.md +54 -0
  477. package/dist/knowledge/references/saas.specifications.application-document-fact-specification.contract.md +59 -0
  478. package/dist/knowledge/references/saas.specifications.application-document-publication.contract.md +74 -0
  479. package/dist/knowledge/references/saas.specifications.assurance-document-blueprint.contract.md +1158 -0
  480. package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +2602 -0
  481. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.catalog-spec-shared.md +180 -0
  482. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.discriminated-union.md +138 -0
  483. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-aggregate-offer.md +46 -0
  484. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-aggregate-rating.md +47 -0
  485. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-article.md +49 -0
  486. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-blog-posting.md +62 -0
  487. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-breadcrumb-list.md +46 -0
  488. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-faq-page.md +51 -0
  489. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-offer.md +46 -0
  490. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-organization.md +48 -0
  491. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-product.md +59 -0
  492. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-review.md +46 -0
  493. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-website.md +46 -0
  494. package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +530 -0
  495. package/dist/knowledge/references/saas.specifications.composite-view-specification.md +49 -0
  496. package/dist/knowledge/references/saas.specifications.error-message-specification.md +92 -0
  497. package/dist/knowledge/references/saas.specifications.family-specifications.md +109 -0
  498. package/dist/knowledge/references/saas.specifications.feature-specification.md +93 -0
  499. package/dist/knowledge/references/saas.specifications.frontend-component-spec-factory.md +113 -0
  500. package/dist/knowledge/references/saas.specifications.frontend-component-spec-model.md +366 -0
  501. package/dist/knowledge/references/saas.specifications.resource-frontend-configuration-aspect.md +41 -0
  502. package/dist/knowledge/references/saas.specifications.resource-operation-spec.md +1978 -0
  503. package/dist/knowledge/references/saas.specifications.resource-pdf-template-spec.md +58 -0
  504. package/dist/knowledge/references/saas.specifications.resource-spec-code-handling.md +49 -0
  505. package/dist/knowledge/references/saas.specifications.resource-spec-config.md +156 -0
  506. package/dist/knowledge/references/saas.specifications.resource-spec-factory.md +171 -0
  507. package/dist/knowledge/references/saas.specifications.resource-spec-frontend-config-type.md +54 -0
  508. package/dist/knowledge/references/saas.specifications.resource-spec-frontend-prose.md +171 -0
  509. package/dist/knowledge/references/saas.website.astro.bridge.md +262 -0
  510. package/dist/knowledge/references/saas.website.astro.head-renderer.md +271 -0
  511. package/dist/knowledge/references/saas.website.astro.headers-renderer.md +41 -0
  512. package/dist/knowledge/references/saas.website.astro.i18n-helper.md +121 -0
  513. package/dist/knowledge/references/saas.website.astro.label-key-collector.md +117 -0
  514. package/dist/knowledge/references/saas.website.astro.label-loader.md +377 -0
  515. package/dist/knowledge/references/saas.website.astro.llms-txt-server.md +46 -0
  516. package/dist/knowledge/references/saas.website.astro.pick-labels-for-page.md +90 -0
  517. package/dist/knowledge/references/saas.website.astro.robots-renderer.md +174 -0
  518. package/dist/knowledge/references/saas.website.astro.runtime-helper.md +187 -0
  519. package/dist/knowledge/references/saas.website.astro.site-context.md +141 -0
  520. package/dist/knowledge/references/saas.website.astro.sitemap-coverage.md +188 -0
  521. package/dist/knowledge/references/saas.website.astro.structured-data-renderer.md +174 -0
  522. package/dist/knowledge/references/saas.website.blog.bridge.md +396 -0
  523. package/dist/knowledge/references/saas.website.blog.collection-config.md +180 -0
  524. package/dist/knowledge/references/saas.website.blog.frontmatter.md +116 -0
  525. package/dist/knowledge/references/saas.website.blog.head-renderer.md +292 -0
  526. package/dist/knowledge/references/saas.website.blog.mdx-provider.md +100 -0
  527. package/dist/knowledge/references/saas.website.blog.post-renderer.md +291 -0
  528. package/dist/knowledge/references/saas.website.design-tokens.bundle.md +29 -0
  529. package/dist/knowledge/references/saas.website.design-tokens.colors.md +64 -0
  530. package/dist/knowledge/references/saas.website.design-tokens.radius.md +38 -0
  531. package/dist/knowledge/references/saas.website.factories.define-page-manifest.md +98 -0
  532. package/dist/knowledge/references/saas.website.factories.define-section.md +128 -0
  533. package/dist/knowledge/references/saas.website.label-keys.compose-helper.md +36 -0
  534. package/dist/knowledge/references/saas.website.label-keys.format.md +67 -0
  535. package/dist/knowledge/references/saas.website.label-pack.validator.md +206 -0
  536. package/dist/knowledge/references/saas.website.page-layout.component.md +217 -0
  537. package/dist/knowledge/references/saas.website.page-manifest.meta-label-keys.md +47 -0
  538. package/dist/knowledge/references/saas.website.page-manifest.route-path.md +49 -0
  539. package/dist/knowledge/references/saas.website.page-manifest.schema.md +186 -0
  540. package/dist/knowledge/references/saas.website.page-manifest.seo.md +46 -0
  541. package/dist/knowledge/references/saas.website.page.context.md +57 -0
  542. package/dist/knowledge/references/saas.website.primitives.button.md +123 -0
  543. package/dist/knowledge/references/saas.website.primitives.heading.md +103 -0
  544. package/dist/knowledge/references/saas.website.primitives.image.md +103 -0
  545. package/dist/knowledge/references/saas.website.primitives.internal-button.md +151 -0
  546. package/dist/knowledge/references/saas.website.primitives.internal-link.md +193 -0
  547. package/dist/knowledge/references/saas.website.primitives.link.md +78 -0
  548. package/dist/knowledge/references/saas.website.primitives.text.md +82 -0
  549. package/dist/knowledge/references/saas.website.refs.page.md +56 -0
  550. package/dist/knowledge/references/saas.website.refs.section.md +57 -0
  551. package/dist/knowledge/references/saas.website.root-config.navigation.md +37 -0
  552. package/dist/knowledge/references/saas.website.root-config.schema.md +192 -0
  553. package/dist/knowledge/references/saas.website.root-config.seo.md +98 -0
  554. package/dist/knowledge/references/saas.website.routing.localized-path.md +84 -0
  555. package/dist/knowledge/references/saas.website.runtime.context.md +174 -0
  556. package/dist/knowledge/references/saas.website.section.component.md +138 -0
  557. package/dist/knowledge/references/saas.website.section.context.md +63 -0
  558. package/dist/knowledge/references/saas.website.sections.category-enum.md +72 -0
  559. package/dist/knowledge/references/saas.website.sections.definition-schema.md +121 -0
  560. package/dist/knowledge/references/saas.website.seo.llms-txt-config.md +37 -0
  561. package/dist/knowledge/references/saas.website.seo.robots-config.md +106 -0
  562. package/dist/knowledge/references/saas.website.seo.sitemap-config.md +73 -0
  563. package/dist/knowledge/references/saas.website.structured-data.payload-shape.md +71 -0
  564. package/dist/knowledge/references/saas.website.use-label-by-key.hook.md +45 -0
  565. package/dist/knowledge/references/saas.website.use-label.hook.md +82 -0
  566. package/dist/knowledge/references/saas.website.use-page.hook.md +30 -0
  567. package/dist/knowledge/references/saas.website.use-runtime.hook.md +36 -0
  568. package/dist/knowledge/references/saas.website.use-section.hook.md +30 -0
  569. package/dist/knowledge/references/saas.website.use-tokens.hook.md +32 -0
  570. package/dist/knowledge/references/vision.authored-metadata.config.md +64 -0
  571. package/dist/knowledge/references/vision.constraint.config.md +66 -0
  572. package/dist/knowledge/references/vision.idea.config.md +45 -0
  573. package/dist/knowledge/references/vision.mission.config.md +46 -0
  574. package/dist/knowledge/references/vision.problem.config.md +51 -0
  575. package/dist/knowledge/references/vision.references.conventions.md +115 -0
  576. package/dist/knowledge/references/vision.snapshot.config.md +85 -0
  577. package/dist/knowledge/references/vision.snapshot.validation.md +226 -0
  578. package/dist/knowledge/references/vision.success-criterion.config.md +60 -0
  579. package/dist/knowledge/references/zod.decorators.chainable-runtime.md +550 -0
  580. package/dist/knowledge/references/zod.decorators.conditional-visibility.md +104 -0
  581. package/dist/knowledge/references/zod.decorators.data-categories.md +197 -0
  582. package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +436 -0
  583. package/dist/knowledge/references/zod.decorators.display-edit-modes.md +174 -0
  584. package/dist/knowledge/references/zod.decorators.enums.frontend-handling.md +101 -0
  585. package/dist/knowledge/references/zod.decorators.field-spec-params.md +317 -0
  586. package/dist/knowledge/references/zod.decorators.file-generation.md +36 -0
  587. package/dist/knowledge/references/zod.decorators.file-rag-source.md +56 -0
  588. package/dist/knowledge/references/zod.decorators.file-schema.md +319 -0
  589. package/dist/knowledge/references/zod.decorators.foreign-key-display-mode.md +83 -0
  590. package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +459 -0
  591. package/dist/knowledge/references/zod.decorators.primitive-ui.md +123 -0
  592. package/dist/knowledge/references/zod.decorators.rag-source.md +164 -0
  593. package/dist/knowledge/references/zod.decorators.schema-metadata.md +122 -0
  594. package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +152 -0
  595. package/dist/knowledge/references/zod.decorators.shared-structural-params.md +314 -0
  596. package/dist/knowledge/references/zod.decorators.structural-lifecycle-params.md +529 -0
  597. package/dist/knowledge/references/zod.factories.bigdecimal.md +155 -0
  598. package/dist/knowledge/references/zod.factories.code.md +127 -0
  599. package/dist/knowledge/references/zod.factories.duration.md +246 -0
  600. package/dist/knowledge/references/zod.factories.money.md +166 -0
  601. package/dist/knowledge/references/zod.factories.phone.md +88 -0
  602. package/dist/knowledge/references/zod.factories.range.md +174 -0
  603. package/dist/knowledge/registries/assurance-authority-bases.json +15 -0
  604. package/dist/knowledge/registries/framework-topics.json +5212 -0
  605. package/dist/knowledge/registries/playbooks.json +488 -0
  606. package/dist/knowledge/registries/source-tags.json +7664 -0
  607. package/dist/knowledge/rules/resource-schema-awareness.md +77 -0
  608. package/dist/knowledge/skills/INDEX.md +349 -0
  609. package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +415 -0
  610. package/dist/knowledge/skills/application-consumer-documentation-authoring/examples/domain-use-case-and-admin-task.example.md +49 -0
  611. package/dist/knowledge/skills/application-consumer-documentation-authoring/references/source-and-ownership-routing.md +52 -0
  612. package/dist/knowledge/skills/application-database-migrations/SKILL.md +218 -0
  613. package/dist/knowledge/skills/application-database-migrations/references/framework-application-database-api.md +84 -0
  614. package/dist/knowledge/skills/application-database-migrations/references/framework-migration-change-risk-api.md +37 -0
  615. package/dist/knowledge/skills/application-database-migrations/references/migration-refusals.md +64 -0
  616. package/dist/knowledge/skills/application-database-migrations/references/postgresql-vs-mongodb-obligations.md +34 -0
  617. package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +323 -0
  618. package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-unit-narrowing-declaration-api.md +84 -0
  619. package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +324 -0
  620. package/dist/knowledge/skills/backend-addon-wiring/references/backend-di-routing.md +7 -0
  621. package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +276 -0
  622. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +374 -0
  623. package/dist/knowledge/skills/backend-custom-operation/references/framework-error-handling-api.md +118 -0
  624. package/dist/knowledge/skills/backend-custom-operation/references/framework-operation-base-and-path-api.md +107 -0
  625. package/dist/knowledge/skills/backend-custom-operation/references/framework-transactional-core-api.md +134 -0
  626. package/dist/knowledge/skills/backend-custom-operation/references/operation-file-conventions.md +10 -0
  627. package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +192 -0
  628. package/dist/knowledge/skills/brand-logo-authoring/references/brand-authoring-decisions.md +55 -0
  629. package/dist/knowledge/skills/brand-logo-authoring/references/framework-brand-asset-api.md +184 -0
  630. package/dist/knowledge/skills/brand-logo-authoring/references/framework-brand-snapshot-api.md +279 -0
  631. package/dist/knowledge/skills/compliance-document-authoring/SKILL.md +346 -0
  632. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-governance.md +160 -0
  633. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +518 -0
  634. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-service-terms.md +158 -0
  635. package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-fact-specification-contract.md +95 -0
  636. package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-publication-contract.md +100 -0
  637. package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +1210 -0
  638. package/dist/knowledge/skills/compliance-document-authoring/references/framework-governed-document-after-drafting.md +40 -0
  639. package/dist/knowledge/skills/config-app-shell/SKILL.md +698 -0
  640. package/dist/knowledge/skills/config-app-shell/references/app-shell-surfaces.md +5 -0
  641. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +415 -0
  642. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-hosted-components-api.md +170 -0
  643. package/dist/knowledge/skills/config-app-shell/references/framework-command-menu-omnibox-api.md +212 -0
  644. package/dist/knowledge/skills/config-app-shell/references/framework-quick-switcher-scope-field-api.md +178 -0
  645. package/dist/knowledge/skills/config-design-system/SKILL.md +424 -0
  646. package/dist/knowledge/skills/config-design-system/references/design-system-file.md +10 -0
  647. package/dist/knowledge/skills/config-design-system/references/framework-design-system-configuration-api.md +77 -0
  648. package/dist/knowledge/skills/config-design-system/references/framework-material-profile-api.md +200 -0
  649. package/dist/knowledge/skills/config-design-system/references/framework-material-runtime-policy-api.md +68 -0
  650. package/dist/knowledge/skills/config-design-system/references/framework-surface-policy-api.md +1212 -0
  651. package/dist/knowledge/skills/config-design-system/references/surface-policy-authoring.md +92 -0
  652. package/dist/knowledge/skills/config-navigation/SKILL.md +249 -0
  653. package/dist/knowledge/skills/config-navigation/references/framework-navigation-layout-api.md +152 -0
  654. package/dist/knowledge/skills/config-navigation/references/navigation-zones.md +5 -0
  655. package/dist/knowledge/skills/config-saas/SKILL.md +209 -0
  656. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +221 -0
  657. package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +408 -0
  658. package/dist/knowledge/skills/config-saas/references/saas-config-scope.md +9 -0
  659. package/dist/knowledge/skills/config-saas-backend/SKILL.md +183 -0
  660. package/dist/knowledge/skills/config-saas-backend/references/framework-backend-authored-config-api.md +40 -0
  661. package/dist/knowledge/skills/configure-billing/SKILL.md +261 -0
  662. package/dist/knowledge/skills/configure-billing/references/config-chain-and-failure-map.md +90 -0
  663. package/dist/knowledge/skills/configure-billing/references/example-backend-provider-module-shape.md +122 -0
  664. package/dist/knowledge/skills/configure-billing/references/example-provider-contribution-and-backend-config.md +48 -0
  665. package/dist/knowledge/skills/configure-billing/references/framework-backend-provider-reachability-api.md +69 -0
  666. package/dist/knowledge/skills/configure-billing/references/framework-billing-resolution-failure-api.md +57 -0
  667. package/dist/knowledge/skills/email-add-template/SKILL.md +439 -0
  668. package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +9 -0
  669. package/dist/knowledge/skills/email-add-template/references/framework-email-template-api.md +72 -0
  670. package/dist/knowledge/skills/email-definition-wiring/SKILL.md +62 -0
  671. package/dist/knowledge/skills/email-labels-authoring/SKILL.md +64 -0
  672. package/dist/knowledge/skills/email-template-authoring/SKILL.md +62 -0
  673. package/dist/knowledge/skills/engine-component-registration/SKILL.md +257 -0
  674. package/dist/knowledge/skills/engine-component-registration/references/component-registration-file.md +7 -0
  675. package/dist/knowledge/skills/engine-component-registration/references/framework-component-registration-api.md +24 -0
  676. package/dist/knowledge/skills/engine-product-definitions/SKILL.md +429 -0
  677. package/dist/knowledge/skills/engine-product-definitions/references/framework-engine-product-definitions-api.md +287 -0
  678. package/dist/knowledge/skills/engine-product-definitions/references/product-registry-scope.md +5 -0
  679. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +491 -0
  680. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +227 -0
  681. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-named-a2a-agents-contract.md +143 -0
  682. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +368 -0
  683. package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +226 -0
  684. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +208 -0
  685. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +286 -0
  686. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +376 -0
  687. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +262 -0
  688. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-invocation-api.md +130 -0
  689. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-prompt-spec-api.md +214 -0
  690. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-operation-and-model-api.md +195 -0
  691. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/operation-key-selection.md +60 -0
  692. package/dist/knowledge/skills/frontend-cdn-publish/SKILL.md +237 -0
  693. package/dist/knowledge/skills/frontend-cdn-publish/references/cloudflare-and-operator-setup.md +56 -0
  694. package/dist/knowledge/skills/frontend-cdn-publish/references/framework-cdn-config-api.md +176 -0
  695. package/dist/knowledge/skills/i18n-label-generation/SKILL.md +261 -0
  696. package/dist/knowledge/skills/i18n-label-generation/references/framework-labelling-sections-api.md +67 -0
  697. package/dist/knowledge/skills/i18n-label-generation/references/label-placement.md +7 -0
  698. package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +269 -0
  699. package/dist/knowledge/skills/i18n-rerun-pipeline/references/framework-labelling-sections-api.md +67 -0
  700. package/dist/knowledge/skills/i18n-rerun-pipeline/references/i18n-routing.md +9 -0
  701. package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +245 -0
  702. package/dist/knowledge/skills/i18n-translation-rerun/references/framework-labelling-sections-api.md +67 -0
  703. package/dist/knowledge/skills/i18n-translation-rerun/references/translation-workflow.md +17 -0
  704. package/dist/knowledge/skills/infra-environment-config/SKILL.md +646 -0
  705. package/dist/knowledge/skills/infra-environment-config/references/framework-application-database-api.md +77 -0
  706. package/dist/knowledge/skills/infra-environment-config/references/framework-backing-services-api.md +282 -0
  707. package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +265 -0
  708. package/dist/knowledge/skills/infra-environment-config/references/infra-config-files.md +7 -0
  709. package/dist/knowledge/skills/journey-approve/SKILL.md +43 -0
  710. package/dist/knowledge/skills/journey-bootstrap-scope/SKILL.md +42 -0
  711. package/dist/knowledge/skills/journey-next/SKILL.md +42 -0
  712. package/dist/knowledge/skills/journey-report/SKILL.md +43 -0
  713. package/dist/knowledge/skills/journey-run/SKILL.md +55 -0
  714. package/dist/knowledge/skills/journey-status/SKILL.md +50 -0
  715. package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +370 -0
  716. package/dist/knowledge/skills/local-environment-bootstrap/references/initialization-recovery-recipe.md +50 -0
  717. package/dist/knowledge/skills/local-environment-bootstrap/references/local-environment-troubleshooting.md +409 -0
  718. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +247 -0
  719. package/dist/knowledge/skills/market-add-feature-benefit/SKILL.md +474 -0
  720. package/dist/knowledge/skills/market-add-feature-benefit/references/framework-feature-benefit-api.md +139 -0
  721. package/dist/knowledge/skills/market-alternatives/SKILL.md +543 -0
  722. package/dist/knowledge/skills/market-authoring-overview/SKILL.md +354 -0
  723. package/dist/knowledge/skills/market-authoring-overview/references/framework-market-references-api.md +138 -0
  724. package/dist/knowledge/skills/market-authoring-overview/references/framework-market-snapshot-api.md +129 -0
  725. package/dist/knowledge/skills/market-category/SKILL.md +290 -0
  726. package/dist/knowledge/skills/market-channels/SKILL.md +361 -0
  727. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +2752 -0
  728. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +2443 -0
  729. package/dist/knowledge/skills/market-generation-cli/SKILL.md +1484 -0
  730. package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +1230 -0
  731. package/dist/knowledge/skills/market-icp/SKILL.md +625 -0
  732. package/dist/knowledge/skills/market-jobs-pains-gains/SKILL.md +352 -0
  733. package/dist/knowledge/skills/market-message-templates-authoring/SKILL.md +415 -0
  734. package/dist/knowledge/skills/market-message-templates-authoring/references/framework-message-template-api.md +1439 -0
  735. package/dist/knowledge/skills/market-persona/SKILL.md +407 -0
  736. package/dist/knowledge/skills/market-positioning-authoring/SKILL.md +392 -0
  737. package/dist/knowledge/skills/market-positioning-authoring/references/framework-positioning-api.md +97 -0
  738. package/dist/knowledge/skills/market-proof-and-objection/SKILL.md +665 -0
  739. package/dist/knowledge/skills/market-scoring-interpretation/SKILL.md +620 -0
  740. package/dist/knowledge/skills/market-scoring-interpretation/references/framework-scoring-api.md +291 -0
  741. package/dist/knowledge/skills/market-snapshot-validation/SKILL.md +1706 -0
  742. package/dist/knowledge/skills/market-snapshot-validation/references/framework-snapshot-validation-api.md +1228 -0
  743. package/dist/knowledge/skills/market-tone-of-voice/SKILL.md +260 -0
  744. package/dist/knowledge/skills/market-triggers-and-journey/SKILL.md +579 -0
  745. package/dist/knowledge/skills/module-companion-exports/SKILL.md +318 -0
  746. package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +544 -0
  747. package/dist/knowledge/skills/module-registration/SKILL.md +212 -0
  748. package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +366 -0
  749. package/dist/knowledge/skills/module-registration/references/registry-files.md +9 -0
  750. package/dist/knowledge/skills/module-relationships/SKILL.md +523 -0
  751. package/dist/knowledge/skills/module-relationships/references/cross-resource-fk-checklist.md +7 -0
  752. package/dist/knowledge/skills/module-relationships/references/framework-resource-relationship-authoring-api.md +738 -0
  753. package/dist/knowledge/skills/pdf-template-authoring/SKILL.md +174 -0
  754. package/dist/knowledge/skills/pdf-template-authoring/references/framework-pdf-template-api.md +203 -0
  755. package/dist/knowledge/skills/pdf-template-authoring/references/framework-pdf-template-spec-api.md +62 -0
  756. package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +239 -0
  757. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-file-provider-constraints-api.md +90 -0
  758. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-module-api.md +50 -0
  759. package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +652 -0
  760. package/dist/knowledge/skills/rate-limit-authoring/references/framework-rate-limit-policy-api.md +182 -0
  761. package/dist/knowledge/skills/rate-limit-authoring/references/scope-key-and-bucket-conventions.md +137 -0
  762. package/dist/knowledge/skills/resource-add-field/SKILL.md +272 -0
  763. package/dist/knowledge/skills/resource-add-field/examples/add-priority-field-to-todos.example.md +153 -0
  764. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +845 -0
  765. package/dist/knowledge/skills/resource-add-module/SKILL.md +322 -0
  766. package/dist/knowledge/skills/resource-add-module/references/framework-new-module-wiring-api.md +67 -0
  767. package/dist/knowledge/skills/resource-add-module/references/module-scaffold-layout.md +15 -0
  768. package/dist/knowledge/skills/resource-add-resource/SKILL.md +222 -0
  769. package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +540 -0
  770. package/dist/knowledge/skills/resource-add-resource/references/scaffold-surfaces-checklist.md +25 -0
  771. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +370 -0
  772. package/dist/knowledge/skills/resource-config-wiring/references/config-change-routing.md +11 -0
  773. package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +622 -0
  774. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-operation-scope-enums-api.md +248 -0
  775. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +1769 -0
  776. package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +1209 -0
  777. package/dist/knowledge/skills/resource-custom-view/SKILL.md +228 -0
  778. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +693 -0
  779. package/dist/knowledge/skills/resource-external-data/SKILL.md +349 -0
  780. package/dist/knowledge/skills/resource-external-data/references/framework-external-data-pipeline-api.md +187 -0
  781. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +261 -0
  782. package/dist/knowledge/skills/resource-external-data/references/lane-selection.md +49 -0
  783. package/dist/knowledge/skills/resource-external-data/references/pipeline-destination-schema.md +43 -0
  784. package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +308 -0
  785. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-named-mcp-servers-contract.md +166 -0
  786. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-resource-mcp-exposure-contract.md +63 -0
  787. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-catalogue-withdrawal-and-verification.md +77 -0
  788. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-client-registration-postures.md +90 -0
  789. package/dist/knowledge/skills/resource-rag-source-fields/SKILL.md +424 -0
  790. package/dist/knowledge/skills/resource-rag-source-fields/references/corpus-field-selection.md +90 -0
  791. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +261 -0
  792. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-file-rag-source-api.md +117 -0
  793. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +597 -0
  794. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-source-decorator-api.md +181 -0
  795. package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +318 -0
  796. package/dist/knowledge/skills/resource-schema-authoring/examples/add-enum-field-with-ui.example.md +132 -0
  797. package/dist/knowledge/skills/resource-schema-authoring/examples/basic-resource-schema.example.md +62 -0
  798. package/dist/knowledge/skills/resource-schema-authoring/references/decorator-layer-map.md +63 -0
  799. package/dist/knowledge/skills/resource-schema-authoring/references/field-type-selection.md +70 -0
  800. package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +559 -0
  801. package/dist/knowledge/skills/resource-schema-authoring/references/framework-personal-data-category-api.md +245 -0
  802. package/dist/knowledge/skills/resource-schema-authoring/references/framework-polymorphic-resources-api.md +147 -0
  803. package/dist/knowledge/skills/resource-schema-authoring/references/framework-schema-family-api.md +247 -0
  804. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +164 -0
  805. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +327 -0
  806. package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +1286 -0
  807. package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +1080 -0
  808. package/dist/knowledge/skills/resource-schema-authoring/references/polymorphic-per-scope-resources.md +75 -0
  809. package/dist/knowledge/skills/resource-schema-authoring/references/schema-variants-and-discriminators.md +62 -0
  810. package/dist/knowledge/skills/resource-schema-authoring/references/shared-layer-decorator-checklist.md +69 -0
  811. package/dist/knowledge/skills/resource-schema-authoring/references/special-factories.md +45 -0
  812. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +389 -0
  813. package/dist/knowledge/skills/resource-ui-behavior/references/framework-conditional-visibility-api.md +106 -0
  814. package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +176 -0
  815. package/dist/knowledge/skills/resource-ui-behavior/references/framework-enum-frontend-handling-api.md +103 -0
  816. package/dist/knowledge/skills/resource-ui-behavior/references/framework-foreign-key-ui-api.md +97 -0
  817. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +839 -0
  818. package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +461 -0
  819. package/dist/knowledge/skills/resource-ui-behavior/references/framework-primitive-ui-api.md +125 -0
  820. package/dist/knowledge/skills/resource-ui-behavior/references/framework-related-resource-embeds-api.md +245 -0
  821. package/dist/knowledge/skills/resource-ui-behavior/references/framework-resource-layout-templates-api.md +302 -0
  822. package/dist/knowledge/skills/resource-ui-behavior/references/ui-layer-boundaries.md +13 -0
  823. package/dist/knowledge/skills/seeding-authoring/SKILL.md +569 -0
  824. package/dist/knowledge/skills/seeding-authoring/references/data-seeding-mode-picker.md +154 -0
  825. package/dist/knowledge/skills/seeding-authoring/references/framework-data-seeding-api.md +176 -0
  826. package/dist/knowledge/skills/seeding-operations/SKILL.md +505 -0
  827. package/dist/knowledge/skills/seeding-operations/references/data-seeding-admin-runbook.md +337 -0
  828. package/dist/knowledge/skills/seeding-operations/references/data-seeding-cron-scheduler.md +171 -0
  829. package/dist/knowledge/skills/seeding-operations/references/framework-data-seeding-operations-api.md +662 -0
  830. package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +134 -0
  831. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +65 -0
  832. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +127 -0
  833. package/dist/knowledge/skills/spec-catalog-authoring/SKILL.md +726 -0
  834. package/dist/knowledge/skills/spec-catalog-authoring/references/catalog-spec-pattern-overview.md +242 -0
  835. package/dist/knowledge/skills/spec-companion-exports/SKILL.md +362 -0
  836. package/dist/knowledge/skills/spec-companion-exports/references/companion-export-checklist.md +8 -0
  837. package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +533 -0
  838. package/dist/knowledge/skills/spec-component-update/SKILL.md +315 -0
  839. package/dist/knowledge/skills/spec-component-update/references/component-spec-props.md +8 -0
  840. package/dist/knowledge/skills/spec-component-update/references/framework-frontend-component-spec-api.md +481 -0
  841. package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +283 -0
  842. package/dist/knowledge/skills/spec-composite-view-update/references/composite-spec-sections.md +5 -0
  843. package/dist/knowledge/skills/spec-composite-view-update/references/framework-composite-view-specification-api.md +51 -0
  844. package/dist/knowledge/skills/spec-family-update/SKILL.md +300 -0
  845. package/dist/knowledge/skills/spec-family-update/references/family-spec-routing.md +13 -0
  846. package/dist/knowledge/skills/spec-family-update/references/framework-error-message-specifications-api.md +108 -0
  847. package/dist/knowledge/skills/spec-family-update/references/framework-family-specifications-api.md +111 -0
  848. package/dist/knowledge/skills/spec-feature-update/SKILL.md +306 -0
  849. package/dist/knowledge/skills/spec-feature-update/references/feature-spec-scope.md +5 -0
  850. package/dist/knowledge/skills/spec-feature-update/references/framework-feature-specification-api.md +95 -0
  851. package/dist/knowledge/skills/spec-resource-update/SKILL.md +220 -0
  852. package/dist/knowledge/skills/spec-resource-update/references/framework-field-spec-params-api.md +319 -0
  853. package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +2610 -0
  854. package/dist/knowledge/skills/spec-resource-update/references/resource-spec-field-routing.md +12 -0
  855. package/dist/knowledge/skills/spec-update-after-change/SKILL.md +195 -0
  856. package/dist/knowledge/skills/spec-update-after-change/references/framework-spec-factory-api.md +173 -0
  857. package/dist/knowledge/skills/spec-update-after-change/references/spec-maintenance-by-surface.md +33 -0
  858. package/dist/knowledge/skills/spec-update-after-change/references/surface-to-spec-routing.md +14 -0
  859. package/dist/knowledge/skills/views-add-composite-view/SKILL.md +259 -0
  860. package/dist/knowledge/skills/views-add-composite-view/references/composite-view-routing.md +10 -0
  861. package/dist/knowledge/skills/views-add-composite-view/references/framework-inserted-view-identity-api.md +151 -0
  862. package/dist/knowledge/skills/views-add-custom-view/SKILL.md +225 -0
  863. package/dist/knowledge/skills/views-add-custom-view/references/custom-view-routing.md +10 -0
  864. package/dist/knowledge/skills/views-add-custom-view/references/framework-view-scope-and-full-custom-api.md +107 -0
  865. package/dist/knowledge/skills/views-app-level/SKILL.md +201 -0
  866. package/dist/knowledge/skills/views-app-level/references/app-level-views-routing.md +9 -0
  867. package/dist/knowledge/skills/views-app-level/references/framework-view-scope-and-full-custom-api.md +107 -0
  868. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +264 -0
  869. package/dist/knowledge/skills/views-chart-authoring/references/chart-view-checklist.md +7 -0
  870. package/dist/knowledge/skills/views-chart-authoring/references/framework-chart-view-contracts-api.md +82 -0
  871. package/dist/knowledge/skills/views-chart-authoring/references/framework-inserted-view-identity-api.md +152 -0
  872. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +302 -0
  873. package/dist/knowledge/skills/views-composite-authoring/references/composite-embedding-checklist.md +23 -0
  874. package/dist/knowledge/skills/views-composite-authoring/references/framework-composite-view-contracts-api.md +133 -0
  875. package/dist/knowledge/skills/views-composite-authoring/references/framework-inserted-view-identity-api.md +152 -0
  876. package/dist/knowledge/skills/views-execution-authoring/SKILL.md +209 -0
  877. package/dist/knowledge/skills/views-execution-authoring/references/execution-view-checklist.md +7 -0
  878. package/dist/knowledge/skills/views-execution-authoring/references/framework-execution-view-contracts-api.md +389 -0
  879. package/dist/knowledge/skills/views-execution-authoring/references/framework-inserted-view-identity-api.md +152 -0
  880. package/dist/knowledge/skills/website-anonymous-session/SKILL.md +444 -0
  881. package/dist/knowledge/skills/website-blog-authoring/SKILL.md +587 -0
  882. package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +1426 -0
  883. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +553 -0
  884. package/dist/knowledge/skills/website-bundle-discipline/references/example-website-button-override.md +52 -0
  885. package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +357 -0
  886. package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +511 -0
  887. package/dist/knowledge/skills/website-factory-advanced/SKILL.md +376 -0
  888. package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +304 -0
  889. package/dist/knowledge/skills/website-label-pack/SKILL.md +390 -0
  890. package/dist/knowledge/skills/website-layout-overrides/SKILL.md +461 -0
  891. package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +264 -0
  892. package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +414 -0
  893. package/dist/knowledge/skills/website-navigation-authoring/references/worked-examples-header-footer.md +366 -0
  894. package/dist/knowledge/skills/website-page-authoring/SKILL.md +420 -0
  895. package/dist/knowledge/skills/website-page-variants/SKILL.md +256 -0
  896. package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +302 -0
  897. package/dist/knowledge/skills/website-section-contact/SKILL.md +950 -0
  898. package/dist/knowledge/skills/website-section-contact/references/define-website-section-api.md +579 -0
  899. package/dist/knowledge/skills/website-section-cta/SKILL.md +822 -0
  900. package/dist/knowledge/skills/website-section-cta/references/define-website-section-api.md +579 -0
  901. package/dist/knowledge/skills/website-section-faq/SKILL.md +917 -0
  902. package/dist/knowledge/skills/website-section-faq/references/define-website-section-api.md +579 -0
  903. package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +878 -0
  904. package/dist/knowledge/skills/website-section-feature-benefit-summary/references/define-website-section-api.md +579 -0
  905. package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +895 -0
  906. package/dist/knowledge/skills/website-section-feature-detail/references/define-website-section-api.md +579 -0
  907. package/dist/knowledge/skills/website-section-footer-cta/SKILL.md +814 -0
  908. package/dist/knowledge/skills/website-section-footer-cta/references/define-website-section-api.md +579 -0
  909. package/dist/knowledge/skills/website-section-hero/SKILL.md +944 -0
  910. package/dist/knowledge/skills/website-section-hero/references/define-website-section-api.md +583 -0
  911. package/dist/knowledge/skills/website-section-pricing/SKILL.md +934 -0
  912. package/dist/knowledge/skills/website-section-pricing/references/define-website-section-api.md +579 -0
  913. package/dist/knowledge/skills/website-section-social-proof/SKILL.md +912 -0
  914. package/dist/knowledge/skills/website-section-social-proof/references/define-website-section-api.md +579 -0
  915. package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +624 -0
  916. package/dist/knowledge/skills/website-seo-aeo-geo/references/aeo-api.md +633 -0
  917. package/dist/knowledge/skills/website-seo-aeo-geo/references/geo-api.md +193 -0
  918. package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +790 -0
  919. package/dist/knowledge/topic-index.json +17510 -0
  920. package/dist/tsconfig.build.tsbuildinfo +1 -0
  921. package/dist/tsconfig.tsbuildinfo +1 -0
  922. package/package.json +49 -0
@@ -0,0 +1,1978 @@
1
+ # saas.specifications.resource-operation-spec
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-specifications`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-specifications`
10
+
11
+ ```typescript
12
+ *
13
+ * Companion-facing semantic prose for operations and variants (`resourceSpecification().operations`).
14
+ *
15
+ * **Per-variant** semantics (`ResourceOperationVariantSpecification`):
16
+ * Provides sparse overlays for an operation's business prose and, when an
17
+ * HTTP response shape genuinely differs, its payload examples. URLs, DTO
18
+ * shape, and authorization rules remain structural contracts; prose explains
19
+ * what the operation accomplishes in business terms, while examples make the
20
+ * concrete transport representation understandable.
21
+ *
22
+ * **Per-operation** map types (`ResourceOperationSpecification`, maps) layer
23
+ * shared operation meaning plus optional named variants (`admin`, `summary`,
24
+ * `context`, …) aligned with the resource configuration vocabulary.
25
+ *
26
+ * **HTTP documentation** fields on `ResourceOperationSpecification`
27
+ * (`responseStatuses`, `errorScenarios`, `idempotent`, `rateLimitNote`,
28
+ * `examples`) carry the transport-level outcomes the OpenAPI generator emits
29
+ * as `responses` / `examples` / `x-idempotent`. Response outcomes are
30
+ * per-operation. Base examples apply to every variant unless a variant owns a
31
+ * complete replacement, preventing a full DTO example from leaking into a
32
+ * context or summary response. HTTP-only fields are intentionally excluded
33
+ * from frontend-view specs, which are not HTTP operations.
34
+ */
35
+ export interface ResourceOperationVariantSpecification {
36
+ /** Business intent of the operation when this variant differs from the base operation. */
37
+ purpose?: string;
38
+ /** Observable business result once the operation succeeds. */
39
+ outcome?: string;
40
+ /** Guidance about when this operation is the right choice. */
41
+ whenToUse?: string;
42
+ /** Relative weight of this operation in the resource understanding. */
43
+ importance?: FieldSemanticImportance;
44
+ /**
45
+ * Override the resource-level label {@link LabelAudience} for THIS operation's
46
+ * generated labels. Use when a mostly-end-user resource exposes an admin-only
47
+ * operation (or vice-versa) so its copy adopts the right register without
48
+ * reclassifying the whole resource. Omit to inherit the resource's `audience`.
49
+ */
50
+ audienceOverride?: LabelAudience;
51
+ /**
52
+ * Variant-specific OpenAPI examples. When present, these REPLACE the base
53
+ * operation `examples` for this variant; they never merge. Use this where a
54
+ * context or summary response has a different schema from the default path.
55
+ */
56
+ examples?: ResourceOperationExampleSpecification[];
57
+ }
58
+
59
+ /**
60
+ * Variant map for one operation.
61
+ *
62
+ * `default` represents the default/no-explicit-variant path. Named variant keys
63
+ * (`admin`, `summary`, `context`, `internal`, ...) mirror the authored
64
+ * operation-variant vocabulary instead of flattening them into synthetic tuples.
65
+ */
66
+ export type ResourceOperationSpecificationVariants = Record<string, ResourceOperationVariantSpecification | undefined> & {
67
+ default?: ResourceOperationVariantSpecification;
68
+ };
69
+
70
+ /**
71
+ * Frontend-view variants preserve business semantics but deliberately exclude
72
+ * HTTP examples: a frontend view is not an API operation and must not become a
73
+ * second authoring path for generated OpenAPI payloads.
74
+ */
75
+ export type ResourceFrontendViewSpecificationVariants = Record<
76
+ string,
77
+ Omit<ResourceOperationVariantSpecification, 'examples'> | undefined
78
+ > & {
79
+ default?: Omit<ResourceOperationVariantSpecification, 'examples'>;
80
+ };
81
+
82
+ /**
83
+ * Import-oriented metadata for the email fired by a resource operation.
84
+ *
85
+ * Lets downstream transposer/code-generation layers point at the real event
86
+ * payload schema without re-reading the resource's backend code.
87
+ */
88
+ export interface ResourceOperationEmailSpecificationCodeHandling {
89
+ /** Public Zod schema symbol that describes the event payload of the email. */
90
+ eventDataSchemaSymbol?: CodeSymbolRef;
91
+ /** Public TypeScript type symbol when the payload type is split from its Zod schema. */
92
+ eventDataTypeSymbol?: CodeSymbolRef;
93
+ /** Extra supporting symbols (builders, renderers) that transposer prompts need. */
94
+ supportingSymbols?: CodeSymbolRef[];
95
+ /** Companion/transposer caveats that must survive serialization. */
96
+ notes?: string[];
97
+ }
98
+
99
+ /**
100
+ * Semantic overlay for ONE email delivery fired by a resource operation.
101
+ *
102
+ * Models the engine fan-out faithfully: every entry in the runtime
103
+ * `userNotifications[]` array with `channel === EMAIL` is one delivery, and
104
+ * the runtime constructs a distinct template-ref path for each
105
+ * `(variantKey, targetType, customNotificationRef)` combination through the
106
+ * notifications dispatcher (`email.{resourceId}.{op}.{variant?}.{target-kebab}_{customRef?}`).
107
+ *
108
+ * Authoring sites declare one delivery per such combination so:
109
+ * - companion prompts know exactly how many template files exist for the operation,
110
+ * - translators can author per-delivery overrides when the audience changes the copy,
111
+ * - transposers can compute the runtime template-ref path from the spec without
112
+ * re-reading the resource configuration code.
113
+ *
114
+ * The parent `ResourceOperationEmailSpecification` carries shared semantics
115
+ * (purpose, tone, default text slots, event data); per-delivery overrides
116
+ * layer on top via `purposeOverride`, `textSlotsOverrides`,
117
+ * `additionalBusinessConstraints`. Omit overrides when the delivery shares
118
+ * the parent copy verbatim — that is the common case.
119
+ */
120
+ export interface ResourceOperationEmailDeliverySpecification {
121
+ /**
122
+ * Audience description: who receives this delivery and why. Required —
123
+ * the deliveries axis exists specifically to distinguish audiences (creator
124
+ * vs assignee vs admin recipient, …), so an undocumented audience defeats
125
+ * the purpose of fanning out.
126
+ */
127
+ audience: string;
128
+ /**
129
+ * Target type from the runtime `UserNotificationDefinition.target` (see
130
+ * `CoreUserNotificationTarget` — `USERS_CUSTOM`, `USER_SELF`,
131
+ * `ORGANIZATION_USERS`, …). The dispatcher kebab-cases this and appends
132
+ * it to the template-ref path, so spec authors must echo the exact runtime
133
+ * target so the computed path stays truthful.
134
+ */
135
+ targetRef: CoreUserNotificationTarget | (string & {});
136
+ /**
137
+ * Operation variant this delivery belongs to. `undefined` means the default
138
+ * variant (no `variantKey` segment in the runtime path). Maps to
139
+ * `variantKey` on the runtime variant when present.
140
+ */
141
+ variantRef?: string;
142
+ /**
143
+ * Distinguishes deliveries when the same `(variantRef, targetRef)` fires
144
+ * multiple emails. Maps 1:1 to `customNotificationRef` on the runtime
145
+ * `UserNotificationDefinition`. Required by the engine when more than one
146
+ * `USERS_CUSTOM` notification appears in the same operation (to make the
147
+ * template paths unique); the spec validator mirrors that contract.
148
+ */
149
+ customDeliveryRef?: string;
150
+ /**
151
+ * Stable `SystemEmailTemplateRef` THIS delivery resolves to, when the
152
+ * runtime template path corresponds to an entry registered in
153
+ * `SystemEmailTemplateRegistry` (system-level emails such as
154
+ * `WELCOME_EMAIL`, `ORGANIZATION_INVITATION`, …). Use it to cross-link a
155
+ * resource-initiated trigger to its authored
156
+ * `SystemEmailTemplateSpecification` overlay in companion prompts.
157
+ *
158
+ * Lives per-delivery (not on `codeHandling`) because the runtime
159
+ * template-ref path is per-delivery: every authored
160
+ * `(variantRef, targetRef, customDeliveryRef)` triple resolves to ONE
161
+ * concrete template, so each delivery either points at a registered
162
+ * `SystemEmailTemplateRef` or — for resource-local templates that live
163
+ * outside `SystemEmailTemplateRegistry` (e.g. Your Application
164
+ * `email.todos.change_status.users-custom_notify-creator`) — leaves the
165
+ * field undefined.
166
+ *
167
+ * Cross-validated at module load against `SystemEmailTemplateRegistry` so
168
+ * a typo or stale ref fails closed instead of leaking a dangling cross-
169
+ * link into companion prompts. Typed as the enum to give authors
170
+ * autocomplete and eliminate the silent-string-identity anti-pattern.
171
+ */
172
+ systemEmailTemplateRef?: SystemEmailTemplateRef;
173
+ /**
174
+ * Optional per-delivery overrides for translatable text slots. When a key
175
+ * is present here, it replaces the parent `textSlots[key]` for THIS
176
+ * delivery only (e.g., creator and assignee share the parent subject
177
+ * normally, but the admin variant for the creator uses a different one).
178
+ * Omit entirely when the delivery uses the parent copy verbatim.
179
+ */
180
+ textSlotsOverrides?: TranslationSlotSpecificationMap;
181
+ /**
182
+ * Per-delivery override for `purpose` when this delivery has its own intent
183
+ * distinct from the parent (e.g., the admin variant explains a managerial
184
+ * intervention rather than a self-progress signal). Falls back to the
185
+ * parent `purpose` when omitted.
186
+ */
187
+ purposeOverride?: string;
188
+ /**
189
+ * Domain/compliance caveats that apply to THIS delivery only, layered on
190
+ * top of the parent `businessConstraints` (which apply to all deliveries).
191
+ */
192
+ additionalBusinessConstraints?: string[];
193
+ /** Companion/transposer caveats specific to this delivery. */
194
+ notes?: string[];
195
+ }
196
+
197
+ /**
198
+ * Semantic overlay for the email fired by a resource operation.
199
+ *
200
+ * Follows the same authoring shape as `SystemEmailTemplateSpecification`:
201
+ * `purpose` and `tone` are plain authoring prose, while every translatable
202
+ * fragment (subject, previewText, ctaLabel, heading, body, …) lives inside
203
+ * `textSlots`. `eventData` documents the meaning of the payload used to render
204
+ * the email so translators know which runtime values will land in each slot.
205
+ *
206
+ * A resource-initiated email is always anchored to its operation: the same
207
+ * action decides what is sent, to whom, and why, so the companion resolves the
208
+ * wording through the operation spec instead of a parallel family.
209
+ *
210
+ * **Engine-parity contract for `deliveries`**. The runtime fans out one email
211
+ * per entry in `userNotifications[]` with `channel === EMAIL`, computing a
212
+ * distinct template-ref path per `(variantKey, target, customNotificationRef)`
213
+ * combination. The spec layer mirrors this faithfully: every such runtime
214
+ * delivery must be authored as one entry in `deliveries`, so the spec is
215
+ * never silent about a real runtime template path. A single-delivery email
216
+ * still needs one `deliveries` entry — the array is required so the engine
217
+ * fan-out semantics are explicit at every authoring site, not implicit in
218
+ * the absence of the field.
219
+ */
220
+ export interface ResourceOperationEmailSpecification {
221
+ /** Why this operation fires an email (shared intent across all deliveries). */
222
+ purpose: string;
223
+ /** Expected voice/posture for the generated copy (urgent, reassuring, informational, ...). */
224
+ tone: string;
225
+ /** Situations where this email must be sent alongside the operation. */
226
+ useWhen?: string;
227
+ /** Situations where this email should not fire (e.g. reassignment to the same user). */
228
+ avoidWhen?: string;
229
+ /**
230
+ * Translatable text slots for the email (`subject`, `previewText`,
231
+ * `ctaLabel`, or any template-specific named slot) with per-slot meaning
232
+ * for translators. `subject` is required because every transactional email
233
+ * needs a subject line. Per-delivery overrides live on each
234
+ * `deliveries[i].textSlotsOverrides`.
235
+ */
236
+ textSlots: TranslationSlotSpecificationMap;
237
+ /** Meaning of the event payload this email renders with (shared across deliveries). */
238
+ eventData?: TranslationSlotSpecification;
239
+ /** Domain/compliance caveats that matter beyond the operation's own constraints. */
240
+ businessConstraints?: string[];
241
+ /**
242
+ * Explicit fan-out: one entry per runtime `userNotifications[]` email
243
+ * delivery. At least one entry is required when an `email` block is
244
+ * authored — see the JSDoc on the parent interface for the engine-parity
245
+ * rationale. The validator enforces uniqueness on
246
+ * `(variantRef, targetRef, customDeliveryRef)` triples and rejects
247
+ * duplicates that would compute the same runtime template-ref path.
248
+ */
249
+ deliveries: ResourceOperationEmailDeliverySpecification[];
250
+ /** Import-oriented coding/transposition metadata. */
251
+ codeHandling?: ResourceOperationEmailSpecificationCodeHandling;
252
+ }
253
+
254
+ /**
255
+ * Import-oriented metadata for the notification fired by a resource operation.
256
+ */
257
+ export interface ResourceOperationNotificationSpecificationCodeHandling {
258
+ /**
259
+ * Public enum exposing the channel vocabulary that each
260
+ * `deliveries[i].channelRef` is drawn from (for example
261
+ * `CoreUserNotificationChannel`). Custom channels remain expressible as raw
262
+ * strings on `deliveries[i].channelRef`, but declaring the owning enum lets
263
+ * transposer layers import the canonical members when generating
264
+ * notification dispatch code.
265
+ */
266
+ channelEnum?: CodeSymbolRef;
267
+ /** Public Zod schema symbol describing the notification event payload. */
268
+ eventDataSchemaSymbol?: CodeSymbolRef;
269
+ /** Public TypeScript type symbol when the payload type is split from its Zod schema. */
270
+ eventDataTypeSymbol?: CodeSymbolRef;
271
+ /** Extra supporting symbols that transposer prompts need. */
272
+ supportingSymbols?: CodeSymbolRef[];
273
+ /** Companion/transposer caveats that must survive serialization. */
274
+ notes?: string[];
275
+ }
276
+
277
+ /**
278
+ * Semantic overlay for ONE in-app notification delivery fired by a resource
279
+ * operation.
280
+ *
281
+ * Models the engine fan-out faithfully: every entry in the runtime
282
+ * `userNotifications[]` array whose `channel` is NOT `EMAIL` is one in-app
283
+ * notification delivery (FRONT_END_SUCCESS toast for the actor, WEBSOCKET push
284
+ * to the activity feed, SMS / PUSH when implemented, …). Each delivery is
285
+ * its own (target, channel) pair at runtime; the spec layer mirrors this so
286
+ * companion prompts know exactly which surfaces the operation actually
287
+ * touches, and translators can author per-delivery copy when a specific
288
+ * channel needs different wording (e.g. SMS character limits vs WebSocket
289
+ * activity-feed prose).
290
+ */
291
+ export interface ResourceOperationNotificationDeliverySpecification {
292
+ /**
293
+ * Audience description: who receives this delivery (the actor themselves
294
+ * via FRONT_END_SUCCESS, the rest of the organization via WEBSOCKET, …).
295
+ * Required — the deliveries axis exists specifically to distinguish
296
+ * audiences, so an undocumented audience defeats the purpose of fanning
297
+ * out.
298
+ */
299
+ audience: string;
300
+ /**
301
+ * Channel the runtime fires through (e.g. `FRONT_END_SUCCESS`, `WEBSOCKET`,
302
+ * `SMS`, `PUSH`). Authoring sites should use `CoreUserNotificationChannel`
303
+ * members for built-in channels (autocomplete + typo-protection); custom
304
+ * channels remain expressible as raw strings.
305
+ */
306
+ channelRef: CoreUserNotificationChannel | (string & {});
307
+ /**
308
+ * Target type from the runtime `UserNotificationDefinition.target` (see
309
+ * `CoreUserNotificationTarget`). Documents whether the delivery is
310
+ * actor-only (`USER_SELF`), org-wide (`ORGANIZATION_USERS`), a specific
311
+ * audience (`USERS_CUSTOM` with a selector), …
312
+ */
313
+ targetRef: CoreUserNotificationTarget | (string & {});
314
+ /**
315
+ * Operation variant this delivery belongs to. `undefined` means the default
316
+ * variant. Maps to `variantKey` on the runtime variant when present.
317
+ */
318
+ variantRef?: string;
319
+ /**
320
+ * Distinguishes deliveries when the same `(variantRef, targetRef, channelRef)`
321
+ * triple fires multiple notifications (rare but supported by the runtime
322
+ * via `customNotificationRef`).
323
+ */
324
+ customDeliveryRef?: string;
325
+ /** Per-delivery overrides for translatable text slots. */
326
+ textSlotsOverrides?: TranslationSlotSpecificationMap;
327
+ /** Per-delivery override for `purpose` when this delivery has its own intent. */
328
+ purposeOverride?: string;
329
+ /** Per-delivery business constraints layered on top of the parent list. */
330
+ additionalBusinessConstraints?: string[];
331
+ /** Companion/transposer caveats specific to this delivery. */
332
+ notes?: string[];
333
+ }
334
+
335
+ /**
336
+ * Semantic overlay for the in-app notifications fired by a resource operation.
337
+ *
338
+ * Mirrors `ResourceOperationEmailSpecification` for consistency: `purpose`
339
+ * and `tone` are plain authoring prose; every translatable fragment (title,
340
+ * body, actionLabel, …) lives in `textSlots`; `eventData` documents the
341
+ * payload meaning. The `deliveries` array makes the engine fan-out explicit
342
+ * — every runtime `userNotifications[]` entry with a non-EMAIL channel maps
343
+ * to one entry here so the spec is never silent about a real runtime
344
+ * notification surface.
345
+ */
346
+ export interface ResourceOperationNotificationSpecification {
347
+ /** Why this operation fires in-app notifications (shared across deliveries). */
348
+ purpose: string;
349
+ /** Expected voice/posture for the generated copy. */
350
+ tone: string;
351
+ /** Situations where this notification must be raised alongside the operation. */
352
+ useWhen?: string;
353
+ /** Situations where this notification should not fire. */
354
+ avoidWhen?: string;
355
+ /**
356
+ * Translatable text slots for the notification (`title`, `body`,
357
+ * `actionLabel`, or any channel-specific named slot). `title` is required
358
+ * so every notification has a recognisable headline for translators and
359
+ * transposers to target. Per-delivery overrides live on each
360
+ * `deliveries[i].textSlotsOverrides`.
361
+ */
362
+ textSlots: TranslationSlotSpecificationMap;
363
+ /**
364
+ * Explicit fan-out: one entry per runtime `userNotifications[]` non-EMAIL
365
+ * delivery. At least one entry is required when a `notification` block is
366
+ * authored. The validator enforces uniqueness on
367
+ * `(variantRef, targetRef, channelRef, customDeliveryRef)` quadruples.
368
+ */
369
+ deliveries: ResourceOperationNotificationDeliverySpecification[];
370
+ /** Meaning of the event payload the notification renders with. */
371
+ eventData?: TranslationSlotSpecification;
372
+ /** Domain/compliance caveats that matter beyond the operation's own constraints. */
373
+ businessConstraints?: string[];
374
+ /** Import-oriented coding/transposition metadata. */
375
+ codeHandling?: ResourceOperationNotificationSpecificationCodeHandling;
376
+ }
377
+
378
+ /**
379
+ * Import-oriented metadata for the M2M (machine-to-machine) notifications
380
+ * fired by a resource operation.
381
+ *
382
+ * M2M notifications are webhook-style fan-outs declared on the resource
383
+ * operation's `m2mNotifications[]` array (see `CoreM2MNotificationChannel` —
384
+ * `WEBHOOK_ORGANIZATION`, `WEBHOOK_APPLICATION`, …). They never carry
385
+ * user-facing copy; transposers/companion prompts only need to know the
386
+ * channel vocabulary, the level vocabulary, and the payload schema to
387
+ * generate truthful integration code.
388
+ */
389
+ export interface ResourceOperationM2MSpecificationCodeHandling {
390
+ /**
391
+ * Public enum exposing the channel vocabulary that `deliveries[i].channelRef`
392
+ * members come from (for example `CoreM2MNotificationChannel`). Custom
393
+ * channels can still be authored as raw string refs in `channelRef`, but
394
+ * declaring the owning enum lets transposer layers import the canonical
395
+ * members when generating webhook dispatch code.
396
+ */
397
+ channelEnum?: CodeSymbolRef;
398
+ /**
399
+ * Public enum exposing the severity vocabulary that `deliveries[i].level`
400
+ * members come from (for example `M2MNotificationLevel`).
401
+ */
402
+ levelEnum?: CodeSymbolRef;
403
+ /**
404
+ * Public Zod schema describing the m2m payload (often the resource main
405
+ * schema augmented with operation metadata, but operations are free to
406
+ * publish a webhook-shaped projection).
407
+ */
408
+ payloadSchemaSymbol?: CodeSymbolRef;
409
+ /** Public TypeScript type symbol when the payload type is split from its Zod schema. */
410
+ payloadTypeSymbol?: CodeSymbolRef;
411
+ /** Extra supporting symbols transposer prompts may need. */
412
+ supportingSymbols?: CodeSymbolRef[];
413
+ /** Companion/transposer caveats that must survive serialization. */
414
+ notes?: string[];
415
+ }
416
+
417
+ /**
418
+ * Semantic overlay for ONE M2M notification delivery fired by a resource
419
+ * operation. Each entry in the runtime `m2mNotifications[]` array maps to
420
+ * one entry here so the spec stays parity-faithful with the engine fan-out.
421
+ */
422
+ export interface ResourceOperationM2MDeliverySpecification {
423
+ /**
424
+ * Audience description: which integration consumers receive this webhook
425
+ * (the organization's configured webhook endpoints, the application's
426
+ * platform-wide endpoint, …). Required for the same fan-out reason as the
427
+ * email/notification delivery audiences.
428
+ */
429
+ audience: string;
430
+ /**
431
+ * Channel ref (e.g. `CoreM2MNotificationChannel.WEBHOOK_ORGANIZATION`).
432
+ * Authoring sites should use `CoreM2MNotificationChannel` members for
433
+ * built-in channels (autocomplete + typo-protection); custom channels
434
+ * remain expressible as raw strings.
435
+ */
436
+ channelRef: CoreM2MNotificationChannel | (string & {});
437
+ /**
438
+ * Severity classification (info / success / error). Authoring sites should
439
+ * use `M2MNotificationLevel` members; mirrors the runtime enum.
440
+ */
441
+ level?: M2MNotificationLevel | (string & {});
442
+ /**
443
+ * Operation variant this delivery belongs to. `undefined` means the default
444
+ * variant. Maps to `variantKey` on the runtime variant when present.
445
+ */
446
+ variantRef?: string;
447
+ /**
448
+ * Distinguishes deliveries when the same `(variantRef, channelRef, level)`
449
+ * triple fires multiple webhooks (e.g. one operation publishing both an
450
+ * org webhook and a partner-specific custom channel).
451
+ */
452
+ customDeliveryRef?: string;
453
+ /** Companion/transposer caveats specific to this delivery. */
454
+ notes?: string[];
455
+ }
456
+
457
+ /**
458
+ * Semantic overlay for the M2M (webhook) notifications fired by a resource
459
+ * operation. Mirrors the email/notification overlay shape so authors get a
460
+ * uniform fan-out vocabulary across all three communications surfaces.
461
+ *
462
+ * The `requiredFeatures` slot is a documentation-oriented feature-gate
463
+ * descriptor — see {@link RequiredFeaturesSpecification}. The runtime checks
464
+ * the M2M dispatch gate at its delivery boundary, so this slot documents the
465
+ * application intent rather than acting as enforcement.
466
+ * The M2M validator opts in to fail-soft cross-registry resolution (see
467
+ * `assertOptionalRequiredFeaturesSpecification` — `crossRegistry:
468
+ * 'fail-soft'`) so application-defined feature refs beyond the engine
469
+ * baseline do not silently re-define the runtime contract.
470
+ */
471
+ export interface ResourceOperationM2MSpecification {
472
+ /** Why this operation fires M2M webhooks (shared intent across deliveries). */
473
+ purpose: string;
474
+ /** Situations where the M2M dispatch must run alongside the operation. */
475
+ useWhen?: string;
476
+ /** Situations where the M2M dispatch should not fire. */
477
+ avoidWhen?: string;
478
+ /** Domain/compliance caveats (rate limits, privacy filters, retry policy …). */
479
+ businessConstraints?: string[];
480
+ /**
481
+ * Explicit fan-out: one entry per runtime `m2mNotifications[]` delivery.
482
+ * At least one entry is required when an `m2m` block is authored.
483
+ */
484
+ deliveries: ResourceOperationM2MDeliverySpecification[];
485
+ /**
486
+ * Documentation-oriented feature-gate descriptor — see
487
+ * {@link RequiredFeaturesSpecification}. Optional. The authoritative
488
+ * runtime gate lives at the M2M dispatcher
489
+ * (`featureResolution.isFeatureEnabled(M2M_WEBHOOK_DELIVERY)`); declaring
490
+ * this slot lets companion prompts surface the same requirement without
491
+ * re-implementing the runtime check. Authors may add additional
492
+ * application-level features here (e.g. `'PARTNER_INTEGRATION'`) when
493
+ * the operation's webhook fan-out is gated beyond the engine baseline.
494
+ */
495
+ requiredFeatures?: RequiredFeaturesSpecification;
496
+ /** Import-oriented coding/transposition metadata. */
497
+ codeHandling?: ResourceOperationM2MSpecificationCodeHandling;
498
+ }
499
+
500
+ /**
501
+ * Outbound communications fired by a resource operation.
502
+ *
503
+ * Each sub-block is optional — an operation may send only an email, only a
504
+ * notification, only an m2m webhook, any combination, or none. The companion
505
+ * will render only the authored sub-blocks. The three sub-blocks mirror the
506
+ * runtime fan-out surfaces:
507
+ * - `email` ↔ `userNotifications[].channel === EMAIL` entries
508
+ * - `notification` ↔ `userNotifications[].channel !== EMAIL` entries
509
+ * - `m2m` ↔ `m2mNotifications[]` entries
510
+ *
511
+ * Variant-level overrides are not modelled at the parent level: deliveries
512
+ * carry their own `variantRef`, so per-variant differences are captured
513
+ * inside the `deliveries` arrays of each sub-block.
514
+ */
515
+ export interface ResourceOperationCommunicationsSpecification {
516
+ /** Email deliveries fired by the operation, when applicable. */
517
+ email?: ResourceOperationEmailSpecification;
518
+ /** In-app notification deliveries fired by the operation, when applicable. */
519
+ notification?: ResourceOperationNotificationSpecification;
520
+ /** M2M (webhook) deliveries fired by the operation, when applicable. */
521
+ m2m?: ResourceOperationM2MSpecification;
522
+ }
523
+
524
+ /**
525
+ * Import-oriented metadata for the scheduled execution of a resource operation.
526
+ *
527
+ * Scheduled work always anchors to `(resourceIdentifier, operationIdentifier)`
528
+ * at runtime — either through a `ResourceOperationVariantType.CRON_JOB`
529
+ * variant of the operation, or through `createCustomBatchExecutionService(...)`
530
+ * whose `batchCronjob_Context` pins the same anchor. Transposer/companion
531
+ * prompts need stable import refs to the input/output schemas and to the
532
+ * batch-ref constant so generated code can reuse the canonical declarations
533
+ * instead of re-typing them.
534
+ */
535
+ export interface ResourceOperationScheduledExecutionCodeHandling {
536
+ /** Public Zod schema symbol describing the scheduled-run input payload. */
537
+ inputSchemaSymbol?: CodeSymbolRef;
538
+ /** Public Zod schema symbol describing the scheduled-run output payload. */
539
+ outputSchemaSymbol?: CodeSymbolRef;
540
+ /** Public TypeScript type symbol when the input type is split from its Zod schema. */
541
+ inputTypeSymbol?: CodeSymbolRef;
542
+ /** Public TypeScript type symbol when the output type is split from its Zod schema. */
543
+ outputTypeSymbol?: CodeSymbolRef;
544
+ /**
545
+ * Public symbol declaring the custom-batch reference constant (for example
546
+ * `FILES_CLEANUP_BATCH_REF`) when the schedule runs through
547
+ * `createCustomBatchExecutionService(...)` rather than a
548
+ * `ResourceOperationVariantType.CRON_JOB` variant.
549
+ */
550
+ customBatchRefSymbol?: CodeSymbolRef;
551
+ /**
552
+ * Public symbol declaring the factory that builds the custom batch service
553
+ * (for example `createFilesCleanupBatch`). Lets generated code import the
554
+ * constructor directly without re-reading the batch file.
555
+ */
556
+ batchFactorySymbol?: CodeSymbolRef;
557
+ /** Extra supporting symbols transposer prompts may need. */
558
+ supportingSymbols?: CodeSymbolRef[];
559
+ /** Companion/transposer caveats that must survive serialization. */
560
+ notes?: string[];
561
+ }
562
+
563
+ /**
564
+ * Discriminant vocabulary for how a scheduled unit of work is anchored to a
565
+ * resource operation at runtime.
566
+ *
567
+ * The spec-layer vocabulary intentionally does NOT reuse
568
+ * `ResourceOperationVariantType` directly. Runtime variants describe how the
569
+ * operation itself is declared on the resource configuration, while custom
570
+ * batches are a separate mechanism registered through
571
+ * `createCustomBatchExecutionService(...)` whose `batchCronjob_Context`
572
+ * happens to anchor to a `(resourceIdentifier, operationIdentifier)` pair.
573
+ * The three spec arms below make the distinction explicit so illegal
574
+ * combinations (a `CRON_JOB` variant with no cron, a `BATCH_JOB` variant
575
+ * with a cron, a custom batch with no `customBatchRef`, …) are
576
+ * unrepresentable at authoring time.
577
+ */
578
+ export enum ResourceOperationScheduledExecutionVariantType {
579
+ /**
580
+ * Operation itself declares a `ResourceOperationVariantType.CRON_JOB`
581
+ * variant whose `cronJobExpression` drives the schedule. The spec echoes
582
+ * the same cron so companion prompts can reason about cadence without
583
+ * reading the runtime configuration.
584
+ */
585
+ NATIVE_CRON_JOB = 'NATIVE_CRON_JOB',
586
+ /**
587
+ * Operation itself declares a `ResourceOperationVariantType.BATCH_JOB`
588
+ * variant. No cron is attached — the batch variant is event-triggered
589
+ * (queue message, deferred work) and runs when upstream work dispatches it.
590
+ */
591
+ NATIVE_BATCH_JOB = 'NATIVE_BATCH_JOB',
592
+ /**
593
+ * Schedule is registered through `createCustomBatchExecutionService(...)`
594
+ * with a `batchCronjob_Context` pinning it to this operation. The batch
595
+ * lives outside the operation's own variants and is addressed by a stable
596
+ * `customBatchRef` that the runtime registry (and the declarative
597
+ * `CustomBatchManifest` aggregator) both consume.
598
+ */
599
+ CUSTOM_BATCH = 'CUSTOM_BATCH',
600
+ }
601
+
602
+ /**
603
+ * Fields shared by every `scheduledExecution` arm. Authoring prose
604
+ * (`purpose` / `outcome`) is not translatable — scheduled runs have no
605
+ * user-facing copy of their own, so we do not carry `textSlots` here.
606
+ */
607
+ interface BaseResourceOperationScheduledExecutionSpecification {
608
+ /** Why this scheduled work runs (business intent, not mechanics). */
609
+ purpose: string;
610
+ /** Observable business result once the scheduled run finishes successfully. */
611
+ outcome: string;
612
+ /** Situations where the scheduled run is the right business path. */
613
+ useWhen?: string;
614
+ /** Situations where the scheduled run should be suppressed (maintenance windows, migrations, …). */
615
+ avoidWhen?: string;
616
+ /** Domain/compliance caveats that matter beyond the operation's own constraints. */
617
+ businessConstraints?: string[];
618
+ /** Import-oriented coding/transposition metadata. */
619
+ codeHandling?: ResourceOperationScheduledExecutionCodeHandling;
620
+ }
621
+
622
+ /**
623
+ * Scheduled-execution overlay for operations whose own variants declare a
624
+ * `ResourceOperationVariantType.CRON_JOB` with an inline cron expression.
625
+ * The spec echoes that cron so companion prompts see the authoritative cadence
626
+ * without re-reading backend code; authors must not invent a cron the runtime
627
+ * variant does not declare.
628
+ */
629
+ export interface NativeCronJobScheduledExecutionSpecification
630
+ extends BaseResourceOperationScheduledExecutionSpecification {
631
+ variantType: ResourceOperationScheduledExecutionVariantType.NATIVE_CRON_JOB;
632
+ /** Echoed cron expression from the operation's `CRON_JOB` variant. */
633
+ cronExpression: string;
634
+ }
635
+
636
+ /**
637
+ * Scheduled-execution overlay for operations whose own variants declare a
638
+ * `ResourceOperationVariantType.BATCH_JOB`. Batch variants run on dispatch
639
+ * rather than a schedule, so no cron is attached and no custom-batch ref is
640
+ * involved.
641
+ */
642
+ export interface NativeBatchJobScheduledExecutionSpecification
643
+ extends BaseResourceOperationScheduledExecutionSpecification {
644
+ variantType: ResourceOperationScheduledExecutionVariantType.NATIVE_BATCH_JOB;
645
+ }
646
+
647
+ /**
648
+ * Scheduled-execution overlay for work registered through
649
+ * `createCustomBatchExecutionService(...)` whose `batchCronjob_Context`
650
+ * anchors to this operation. The stable `customBatchRef` must match the
651
+ * `CustomBatchManifest.batchRef` exported next to the batch factory, which
652
+ * in turn feeds the imperative `customBatches.set(...)` registration in
653
+ * `start-application.backend.service.ts`.
654
+ *
655
+ * `cronExpression` echoes the custom batch's `batchCronjob_Context.cronJobExpression`
656
+ * when one is declared; event-triggered custom batches (for example the
657
+ * email `batch-send` path) omit both the cron and the `cronExpression` field.
658
+ */
659
+ export interface CustomBatchScheduledExecutionSpecification
660
+ extends BaseResourceOperationScheduledExecutionSpecification {
661
+ variantType: ResourceOperationScheduledExecutionVariantType.CUSTOM_BATCH;
662
+ /** Stable ref that resolves to a `CustomBatchManifest` at module load. */
663
+ customBatchRef: string;
664
+ /**
665
+ * Echoed cron expression from the custom batch's `batchCronjob_Context`.
666
+ * Must match the manifest: present when the batch declares a cron, absent
667
+ * when the batch is purely event-triggered.
668
+ */
669
+ cronExpression?: string;
670
+ }
671
+
672
+ /**
673
+ * Discriminated-union semantic overlay for scheduled execution of a resource
674
+ * operation. The discriminant is
675
+ * {@link ResourceOperationScheduledExecutionVariantType} and each arm enforces
676
+ * the fields the runtime anchor actually requires, so illegal combinations
677
+ * (cron without variant, batch-job with cron, custom batch without ref, …)
678
+ * are rejected at authoring time.
679
+ *
680
+ * Attaching the slot at the operation level mirrors the runtime invariant
681
+ * that every scheduled unit of work anchors to a resource operation
682
+ * (`ResourceOperationVariantType.CRON_JOB` / `BATCH_JOB` or a custom batch
683
+ * whose `batchCronjob_Context` binds it to `(resourceIdentifier,
684
+ * operationIdentifier)`). There is no operation-less scheduled path.
685
+ *
686
+ * Cross-registry verification of `customBatchRef` runs at module load by
687
+ * consulting the declarative `CustomBatchManifest` registry — see
688
+ * {@link registerCustomBatchManifests} and the engine's
689
+ * `ENGINE_CUSTOM_BATCH_MANIFESTS` export in `@wildo-ai/saas-backend-lib`.
690
+ */
691
+ export type ResourceOperationScheduledExecutionSpecification =
692
+ | NativeCronJobScheduledExecutionSpecification
693
+ | NativeBatchJobScheduledExecutionSpecification
694
+ | CustomBatchScheduledExecutionSpecification;
695
+
696
+ // ── Operation HTTP-documentation overlay (Tier 3 — OpenAPI semantics) ───────
697
+
698
+ /**
699
+ * Fixed vocabulary of HTTP response status codes an operation may document.
700
+ * An enum (not a literal union) per the framework rule — a single source of
701
+ * truth for the renderer and the OpenAPI generator. The string VALUE is the
702
+ * OpenAPI `responses` key (`'200'`, `'404'`, …) so it splices in verbatim.
703
+ */
704
+ export enum HttpResponseStatusCode {
705
+ OK_200 = '200',
706
+ CREATED_201 = '201',
707
+ ACCEPTED_202 = '202',
708
+ NO_CONTENT_204 = '204',
709
+ BAD_REQUEST_400 = '400',
710
+ UNAUTHORIZED_401 = '401',
711
+ FORBIDDEN_403 = '403',
712
+ NOT_FOUND_404 = '404',
713
+ CONFLICT_409 = '409',
714
+ UNPROCESSABLE_ENTITY_422 = '422',
715
+ TOO_MANY_REQUESTS_429 = '429',
716
+ INTERNAL_SERVER_ERROR_500 = '500',
717
+ }
718
+
719
+ /**
720
+ * One documented response status for an operation. Becomes an OpenAPI
721
+ * `responses.<code>` entry whose `description` is the authored `meaning`.
722
+ */
723
+ export interface ResourceOperationResponseStatusSpecification {
724
+ /** HTTP status code this operation returns on this outcome. */
725
+ code: HttpResponseStatusCode;
726
+ /** What this status means for THIS operation, in business terms. */
727
+ meaning: string;
728
+ }
729
+
730
+ /**
731
+ * One documented failure mode beyond the happy path. Becomes an OpenAPI error
732
+ * `responses.<code>` entry; `when` explains the trigger and `errorCode` (if
733
+ * set) is the machine-stable identifier the API returns in the error body.
734
+ */
735
+ export interface ResourceOperationErrorScenarioSpecification {
736
+ /** HTTP status code returned in this failure mode. */
737
+ code: HttpResponseStatusCode;
738
+ /** Trigger condition — when/why this error occurs. */
739
+ when: string;
740
+ /** Optional machine-stable error identifier emitted in the error body. */
741
+ errorCode?: string;
742
+ }
743
+
744
+ /**
745
+ * A request/response payload example for docs + client codegen. Becomes an
746
+ * OpenAPI example on the request body and/or the `forStatus` response.
747
+ */
748
+ export interface ResourceOperationExampleSpecification {
749
+ /** Short human label, e.g. "Create with assignee". */
750
+ title: string;
751
+ /** Optional example request body (JSON-serialisable). */
752
+ request?: unknown;
753
+ /** Optional example response body (JSON-serialisable). */
754
+ response?: unknown;
755
+ /** Which response status this example illustrates (links to `responseStatuses`). */
756
+ forStatus?: HttpResponseStatusCode;
757
+ }
758
+
759
+ /**
760
+ * Semantic explanation for one logical resource operation.
761
+ *
762
+ * The operation-level fields capture the invariant business meaning of the
763
+ * action, while `variants` captures frontend/runtime-specific differences when
764
+ * multiple operation variants exist.
765
+ */
766
+ export interface ResourceOperationSpecification {
767
+ /** Stable operation identifier as declared by the resource configuration. */
768
+ operationId?: string;
769
+ /** Shared business intent across all variants of the operation. */
770
+ purpose?: string;
771
+ /** Shared observable business result once the operation succeeds. */
772
+ outcome?: string;
773
+ /** Guidance about when this operation is the right choice. */
774
+ whenToUse?: string;
775
+ /** Relative weight of this operation in the resource understanding. */
776
+ importance?: FieldSemanticImportance;
777
+ /**
778
+ * Outbound communications (emails, notifications) fired as a side-effect of
779
+ * running the operation. Because `ResourceFrontendViewSpecification`
780
+ * structurally extends this interface, communications authored at the base
781
+ * level are automatically visible through `frontend.views` as well.
782
+ */
783
+ communications?: ResourceOperationCommunicationsSpecification;
784
+ /**
785
+ * Scheduled-execution overlay for cron/batch operations. Applies when the
786
+ * operation has a `CRON_JOB` / `BATCH_JOB` variant or is implemented by a
787
+ * custom batch whose `batchCronjob_Context` anchors to this operation.
788
+ * Attached at the base level so it also surfaces through
789
+ * `frontend.views` via structural inheritance — scheduled work is a
790
+ * backend-initiated side effect, not a UI seam.
791
+ */
792
+ scheduledExecution?: ResourceOperationScheduledExecutionSpecification;
793
+ /** Variant-specific semantics layered under the same logical operation id. */
794
+ variants?: ResourceOperationSpecificationVariants;
795
+ /**
796
+ * Authored HTTP response statuses for this operation. Feeds the OpenAPI
797
+ * `responses` object, replacing the generator's default single `200`/`204`.
798
+ * Per-operation — variants share the same HTTP contract (a per-variant
799
+ * response set would multiply identical contracts with no semantic gain).
800
+ */
801
+ responseStatuses?: ResourceOperationResponseStatusSpecification[];
802
+ /**
803
+ * Failure modes a client should handle beyond the happy path. Each becomes
804
+ * an OpenAPI error `responses` entry (400/403/404/409/…) carrying its `when`
805
+ * prose. Per-operation.
806
+ */
807
+ errorScenarios?: ResourceOperationErrorScenarioSpecification[];
808
+ /**
809
+ * Whether repeating the request with the same input is side-effect-free.
810
+ * Surfaces as an OpenAPI `x-idempotent` extension plus a description note.
811
+ */
812
+ idempotent?: boolean;
813
+ /** Optional human note on the operation's rate-limiting posture (free prose). */
814
+ rateLimitNote?: string;
815
+ /**
816
+ * Request/response payload examples for docs + client codegen. Base examples
817
+ * apply to every variant unless `variants.<key>.examples` provides a complete
818
+ * replacement for a divergent variant response schema.
819
+ */
820
+ examples?: ResourceOperationExampleSpecification[];
821
+ }
822
+
823
+ /**
824
+ * Validation entry point used by the resource specification factory to assert
825
+ * that an authored `communications` block is internally consistent. Factories
826
+ * call this from the same place they already assert frontend-operation
827
+ * completeness, so misconfigurations fail at module load rather than leaking
828
+ * into companion renderers as half-formed prose.
829
+ *
830
+ * @param ownerLabel Stable identifier of the owning operation (used in error
831
+ * messages so authors can locate the broken spec immediately).
832
+ * @param communications The authored communications block, or undefined when
833
+ * the operation does not declare one.
834
+ * @param resourcePrimaryScope The owning resource's `resourcePrimaryScope`.
835
+ * This is the specification author's explicitly declared scope (the fourth
836
+ * `options` argument to {@link resourceSpecification}), threaded through
837
+ * every re-validation path (including
838
+ * {@link resourceSpecificationFromFrontendConfiguration}'s
839
+ * `base.operations` / `base.frontend.views` / `frontend.views`
840
+ * re-validation passes). It MAY still be `undefined` only on hand-built
841
+ * spec configs that bypass both factories — those paths intentionally
842
+ * soft-skip the cross-check because they have no contract with the spec
843
+ * author for declaring scope. The primary entry point hard-fails on
844
+ * missing scope (TypeScript-enforced), so production specs always
845
+ * exercise the cross-check.
846
+ */
847
+ export function validateResourceOperationCommunicationsSpecification(
848
+ ownerLabel: string,
849
+ communications: ResourceOperationCommunicationsSpecification | undefined,
850
+ resourcePrimaryScope?: ResourcePrimaryScope,
851
+ ): void {
852
+ if (!communications) {
853
+ return;
854
+ }
855
+ if (communications.email) {
856
+ assertNonEmptyProseSlot(
857
+ ownerLabel,
858
+ 'communications.email.purpose',
859
+ communications.email.purpose,
860
+ );
861
+ assertNonEmptyProseSlot(ownerLabel, 'communications.email.tone', communications.email.tone);
862
+ assertOptionalNonEmptyProseSlot(
863
+ ownerLabel,
864
+ 'communications.email.useWhen',
865
+ communications.email.useWhen,
866
+ );
867
+ assertOptionalNonEmptyProseSlot(
868
+ ownerLabel,
869
+ 'communications.email.avoidWhen',
870
+ communications.email.avoidWhen,
871
+ );
872
+ assertEveryAuthoredTextSlot(
873
+ ownerLabel,
874
+ 'email',
875
+ ['subject'],
876
+ communications.email.textSlots,
877
+ );
878
+ assertOptionalEventDataSlot(ownerLabel, 'email', communications.email.eventData);
879
+ assertOptionalNonEmptyStringList(
880
+ ownerLabel,
881
+ 'communications.email.businessConstraints',
882
+ communications.email.businessConstraints,
883
+ );
884
+ assertOptionalNonEmptyStringList(
885
+ ownerLabel,
886
+ 'communications.email.codeHandling.notes',
887
+ communications.email.codeHandling?.notes,
888
+ );
889
+ assertEmailDeliveries(ownerLabel, communications.email.deliveries);
890
+ }
891
+ if (communications.notification) {
892
+ assertNonEmptyProseSlot(
893
+ ownerLabel,
894
+ 'communications.notification.purpose',
895
+ communications.notification.purpose,
896
+ );
897
+ assertNonEmptyProseSlot(
898
+ ownerLabel,
899
+ 'communications.notification.tone',
900
+ communications.notification.tone,
901
+ );
902
+ assertOptionalNonEmptyProseSlot(
903
+ ownerLabel,
904
+ 'communications.notification.useWhen',
905
+ communications.notification.useWhen,
906
+ );
907
+ assertOptionalNonEmptyProseSlot(
908
+ ownerLabel,
909
+ 'communications.notification.avoidWhen',
910
+ communications.notification.avoidWhen,
911
+ );
912
+ assertEveryAuthoredTextSlot(
913
+ ownerLabel,
914
+ 'notification',
915
+ ['title'],
916
+ communications.notification.textSlots,
917
+ );
918
+ assertOptionalEventDataSlot(
919
+ ownerLabel,
920
+ 'notification',
921
+ communications.notification.eventData,
922
+ );
923
+ assertOptionalNonEmptyStringList(
924
+ ownerLabel,
925
+ 'communications.notification.businessConstraints',
926
+ communications.notification.businessConstraints,
927
+ );
928
+ assertOptionalNonEmptyStringList(
929
+ ownerLabel,
930
+ 'communications.notification.codeHandling.notes',
931
+ communications.notification.codeHandling?.notes,
932
+ );
933
+ assertNotificationDeliveries(ownerLabel, communications.notification.deliveries);
934
+ }
935
+ if (communications.m2m) {
936
+ assertNonEmptyProseSlot(ownerLabel, 'communications.m2m.purpose', communications.m2m.purpose);
937
+ assertOptionalNonEmptyProseSlot(
938
+ ownerLabel,
939
+ 'communications.m2m.useWhen',
940
+ communications.m2m.useWhen,
941
+ );
942
+ assertOptionalNonEmptyProseSlot(
943
+ ownerLabel,
944
+ 'communications.m2m.avoidWhen',
945
+ communications.m2m.avoidWhen,
946
+ );
947
+ assertOptionalNonEmptyStringList(
948
+ ownerLabel,
949
+ 'communications.m2m.businessConstraints',
950
+ communications.m2m.businessConstraints,
951
+ );
952
+ assertOptionalNonEmptyStringList(
953
+ ownerLabel,
954
+ 'communications.m2m.codeHandling.notes',
955
+ communications.m2m.codeHandling?.notes,
956
+ );
957
+ assertOptionalRequiredFeaturesSpecification(
958
+ `Resource operation "${ownerLabel}" communications.m2m.requiredFeatures`,
959
+ communications.m2m.requiredFeatures,
960
+ { crossRegistry: 'fail-soft' },
961
+ );
962
+ assertM2MDeliveries(ownerLabel, communications.m2m.deliveries, resourcePrimaryScope);
963
+ }
964
+ }
965
+
966
+ /**
967
+ * Assert that a REQUIRED prose slot (`purpose`, `tone`, `audience`, …) is
968
+ * non-empty trimmed. `slotLabel` is the full owner-relative path included
969
+ * verbatim in the error (e.g. `communications.email.purpose`,
970
+ * `communications.email.deliveries[0].audience`) so callers can locate the
971
+ * broken authoring site immediately, regardless of whether the slot lives
972
+ * directly under `communications.*` or further nested under a `deliveries[i]`.
973
+ */
974
+ function assertNonEmptyProseSlot(
975
+ ownerLabel: string,
976
+ slotLabel: string,
977
+ value: string | undefined,
978
+ ): void {
979
+ if (!value || !value.trim()) {
980
+ throw new Error(
981
+ `Resource operation "${ownerLabel}" ${slotLabel} must be a non-empty prose slot.`,
982
+ );
983
+ }
984
+ }
985
+
986
+ /**
987
+ * Best-effort resource-type hint derivation from the `_factory` argument
988
+ * passed to `resourceSpecification(...)`.
989
+ *
990
+ * Used exclusively to enrich the `validateFieldShapes(...)` error prefix so
991
+ * authors see `resourceSpecification(TODOS): ...` instead of a
992
+ * bare `resourceSpecification(): ...` when multiple resources fail
993
+ * validation in the same bundle. Returns an empty string when the hint
994
+ * cannot be derived — callers must treat that case as "use the bare
995
+ * prefix" rather than throwing.
996
+ *
997
+ * Handles both factory forms:
998
+ * - Function form (`ResourceConfiguration_InitializationFactory`): reads
999
+ * the function `name` and strips the standard
1000
+ * `_ResourceConfiguration_InitializationFactory` suffix. This matches the
1001
+ * application factory naming convention.
1002
+ * - Object form (`ResourceConfiguration`): reads the
1003
+ * `resourceType?.memberName` when present. Older static object-form
1004
+ * factories do not always set this; the empty-string fallback keeps
1005
+ * them working.
1006
+ */
1007
+ function extractResourceTypeHintFromFactory(factory: unknown): string {
1008
+ if (typeof factory === 'function') {
1009
+ const name = typeof factory.name === 'string' ? factory.name : '';
1010
+ const stripped = name.replace(/_ResourceConfiguration_InitializationFactory$/, '');
1011
+ return stripped.trim();
1012
+ }
1013
+ if (factory && typeof factory === 'object') {
1014
+ const maybeRef = (factory as { resourceType?: { memberName?: unknown } }).resourceType;
1015
+ if (maybeRef && typeof maybeRef.memberName === 'string') {
1016
+ return maybeRef.memberName;
1017
+ }
1018
+ }
1019
+ return '';
1020
+ }
1021
+
1022
+ /**
1023
+ * Assert that an OPTIONAL prose slot (`useWhen`, `avoidWhen`, `purposeOverride`,
1024
+ * …) is non-empty trimmed when authored. Absent slots are a no-op.
1025
+ *
1026
+ * Mirrors the per-bullet contract on `assertOptionalNonEmptyStringList`: every
1027
+ * surface the renderer prints — even optional ones — must fail closed on
1028
+ * blanks because a blank `useWhen` line silently appears as `Use when .` in
1029
+ * companion prompts and undermines translator/transposer grounding.
1030
+ *
1031
+ * `slotLabel` is the full owner-relative path included verbatim in the error
1032
+ * (e.g. `email.useWhen`, `scheduledExecution.avoidWhen`,
1033
+ * `communications.email.deliveries[0].purposeOverride`) so callers can locate
1034
+ * the broken authoring site immediately.
1035
+ */
1036
+ function assertOptionalNonEmptyProseSlot(
1037
+ ownerLabel: string,
1038
+ slotLabel: string,
1039
+ value: string | undefined,
1040
+ ): void {
1041
+ if (value === undefined) {
1042
+ return;
1043
+ }
1044
+ if (typeof value !== 'string' || !value.trim()) {
1045
+ throw new Error(
1046
+ `Resource operation "${ownerLabel}" ${slotLabel} must be a non-empty trimmed prose slot when authored (omit the field entirely instead of declaring an empty value).`,
1047
+ );
1048
+ }
1049
+ }
1050
+
1051
+ /**
1052
+ * Validate the `deliveries` array on a `ResourceOperationEmailSpecification`.
1053
+ *
1054
+ * Engine-parity contract: every entry must mirror one runtime
1055
+ * `userNotifications[]` email delivery, so the spec is never silent about a
1056
+ * real runtime template path. The validator enforces:
1057
+ * - at least one delivery (the array is required when an `email` block is
1058
+ * authored — single-delivery emails still need one explicit entry),
1059
+ * - non-empty `audience` and `targetRef` on every delivery,
1060
+ * - non-empty trimmed `variantRef` / `customDeliveryRef` when authored,
1061
+ * - non-empty trimmed `purposeOverride` when authored,
1062
+ * - per-delivery `systemEmailTemplateRef` (when authored) is a member of
1063
+ * `SystemEmailTemplateRegistry` — the cross-link lives per-delivery
1064
+ * because the runtime template-ref path is per-delivery,
1065
+ * - per-delivery `textSlotsOverrides` slots carry a non-empty `purpose`,
1066
+ * - per-delivery `additionalBusinessConstraints` and `notes` follow the
1067
+ * per-bullet non-empty contract,
1068
+ * - uniqueness on `(variantRef ?? '__default__', targetRef, customDeliveryRef ?? '__none__')`
1069
+ * so two deliveries cannot collide on the runtime template-ref path.
1070
+ */
1071
+ function assertEmailDeliveries(
1072
+ ownerLabel: string,
1073
+ deliveries: ResourceOperationEmailDeliverySpecification[] | undefined,
1074
+ ): void {
1075
+ if (!deliveries || deliveries.length === 0) {
1076
+ throw new Error(
1077
+ `Resource operation "${ownerLabel}" communications.email.deliveries must declare at least one delivery so the spec is never silent about a real runtime email template path. Even single-delivery emails need one explicit entry.`,
1078
+ );
1079
+ }
1080
+ const seenKeys = new Set<string>();
1081
+ for (const [index, delivery] of deliveries.entries()) {
1082
+ const path = `communications.email.deliveries[${index}]`;
1083
+ assertNonEmptyProseSlot(ownerLabel, `${path}.audience`, delivery.audience);
1084
+ if (typeof delivery.targetRef !== 'string' || !delivery.targetRef.trim()) {
1085
+ throw new Error(
1086
+ `Resource operation "${ownerLabel}" ${path}.targetRef must be a non-empty trimmed string (use a CoreUserNotificationTarget member or a custom target ref).`,
1087
+ );
1088
+ }
1089
+ assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.variantRef`, delivery.variantRef);
1090
+ assertOptionalNonEmptyProseSlot(
1091
+ ownerLabel,
1092
+ `${path}.customDeliveryRef`,
1093
+ delivery.customDeliveryRef,
1094
+ );
1095
+ assertSystemEmailTemplateCrossLink(
1096
+ ownerLabel,
1097
+ `${path}.systemEmailTemplateRef`,
1098
+ delivery.systemEmailTemplateRef,
1099
+ );
1100
+ assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.purposeOverride`, delivery.purposeOverride);
1101
+ assertTextSlotsOverrides(
1102
+ ownerLabel,
1103
+ `${path}.textSlotsOverrides`,
1104
+ delivery.textSlotsOverrides,
1105
+ );
1106
+ assertOptionalNonEmptyStringList(
1107
+ ownerLabel,
1108
+ `${path}.additionalBusinessConstraints`,
1109
+ delivery.additionalBusinessConstraints,
1110
+ );
1111
+ assertOptionalNonEmptyStringList(ownerLabel, `${path}.notes`, delivery.notes);
1112
+
1113
+ const key = `${delivery.variantRef ?? '__default__'}::${delivery.targetRef}::${delivery.customDeliveryRef ?? '__none__'}`;
1114
+ if (seenKeys.has(key)) {
1115
+ throw new Error(
1116
+ `Resource operation "${ownerLabel}" ${path} duplicates the (variantRef, targetRef, customDeliveryRef) triple of an earlier delivery. Two deliveries with the same triple compute the same runtime template-ref path and would silently shadow each other; add a distinguishing customDeliveryRef or merge the entries.`,
1117
+ );
1118
+ }
1119
+ seenKeys.add(key);
1120
+ }
1121
+ }
1122
+
1123
+ /**
1124
+ * Validate the `deliveries` array on a `ResourceOperationNotificationSpecification`.
1125
+ * Same engine-parity contract as {@link assertEmailDeliveries}, with `channelRef`
1126
+ * added to the uniqueness key (notifications fan out per (target, channel) pair).
1127
+ */
1128
+ function assertNotificationDeliveries(
1129
+ ownerLabel: string,
1130
+ deliveries: ResourceOperationNotificationDeliverySpecification[] | undefined,
1131
+ ): void {
1132
+ if (!deliveries || deliveries.length === 0) {
1133
+ throw new Error(
1134
+ `Resource operation "${ownerLabel}" communications.notification.deliveries must declare at least one delivery so companion routing cannot invent an in-app surface that the runtime does not fire.`,
1135
+ );
1136
+ }
1137
+ const seenKeys = new Set<string>();
1138
+ for (const [index, delivery] of deliveries.entries()) {
1139
+ const path = `communications.notification.deliveries[${index}]`;
1140
+ assertNonEmptyProseSlot(ownerLabel, `${path}.audience`, delivery.audience);
1141
+ if (typeof delivery.channelRef !== 'string' || !delivery.channelRef.trim()) {
1142
+ throw new Error(
1143
+ `Resource operation "${ownerLabel}" ${path}.channelRef must be a non-empty trimmed string (use a CoreUserNotificationChannel member or a custom channel ref).`,
1144
+ );
1145
+ }
1146
+ if (typeof delivery.targetRef !== 'string' || !delivery.targetRef.trim()) {
1147
+ throw new Error(
1148
+ `Resource operation "${ownerLabel}" ${path}.targetRef must be a non-empty trimmed string (use a CoreUserNotificationTarget member or a custom target ref).`,
1149
+ );
1150
+ }
1151
+ assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.variantRef`, delivery.variantRef);
1152
+ assertOptionalNonEmptyProseSlot(
1153
+ ownerLabel,
1154
+ `${path}.customDeliveryRef`,
1155
+ delivery.customDeliveryRef,
1156
+ );
1157
+ assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.purposeOverride`, delivery.purposeOverride);
1158
+ assertTextSlotsOverrides(
1159
+ ownerLabel,
1160
+ `${path}.textSlotsOverrides`,
1161
+ delivery.textSlotsOverrides,
1162
+ );
1163
+ assertOptionalNonEmptyStringList(
1164
+ ownerLabel,
1165
+ `${path}.additionalBusinessConstraints`,
1166
+ delivery.additionalBusinessConstraints,
1167
+ );
1168
+ assertOptionalNonEmptyStringList(ownerLabel, `${path}.notes`, delivery.notes);
1169
+
1170
+ const key = `${delivery.variantRef ?? '__default__'}::${delivery.targetRef}::${delivery.channelRef}::${delivery.customDeliveryRef ?? '__none__'}`;
1171
+ if (seenKeys.has(key)) {
1172
+ throw new Error(
1173
+ `Resource operation "${ownerLabel}" ${path} duplicates the (variantRef, targetRef, channelRef, customDeliveryRef) quadruple of an earlier delivery; add a distinguishing customDeliveryRef or merge the entries.`,
1174
+ );
1175
+ }
1176
+ seenKeys.add(key);
1177
+ }
1178
+ }
1179
+
1180
+ /**
1181
+ * Validate the `deliveries` array on a `ResourceOperationM2MSpecification`.
1182
+ *
1183
+ * Webhook-style M2M deliveries fan out per
1184
+ * `(variantRef, channelRef, level, customDeliveryRef)` — the validator
1185
+ * enforces uniqueness on that quadruple so two deliveries that genuinely
1186
+ * differ on those axes can coexist. `variantRef` is the first segment of
1187
+ * the key (defaulting to `__default__` when omitted), so two deliveries
1188
+ * that differ only by their owning variant remain distinct.
1189
+ *
1190
+ * Each authored `level` (when present) is also enum-membership-checked
1191
+ * against `M2MNotificationLevel` so a typo (`'inf0'`, `'WARN'`,
1192
+ * …) fails at module load — the runtime schema is strict-enum even
1193
+ * though the TypeScript declaration is widened with `(string & {})` for
1194
+ * IDE autocomplete.
1195
+ *
1196
+ * **Runtime-identity cross-check.** The runtime
1197
+ * `M2MNotificationDefinitionSchema` carries no `customNotificationRef`
1198
+ * field; the dispatcher constructs the fan-out identifier as
1199
+ * `${resourceIdentifier}_${operationIdentifier}_${channel}` only — no
1200
+ * variant, no level and no custom-reference segment.
1201
+ * The spec layer is therefore free to author multiple deliveries on the
1202
+ * same `channelRef` (disambiguated by `level` / `customDeliveryRef`), but
1203
+ * at runtime they would collapse to a single identifier and one of the
1204
+ * deliveries would silently shadow the other. The validator fail-closes
1205
+ * on this collision: every authored delivery must project to a unique
1206
+ * `channelRef` within its operation. Authors who genuinely need multiple
1207
+ * fan-outs on the same channel must wait until the runtime carries a
1208
+ * `customNotificationRef` axis (engineering scope, separate workstream).
1209
+ */
1210
+ function assertM2MDeliveries(
1211
+ ownerLabel: string,
1212
+ deliveries: ResourceOperationM2MDeliverySpecification[] | undefined,
1213
+ resourcePrimaryScope?: ResourcePrimaryScope,
1214
+ ): void {
1215
+ if (!deliveries || deliveries.length === 0) {
1216
+ throw new Error(
1217
+ `Resource operation "${ownerLabel}" communications.m2m.deliveries must declare at least one delivery so companion routing cannot invent a webhook surface that the runtime does not fire.`,
1218
+ );
1219
+ }
1220
+ const seenKeys = new Set<string>();
1221
+ const seenRuntimeIdentities = new Map<string, number>();
1222
+ for (const [index, delivery] of deliveries.entries()) {
1223
+ const path = `communications.m2m.deliveries[${index}]`;
1224
+ assertNonEmptyProseSlot(ownerLabel, `${path}.audience`, delivery.audience);
1225
+ if (typeof delivery.channelRef !== 'string' || !delivery.channelRef.trim()) {
1226
+ throw new Error(
1227
+ `Resource operation "${ownerLabel}" ${path}.channelRef must be a non-empty trimmed string (use a CoreM2MNotificationChannel member or a custom channel ref).`,
1228
+ );
1229
+ }
1230
+ assertM2MChannelMatchesPrimaryScope(
1231
+ ownerLabel,
1232
+ `${path}.channelRef`,
1233
+ delivery.channelRef,
1234
+ resourcePrimaryScope,
1235
+ );
1236
+ assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.level`, delivery.level);
1237
+ assertOptionalM2MNotificationLevelMembership(
1238
+ ownerLabel,
1239
+ `${path}.level`,
1240
+ delivery.level,
1241
+ );
1242
+ assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.variantRef`, delivery.variantRef);
1243
+ assertOptionalNonEmptyProseSlot(
1244
+ ownerLabel,
1245
+ `${path}.customDeliveryRef`,
1246
+ delivery.customDeliveryRef,
1247
+ );
1248
+ assertOptionalNonEmptyStringList(ownerLabel, `${path}.notes`, delivery.notes);
1249
+
1250
+ const key = `${delivery.variantRef ?? '__default__'}::${delivery.channelRef}::${delivery.level ?? '__none__'}::${delivery.customDeliveryRef ?? '__none__'}`;
1251
+ if (seenKeys.has(key)) {
1252
+ throw new Error(
1253
+ `Resource operation "${ownerLabel}" ${path} duplicates the (variantRef, channelRef, level, customDeliveryRef) quadruple of an earlier delivery; add a distinguishing customDeliveryRef or merge the entries.`,
1254
+ );
1255
+ }
1256
+ seenKeys.add(key);
1257
+
1258
+ const runtimeIdentityKey = delivery.channelRef;
1259
+ const previousIndex = seenRuntimeIdentities.get(runtimeIdentityKey);
1260
+ if (previousIndex !== undefined) {
1261
+ throw new Error(
1262
+ `Resource operation "${ownerLabel}" ${path} collides with deliveries[${previousIndex}] on the runtime m2m identifier (resource_op_channel) — both project to channel "${runtimeIdentityKey}". The runtime M2MNotificationDefinitionSchema carries no customNotificationRef axis, so two deliveries that differ only by (variantRef, level, customDeliveryRef) collapse to a single identifier and one would silently shadow the other. Either merge the entries or wait until the runtime carries a customNotificationRef axis.`,
1263
+ );
1264
+ }
1265
+ seenRuntimeIdentities.set(runtimeIdentityKey, index);
1266
+ }
1267
+ }
1268
+
1269
+ /**
1270
+ * Iterate every authored text slot and assert it has a non-empty trimmed
1271
+ * `purpose`, then assert the required slot keys (`subject` for email, `title`
1272
+ * for notification) are also present. This protects optional translatable
1273
+ * fragments (`previewText`, `ctaLabel`, `body`, `actionLabel`, …) from being
1274
+ * authored as placeholders that the translator cannot ground in author intent.
1275
+ */
1276
+ function assertEveryAuthoredTextSlot(
1277
+ ownerLabel: string,
1278
+ blockLabel: 'email' | 'notification',
1279
+ requiredSlotKeys: readonly string[],
1280
+ textSlots: TranslationSlotSpecificationMap | undefined,
1281
+ ): void {
1282
+ for (const requiredKey of requiredSlotKeys) {
1283
+ const slot = textSlots?.[requiredKey];
1284
+ if (!slot || !slot.purpose || !slot.purpose.trim()) {
1285
+ throw new Error(
1286
+ `Resource operation "${ownerLabel}" communications.${blockLabel} must document text slot "${requiredKey}" with a non-empty purpose so translators have a grounded target.`,
1287
+ );
1288
+ }
1289
+ }
1290
+ if (!textSlots) {
1291
+ return;
1292
+ }
1293
+ for (const [slotKey, slot] of Object.entries(textSlots)) {
1294
+ if (!slot || !slot.purpose || !slot.purpose.trim()) {
1295
+ throw new Error(
1296
+ `Resource operation "${ownerLabel}" communications.${blockLabel}.textSlots["${slotKey}"] must carry a non-empty purpose so translators have a grounded target for every authored slot.`,
1297
+ );
1298
+ }
1299
+ assertOptionalNonEmptyProseSlot(
1300
+ ownerLabel,
1301
+ `communications.${blockLabel}.textSlots["${slotKey}"].whenToUse`,
1302
+ slot.whenToUse,
1303
+ );
1304
+ assertOptionalNonEmptyStringList(
1305
+ ownerLabel,
1306
+ `communications.${blockLabel}.textSlots["${slotKey}"].notes`,
1307
+ slot.notes,
1308
+ );
1309
+ }
1310
+ }
1311
+
1312
+ /**
1313
+ * When `eventData` is authored on either communications sub-block, assert its
1314
+ * `purpose` is a non-empty trimmed string. Companion prompts use this slot to
1315
+ * narrate which runtime values land in each translatable text slot, so a blank
1316
+ * `purpose` would produce a labelled but undocumented payload reference.
1317
+ */
1318
+ function assertOptionalEventDataSlot(
1319
+ ownerLabel: string,
1320
+ blockLabel: 'email' | 'notification',
1321
+ eventData: TranslationSlotSpecification | undefined,
1322
+ ): void {
1323
+ if (!eventData) {
1324
+ return;
1325
+ }
1326
+ if (!eventData.purpose || !eventData.purpose.trim()) {
1327
+ throw new Error(
1328
+ `Resource operation "${ownerLabel}" communications.${blockLabel}.eventData must carry a non-empty purpose so companion prompts can narrate which runtime values land in each text slot.`,
1329
+ );
1330
+ }
1331
+ assertOptionalNonEmptyProseSlot(
1332
+ ownerLabel,
1333
+ `communications.${blockLabel}.eventData.whenToUse`,
1334
+ eventData.whenToUse,
1335
+ );
1336
+ assertOptionalNonEmptyStringList(
1337
+ ownerLabel,
1338
+ `communications.${blockLabel}.eventData.notes`,
1339
+ eventData.notes,
1340
+ );
1341
+ }
1342
+
1343
+ /**
1344
+ * Validate a per-delivery `textSlotsOverrides` map (or any structurally
1345
+ * compatible `TranslationSlotSpecificationMap`):
1346
+ *
1347
+ * - absent map → no-op,
1348
+ * - every authored slot must carry a non-empty trimmed `purpose`,
1349
+ * - every authored optional `whenToUse` (if present) must be non-empty
1350
+ * trimmed prose so the renderer never prints `When to use .`,
1351
+ * - every authored `notes` array must follow the per-bullet contract.
1352
+ *
1353
+ * Path-agnostic: callers pass the full owner-relative path prefix (for
1354
+ * example `communications.email.deliveries[0].textSlotsOverrides`) so this
1355
+ * primitive serves every overlay surface without baking a sub-tree prefix
1356
+ * into the helper.
1357
+ */
1358
+ function assertTextSlotsOverrides(
1359
+ ownerLabel: string,
1360
+ pathPrefix: string,
1361
+ slots: TranslationSlotSpecificationMap | undefined,
1362
+ ): void {
1363
+ if (!slots) {
1364
+ return;
1365
+ }
1366
+ for (const [slotKey, slot] of Object.entries(slots)) {
1367
+ if (!slot || !slot.purpose || !slot.purpose.trim()) {
1368
+ throw new Error(
1369
+ `Resource operation "${ownerLabel}" ${pathPrefix}["${slotKey}"] must carry a non-empty purpose so translators have a grounded target for every authored override.`,
1370
+ );
1371
+ }
1372
+ assertOptionalNonEmptyProseSlot(
1373
+ ownerLabel,
1374
+ `${pathPrefix}["${slotKey}"].whenToUse`,
1375
+ slot.whenToUse,
1376
+ );
1377
+ assertOptionalNonEmptyStringList(
1378
+ ownerLabel,
1379
+ `${pathPrefix}["${slotKey}"].notes`,
1380
+ slot.notes,
1381
+ );
1382
+ }
1383
+ }
1384
+
1385
+ /**
1386
+ * Defensive guard for any optional `string[]` companion-bullet surface
1387
+ * (notes arrays, businessConstraints arrays, …). When the array is absent
1388
+ * the check is a no-op; when present, every entry must be a non-empty
1389
+ * trimmed string because the renderer emits each entry as a bullet — empty
1390
+ * entries leak blank lines into companion prompts and break the fail-closed
1391
+ * contract the surrounding validators promise.
1392
+ *
1393
+ * The helper is path-agnostic: callers pass the full owner-relative path
1394
+ * (for example `communications.email.codeHandling.notes` or
1395
+ * `scheduledExecution.codeHandling.notes`) so the same primitive serves
1396
+ * every overlay surface without baking a sub-tree prefix into the helper.
1397
+ *
1398
+ * @param ownerLabel Stable identifier of the owning operation (used in error
1399
+ * messages so authors can locate the broken spec immediately).
1400
+ * @param fullPath Dotted owner-relative authoring path; included verbatim in
1401
+ * the error message.
1402
+ */
1403
+ function assertOptionalNonEmptyStringList(
1404
+ ownerLabel: string,
1405
+ fullPath: string,
1406
+ values: string[] | undefined,
1407
+ ): void {
1408
+ if (!values) {
1409
+ return;
1410
+ }
1411
+ for (const [index, value] of values.entries()) {
1412
+ if (typeof value !== 'string' || !value.trim()) {
1413
+ throw new Error(
1414
+ `Resource operation "${ownerLabel}" ${fullPath}[${index}] must be a non-empty trimmed string.`,
1415
+ );
1416
+ }
1417
+ }
1418
+ }
1419
+
1420
+ /**
1421
+ * Cross-validate the optional m2m delivery `level` against the runtime
1422
+ * `M2MNotificationLevel` enum so a typo (`'inf0'`, `'WARN'`, `'crit'`, …)
1423
+ * fails at module load instead of leaking through the spec validator and
1424
+ * surfacing later as a runtime Zod parse error (or, worse, leaking into
1425
+ * companion prompts unchanged).
1426
+ *
1427
+ * The TypeScript declaration `M2MNotificationLevel | (string & {})` exists
1428
+ * to give autocomplete on enum members in IDEs, but the runtime
1429
+ * `M2MNotificationDefinitionSchema` declares `level` as
1430
+ * `z.enum(M2MNotificationLevel).optional()` — strict enum-only. The spec
1431
+ * layer mirrors that runtime contract here so spec → runtime parity is
1432
+ * fail-closed at module load.
1433
+ *
1434
+ * Mirrors `assertSystemEmailTemplateCrossLink` in error-message structure:
1435
+ * `slotPath` is the full owner-relative path included verbatim so authors
1436
+ * can locate the broken delivery directly.
1437
+ */
1438
+ function assertOptionalM2MNotificationLevelMembership(
1439
+ ownerLabel: string,
1440
+ slotPath: string,
1441
+ level: M2MNotificationLevel | (string & {}) | undefined,
1442
+ ): void {
1443
+ if (level === undefined) {
1444
+ return;
1445
+ }
1446
+ const allowedValues = Object.values(M2MNotificationLevel) as string[];
1447
+ if (!allowedValues.includes(level)) {
1448
+ throw new Error(
1449
+ `Resource operation "${ownerLabel}" ${slotPath} "${level}" is not a member of M2MNotificationLevel (expected one of: ${allowedValues.join(', ')}). Use a M2MNotificationLevel enum value so spec → runtime parity stays fail-closed at module load.`,
1450
+ );
1451
+ }
1452
+ }
1453
+
1454
+ /**
1455
+ * Cross-validate one M2M delivery `channelRef` against the owning resource's
1456
+ * `resourcePrimaryScope`.
1457
+ *
1458
+ * The runtime `WEBHOOK_ORGANIZATION` channel only fires when the operation's
1459
+ * resource lives under an organization scope — the dispatcher resolves the
1460
+ * scope from the organization initiator identity, which is only present on
1461
+ * organization-scoped operations.
1462
+ * Authoring `WEBHOOK_ORGANIZATION` on an APPLICATION/USER_SELF/ANONYMOUS
1463
+ * resource silently no-ops at runtime and is therefore a fail-closed
1464
+ * authoring error here.
1465
+ *
1466
+ * `WEBHOOK_APPLICATION` is allowed on any scope: the dispatcher resolves the
1467
+ * application scope from the always-present
1468
+ * `appConfigService.applicationId`, so the channel fires regardless of the
1469
+ * resource's own scope. The check is therefore one-sided — only the
1470
+ * `WEBHOOK_ORGANIZATION` arm fails closed.
1471
+ *
1472
+ * Custom channel refs (anything other than the two `CoreM2MNotificationChannel`
1473
+ * members) bypass the cross-check — third-party channels declare their own
1474
+ * scope semantics and are not the engine's contract.
1475
+ *
1476
+ * The cross-check is skipped when `resourcePrimaryScope` is `undefined`
1477
+ * — a defensive guard for re-validation seams that may be reached without
1478
+ * a scope (e.g., test fixtures invoking the validator directly, or future
1479
+ * call sites that haven't been updated). All production entry points
1480
+ * (`resourceSpecification`, `resourceSpecificationFromFrontendConfiguration`)
1481
+ * thread the scope explicitly, so this branch should not fire from the main
1482
+ * application path.
1483
+ */
1484
+ function assertM2MChannelMatchesPrimaryScope(
1485
+ ownerLabel: string,
1486
+ slotPath: string,
1487
+ channelRef: CoreM2MNotificationChannel | (string & {}),
1488
+ resourcePrimaryScope: ResourcePrimaryScope | undefined,
1489
+ ): void {
1490
+ if (resourcePrimaryScope === undefined) {
1491
+ return;
1492
+ }
1493
+ if (channelRef === CoreM2MNotificationChannel.WEBHOOK_ORGANIZATION) {
1494
+ if (resourcePrimaryScope !== ResourcePrimaryScope.ORGANIZATIONS) {
1495
+ throw new Error(
1496
+ `Resource operation "${ownerLabel}" ${slotPath} declares CoreM2MNotificationChannel.WEBHOOK_ORGANIZATION on a resource whose resourcePrimaryScope is "${resourcePrimaryScope}". WEBHOOK_ORGANIZATION resolves its scope from executionContext.initiatorIds.organizationId, which is only present on resources whose resourcePrimaryScope is "${ResourcePrimaryScope.ORGANIZATIONS}" — for application/user/anonymous-scoped resources use CoreM2MNotificationChannel.WEBHOOK_APPLICATION instead so the dispatcher can resolve the scope from appConfigService.applicationId.`,
1497
+ );
1498
+ }
1499
+ }
1500
+ // WEBHOOK_APPLICATION resolves scope from appConfigService.applicationId,
1501
+ // which is always present, so it is allowed on every primary scope.
1502
+ // Custom (non-Core) channel refs intentionally bypass the cross-check —
1503
+ // third-party channels declare their own scope semantics.
1504
+ }
1505
+
1506
+ /**
1507
+ * Cross-validate the optional `systemEmailTemplateRef` (now per-delivery)
1508
+ * against the runtime `SystemEmailTemplateRegistry` so a typo or stale ref
1509
+ * fails at module load instead of leaking a dangling cross-link into
1510
+ * companion prompts. Mirrors the registered-manifest cross-validation used
1511
+ * by the scheduledExecution `customBatchRef` arm — same anti-pattern, same
1512
+ * fail-closed treatment.
1513
+ *
1514
+ * `slotPath` is the full owner-relative path (e.g.
1515
+ * `communications.email.deliveries[2].systemEmailTemplateRef`) so error
1516
+ * messages locate the broken delivery directly.
1517
+ */
1518
+ function assertSystemEmailTemplateCrossLink(
1519
+ ownerLabel: string,
1520
+ slotPath: string,
1521
+ systemEmailTemplateRef: SystemEmailTemplateRef | undefined,
1522
+ ): void {
1523
+ if (systemEmailTemplateRef === undefined) {
1524
+ return;
1525
+ }
1526
+ if (typeof systemEmailTemplateRef !== 'string' || !systemEmailTemplateRef.trim()) {
1527
+ throw new Error(
1528
+ `Resource operation "${ownerLabel}" ${slotPath} must be a non-empty trimmed SystemEmailTemplateRef value.`,
1529
+ );
1530
+ }
1531
+ if (!Object.prototype.hasOwnProperty.call(SystemEmailTemplateRegistry, systemEmailTemplateRef)) {
1532
+ throw new Error(
1533
+ `Resource operation "${ownerLabel}" ${slotPath} "${systemEmailTemplateRef}" is not a member of SystemEmailTemplateRegistry. Use a SystemEmailTemplateRef enum value or register the template before this spec loads.`,
1534
+ );
1535
+ }
1536
+ }
1537
+
1538
+ /**
1539
+ * Iterate an operation map and validate every authored `communications` block.
1540
+ *
1541
+ * `ownerLabelPrefix` lets factories disambiguate which seam produced the error
1542
+ * (base-operation vs frontend-view), since `ResourceFrontendViewSpecification`
1543
+ * structurally extends `ResourceOperationSpecification` and can therefore
1544
+ * author communications too.
1545
+ */
1546
+ function validateResourceOperationsCommunications(
1547
+ ownerLabelPrefix: string,
1548
+ operations:
1549
+ | Record<string, ResourceOperationSpecification | ResourceFrontendViewSpecification | undefined>
1550
+ | undefined,
1551
+ resourcePrimaryScope?: ResourcePrimaryScope,
1552
+ ): void {
1553
+ if (!operations) {
1554
+ return;
1555
+ }
1556
+ for (const [operationId, operationSpec] of Object.entries(operations)) {
1557
+ if (!operationSpec) {
1558
+ continue;
1559
+ }
1560
+ validateResourceOperationCommunicationsSpecification(
1561
+ `${ownerLabelPrefix}${operationId}`,
1562
+ operationSpec.communications,
1563
+ resourcePrimaryScope,
1564
+ );
1565
+ }
1566
+ }
1567
+
1568
+ const registeredCustomBatchManifests = new Map<string, CustomBatchManifest>();
1569
+
1570
+ /**
1571
+ * Register custom-batch manifests with the spec-layer registry so authored
1572
+ * `scheduledExecution.customBatchRef` values can be cross-validated at
1573
+ * module load. Safe to call multiple times; re-registering the same
1574
+ * `batchRef` with an identical manifest is a no-op, but re-registering with
1575
+ * a divergent shape is a fail-closed error so silent drift between the
1576
+ * runtime batch and the spec layer is caught immediately.
1577
+ *
1578
+ * The framework registers its built-in batches when the public specification
1579
+ * package is loaded. Applications with custom batches should register them
1580
+ * from their specification bootstrap before evaluating a resource
1581
+ * specification that refers to them.
1582
+ *
1583
+ * **Import-order contract — read this if you author CUSTOM_BATCH specs.**
1584
+ * Registering built-in batches depends on loading the public package entry.
1585
+ * A consumer that reaches a low-level internal module first can evaluate a
1586
+ * CUSTOM_BATCH-bearing resource spec against an empty registry and fail closed
1587
+ * on the cross-link check at
1588
+ * {@link validateResourceOperationScheduledExecutionSpecification}. The
1589
+ * fix in that case is to either (a) ensure the engine barrel is imported
1590
+ * first (typically via `import '@wildo-ai/saas-specifications'`), or (b)
1591
+ * explicitly register the manifests required by that application's bootstrap.
1592
+ * Both paths make the contract explicit rather than leaving availability to
1593
+ * import order. Test suites that reset the registry must re-seed for the same
1594
+ * reason.
1595
+ */
1596
+ export function registerCustomBatchManifests(
1597
+ manifests: Iterable<CustomBatchManifest>,
1598
+ ): void {
1599
+ for (const manifest of manifests) {
1600
+ if (!manifest.batchRef || !manifest.batchRef.trim()) {
1601
+ throw new Error('registerCustomBatchManifests(): every manifest must carry a non-empty `batchRef`.');
1602
+ }
1603
+ if (!manifest.operationIdentifier || !manifest.operationIdentifier.trim()) {
1604
+ throw new Error(
1605
+ `registerCustomBatchManifests(): manifest for "${manifest.batchRef}" must declare a non-empty trimmed \`operationIdentifier\`.`,
1606
+ );
1607
+ }
1608
+ assertCustomBatchManifestKindArm(manifest);
1609
+ const existing = registeredCustomBatchManifests.get(manifest.batchRef);
1610
+ if (existing && !areCustomBatchManifestsEqual(existing, manifest)) {
1611
+ throw new Error(
1612
+ `registerCustomBatchManifests(): manifest for "${manifest.batchRef}" was registered twice with divergent shapes. Deduplicate the co-located manifest exports or update the spec-layer registration call.`,
1613
+ );
1614
+ }
1615
+ registeredCustomBatchManifests.set(manifest.batchRef, manifest);
1616
+ }
1617
+ }
1618
+
1619
+ /**
1620
+ * Per-arm structural validation for a {@link CustomBatchManifest} at
1621
+ * registration time. Mirrors the discriminated union split in
1622
+ * `ExecutionContextCreatorBackendService.createForInternalCustomBatch`:
1623
+ *
1624
+ * - `resource_anchored` — must declare a non-empty `resourceIdentifier`.
1625
+ * The spec layer does not (and should not) try to verify that the
1626
+ * identifier resolves to a registered resource — that cross-check lives
1627
+ * inside the runtime EC creator where the resources registry is the
1628
+ * source of truth and where a missing resource fails closed with the
1629
+ * same error message authors already see today.
1630
+ * - `scope_anchored` — must declare a `primaryScope` that is a member of
1631
+ * {@link ResourcePrimaryScope} (the runtime synthetic operation copies
1632
+ * this value into `resourcePrimaryScope`, so a typo would silently
1633
+ * widen or narrow downstream authorization). The `operationIdentifier`
1634
+ * must follow the `<domain>:<batch-ref>` convention so synthetic
1635
+ * operation labels stay grep-able alongside their batch ref — the
1636
+ * convention is also pinned by a dedicated unit test.
1637
+ *
1638
+ * Adding a future arm to {@link CustomBatchManifest} is a compile-time
1639
+ * error in the exhaustive `default` branch, forcing the author to extend
1640
+ * the per-arm rules instead of leaking an unchecked manifest into the
1641
+ * registry.
1642
+ */
1643
+ function assertCustomBatchManifestKindArm(manifest: CustomBatchManifest): void {
1644
+ switch (manifest.kind) {
1645
+ case CustomBatchManifestKind.RESOURCE_ANCHORED: {
1646
+ if (!manifest.resourceIdentifier || !manifest.resourceIdentifier.trim()) {
1647
+ throw new Error(
1648
+ `registerCustomBatchManifests(): resource_anchored manifest for "${manifest.batchRef}" must declare a non-empty trimmed \`resourceIdentifier\`.`,
1649
+ );
1650
+ }
1651
+ return;
1652
+ }
1653
+ case CustomBatchManifestKind.SCOPE_ANCHORED: {
1654
+ const allowedPrimaryScopes = Object.values(ResourcePrimaryScope) as readonly string[];
1655
+ if (!allowedPrimaryScopes.includes(manifest.primaryScope)) {
1656
+ throw new Error(
1657
+ `registerCustomBatchManifests(): scope_anchored manifest for "${manifest.batchRef}" declares unknown primaryScope "${manifest.primaryScope}". Use one of: ${allowedPrimaryScopes.join(', ')}.`,
1658
+ );
1659
+ }
1660
+ const colonIndex = manifest.operationIdentifier.indexOf(':');
1661
+ const domain = colonIndex >= 0 ? manifest.operationIdentifier.slice(0, colonIndex).trim() : '';
1662
+ const tail = colonIndex >= 0 ? manifest.operationIdentifier.slice(colonIndex + 1).trim() : '';
1663
+ if (colonIndex < 0 || !domain || tail !== manifest.batchRef) {
1664
+ throw new Error(
1665
+ `registerCustomBatchManifests(): scope_anchored manifest for "${manifest.batchRef}" must use the "<domain>:${manifest.batchRef}" convention for \`operationIdentifier\` (got "${manifest.operationIdentifier}"). Pick a non-empty domain prefix (e.g. "notifications") so synthetic operation labels stay grep-able alongside their batch ref.`,
1666
+ );
1667
+ }
1668
+ return;
1669
+ }
1670
+ default: {
1671
+ const exhaustiveCheck: never = manifest;
1672
+ throw new Error(
1673
+ `registerCustomBatchManifests(): unsupported CustomBatchManifest kind: ${JSON.stringify(exhaustiveCheck)}.`,
1674
+ );
1675
+ }
1676
+ }
1677
+ }
1678
+
1679
+ /**
1680
+ * Test-only helper that wipes the module-local custom-batch manifest registry.
1681
+ * Authored specifications should never call this at runtime — it exists only
1682
+ * so tests can exercise registration / cross-validation in isolation.
1683
+ */
1684
+ export function resetCustomBatchManifestRegistryForTesting(): void {
1685
+ registeredCustomBatchManifests.clear();
1686
+ }
1687
+
1688
+ /**
1689
+ * Structural equality for two {@link CustomBatchManifest} values, used by
1690
+ * {@link registerCustomBatchManifests} to detect divergent re-registration of
1691
+ * the same `batchRef` across the engine + app bootstrap seams.
1692
+ *
1693
+ * Comparison rules:
1694
+ * - Both manifests must declare the same `kind` discriminator. A
1695
+ * `resource_anchored` manifest is **never** equal to a `scope_anchored`
1696
+ * one even if their non-arm fields happen to align — the two arms model
1697
+ * structurally different bootstrap semantics in
1698
+ * `ExecutionContextCreatorBackendService.createForInternalCustomBatch` and
1699
+ * silently treating them as interchangeable would mask a real authoring
1700
+ * bug at registration time.
1701
+ * - Common fields (`batchRef`, `operationIdentifier`, `cronExpression`,
1702
+ * `cronExpressionConfigurable`) must match across both arms.
1703
+ * - The arm-specific identity field is then compared:
1704
+ * `resourceIdentifier` for `resource_anchored`, `primaryScope` for
1705
+ * `scope_anchored`. The exhaustive switch makes adding a future arm a
1706
+ * compile-time error here rather than a silent equality regression.
1707
+ */
1708
+ function areCustomBatchManifestsEqual(a: CustomBatchManifest, b: CustomBatchManifest): boolean {
1709
+ if (a.kind !== b.kind) {
1710
+ return false;
1711
+ }
1712
+ const commonEqual =
1713
+ a.batchRef === b.batchRef
1714
+ && a.operationIdentifier === b.operationIdentifier
1715
+ && a.cronExpression === b.cronExpression
1716
+ && Boolean(a.cronExpressionConfigurable) === Boolean(b.cronExpressionConfigurable);
1717
+ if (!commonEqual) {
1718
+ return false;
1719
+ }
1720
+ switch (a.kind) {
1721
+ case CustomBatchManifestKind.RESOURCE_ANCHORED:
1722
+ return a.resourceIdentifier
1723
+ === (b as ResourceAnchoredCustomBatchManifest).resourceIdentifier;
1724
+ case CustomBatchManifestKind.SCOPE_ANCHORED:
1725
+ return a.primaryScope
1726
+ === (b as ScopeAnchoredCustomBatchManifest).primaryScope;
1727
+ default: {
1728
+ const exhaustiveCheck: never = a;
1729
+ throw new Error(
1730
+ `areCustomBatchManifestsEqual(): unsupported CustomBatchManifest kind: ${JSON.stringify(exhaustiveCheck)}.`,
1731
+ );
1732
+ }
1733
+ }
1734
+ }
1735
+
1736
+ /**
1737
+ * Validation entry point used by the resource specification factory to assert
1738
+ * that an authored `scheduledExecution` block is internally consistent and,
1739
+ * for custom-batch arms, cross-checks against the declarative
1740
+ * {@link CustomBatchManifest} registry so typos or unregistered refs fail at
1741
+ * module load rather than silently at runtime.
1742
+ *
1743
+ * Each arm of the discriminated union enforces its own fail-closed contract:
1744
+ * - `NATIVE_CRON_JOB`: `cronExpression` must be a non-empty trimmed string.
1745
+ * - `NATIVE_BATCH_JOB`: no schedule or batch ref is permitted.
1746
+ * - `CUSTOM_BATCH`: `customBatchRef` must resolve to a registered manifest;
1747
+ * when the manifest declares a fixed cron the spec must echo it; when the
1748
+ * manifest is `cronExpressionConfigurable: true` the spec only needs to
1749
+ * carry a non-empty cron (divergence from the manifest default is allowed
1750
+ * because the runtime cron comes from app config); when the manifest omits
1751
+ * a cron entirely the spec must omit it too.
1752
+ *
1753
+ * Cross-validation is opt-in by design: the spec layer is built around a
1754
+ * declarative `CustomBatchManifest` registry seeded by the engine (and
1755
+ * optionally by app bootstraps) rather than an imperative dependency on
1756
+ * runtime service instances. If no manifest has been registered for a
1757
+ * `customBatchRef`, validation fails closed with an actionable message.
1758
+ *
1759
+ * **Test-suite seeding contract.** The framework registers built-in batches
1760
+ * when the public package entry is imported. Test files that
1761
+ * (a) reset the registry via {@link resetCustomBatchManifestRegistryForTesting}
1762
+ * and (b) need engine batches available afterwards must re-seed by calling
1763
+ * `registerCustomBatchManifests(ENGINE_CUSTOM_BATCH_MANIFESTS)` in `beforeAll`
1764
+ * or `beforeEach`. The current test suites either scope their reset to
1765
+ * test-only manifests or never reach built-in batches, so this remains an
1766
+ * explicit test setup contract.
1767
+ *
1768
+ * @param ownerLabel Stable identifier of the owning operation (used in error
1769
+ * messages so authors can locate the broken spec immediately).
1770
+ */
1771
+ export function validateResourceOperationScheduledExecutionSpecification(
1772
+ ownerLabel: string,
1773
+ scheduledExecution: ResourceOperationScheduledExecutionSpecification | undefined,
1774
+ ): void {
1775
+ if (!scheduledExecution) {
1776
+ return;
1777
+ }
1778
+ assertNonEmptyScheduledExecutionProseSlot(ownerLabel, 'purpose', scheduledExecution.purpose);
1779
+ assertNonEmptyScheduledExecutionProseSlot(ownerLabel, 'outcome', scheduledExecution.outcome);
1780
+ assertOptionalNonEmptyProseSlot(
1781
+ ownerLabel,
1782
+ 'scheduledExecution.useWhen',
1783
+ scheduledExecution.useWhen,
1784
+ );
1785
+ assertOptionalNonEmptyProseSlot(
1786
+ ownerLabel,
1787
+ 'scheduledExecution.avoidWhen',
1788
+ scheduledExecution.avoidWhen,
1789
+ );
1790
+ assertOptionalNonEmptyStringList(
1791
+ ownerLabel,
1792
+ 'scheduledExecution.businessConstraints',
1793
+ scheduledExecution.businessConstraints,
1794
+ );
1795
+ assertOptionalNonEmptyStringList(
1796
+ ownerLabel,
1797
+ 'scheduledExecution.codeHandling.notes',
1798
+ scheduledExecution.codeHandling?.notes,
1799
+ );
1800
+
1801
+ switch (scheduledExecution.variantType) {
1802
+ case ResourceOperationScheduledExecutionVariantType.NATIVE_CRON_JOB:
1803
+ assertNativeCronJobArm(ownerLabel, scheduledExecution);
1804
+ return;
1805
+ case ResourceOperationScheduledExecutionVariantType.NATIVE_BATCH_JOB:
1806
+ assertNativeBatchJobArm(ownerLabel, scheduledExecution);
1807
+ return;
1808
+ case ResourceOperationScheduledExecutionVariantType.CUSTOM_BATCH:
1809
+ assertCustomBatchArm(ownerLabel, scheduledExecution);
1810
+ return;
1811
+ default: {
1812
+ const exhaustiveCheck: never = scheduledExecution;
1813
+ throw new Error(
1814
+ `Resource operation "${ownerLabel}" scheduledExecution carries an unsupported variantType: ${JSON.stringify(exhaustiveCheck)}.`,
1815
+ );
1816
+ }
1817
+ }
1818
+ }
1819
+
1820
+ function assertNonEmptyScheduledExecutionProseSlot(
1821
+ ownerLabel: string,
1822
+ slotLabel: 'purpose' | 'outcome',
1823
+ value: string | undefined,
1824
+ ): void {
1825
+ if (!value || !value.trim()) {
1826
+ throw new Error(
1827
+ `Resource operation "${ownerLabel}" scheduledExecution.${slotLabel} must be a non-empty prose slot so companion prompts have grounded cron-run semantics.`,
1828
+ );
1829
+ }
1830
+ }
1831
+
1832
+ /**
1833
+ * Defense-in-depth runtime guards for the NATIVE_CRON_JOB arm.
1834
+ *
1835
+ * The static type already requires `cronExpression: string` and does **not**
1836
+ * declare `customBatchRef`, so well-typed authoring sites cannot reach an
1837
+ * invalid state. We still trim-check `cronExpression` and structurally reject
1838
+ * a smuggled `customBatchRef` so authoring sites that bypass type narrowing
1839
+ * (`as never`, `as any`, dynamic data, custom factories) cannot leak a blank
1840
+ * schedule or a foreign field into companion prompts. Symmetric with
1841
+ * {@link assertNativeBatchJobArm} so every arm enforces the same defensive
1842
+ * discipline.
1843
+ */
1844
+ function assertNativeCronJobArm(
1845
+ ownerLabel: string,
1846
+ arm: NativeCronJobScheduledExecutionSpecification,
1847
+ ): void {
1848
+ if (!arm.cronExpression || !arm.cronExpression.trim()) {
1849
+ throw new Error(
1850
+ `Resource operation "${ownerLabel}" scheduledExecution.cronExpression must be a non-empty trimmed cron expression for the NATIVE_CRON_JOB arm (the runtime CRON_JOB variant requires a concrete schedule).`,
1851
+ );
1852
+ }
1853
+ if ('customBatchRef' in arm && (arm as unknown as { customBatchRef?: unknown }).customBatchRef !== undefined) {
1854
+ throw new Error(
1855
+ `Resource operation "${ownerLabel}" scheduledExecution cannot declare customBatchRef for the NATIVE_CRON_JOB arm — custom batches belong to the CUSTOM_BATCH arm so the declarative manifest cross-validation runs.`,
1856
+ );
1857
+ }
1858
+ }
1859
+
1860
+ /**
1861
+ * Defense-in-depth runtime guards for the NATIVE_BATCH_JOB arm.
1862
+ *
1863
+ * The static type does **not** declare `cronExpression` or `customBatchRef`,
1864
+ * so well-typed authoring sites cannot reach this state. The structural
1865
+ * `'<key>' in arm` checks back the `// @ts-expect-error` test cases and
1866
+ * protect against dynamic data or `as any` bypasses at authoring sites — if
1867
+ * an author silences TypeScript to attach a stray field to a batch-job arm,
1868
+ * the validator still rejects it at module load.
1869
+ */
1870
+ function assertNativeBatchJobArm(
1871
+ ownerLabel: string,
1872
+ arm: NativeBatchJobScheduledExecutionSpecification,
1873
+ ): void {
1874
+ if ('cronExpression' in arm && (arm as unknown as { cronExpression?: unknown }).cronExpression !== undefined) {
1875
+ throw new Error(
1876
+ `Resource operation "${ownerLabel}" scheduledExecution cannot declare cronExpression for the NATIVE_BATCH_JOB arm — batch-job variants are event-triggered and never carry a cron. Move the schedule to the NATIVE_CRON_JOB or CUSTOM_BATCH arm.`,
1877
+ );
1878
+ }
1879
+ if ('customBatchRef' in arm && (arm as unknown as { customBatchRef?: unknown }).customBatchRef !== undefined) {
1880
+ throw new Error(
1881
+ `Resource operation "${ownerLabel}" scheduledExecution cannot declare customBatchRef for the NATIVE_BATCH_JOB arm — custom batches belong to the CUSTOM_BATCH arm so the declarative manifest and cron echo stay consistent.`,
1882
+ );
1883
+ }
1884
+ }
1885
+
1886
+ /**
1887
+ * Validates the CUSTOM_BATCH arm against the spec-layer manifest registry.
1888
+ *
1889
+ * Cron-echo policy:
1890
+ * - **Fixed-cron manifest** (`cronExpressionConfigurable !== true` and
1891
+ * `cronExpression` declared): the authored spec must echo the manifest's
1892
+ * cron exactly, so companion prompts and the runtime cannot drift.
1893
+ * - **Configurable-cron manifest** (`cronExpressionConfigurable === true`):
1894
+ * the authored spec must still carry a non-empty cron (companion prompts
1895
+ * need a cadence) but is free to diverge from the manifest's runtime
1896
+ * default — divergence is the whole point of configurability.
1897
+ * - **Event-triggered manifest** (`cronExpression` undefined): the spec
1898
+ * must omit `cronExpression` so it does not invent a schedule the runtime
1899
+ * never honors.
1900
+ */
1901
+ function assertCustomBatchArm(
1902
+ ownerLabel: string,
1903
+ arm: CustomBatchScheduledExecutionSpecification,
1904
+ ): void {
1905
+ if (!arm.customBatchRef || !arm.customBatchRef.trim()) {
1906
+ throw new Error(
1907
+ `Resource operation "${ownerLabel}" scheduledExecution.customBatchRef must be a non-empty trimmed batch ref for the CUSTOM_BATCH arm (for example "files-cleanup").`,
1908
+ );
1909
+ }
1910
+ if (
1911
+ 'cronExpression' in arm
1912
+ && arm.cronExpression !== undefined
1913
+ && (!arm.cronExpression || !arm.cronExpression.trim())
1914
+ ) {
1915
+ throw new Error(
1916
+ `Resource operation "${ownerLabel}" scheduledExecution.cronExpression must be a non-empty trimmed cron expression when provided (authors must not declare an empty schedule).`,
1917
+ );
1918
+ }
1919
+
1920
+ const manifest = registeredCustomBatchManifests.get(arm.customBatchRef);
1921
+ if (!manifest) {
1922
+ throw new Error(
1923
+ `Resource operation "${ownerLabel}" scheduledExecution.customBatchRef "${arm.customBatchRef}" is not registered. Either export a CustomBatchManifest next to the batch factory (engine batches go through ENGINE_CUSTOM_BATCH_MANIFESTS) and call registerCustomBatchManifests() before this spec loads, or correct the ref.`,
1924
+ );
1925
+ }
1926
+ if (manifest.cronExpression && !arm.cronExpression) {
1927
+ throw new Error(
1928
+ `Resource operation "${ownerLabel}" scheduledExecution.cronExpression must echo the runtime cron "${manifest.cronExpression}" declared by custom batch "${arm.customBatchRef}" so companion prompts see the authoritative cadence.`,
1929
+ );
1930
+ }
1931
+ if (!manifest.cronExpression && arm.cronExpression) {
1932
+ throw new Error(
1933
+ `Resource operation "${ownerLabel}" scheduledExecution.cronExpression is declared but custom batch "${arm.customBatchRef}" is registered without a cron (event-triggered). Remove the authored cron or update the manifest if the runtime actually schedules this batch.`,
1934
+ );
1935
+ }
1936
+ if (
1937
+ manifest.cronExpression
1938
+ && arm.cronExpression
1939
+ && !manifest.cronExpressionConfigurable
1940
+ && manifest.cronExpression !== arm.cronExpression
1941
+ ) {
1942
+ throw new Error(
1943
+ `Resource operation "${ownerLabel}" scheduledExecution.cronExpression "${arm.cronExpression}" does not match the manifest cron "${manifest.cronExpression}" for custom batch "${arm.customBatchRef}". Align the authored cron with the runtime batchCronjob_Context, or mark the manifest as cronExpressionConfigurable if the schedule is intentionally driven by app config.`,
1944
+ );
1945
+ }
1946
+ }
1947
+
1948
+ /**
1949
+ * Iterate an operation map and validate every authored `scheduledExecution`
1950
+ * block. Same dual-seam rationale as communications: base-operation and
1951
+ * frontend-operation both structurally carry the slot, and both seams must
1952
+ * fail closed at module load.
1953
+ */
1954
+ function validateResourceOperationsScheduledExecution(
1955
+ ownerLabelPrefix: string,
1956
+ operations:
1957
+ | Record<string, ResourceOperationSpecification | ResourceFrontendViewSpecification | undefined>
1958
+ | undefined,
1959
+ ): void {
1960
+ if (!operations) {
1961
+ return;
1962
+ }
1963
+ for (const [operationId, operationSpec] of Object.entries(operations)) {
1964
+ if (!operationSpec) {
1965
+ continue;
1966
+ }
1967
+ validateResourceOperationScheduledExecutionSpecification(
1968
+ `${ownerLabelPrefix}${operationId}`,
1969
+ operationSpec.scheduledExecution,
1970
+ );
1971
+ }
1972
+ }
1973
+
1974
+ export type ResourceOperationSpecificationMap<
1975
+ TCustomOp extends EnumLikeType | undefined = any,
1976
+ TCoreOp extends Partial<CoreResourceOperation> | undefined = any,
1977
+ > = Partial<Record<ValidOperationKeys<TCustomOp, TCoreOp>, ResourceOperationSpecification>>;
1978
+ ```