@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,2610 @@
1
+ # Framework — resource specification contracts (saas-specifications)
2
+
3
+ Source-backed excerpts for operation/variant prose, frontend aspect distillation, spec `frontend` prose and config types, `codeHandling`, `ResourceSpecificationConfig`, and `resourceSpecification()` factory.
4
+
5
+ ## Import Origins
6
+
7
+ - `@wildo-ai/saas-specifications`
8
+
9
+ ## Source Excerpts
10
+
11
+ ### Origin Package: `@wildo-ai/saas-specifications`
12
+
13
+ ```typescript
14
+ *
15
+ * Companion-facing semantic prose for operations and variants (`resourceSpecification().operations`).
16
+ *
17
+ * **Per-variant** semantics (`ResourceOperationVariantSpecification`):
18
+ * Provides sparse overlays for an operation's business prose and, when an
19
+ * HTTP response shape genuinely differs, its payload examples. URLs, DTO
20
+ * shape, and authorization rules remain structural contracts; prose explains
21
+ * what the operation accomplishes in business terms, while examples make the
22
+ * concrete transport representation understandable.
23
+ *
24
+ * **Per-operation** map types (`ResourceOperationSpecification`, maps) layer
25
+ * shared operation meaning plus optional named variants (`admin`, `summary`,
26
+ * `context`, …) aligned with the resource configuration vocabulary.
27
+ *
28
+ * **HTTP documentation** fields on `ResourceOperationSpecification`
29
+ * (`responseStatuses`, `errorScenarios`, `idempotent`, `rateLimitNote`,
30
+ * `examples`) carry the transport-level outcomes the OpenAPI generator emits
31
+ * as `responses` / `examples` / `x-idempotent`. Response outcomes are
32
+ * per-operation. Base examples apply to every variant unless a variant owns a
33
+ * complete replacement, preventing a full DTO example from leaking into a
34
+ * context or summary response. HTTP-only fields are intentionally excluded
35
+ * from frontend-view specs, which are not HTTP operations.
36
+ */
37
+ export interface ResourceOperationVariantSpecification {
38
+ /** Business intent of the operation when this variant differs from the base operation. */
39
+ purpose?: string;
40
+ /** Observable business result once the operation succeeds. */
41
+ outcome?: string;
42
+ /** Guidance about when this operation is the right choice. */
43
+ whenToUse?: string;
44
+ /** Relative weight of this operation in the resource understanding. */
45
+ importance?: FieldSemanticImportance;
46
+ /**
47
+ * Override the resource-level label {@link LabelAudience} for THIS operation's
48
+ * generated labels. Use when a mostly-end-user resource exposes an admin-only
49
+ * operation (or vice-versa) so its copy adopts the right register without
50
+ * reclassifying the whole resource. Omit to inherit the resource's `audience`.
51
+ */
52
+ audienceOverride?: LabelAudience;
53
+ /**
54
+ * Variant-specific OpenAPI examples. When present, these REPLACE the base
55
+ * operation `examples` for this variant; they never merge. Use this where a
56
+ * context or summary response has a different schema from the default path.
57
+ */
58
+ examples?: ResourceOperationExampleSpecification[];
59
+ }
60
+
61
+ /**
62
+ * Variant map for one operation.
63
+ *
64
+ * `default` represents the default/no-explicit-variant path. Named variant keys
65
+ * (`admin`, `summary`, `context`, `internal`, ...) mirror the authored
66
+ * operation-variant vocabulary instead of flattening them into synthetic tuples.
67
+ */
68
+ export type ResourceOperationSpecificationVariants = Record<string, ResourceOperationVariantSpecification | undefined> & {
69
+ default?: ResourceOperationVariantSpecification;
70
+ };
71
+
72
+ /**
73
+ * Frontend-view variants preserve business semantics but deliberately exclude
74
+ * HTTP examples: a frontend view is not an API operation and must not become a
75
+ * second authoring path for generated OpenAPI payloads.
76
+ */
77
+ export type ResourceFrontendViewSpecificationVariants = Record<
78
+ string,
79
+ Omit<ResourceOperationVariantSpecification, 'examples'> | undefined
80
+ > & {
81
+ default?: Omit<ResourceOperationVariantSpecification, 'examples'>;
82
+ };
83
+
84
+ /**
85
+ * Import-oriented metadata for the email fired by a resource operation.
86
+ *
87
+ * Lets downstream transposer/code-generation layers point at the real event
88
+ * payload schema without re-reading the resource's backend code.
89
+ */
90
+ export interface ResourceOperationEmailSpecificationCodeHandling {
91
+ /** Public Zod schema symbol that describes the event payload of the email. */
92
+ eventDataSchemaSymbol?: CodeSymbolRef;
93
+ /** Public TypeScript type symbol when the payload type is split from its Zod schema. */
94
+ eventDataTypeSymbol?: CodeSymbolRef;
95
+ /** Extra supporting symbols (builders, renderers) that transposer prompts need. */
96
+ supportingSymbols?: CodeSymbolRef[];
97
+ /** Companion/transposer caveats that must survive serialization. */
98
+ notes?: string[];
99
+ }
100
+
101
+ /**
102
+ * Semantic overlay for ONE email delivery fired by a resource operation.
103
+ *
104
+ * Models the engine fan-out faithfully: every entry in the runtime
105
+ * `userNotifications[]` array with `channel === EMAIL` is one delivery, and
106
+ * the runtime constructs a distinct template-ref path for each
107
+ * `(variantKey, targetType, customNotificationRef)` combination through the
108
+ * notifications dispatcher (`email.{resourceId}.{op}.{variant?}.{target-kebab}_{customRef?}`).
109
+ *
110
+ * Authoring sites declare one delivery per such combination so:
111
+ * - companion prompts know exactly how many template files exist for the operation,
112
+ * - translators can author per-delivery overrides when the audience changes the copy,
113
+ * - transposers can compute the runtime template-ref path from the spec without
114
+ * re-reading the resource configuration code.
115
+ *
116
+ * The parent `ResourceOperationEmailSpecification` carries shared semantics
117
+ * (purpose, tone, default text slots, event data); per-delivery overrides
118
+ * layer on top via `purposeOverride`, `textSlotsOverrides`,
119
+ * `additionalBusinessConstraints`. Omit overrides when the delivery shares
120
+ * the parent copy verbatim — that is the common case.
121
+ */
122
+ export interface ResourceOperationEmailDeliverySpecification {
123
+ /**
124
+ * Audience description: who receives this delivery and why. Required —
125
+ * the deliveries axis exists specifically to distinguish audiences (creator
126
+ * vs assignee vs admin recipient, …), so an undocumented audience defeats
127
+ * the purpose of fanning out.
128
+ */
129
+ audience: string;
130
+ /**
131
+ * Target type from the runtime `UserNotificationDefinition.target` (see
132
+ * `CoreUserNotificationTarget` — `USERS_CUSTOM`, `USER_SELF`,
133
+ * `ORGANIZATION_USERS`, …). The dispatcher kebab-cases this and appends
134
+ * it to the template-ref path, so spec authors must echo the exact runtime
135
+ * target so the computed path stays truthful.
136
+ */
137
+ targetRef: CoreUserNotificationTarget | (string & {});
138
+ /**
139
+ * Operation variant this delivery belongs to. `undefined` means the default
140
+ * variant (no `variantKey` segment in the runtime path). Maps to
141
+ * `variantKey` on the runtime variant when present.
142
+ */
143
+ variantRef?: string;
144
+ /**
145
+ * Distinguishes deliveries when the same `(variantRef, targetRef)` fires
146
+ * multiple emails. Maps 1:1 to `customNotificationRef` on the runtime
147
+ * `UserNotificationDefinition`. Required by the engine when more than one
148
+ * `USERS_CUSTOM` notification appears in the same operation (to make the
149
+ * template paths unique); the spec validator mirrors that contract.
150
+ */
151
+ customDeliveryRef?: string;
152
+ /**
153
+ * Stable `SystemEmailTemplateRef` THIS delivery resolves to, when the
154
+ * runtime template path corresponds to an entry registered in
155
+ * `SystemEmailTemplateRegistry` (system-level emails such as
156
+ * `WELCOME_EMAIL`, `ORGANIZATION_INVITATION`, …). Use it to cross-link a
157
+ * resource-initiated trigger to its authored
158
+ * `SystemEmailTemplateSpecification` overlay in companion prompts.
159
+ *
160
+ * Lives per-delivery (not on `codeHandling`) because the runtime
161
+ * template-ref path is per-delivery: every authored
162
+ * `(variantRef, targetRef, customDeliveryRef)` triple resolves to ONE
163
+ * concrete template, so each delivery either points at a registered
164
+ * `SystemEmailTemplateRef` or — for resource-local templates that live
165
+ * outside `SystemEmailTemplateRegistry` (e.g. Your Application
166
+ * `email.todos.change_status.users-custom_notify-creator`) — leaves the
167
+ * field undefined.
168
+ *
169
+ * Cross-validated at module load against `SystemEmailTemplateRegistry` so
170
+ * a typo or stale ref fails closed instead of leaking a dangling cross-
171
+ * link into companion prompts. Typed as the enum to give authors
172
+ * autocomplete and eliminate the silent-string-identity anti-pattern.
173
+ */
174
+ systemEmailTemplateRef?: SystemEmailTemplateRef;
175
+ /**
176
+ * Optional per-delivery overrides for translatable text slots. When a key
177
+ * is present here, it replaces the parent `textSlots[key]` for THIS
178
+ * delivery only (e.g., creator and assignee share the parent subject
179
+ * normally, but the admin variant for the creator uses a different one).
180
+ * Omit entirely when the delivery uses the parent copy verbatim.
181
+ */
182
+ textSlotsOverrides?: TranslationSlotSpecificationMap;
183
+ /**
184
+ * Per-delivery override for `purpose` when this delivery has its own intent
185
+ * distinct from the parent (e.g., the admin variant explains a managerial
186
+ * intervention rather than a self-progress signal). Falls back to the
187
+ * parent `purpose` when omitted.
188
+ */
189
+ purposeOverride?: string;
190
+ /**
191
+ * Domain/compliance caveats that apply to THIS delivery only, layered on
192
+ * top of the parent `businessConstraints` (which apply to all deliveries).
193
+ */
194
+ additionalBusinessConstraints?: string[];
195
+ /** Companion/transposer caveats specific to this delivery. */
196
+ notes?: string[];
197
+ }
198
+
199
+ /**
200
+ * Semantic overlay for the email fired by a resource operation.
201
+ *
202
+ * Follows the same authoring shape as `SystemEmailTemplateSpecification`:
203
+ * `purpose` and `tone` are plain authoring prose, while every translatable
204
+ * fragment (subject, previewText, ctaLabel, heading, body, …) lives inside
205
+ * `textSlots`. `eventData` documents the meaning of the payload used to render
206
+ * the email so translators know which runtime values will land in each slot.
207
+ *
208
+ * A resource-initiated email is always anchored to its operation: the same
209
+ * action decides what is sent, to whom, and why, so the companion resolves the
210
+ * wording through the operation spec instead of a parallel family.
211
+ *
212
+ * **Engine-parity contract for `deliveries`**. The runtime fans out one email
213
+ * per entry in `userNotifications[]` with `channel === EMAIL`, computing a
214
+ * distinct template-ref path per `(variantKey, target, customNotificationRef)`
215
+ * combination. The spec layer mirrors this faithfully: every such runtime
216
+ * delivery must be authored as one entry in `deliveries`, so the spec is
217
+ * never silent about a real runtime template path. A single-delivery email
218
+ * still needs one `deliveries` entry — the array is required so the engine
219
+ * fan-out semantics are explicit at every authoring site, not implicit in
220
+ * the absence of the field.
221
+ */
222
+ export interface ResourceOperationEmailSpecification {
223
+ /** Why this operation fires an email (shared intent across all deliveries). */
224
+ purpose: string;
225
+ /** Expected voice/posture for the generated copy (urgent, reassuring, informational, ...). */
226
+ tone: string;
227
+ /** Situations where this email must be sent alongside the operation. */
228
+ useWhen?: string;
229
+ /** Situations where this email should not fire (e.g. reassignment to the same user). */
230
+ avoidWhen?: string;
231
+ /**
232
+ * Translatable text slots for the email (`subject`, `previewText`,
233
+ * `ctaLabel`, or any template-specific named slot) with per-slot meaning
234
+ * for translators. `subject` is required because every transactional email
235
+ * needs a subject line. Per-delivery overrides live on each
236
+ * `deliveries[i].textSlotsOverrides`.
237
+ */
238
+ textSlots: TranslationSlotSpecificationMap;
239
+ /** Meaning of the event payload this email renders with (shared across deliveries). */
240
+ eventData?: TranslationSlotSpecification;
241
+ /** Domain/compliance caveats that matter beyond the operation's own constraints. */
242
+ businessConstraints?: string[];
243
+ /**
244
+ * Explicit fan-out: one entry per runtime `userNotifications[]` email
245
+ * delivery. At least one entry is required when an `email` block is
246
+ * authored — see the JSDoc on the parent interface for the engine-parity
247
+ * rationale. The validator enforces uniqueness on
248
+ * `(variantRef, targetRef, customDeliveryRef)` triples and rejects
249
+ * duplicates that would compute the same runtime template-ref path.
250
+ */
251
+ deliveries: ResourceOperationEmailDeliverySpecification[];
252
+ /** Import-oriented coding/transposition metadata. */
253
+ codeHandling?: ResourceOperationEmailSpecificationCodeHandling;
254
+ }
255
+
256
+ /**
257
+ * Import-oriented metadata for the notification fired by a resource operation.
258
+ */
259
+ export interface ResourceOperationNotificationSpecificationCodeHandling {
260
+ /**
261
+ * Public enum exposing the channel vocabulary that each
262
+ * `deliveries[i].channelRef` is drawn from (for example
263
+ * `CoreUserNotificationChannel`). Custom channels remain expressible as raw
264
+ * strings on `deliveries[i].channelRef`, but declaring the owning enum lets
265
+ * transposer layers import the canonical members when generating
266
+ * notification dispatch code.
267
+ */
268
+ channelEnum?: CodeSymbolRef;
269
+ /** Public Zod schema symbol describing the notification event payload. */
270
+ eventDataSchemaSymbol?: CodeSymbolRef;
271
+ /** Public TypeScript type symbol when the payload type is split from its Zod schema. */
272
+ eventDataTypeSymbol?: CodeSymbolRef;
273
+ /** Extra supporting symbols that transposer prompts need. */
274
+ supportingSymbols?: CodeSymbolRef[];
275
+ /** Companion/transposer caveats that must survive serialization. */
276
+ notes?: string[];
277
+ }
278
+
279
+ /**
280
+ * Semantic overlay for ONE in-app notification delivery fired by a resource
281
+ * operation.
282
+ *
283
+ * Models the engine fan-out faithfully: every entry in the runtime
284
+ * `userNotifications[]` array whose `channel` is NOT `EMAIL` is one in-app
285
+ * notification delivery (FRONT_END_SUCCESS toast for the actor, WEBSOCKET push
286
+ * to the activity feed, SMS / PUSH when implemented, …). Each delivery is
287
+ * its own (target, channel) pair at runtime; the spec layer mirrors this so
288
+ * companion prompts know exactly which surfaces the operation actually
289
+ * touches, and translators can author per-delivery copy when a specific
290
+ * channel needs different wording (e.g. SMS character limits vs WebSocket
291
+ * activity-feed prose).
292
+ */
293
+ export interface ResourceOperationNotificationDeliverySpecification {
294
+ /**
295
+ * Audience description: who receives this delivery (the actor themselves
296
+ * via FRONT_END_SUCCESS, the rest of the organization via WEBSOCKET, …).
297
+ * Required — the deliveries axis exists specifically to distinguish
298
+ * audiences, so an undocumented audience defeats the purpose of fanning
299
+ * out.
300
+ */
301
+ audience: string;
302
+ /**
303
+ * Channel the runtime fires through (e.g. `FRONT_END_SUCCESS`, `WEBSOCKET`,
304
+ * `SMS`, `PUSH`). Authoring sites should use `CoreUserNotificationChannel`
305
+ * members for built-in channels (autocomplete + typo-protection); custom
306
+ * channels remain expressible as raw strings.
307
+ */
308
+ channelRef: CoreUserNotificationChannel | (string & {});
309
+ /**
310
+ * Target type from the runtime `UserNotificationDefinition.target` (see
311
+ * `CoreUserNotificationTarget`). Documents whether the delivery is
312
+ * actor-only (`USER_SELF`), org-wide (`ORGANIZATION_USERS`), a specific
313
+ * audience (`USERS_CUSTOM` with a selector), …
314
+ */
315
+ targetRef: CoreUserNotificationTarget | (string & {});
316
+ /**
317
+ * Operation variant this delivery belongs to. `undefined` means the default
318
+ * variant. Maps to `variantKey` on the runtime variant when present.
319
+ */
320
+ variantRef?: string;
321
+ /**
322
+ * Distinguishes deliveries when the same `(variantRef, targetRef, channelRef)`
323
+ * triple fires multiple notifications (rare but supported by the runtime
324
+ * via `customNotificationRef`).
325
+ */
326
+ customDeliveryRef?: string;
327
+ /** Per-delivery overrides for translatable text slots. */
328
+ textSlotsOverrides?: TranslationSlotSpecificationMap;
329
+ /** Per-delivery override for `purpose` when this delivery has its own intent. */
330
+ purposeOverride?: string;
331
+ /** Per-delivery business constraints layered on top of the parent list. */
332
+ additionalBusinessConstraints?: string[];
333
+ /** Companion/transposer caveats specific to this delivery. */
334
+ notes?: string[];
335
+ }
336
+
337
+ /**
338
+ * Semantic overlay for the in-app notifications fired by a resource operation.
339
+ *
340
+ * Mirrors `ResourceOperationEmailSpecification` for consistency: `purpose`
341
+ * and `tone` are plain authoring prose; every translatable fragment (title,
342
+ * body, actionLabel, …) lives in `textSlots`; `eventData` documents the
343
+ * payload meaning. The `deliveries` array makes the engine fan-out explicit
344
+ * — every runtime `userNotifications[]` entry with a non-EMAIL channel maps
345
+ * to one entry here so the spec is never silent about a real runtime
346
+ * notification surface.
347
+ */
348
+ export interface ResourceOperationNotificationSpecification {
349
+ /** Why this operation fires in-app notifications (shared across deliveries). */
350
+ purpose: string;
351
+ /** Expected voice/posture for the generated copy. */
352
+ tone: string;
353
+ /** Situations where this notification must be raised alongside the operation. */
354
+ useWhen?: string;
355
+ /** Situations where this notification should not fire. */
356
+ avoidWhen?: string;
357
+ /**
358
+ * Translatable text slots for the notification (`title`, `body`,
359
+ * `actionLabel`, or any channel-specific named slot). `title` is required
360
+ * so every notification has a recognisable headline for translators and
361
+ * transposers to target. Per-delivery overrides live on each
362
+ * `deliveries[i].textSlotsOverrides`.
363
+ */
364
+ textSlots: TranslationSlotSpecificationMap;
365
+ /**
366
+ * Explicit fan-out: one entry per runtime `userNotifications[]` non-EMAIL
367
+ * delivery. At least one entry is required when a `notification` block is
368
+ * authored. The validator enforces uniqueness on
369
+ * `(variantRef, targetRef, channelRef, customDeliveryRef)` quadruples.
370
+ */
371
+ deliveries: ResourceOperationNotificationDeliverySpecification[];
372
+ /** Meaning of the event payload the notification renders with. */
373
+ eventData?: TranslationSlotSpecification;
374
+ /** Domain/compliance caveats that matter beyond the operation's own constraints. */
375
+ businessConstraints?: string[];
376
+ /** Import-oriented coding/transposition metadata. */
377
+ codeHandling?: ResourceOperationNotificationSpecificationCodeHandling;
378
+ }
379
+
380
+ /**
381
+ * Import-oriented metadata for the M2M (machine-to-machine) notifications
382
+ * fired by a resource operation.
383
+ *
384
+ * M2M notifications are webhook-style fan-outs declared on the resource
385
+ * operation's `m2mNotifications[]` array (see `CoreM2MNotificationChannel` —
386
+ * `WEBHOOK_ORGANIZATION`, `WEBHOOK_APPLICATION`, …). They never carry
387
+ * user-facing copy; transposers/companion prompts only need to know the
388
+ * channel vocabulary, the level vocabulary, and the payload schema to
389
+ * generate truthful integration code.
390
+ */
391
+ export interface ResourceOperationM2MSpecificationCodeHandling {
392
+ /**
393
+ * Public enum exposing the channel vocabulary that `deliveries[i].channelRef`
394
+ * members come from (for example `CoreM2MNotificationChannel`). Custom
395
+ * channels can still be authored as raw string refs in `channelRef`, but
396
+ * declaring the owning enum lets transposer layers import the canonical
397
+ * members when generating webhook dispatch code.
398
+ */
399
+ channelEnum?: CodeSymbolRef;
400
+ /**
401
+ * Public enum exposing the severity vocabulary that `deliveries[i].level`
402
+ * members come from (for example `M2MNotificationLevel`).
403
+ */
404
+ levelEnum?: CodeSymbolRef;
405
+ /**
406
+ * Public Zod schema describing the m2m payload (often the resource main
407
+ * schema augmented with operation metadata, but operations are free to
408
+ * publish a webhook-shaped projection).
409
+ */
410
+ payloadSchemaSymbol?: CodeSymbolRef;
411
+ /** Public TypeScript type symbol when the payload type is split from its Zod schema. */
412
+ payloadTypeSymbol?: CodeSymbolRef;
413
+ /** Extra supporting symbols transposer prompts may need. */
414
+ supportingSymbols?: CodeSymbolRef[];
415
+ /** Companion/transposer caveats that must survive serialization. */
416
+ notes?: string[];
417
+ }
418
+
419
+ /**
420
+ * Semantic overlay for ONE M2M notification delivery fired by a resource
421
+ * operation. Each entry in the runtime `m2mNotifications[]` array maps to
422
+ * one entry here so the spec stays parity-faithful with the engine fan-out.
423
+ */
424
+ export interface ResourceOperationM2MDeliverySpecification {
425
+ /**
426
+ * Audience description: which integration consumers receive this webhook
427
+ * (the organization's configured webhook endpoints, the application's
428
+ * platform-wide endpoint, …). Required for the same fan-out reason as the
429
+ * email/notification delivery audiences.
430
+ */
431
+ audience: string;
432
+ /**
433
+ * Channel ref (e.g. `CoreM2MNotificationChannel.WEBHOOK_ORGANIZATION`).
434
+ * Authoring sites should use `CoreM2MNotificationChannel` members for
435
+ * built-in channels (autocomplete + typo-protection); custom channels
436
+ * remain expressible as raw strings.
437
+ */
438
+ channelRef: CoreM2MNotificationChannel | (string & {});
439
+ /**
440
+ * Severity classification (info / success / error). Authoring sites should
441
+ * use `M2MNotificationLevel` members; mirrors the runtime enum.
442
+ */
443
+ level?: M2MNotificationLevel | (string & {});
444
+ /**
445
+ * Operation variant this delivery belongs to. `undefined` means the default
446
+ * variant. Maps to `variantKey` on the runtime variant when present.
447
+ */
448
+ variantRef?: string;
449
+ /**
450
+ * Distinguishes deliveries when the same `(variantRef, channelRef, level)`
451
+ * triple fires multiple webhooks (e.g. one operation publishing both an
452
+ * org webhook and a partner-specific custom channel).
453
+ */
454
+ customDeliveryRef?: string;
455
+ /** Companion/transposer caveats specific to this delivery. */
456
+ notes?: string[];
457
+ }
458
+
459
+ /**
460
+ * Semantic overlay for the M2M (webhook) notifications fired by a resource
461
+ * operation. Mirrors the email/notification overlay shape so authors get a
462
+ * uniform fan-out vocabulary across all three communications surfaces.
463
+ *
464
+ * The `requiredFeatures` slot is a documentation-oriented feature-gate
465
+ * descriptor — see {@link RequiredFeaturesSpecification}. The runtime checks
466
+ * the M2M dispatch gate at its delivery boundary, so this slot documents the
467
+ * application intent rather than acting as enforcement.
468
+ * The M2M validator opts in to fail-soft cross-registry resolution (see
469
+ * `assertOptionalRequiredFeaturesSpecification` — `crossRegistry:
470
+ * 'fail-soft'`) so application-defined feature refs beyond the engine
471
+ * baseline do not silently re-define the runtime contract.
472
+ */
473
+ export interface ResourceOperationM2MSpecification {
474
+ /** Why this operation fires M2M webhooks (shared intent across deliveries). */
475
+ purpose: string;
476
+ /** Situations where the M2M dispatch must run alongside the operation. */
477
+ useWhen?: string;
478
+ /** Situations where the M2M dispatch should not fire. */
479
+ avoidWhen?: string;
480
+ /** Domain/compliance caveats (rate limits, privacy filters, retry policy …). */
481
+ businessConstraints?: string[];
482
+ /**
483
+ * Explicit fan-out: one entry per runtime `m2mNotifications[]` delivery.
484
+ * At least one entry is required when an `m2m` block is authored.
485
+ */
486
+ deliveries: ResourceOperationM2MDeliverySpecification[];
487
+ /**
488
+ * Documentation-oriented feature-gate descriptor — see
489
+ * {@link RequiredFeaturesSpecification}. Optional. The authoritative
490
+ * runtime gate lives at the M2M dispatcher
491
+ * (`featureResolution.isFeatureEnabled(M2M_WEBHOOK_DELIVERY)`); declaring
492
+ * this slot lets companion prompts surface the same requirement without
493
+ * re-implementing the runtime check. Authors may add additional
494
+ * application-level features here (e.g. `'PARTNER_INTEGRATION'`) when
495
+ * the operation's webhook fan-out is gated beyond the engine baseline.
496
+ */
497
+ requiredFeatures?: RequiredFeaturesSpecification;
498
+ /** Import-oriented coding/transposition metadata. */
499
+ codeHandling?: ResourceOperationM2MSpecificationCodeHandling;
500
+ }
501
+
502
+ /**
503
+ * Outbound communications fired by a resource operation.
504
+ *
505
+ * Each sub-block is optional — an operation may send only an email, only a
506
+ * notification, only an m2m webhook, any combination, or none. The companion
507
+ * will render only the authored sub-blocks. The three sub-blocks mirror the
508
+ * runtime fan-out surfaces:
509
+ * - `email` ↔ `userNotifications[].channel === EMAIL` entries
510
+ * - `notification` ↔ `userNotifications[].channel !== EMAIL` entries
511
+ * - `m2m` ↔ `m2mNotifications[]` entries
512
+ *
513
+ * Variant-level overrides are not modelled at the parent level: deliveries
514
+ * carry their own `variantRef`, so per-variant differences are captured
515
+ * inside the `deliveries` arrays of each sub-block.
516
+ */
517
+ export interface ResourceOperationCommunicationsSpecification {
518
+ /** Email deliveries fired by the operation, when applicable. */
519
+ email?: ResourceOperationEmailSpecification;
520
+ /** In-app notification deliveries fired by the operation, when applicable. */
521
+ notification?: ResourceOperationNotificationSpecification;
522
+ /** M2M (webhook) deliveries fired by the operation, when applicable. */
523
+ m2m?: ResourceOperationM2MSpecification;
524
+ }
525
+
526
+ /**
527
+ * Import-oriented metadata for the scheduled execution of a resource operation.
528
+ *
529
+ * Scheduled work always anchors to `(resourceIdentifier, operationIdentifier)`
530
+ * at runtime — either through a `ResourceOperationVariantType.CRON_JOB`
531
+ * variant of the operation, or through `createCustomBatchExecutionService(...)`
532
+ * whose `batchCronjob_Context` pins the same anchor. Transposer/companion
533
+ * prompts need stable import refs to the input/output schemas and to the
534
+ * batch-ref constant so generated code can reuse the canonical declarations
535
+ * instead of re-typing them.
536
+ */
537
+ export interface ResourceOperationScheduledExecutionCodeHandling {
538
+ /** Public Zod schema symbol describing the scheduled-run input payload. */
539
+ inputSchemaSymbol?: CodeSymbolRef;
540
+ /** Public Zod schema symbol describing the scheduled-run output payload. */
541
+ outputSchemaSymbol?: CodeSymbolRef;
542
+ /** Public TypeScript type symbol when the input type is split from its Zod schema. */
543
+ inputTypeSymbol?: CodeSymbolRef;
544
+ /** Public TypeScript type symbol when the output type is split from its Zod schema. */
545
+ outputTypeSymbol?: CodeSymbolRef;
546
+ /**
547
+ * Public symbol declaring the custom-batch reference constant (for example
548
+ * `FILES_CLEANUP_BATCH_REF`) when the schedule runs through
549
+ * `createCustomBatchExecutionService(...)` rather than a
550
+ * `ResourceOperationVariantType.CRON_JOB` variant.
551
+ */
552
+ customBatchRefSymbol?: CodeSymbolRef;
553
+ /**
554
+ * Public symbol declaring the factory that builds the custom batch service
555
+ * (for example `createFilesCleanupBatch`). Lets generated code import the
556
+ * constructor directly without re-reading the batch file.
557
+ */
558
+ batchFactorySymbol?: CodeSymbolRef;
559
+ /** Extra supporting symbols transposer prompts may need. */
560
+ supportingSymbols?: CodeSymbolRef[];
561
+ /** Companion/transposer caveats that must survive serialization. */
562
+ notes?: string[];
563
+ }
564
+
565
+ /**
566
+ * Discriminant vocabulary for how a scheduled unit of work is anchored to a
567
+ * resource operation at runtime.
568
+ *
569
+ * The spec-layer vocabulary intentionally does NOT reuse
570
+ * `ResourceOperationVariantType` directly. Runtime variants describe how the
571
+ * operation itself is declared on the resource configuration, while custom
572
+ * batches are a separate mechanism registered through
573
+ * `createCustomBatchExecutionService(...)` whose `batchCronjob_Context`
574
+ * happens to anchor to a `(resourceIdentifier, operationIdentifier)` pair.
575
+ * The three spec arms below make the distinction explicit so illegal
576
+ * combinations (a `CRON_JOB` variant with no cron, a `BATCH_JOB` variant
577
+ * with a cron, a custom batch with no `customBatchRef`, …) are
578
+ * unrepresentable at authoring time.
579
+ */
580
+ export enum ResourceOperationScheduledExecutionVariantType {
581
+ /**
582
+ * Operation itself declares a `ResourceOperationVariantType.CRON_JOB`
583
+ * variant whose `cronJobExpression` drives the schedule. The spec echoes
584
+ * the same cron so companion prompts can reason about cadence without
585
+ * reading the runtime configuration.
586
+ */
587
+ NATIVE_CRON_JOB = 'NATIVE_CRON_JOB',
588
+ /**
589
+ * Operation itself declares a `ResourceOperationVariantType.BATCH_JOB`
590
+ * variant. No cron is attached — the batch variant is event-triggered
591
+ * (queue message, deferred work) and runs when upstream work dispatches it.
592
+ */
593
+ NATIVE_BATCH_JOB = 'NATIVE_BATCH_JOB',
594
+ /**
595
+ * Schedule is registered through `createCustomBatchExecutionService(...)`
596
+ * with a `batchCronjob_Context` pinning it to this operation. The batch
597
+ * lives outside the operation's own variants and is addressed by a stable
598
+ * `customBatchRef` that the runtime registry (and the declarative
599
+ * `CustomBatchManifest` aggregator) both consume.
600
+ */
601
+ CUSTOM_BATCH = 'CUSTOM_BATCH',
602
+ }
603
+
604
+ /**
605
+ * Fields shared by every `scheduledExecution` arm. Authoring prose
606
+ * (`purpose` / `outcome`) is not translatable — scheduled runs have no
607
+ * user-facing copy of their own, so we do not carry `textSlots` here.
608
+ */
609
+ interface BaseResourceOperationScheduledExecutionSpecification {
610
+ /** Why this scheduled work runs (business intent, not mechanics). */
611
+ purpose: string;
612
+ /** Observable business result once the scheduled run finishes successfully. */
613
+ outcome: string;
614
+ /** Situations where the scheduled run is the right business path. */
615
+ useWhen?: string;
616
+ /** Situations where the scheduled run should be suppressed (maintenance windows, migrations, …). */
617
+ avoidWhen?: string;
618
+ /** Domain/compliance caveats that matter beyond the operation's own constraints. */
619
+ businessConstraints?: string[];
620
+ /** Import-oriented coding/transposition metadata. */
621
+ codeHandling?: ResourceOperationScheduledExecutionCodeHandling;
622
+ }
623
+
624
+ /**
625
+ * Scheduled-execution overlay for operations whose own variants declare a
626
+ * `ResourceOperationVariantType.CRON_JOB` with an inline cron expression.
627
+ * The spec echoes that cron so companion prompts see the authoritative cadence
628
+ * without re-reading backend code; authors must not invent a cron the runtime
629
+ * variant does not declare.
630
+ */
631
+ export interface NativeCronJobScheduledExecutionSpecification
632
+ extends BaseResourceOperationScheduledExecutionSpecification {
633
+ variantType: ResourceOperationScheduledExecutionVariantType.NATIVE_CRON_JOB;
634
+ /** Echoed cron expression from the operation's `CRON_JOB` variant. */
635
+ cronExpression: string;
636
+ }
637
+
638
+ /**
639
+ * Scheduled-execution overlay for operations whose own variants declare a
640
+ * `ResourceOperationVariantType.BATCH_JOB`. Batch variants run on dispatch
641
+ * rather than a schedule, so no cron is attached and no custom-batch ref is
642
+ * involved.
643
+ */
644
+ export interface NativeBatchJobScheduledExecutionSpecification
645
+ extends BaseResourceOperationScheduledExecutionSpecification {
646
+ variantType: ResourceOperationScheduledExecutionVariantType.NATIVE_BATCH_JOB;
647
+ }
648
+
649
+ /**
650
+ * Scheduled-execution overlay for work registered through
651
+ * `createCustomBatchExecutionService(...)` whose `batchCronjob_Context`
652
+ * anchors to this operation. The stable `customBatchRef` must match the
653
+ * `CustomBatchManifest.batchRef` exported next to the batch factory, which
654
+ * in turn feeds the imperative `customBatches.set(...)` registration in
655
+ * `start-application.backend.service.ts`.
656
+ *
657
+ * `cronExpression` echoes the custom batch's `batchCronjob_Context.cronJobExpression`
658
+ * when one is declared; event-triggered custom batches (for example the
659
+ * email `batch-send` path) omit both the cron and the `cronExpression` field.
660
+ */
661
+ export interface CustomBatchScheduledExecutionSpecification
662
+ extends BaseResourceOperationScheduledExecutionSpecification {
663
+ variantType: ResourceOperationScheduledExecutionVariantType.CUSTOM_BATCH;
664
+ /** Stable ref that resolves to a `CustomBatchManifest` at module load. */
665
+ customBatchRef: string;
666
+ /**
667
+ * Echoed cron expression from the custom batch's `batchCronjob_Context`.
668
+ * Must match the manifest: present when the batch declares a cron, absent
669
+ * when the batch is purely event-triggered.
670
+ */
671
+ cronExpression?: string;
672
+ }
673
+
674
+ /**
675
+ * Discriminated-union semantic overlay for scheduled execution of a resource
676
+ * operation. The discriminant is
677
+ * {@link ResourceOperationScheduledExecutionVariantType} and each arm enforces
678
+ * the fields the runtime anchor actually requires, so illegal combinations
679
+ * (cron without variant, batch-job with cron, custom batch without ref, …)
680
+ * are rejected at authoring time.
681
+ *
682
+ * Attaching the slot at the operation level mirrors the runtime invariant
683
+ * that every scheduled unit of work anchors to a resource operation
684
+ * (`ResourceOperationVariantType.CRON_JOB` / `BATCH_JOB` or a custom batch
685
+ * whose `batchCronjob_Context` binds it to `(resourceIdentifier,
686
+ * operationIdentifier)`). There is no operation-less scheduled path.
687
+ *
688
+ * Cross-registry verification of `customBatchRef` runs at module load by
689
+ * consulting the declarative `CustomBatchManifest` registry — see
690
+ * {@link registerCustomBatchManifests} and the engine's
691
+ * `ENGINE_CUSTOM_BATCH_MANIFESTS` export in `@wildo-ai/saas-backend-lib`.
692
+ */
693
+ export type ResourceOperationScheduledExecutionSpecification =
694
+ | NativeCronJobScheduledExecutionSpecification
695
+ | NativeBatchJobScheduledExecutionSpecification
696
+ | CustomBatchScheduledExecutionSpecification;
697
+
698
+ // ── Operation HTTP-documentation overlay (Tier 3 — OpenAPI semantics) ───────
699
+
700
+ /**
701
+ * Fixed vocabulary of HTTP response status codes an operation may document.
702
+ * An enum (not a literal union) per the framework rule — a single source of
703
+ * truth for the renderer and the OpenAPI generator. The string VALUE is the
704
+ * OpenAPI `responses` key (`'200'`, `'404'`, …) so it splices in verbatim.
705
+ */
706
+ export enum HttpResponseStatusCode {
707
+ OK_200 = '200',
708
+ CREATED_201 = '201',
709
+ ACCEPTED_202 = '202',
710
+ NO_CONTENT_204 = '204',
711
+ BAD_REQUEST_400 = '400',
712
+ UNAUTHORIZED_401 = '401',
713
+ FORBIDDEN_403 = '403',
714
+ NOT_FOUND_404 = '404',
715
+ CONFLICT_409 = '409',
716
+ UNPROCESSABLE_ENTITY_422 = '422',
717
+ TOO_MANY_REQUESTS_429 = '429',
718
+ INTERNAL_SERVER_ERROR_500 = '500',
719
+ }
720
+
721
+ /**
722
+ * One documented response status for an operation. Becomes an OpenAPI
723
+ * `responses.<code>` entry whose `description` is the authored `meaning`.
724
+ */
725
+ export interface ResourceOperationResponseStatusSpecification {
726
+ /** HTTP status code this operation returns on this outcome. */
727
+ code: HttpResponseStatusCode;
728
+ /** What this status means for THIS operation, in business terms. */
729
+ meaning: string;
730
+ }
731
+
732
+ /**
733
+ * One documented failure mode beyond the happy path. Becomes an OpenAPI error
734
+ * `responses.<code>` entry; `when` explains the trigger and `errorCode` (if
735
+ * set) is the machine-stable identifier the API returns in the error body.
736
+ */
737
+ export interface ResourceOperationErrorScenarioSpecification {
738
+ /** HTTP status code returned in this failure mode. */
739
+ code: HttpResponseStatusCode;
740
+ /** Trigger condition — when/why this error occurs. */
741
+ when: string;
742
+ /** Optional machine-stable error identifier emitted in the error body. */
743
+ errorCode?: string;
744
+ }
745
+
746
+ /**
747
+ * A request/response payload example for docs + client codegen. Becomes an
748
+ * OpenAPI example on the request body and/or the `forStatus` response.
749
+ */
750
+ export interface ResourceOperationExampleSpecification {
751
+ /** Short human label, e.g. "Create with assignee". */
752
+ title: string;
753
+ /** Optional example request body (JSON-serialisable). */
754
+ request?: unknown;
755
+ /** Optional example response body (JSON-serialisable). */
756
+ response?: unknown;
757
+ /** Which response status this example illustrates (links to `responseStatuses`). */
758
+ forStatus?: HttpResponseStatusCode;
759
+ }
760
+
761
+ /**
762
+ * Semantic explanation for one logical resource operation.
763
+ *
764
+ * The operation-level fields capture the invariant business meaning of the
765
+ * action, while `variants` captures frontend/runtime-specific differences when
766
+ * multiple operation variants exist.
767
+ */
768
+ export interface ResourceOperationSpecification {
769
+ /** Stable operation identifier as declared by the resource configuration. */
770
+ operationId?: string;
771
+ /** Shared business intent across all variants of the operation. */
772
+ purpose?: string;
773
+ /** Shared observable business result once the operation succeeds. */
774
+ outcome?: string;
775
+ /** Guidance about when this operation is the right choice. */
776
+ whenToUse?: string;
777
+ /** Relative weight of this operation in the resource understanding. */
778
+ importance?: FieldSemanticImportance;
779
+ /**
780
+ * Outbound communications (emails, notifications) fired as a side-effect of
781
+ * running the operation. Because `ResourceFrontendViewSpecification`
782
+ * structurally extends this interface, communications authored at the base
783
+ * level are automatically visible through `frontend.views` as well.
784
+ */
785
+ communications?: ResourceOperationCommunicationsSpecification;
786
+ /**
787
+ * Scheduled-execution overlay for cron/batch operations. Applies when the
788
+ * operation has a `CRON_JOB` / `BATCH_JOB` variant or is implemented by a
789
+ * custom batch whose `batchCronjob_Context` anchors to this operation.
790
+ * Attached at the base level so it also surfaces through
791
+ * `frontend.views` via structural inheritance — scheduled work is a
792
+ * backend-initiated side effect, not a UI seam.
793
+ */
794
+ scheduledExecution?: ResourceOperationScheduledExecutionSpecification;
795
+ /** Variant-specific semantics layered under the same logical operation id. */
796
+ variants?: ResourceOperationSpecificationVariants;
797
+ /**
798
+ * Authored HTTP response statuses for this operation. Feeds the OpenAPI
799
+ * `responses` object, replacing the generator's default single `200`/`204`.
800
+ * Per-operation — variants share the same HTTP contract (a per-variant
801
+ * response set would multiply identical contracts with no semantic gain).
802
+ */
803
+ responseStatuses?: ResourceOperationResponseStatusSpecification[];
804
+ /**
805
+ * Failure modes a client should handle beyond the happy path. Each becomes
806
+ * an OpenAPI error `responses` entry (400/403/404/409/…) carrying its `when`
807
+ * prose. Per-operation.
808
+ */
809
+ errorScenarios?: ResourceOperationErrorScenarioSpecification[];
810
+ /**
811
+ * Whether repeating the request with the same input is side-effect-free.
812
+ * Surfaces as an OpenAPI `x-idempotent` extension plus a description note.
813
+ */
814
+ idempotent?: boolean;
815
+ /** Optional human note on the operation's rate-limiting posture (free prose). */
816
+ rateLimitNote?: string;
817
+ /**
818
+ * Request/response payload examples for docs + client codegen. Base examples
819
+ * apply to every variant unless `variants.<key>.examples` provides a complete
820
+ * replacement for a divergent variant response schema.
821
+ */
822
+ examples?: ResourceOperationExampleSpecification[];
823
+ }
824
+
825
+ /**
826
+ * Validation entry point used by the resource specification factory to assert
827
+ * that an authored `communications` block is internally consistent. Factories
828
+ * call this from the same place they already assert frontend-operation
829
+ * completeness, so misconfigurations fail at module load rather than leaking
830
+ * into companion renderers as half-formed prose.
831
+ *
832
+ * @param ownerLabel Stable identifier of the owning operation (used in error
833
+ * messages so authors can locate the broken spec immediately).
834
+ * @param communications The authored communications block, or undefined when
835
+ * the operation does not declare one.
836
+ * @param resourcePrimaryScope The owning resource's `resourcePrimaryScope`.
837
+ * This is the specification author's explicitly declared scope (the fourth
838
+ * `options` argument to {@link resourceSpecification}), threaded through
839
+ * every re-validation path (including
840
+ * {@link resourceSpecificationFromFrontendConfiguration}'s
841
+ * `base.operations` / `base.frontend.views` / `frontend.views`
842
+ * re-validation passes). It MAY still be `undefined` only on hand-built
843
+ * spec configs that bypass both factories — those paths intentionally
844
+ * soft-skip the cross-check because they have no contract with the spec
845
+ * author for declaring scope. The primary entry point hard-fails on
846
+ * missing scope (TypeScript-enforced), so production specs always
847
+ * exercise the cross-check.
848
+ */
849
+ export function validateResourceOperationCommunicationsSpecification(
850
+ ownerLabel: string,
851
+ communications: ResourceOperationCommunicationsSpecification | undefined,
852
+ resourcePrimaryScope?: ResourcePrimaryScope,
853
+ ): void {
854
+ if (!communications) {
855
+ return;
856
+ }
857
+ if (communications.email) {
858
+ assertNonEmptyProseSlot(
859
+ ownerLabel,
860
+ 'communications.email.purpose',
861
+ communications.email.purpose,
862
+ );
863
+ assertNonEmptyProseSlot(ownerLabel, 'communications.email.tone', communications.email.tone);
864
+ assertOptionalNonEmptyProseSlot(
865
+ ownerLabel,
866
+ 'communications.email.useWhen',
867
+ communications.email.useWhen,
868
+ );
869
+ assertOptionalNonEmptyProseSlot(
870
+ ownerLabel,
871
+ 'communications.email.avoidWhen',
872
+ communications.email.avoidWhen,
873
+ );
874
+ assertEveryAuthoredTextSlot(
875
+ ownerLabel,
876
+ 'email',
877
+ ['subject'],
878
+ communications.email.textSlots,
879
+ );
880
+ assertOptionalEventDataSlot(ownerLabel, 'email', communications.email.eventData);
881
+ assertOptionalNonEmptyStringList(
882
+ ownerLabel,
883
+ 'communications.email.businessConstraints',
884
+ communications.email.businessConstraints,
885
+ );
886
+ assertOptionalNonEmptyStringList(
887
+ ownerLabel,
888
+ 'communications.email.codeHandling.notes',
889
+ communications.email.codeHandling?.notes,
890
+ );
891
+ assertEmailDeliveries(ownerLabel, communications.email.deliveries);
892
+ }
893
+ if (communications.notification) {
894
+ assertNonEmptyProseSlot(
895
+ ownerLabel,
896
+ 'communications.notification.purpose',
897
+ communications.notification.purpose,
898
+ );
899
+ assertNonEmptyProseSlot(
900
+ ownerLabel,
901
+ 'communications.notification.tone',
902
+ communications.notification.tone,
903
+ );
904
+ assertOptionalNonEmptyProseSlot(
905
+ ownerLabel,
906
+ 'communications.notification.useWhen',
907
+ communications.notification.useWhen,
908
+ );
909
+ assertOptionalNonEmptyProseSlot(
910
+ ownerLabel,
911
+ 'communications.notification.avoidWhen',
912
+ communications.notification.avoidWhen,
913
+ );
914
+ assertEveryAuthoredTextSlot(
915
+ ownerLabel,
916
+ 'notification',
917
+ ['title'],
918
+ communications.notification.textSlots,
919
+ );
920
+ assertOptionalEventDataSlot(
921
+ ownerLabel,
922
+ 'notification',
923
+ communications.notification.eventData,
924
+ );
925
+ assertOptionalNonEmptyStringList(
926
+ ownerLabel,
927
+ 'communications.notification.businessConstraints',
928
+ communications.notification.businessConstraints,
929
+ );
930
+ assertOptionalNonEmptyStringList(
931
+ ownerLabel,
932
+ 'communications.notification.codeHandling.notes',
933
+ communications.notification.codeHandling?.notes,
934
+ );
935
+ assertNotificationDeliveries(ownerLabel, communications.notification.deliveries);
936
+ }
937
+ if (communications.m2m) {
938
+ assertNonEmptyProseSlot(ownerLabel, 'communications.m2m.purpose', communications.m2m.purpose);
939
+ assertOptionalNonEmptyProseSlot(
940
+ ownerLabel,
941
+ 'communications.m2m.useWhen',
942
+ communications.m2m.useWhen,
943
+ );
944
+ assertOptionalNonEmptyProseSlot(
945
+ ownerLabel,
946
+ 'communications.m2m.avoidWhen',
947
+ communications.m2m.avoidWhen,
948
+ );
949
+ assertOptionalNonEmptyStringList(
950
+ ownerLabel,
951
+ 'communications.m2m.businessConstraints',
952
+ communications.m2m.businessConstraints,
953
+ );
954
+ assertOptionalNonEmptyStringList(
955
+ ownerLabel,
956
+ 'communications.m2m.codeHandling.notes',
957
+ communications.m2m.codeHandling?.notes,
958
+ );
959
+ assertOptionalRequiredFeaturesSpecification(
960
+ `Resource operation "${ownerLabel}" communications.m2m.requiredFeatures`,
961
+ communications.m2m.requiredFeatures,
962
+ { crossRegistry: 'fail-soft' },
963
+ );
964
+ assertM2MDeliveries(ownerLabel, communications.m2m.deliveries, resourcePrimaryScope);
965
+ }
966
+ }
967
+
968
+ /**
969
+ * Assert that a REQUIRED prose slot (`purpose`, `tone`, `audience`, …) is
970
+ * non-empty trimmed. `slotLabel` is the full owner-relative path included
971
+ * verbatim in the error (e.g. `communications.email.purpose`,
972
+ * `communications.email.deliveries[0].audience`) so callers can locate the
973
+ * broken authoring site immediately, regardless of whether the slot lives
974
+ * directly under `communications.*` or further nested under a `deliveries[i]`.
975
+ */
976
+ function assertNonEmptyProseSlot(
977
+ ownerLabel: string,
978
+ slotLabel: string,
979
+ value: string | undefined,
980
+ ): void {
981
+ if (!value || !value.trim()) {
982
+ throw new Error(
983
+ `Resource operation "${ownerLabel}" ${slotLabel} must be a non-empty prose slot.`,
984
+ );
985
+ }
986
+ }
987
+
988
+ /**
989
+ * Best-effort resource-type hint derivation from the `_factory` argument
990
+ * passed to `resourceSpecification(...)`.
991
+ *
992
+ * Used exclusively to enrich the `validateFieldShapes(...)` error prefix so
993
+ * authors see `resourceSpecification(TODOS): ...` instead of a
994
+ * bare `resourceSpecification(): ...` when multiple resources fail
995
+ * validation in the same bundle. Returns an empty string when the hint
996
+ * cannot be derived — callers must treat that case as "use the bare
997
+ * prefix" rather than throwing.
998
+ *
999
+ * Handles both factory forms:
1000
+ * - Function form (`ResourceConfiguration_InitializationFactory`): reads
1001
+ * the function `name` and strips the standard
1002
+ * `_ResourceConfiguration_InitializationFactory` suffix. This matches the
1003
+ * application factory naming convention.
1004
+ * - Object form (`ResourceConfiguration`): reads the
1005
+ * `resourceType?.memberName` when present. Older static object-form
1006
+ * factories do not always set this; the empty-string fallback keeps
1007
+ * them working.
1008
+ */
1009
+ function extractResourceTypeHintFromFactory(factory: unknown): string {
1010
+ if (typeof factory === 'function') {
1011
+ const name = typeof factory.name === 'string' ? factory.name : '';
1012
+ const stripped = name.replace(/_ResourceConfiguration_InitializationFactory$/, '');
1013
+ return stripped.trim();
1014
+ }
1015
+ if (factory && typeof factory === 'object') {
1016
+ const maybeRef = (factory as { resourceType?: { memberName?: unknown } }).resourceType;
1017
+ if (maybeRef && typeof maybeRef.memberName === 'string') {
1018
+ return maybeRef.memberName;
1019
+ }
1020
+ }
1021
+ return '';
1022
+ }
1023
+
1024
+ /**
1025
+ * Assert that an OPTIONAL prose slot (`useWhen`, `avoidWhen`, `purposeOverride`,
1026
+ * …) is non-empty trimmed when authored. Absent slots are a no-op.
1027
+ *
1028
+ * Mirrors the per-bullet contract on `assertOptionalNonEmptyStringList`: every
1029
+ * surface the renderer prints — even optional ones — must fail closed on
1030
+ * blanks because a blank `useWhen` line silently appears as `Use when .` in
1031
+ * companion prompts and undermines translator/transposer grounding.
1032
+ *
1033
+ * `slotLabel` is the full owner-relative path included verbatim in the error
1034
+ * (e.g. `email.useWhen`, `scheduledExecution.avoidWhen`,
1035
+ * `communications.email.deliveries[0].purposeOverride`) so callers can locate
1036
+ * the broken authoring site immediately.
1037
+ */
1038
+ function assertOptionalNonEmptyProseSlot(
1039
+ ownerLabel: string,
1040
+ slotLabel: string,
1041
+ value: string | undefined,
1042
+ ): void {
1043
+ if (value === undefined) {
1044
+ return;
1045
+ }
1046
+ if (typeof value !== 'string' || !value.trim()) {
1047
+ throw new Error(
1048
+ `Resource operation "${ownerLabel}" ${slotLabel} must be a non-empty trimmed prose slot when authored (omit the field entirely instead of declaring an empty value).`,
1049
+ );
1050
+ }
1051
+ }
1052
+
1053
+ /**
1054
+ * Validate the `deliveries` array on a `ResourceOperationEmailSpecification`.
1055
+ *
1056
+ * Engine-parity contract: every entry must mirror one runtime
1057
+ * `userNotifications[]` email delivery, so the spec is never silent about a
1058
+ * real runtime template path. The validator enforces:
1059
+ * - at least one delivery (the array is required when an `email` block is
1060
+ * authored — single-delivery emails still need one explicit entry),
1061
+ * - non-empty `audience` and `targetRef` on every delivery,
1062
+ * - non-empty trimmed `variantRef` / `customDeliveryRef` when authored,
1063
+ * - non-empty trimmed `purposeOverride` when authored,
1064
+ * - per-delivery `systemEmailTemplateRef` (when authored) is a member of
1065
+ * `SystemEmailTemplateRegistry` — the cross-link lives per-delivery
1066
+ * because the runtime template-ref path is per-delivery,
1067
+ * - per-delivery `textSlotsOverrides` slots carry a non-empty `purpose`,
1068
+ * - per-delivery `additionalBusinessConstraints` and `notes` follow the
1069
+ * per-bullet non-empty contract,
1070
+ * - uniqueness on `(variantRef ?? '__default__', targetRef, customDeliveryRef ?? '__none__')`
1071
+ * so two deliveries cannot collide on the runtime template-ref path.
1072
+ */
1073
+ function assertEmailDeliveries(
1074
+ ownerLabel: string,
1075
+ deliveries: ResourceOperationEmailDeliverySpecification[] | undefined,
1076
+ ): void {
1077
+ if (!deliveries || deliveries.length === 0) {
1078
+ throw new Error(
1079
+ `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.`,
1080
+ );
1081
+ }
1082
+ const seenKeys = new Set<string>();
1083
+ for (const [index, delivery] of deliveries.entries()) {
1084
+ const path = `communications.email.deliveries[${index}]`;
1085
+ assertNonEmptyProseSlot(ownerLabel, `${path}.audience`, delivery.audience);
1086
+ if (typeof delivery.targetRef !== 'string' || !delivery.targetRef.trim()) {
1087
+ throw new Error(
1088
+ `Resource operation "${ownerLabel}" ${path}.targetRef must be a non-empty trimmed string (use a CoreUserNotificationTarget member or a custom target ref).`,
1089
+ );
1090
+ }
1091
+ assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.variantRef`, delivery.variantRef);
1092
+ assertOptionalNonEmptyProseSlot(
1093
+ ownerLabel,
1094
+ `${path}.customDeliveryRef`,
1095
+ delivery.customDeliveryRef,
1096
+ );
1097
+ assertSystemEmailTemplateCrossLink(
1098
+ ownerLabel,
1099
+ `${path}.systemEmailTemplateRef`,
1100
+ delivery.systemEmailTemplateRef,
1101
+ );
1102
+ assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.purposeOverride`, delivery.purposeOverride);
1103
+ assertTextSlotsOverrides(
1104
+ ownerLabel,
1105
+ `${path}.textSlotsOverrides`,
1106
+ delivery.textSlotsOverrides,
1107
+ );
1108
+ assertOptionalNonEmptyStringList(
1109
+ ownerLabel,
1110
+ `${path}.additionalBusinessConstraints`,
1111
+ delivery.additionalBusinessConstraints,
1112
+ );
1113
+ assertOptionalNonEmptyStringList(ownerLabel, `${path}.notes`, delivery.notes);
1114
+
1115
+ const key = `${delivery.variantRef ?? '__default__'}::${delivery.targetRef}::${delivery.customDeliveryRef ?? '__none__'}`;
1116
+ if (seenKeys.has(key)) {
1117
+ throw new Error(
1118
+ `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.`,
1119
+ );
1120
+ }
1121
+ seenKeys.add(key);
1122
+ }
1123
+ }
1124
+
1125
+ /**
1126
+ * Validate the `deliveries` array on a `ResourceOperationNotificationSpecification`.
1127
+ * Same engine-parity contract as {@link assertEmailDeliveries}, with `channelRef`
1128
+ * added to the uniqueness key (notifications fan out per (target, channel) pair).
1129
+ */
1130
+ function assertNotificationDeliveries(
1131
+ ownerLabel: string,
1132
+ deliveries: ResourceOperationNotificationDeliverySpecification[] | undefined,
1133
+ ): void {
1134
+ if (!deliveries || deliveries.length === 0) {
1135
+ throw new Error(
1136
+ `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.`,
1137
+ );
1138
+ }
1139
+ const seenKeys = new Set<string>();
1140
+ for (const [index, delivery] of deliveries.entries()) {
1141
+ const path = `communications.notification.deliveries[${index}]`;
1142
+ assertNonEmptyProseSlot(ownerLabel, `${path}.audience`, delivery.audience);
1143
+ if (typeof delivery.channelRef !== 'string' || !delivery.channelRef.trim()) {
1144
+ throw new Error(
1145
+ `Resource operation "${ownerLabel}" ${path}.channelRef must be a non-empty trimmed string (use a CoreUserNotificationChannel member or a custom channel ref).`,
1146
+ );
1147
+ }
1148
+ if (typeof delivery.targetRef !== 'string' || !delivery.targetRef.trim()) {
1149
+ throw new Error(
1150
+ `Resource operation "${ownerLabel}" ${path}.targetRef must be a non-empty trimmed string (use a CoreUserNotificationTarget member or a custom target ref).`,
1151
+ );
1152
+ }
1153
+ assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.variantRef`, delivery.variantRef);
1154
+ assertOptionalNonEmptyProseSlot(
1155
+ ownerLabel,
1156
+ `${path}.customDeliveryRef`,
1157
+ delivery.customDeliveryRef,
1158
+ );
1159
+ assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.purposeOverride`, delivery.purposeOverride);
1160
+ assertTextSlotsOverrides(
1161
+ ownerLabel,
1162
+ `${path}.textSlotsOverrides`,
1163
+ delivery.textSlotsOverrides,
1164
+ );
1165
+ assertOptionalNonEmptyStringList(
1166
+ ownerLabel,
1167
+ `${path}.additionalBusinessConstraints`,
1168
+ delivery.additionalBusinessConstraints,
1169
+ );
1170
+ assertOptionalNonEmptyStringList(ownerLabel, `${path}.notes`, delivery.notes);
1171
+
1172
+ const key = `${delivery.variantRef ?? '__default__'}::${delivery.targetRef}::${delivery.channelRef}::${delivery.customDeliveryRef ?? '__none__'}`;
1173
+ if (seenKeys.has(key)) {
1174
+ throw new Error(
1175
+ `Resource operation "${ownerLabel}" ${path} duplicates the (variantRef, targetRef, channelRef, customDeliveryRef) quadruple of an earlier delivery; add a distinguishing customDeliveryRef or merge the entries.`,
1176
+ );
1177
+ }
1178
+ seenKeys.add(key);
1179
+ }
1180
+ }
1181
+
1182
+ /**
1183
+ * Validate the `deliveries` array on a `ResourceOperationM2MSpecification`.
1184
+ *
1185
+ * Webhook-style M2M deliveries fan out per
1186
+ * `(variantRef, channelRef, level, customDeliveryRef)` — the validator
1187
+ * enforces uniqueness on that quadruple so two deliveries that genuinely
1188
+ * differ on those axes can coexist. `variantRef` is the first segment of
1189
+ * the key (defaulting to `__default__` when omitted), so two deliveries
1190
+ * that differ only by their owning variant remain distinct.
1191
+ *
1192
+ * Each authored `level` (when present) is also enum-membership-checked
1193
+ * against `M2MNotificationLevel` so a typo (`'inf0'`, `'WARN'`,
1194
+ * …) fails at module load — the runtime schema is strict-enum even
1195
+ * though the TypeScript declaration is widened with `(string & {})` for
1196
+ * IDE autocomplete.
1197
+ *
1198
+ * **Runtime-identity cross-check.** The runtime
1199
+ * `M2MNotificationDefinitionSchema` carries no `customNotificationRef`
1200
+ * field; the dispatcher constructs the fan-out identifier as
1201
+ * `${resourceIdentifier}_${operationIdentifier}_${channel}` only — no
1202
+ * variant, no level and no custom-reference segment.
1203
+ * The spec layer is therefore free to author multiple deliveries on the
1204
+ * same `channelRef` (disambiguated by `level` / `customDeliveryRef`), but
1205
+ * at runtime they would collapse to a single identifier and one of the
1206
+ * deliveries would silently shadow the other. The validator fail-closes
1207
+ * on this collision: every authored delivery must project to a unique
1208
+ * `channelRef` within its operation. Authors who genuinely need multiple
1209
+ * fan-outs on the same channel must wait until the runtime carries a
1210
+ * `customNotificationRef` axis (engineering scope, separate workstream).
1211
+ */
1212
+ function assertM2MDeliveries(
1213
+ ownerLabel: string,
1214
+ deliveries: ResourceOperationM2MDeliverySpecification[] | undefined,
1215
+ resourcePrimaryScope?: ResourcePrimaryScope,
1216
+ ): void {
1217
+ if (!deliveries || deliveries.length === 0) {
1218
+ throw new Error(
1219
+ `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.`,
1220
+ );
1221
+ }
1222
+ const seenKeys = new Set<string>();
1223
+ const seenRuntimeIdentities = new Map<string, number>();
1224
+ for (const [index, delivery] of deliveries.entries()) {
1225
+ const path = `communications.m2m.deliveries[${index}]`;
1226
+ assertNonEmptyProseSlot(ownerLabel, `${path}.audience`, delivery.audience);
1227
+ if (typeof delivery.channelRef !== 'string' || !delivery.channelRef.trim()) {
1228
+ throw new Error(
1229
+ `Resource operation "${ownerLabel}" ${path}.channelRef must be a non-empty trimmed string (use a CoreM2MNotificationChannel member or a custom channel ref).`,
1230
+ );
1231
+ }
1232
+ assertM2MChannelMatchesPrimaryScope(
1233
+ ownerLabel,
1234
+ `${path}.channelRef`,
1235
+ delivery.channelRef,
1236
+ resourcePrimaryScope,
1237
+ );
1238
+ assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.level`, delivery.level);
1239
+ assertOptionalM2MNotificationLevelMembership(
1240
+ ownerLabel,
1241
+ `${path}.level`,
1242
+ delivery.level,
1243
+ );
1244
+ assertOptionalNonEmptyProseSlot(ownerLabel, `${path}.variantRef`, delivery.variantRef);
1245
+ assertOptionalNonEmptyProseSlot(
1246
+ ownerLabel,
1247
+ `${path}.customDeliveryRef`,
1248
+ delivery.customDeliveryRef,
1249
+ );
1250
+ assertOptionalNonEmptyStringList(ownerLabel, `${path}.notes`, delivery.notes);
1251
+
1252
+ const key = `${delivery.variantRef ?? '__default__'}::${delivery.channelRef}::${delivery.level ?? '__none__'}::${delivery.customDeliveryRef ?? '__none__'}`;
1253
+ if (seenKeys.has(key)) {
1254
+ throw new Error(
1255
+ `Resource operation "${ownerLabel}" ${path} duplicates the (variantRef, channelRef, level, customDeliveryRef) quadruple of an earlier delivery; add a distinguishing customDeliveryRef or merge the entries.`,
1256
+ );
1257
+ }
1258
+ seenKeys.add(key);
1259
+
1260
+ const runtimeIdentityKey = delivery.channelRef;
1261
+ const previousIndex = seenRuntimeIdentities.get(runtimeIdentityKey);
1262
+ if (previousIndex !== undefined) {
1263
+ throw new Error(
1264
+ `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.`,
1265
+ );
1266
+ }
1267
+ seenRuntimeIdentities.set(runtimeIdentityKey, index);
1268
+ }
1269
+ }
1270
+
1271
+ /**
1272
+ * Iterate every authored text slot and assert it has a non-empty trimmed
1273
+ * `purpose`, then assert the required slot keys (`subject` for email, `title`
1274
+ * for notification) are also present. This protects optional translatable
1275
+ * fragments (`previewText`, `ctaLabel`, `body`, `actionLabel`, …) from being
1276
+ * authored as placeholders that the translator cannot ground in author intent.
1277
+ */
1278
+ function assertEveryAuthoredTextSlot(
1279
+ ownerLabel: string,
1280
+ blockLabel: 'email' | 'notification',
1281
+ requiredSlotKeys: readonly string[],
1282
+ textSlots: TranslationSlotSpecificationMap | undefined,
1283
+ ): void {
1284
+ for (const requiredKey of requiredSlotKeys) {
1285
+ const slot = textSlots?.[requiredKey];
1286
+ if (!slot || !slot.purpose || !slot.purpose.trim()) {
1287
+ throw new Error(
1288
+ `Resource operation "${ownerLabel}" communications.${blockLabel} must document text slot "${requiredKey}" with a non-empty purpose so translators have a grounded target.`,
1289
+ );
1290
+ }
1291
+ }
1292
+ if (!textSlots) {
1293
+ return;
1294
+ }
1295
+ for (const [slotKey, slot] of Object.entries(textSlots)) {
1296
+ if (!slot || !slot.purpose || !slot.purpose.trim()) {
1297
+ throw new Error(
1298
+ `Resource operation "${ownerLabel}" communications.${blockLabel}.textSlots["${slotKey}"] must carry a non-empty purpose so translators have a grounded target for every authored slot.`,
1299
+ );
1300
+ }
1301
+ assertOptionalNonEmptyProseSlot(
1302
+ ownerLabel,
1303
+ `communications.${blockLabel}.textSlots["${slotKey}"].whenToUse`,
1304
+ slot.whenToUse,
1305
+ );
1306
+ assertOptionalNonEmptyStringList(
1307
+ ownerLabel,
1308
+ `communications.${blockLabel}.textSlots["${slotKey}"].notes`,
1309
+ slot.notes,
1310
+ );
1311
+ }
1312
+ }
1313
+
1314
+ /**
1315
+ * When `eventData` is authored on either communications sub-block, assert its
1316
+ * `purpose` is a non-empty trimmed string. Companion prompts use this slot to
1317
+ * narrate which runtime values land in each translatable text slot, so a blank
1318
+ * `purpose` would produce a labelled but undocumented payload reference.
1319
+ */
1320
+ function assertOptionalEventDataSlot(
1321
+ ownerLabel: string,
1322
+ blockLabel: 'email' | 'notification',
1323
+ eventData: TranslationSlotSpecification | undefined,
1324
+ ): void {
1325
+ if (!eventData) {
1326
+ return;
1327
+ }
1328
+ if (!eventData.purpose || !eventData.purpose.trim()) {
1329
+ throw new Error(
1330
+ `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.`,
1331
+ );
1332
+ }
1333
+ assertOptionalNonEmptyProseSlot(
1334
+ ownerLabel,
1335
+ `communications.${blockLabel}.eventData.whenToUse`,
1336
+ eventData.whenToUse,
1337
+ );
1338
+ assertOptionalNonEmptyStringList(
1339
+ ownerLabel,
1340
+ `communications.${blockLabel}.eventData.notes`,
1341
+ eventData.notes,
1342
+ );
1343
+ }
1344
+
1345
+ /**
1346
+ * Validate a per-delivery `textSlotsOverrides` map (or any structurally
1347
+ * compatible `TranslationSlotSpecificationMap`):
1348
+ *
1349
+ * - absent map → no-op,
1350
+ * - every authored slot must carry a non-empty trimmed `purpose`,
1351
+ * - every authored optional `whenToUse` (if present) must be non-empty
1352
+ * trimmed prose so the renderer never prints `When to use .`,
1353
+ * - every authored `notes` array must follow the per-bullet contract.
1354
+ *
1355
+ * Path-agnostic: callers pass the full owner-relative path prefix (for
1356
+ * example `communications.email.deliveries[0].textSlotsOverrides`) so this
1357
+ * primitive serves every overlay surface without baking a sub-tree prefix
1358
+ * into the helper.
1359
+ */
1360
+ function assertTextSlotsOverrides(
1361
+ ownerLabel: string,
1362
+ pathPrefix: string,
1363
+ slots: TranslationSlotSpecificationMap | undefined,
1364
+ ): void {
1365
+ if (!slots) {
1366
+ return;
1367
+ }
1368
+ for (const [slotKey, slot] of Object.entries(slots)) {
1369
+ if (!slot || !slot.purpose || !slot.purpose.trim()) {
1370
+ throw new Error(
1371
+ `Resource operation "${ownerLabel}" ${pathPrefix}["${slotKey}"] must carry a non-empty purpose so translators have a grounded target for every authored override.`,
1372
+ );
1373
+ }
1374
+ assertOptionalNonEmptyProseSlot(
1375
+ ownerLabel,
1376
+ `${pathPrefix}["${slotKey}"].whenToUse`,
1377
+ slot.whenToUse,
1378
+ );
1379
+ assertOptionalNonEmptyStringList(
1380
+ ownerLabel,
1381
+ `${pathPrefix}["${slotKey}"].notes`,
1382
+ slot.notes,
1383
+ );
1384
+ }
1385
+ }
1386
+
1387
+ /**
1388
+ * Defensive guard for any optional `string[]` companion-bullet surface
1389
+ * (notes arrays, businessConstraints arrays, …). When the array is absent
1390
+ * the check is a no-op; when present, every entry must be a non-empty
1391
+ * trimmed string because the renderer emits each entry as a bullet — empty
1392
+ * entries leak blank lines into companion prompts and break the fail-closed
1393
+ * contract the surrounding validators promise.
1394
+ *
1395
+ * The helper is path-agnostic: callers pass the full owner-relative path
1396
+ * (for example `communications.email.codeHandling.notes` or
1397
+ * `scheduledExecution.codeHandling.notes`) so the same primitive serves
1398
+ * every overlay surface without baking a sub-tree prefix into the helper.
1399
+ *
1400
+ * @param ownerLabel Stable identifier of the owning operation (used in error
1401
+ * messages so authors can locate the broken spec immediately).
1402
+ * @param fullPath Dotted owner-relative authoring path; included verbatim in
1403
+ * the error message.
1404
+ */
1405
+ function assertOptionalNonEmptyStringList(
1406
+ ownerLabel: string,
1407
+ fullPath: string,
1408
+ values: string[] | undefined,
1409
+ ): void {
1410
+ if (!values) {
1411
+ return;
1412
+ }
1413
+ for (const [index, value] of values.entries()) {
1414
+ if (typeof value !== 'string' || !value.trim()) {
1415
+ throw new Error(
1416
+ `Resource operation "${ownerLabel}" ${fullPath}[${index}] must be a non-empty trimmed string.`,
1417
+ );
1418
+ }
1419
+ }
1420
+ }
1421
+
1422
+ /**
1423
+ * Cross-validate the optional m2m delivery `level` against the runtime
1424
+ * `M2MNotificationLevel` enum so a typo (`'inf0'`, `'WARN'`, `'crit'`, …)
1425
+ * fails at module load instead of leaking through the spec validator and
1426
+ * surfacing later as a runtime Zod parse error (or, worse, leaking into
1427
+ * companion prompts unchanged).
1428
+ *
1429
+ * The TypeScript declaration `M2MNotificationLevel | (string & {})` exists
1430
+ * to give autocomplete on enum members in IDEs, but the runtime
1431
+ * `M2MNotificationDefinitionSchema` declares `level` as
1432
+ * `z.enum(M2MNotificationLevel).optional()` — strict enum-only. The spec
1433
+ * layer mirrors that runtime contract here so spec → runtime parity is
1434
+ * fail-closed at module load.
1435
+ *
1436
+ * Mirrors `assertSystemEmailTemplateCrossLink` in error-message structure:
1437
+ * `slotPath` is the full owner-relative path included verbatim so authors
1438
+ * can locate the broken delivery directly.
1439
+ */
1440
+ function assertOptionalM2MNotificationLevelMembership(
1441
+ ownerLabel: string,
1442
+ slotPath: string,
1443
+ level: M2MNotificationLevel | (string & {}) | undefined,
1444
+ ): void {
1445
+ if (level === undefined) {
1446
+ return;
1447
+ }
1448
+ const allowedValues = Object.values(M2MNotificationLevel) as string[];
1449
+ if (!allowedValues.includes(level)) {
1450
+ throw new Error(
1451
+ `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.`,
1452
+ );
1453
+ }
1454
+ }
1455
+
1456
+ /**
1457
+ * Cross-validate one M2M delivery `channelRef` against the owning resource's
1458
+ * `resourcePrimaryScope`.
1459
+ *
1460
+ * The runtime `WEBHOOK_ORGANIZATION` channel only fires when the operation's
1461
+ * resource lives under an organization scope — the dispatcher resolves the
1462
+ * scope from the organization initiator identity, which is only present on
1463
+ * organization-scoped operations.
1464
+ * Authoring `WEBHOOK_ORGANIZATION` on an APPLICATION/USER_SELF/ANONYMOUS
1465
+ * resource silently no-ops at runtime and is therefore a fail-closed
1466
+ * authoring error here.
1467
+ *
1468
+ * `WEBHOOK_APPLICATION` is allowed on any scope: the dispatcher resolves the
1469
+ * application scope from the always-present
1470
+ * `appConfigService.applicationId`, so the channel fires regardless of the
1471
+ * resource's own scope. The check is therefore one-sided — only the
1472
+ * `WEBHOOK_ORGANIZATION` arm fails closed.
1473
+ *
1474
+ * Custom channel refs (anything other than the two `CoreM2MNotificationChannel`
1475
+ * members) bypass the cross-check — third-party channels declare their own
1476
+ * scope semantics and are not the engine's contract.
1477
+ *
1478
+ * The cross-check is skipped when `resourcePrimaryScope` is `undefined`
1479
+ * — a defensive guard for re-validation seams that may be reached without
1480
+ * a scope (e.g., test fixtures invoking the validator directly, or future
1481
+ * call sites that haven't been updated). All production entry points
1482
+ * (`resourceSpecification`, `resourceSpecificationFromFrontendConfiguration`)
1483
+ * thread the scope explicitly, so this branch should not fire from the main
1484
+ * application path.
1485
+ */
1486
+ function assertM2MChannelMatchesPrimaryScope(
1487
+ ownerLabel: string,
1488
+ slotPath: string,
1489
+ channelRef: CoreM2MNotificationChannel | (string & {}),
1490
+ resourcePrimaryScope: ResourcePrimaryScope | undefined,
1491
+ ): void {
1492
+ if (resourcePrimaryScope === undefined) {
1493
+ return;
1494
+ }
1495
+ if (channelRef === CoreM2MNotificationChannel.WEBHOOK_ORGANIZATION) {
1496
+ if (resourcePrimaryScope !== ResourcePrimaryScope.ORGANIZATIONS) {
1497
+ throw new Error(
1498
+ `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.`,
1499
+ );
1500
+ }
1501
+ }
1502
+ // WEBHOOK_APPLICATION resolves scope from appConfigService.applicationId,
1503
+ // which is always present, so it is allowed on every primary scope.
1504
+ // Custom (non-Core) channel refs intentionally bypass the cross-check —
1505
+ // third-party channels declare their own scope semantics.
1506
+ }
1507
+
1508
+ /**
1509
+ * Cross-validate the optional `systemEmailTemplateRef` (now per-delivery)
1510
+ * against the runtime `SystemEmailTemplateRegistry` so a typo or stale ref
1511
+ * fails at module load instead of leaking a dangling cross-link into
1512
+ * companion prompts. Mirrors the registered-manifest cross-validation used
1513
+ * by the scheduledExecution `customBatchRef` arm — same anti-pattern, same
1514
+ * fail-closed treatment.
1515
+ *
1516
+ * `slotPath` is the full owner-relative path (e.g.
1517
+ * `communications.email.deliveries[2].systemEmailTemplateRef`) so error
1518
+ * messages locate the broken delivery directly.
1519
+ */
1520
+ function assertSystemEmailTemplateCrossLink(
1521
+ ownerLabel: string,
1522
+ slotPath: string,
1523
+ systemEmailTemplateRef: SystemEmailTemplateRef | undefined,
1524
+ ): void {
1525
+ if (systemEmailTemplateRef === undefined) {
1526
+ return;
1527
+ }
1528
+ if (typeof systemEmailTemplateRef !== 'string' || !systemEmailTemplateRef.trim()) {
1529
+ throw new Error(
1530
+ `Resource operation "${ownerLabel}" ${slotPath} must be a non-empty trimmed SystemEmailTemplateRef value.`,
1531
+ );
1532
+ }
1533
+ if (!Object.prototype.hasOwnProperty.call(SystemEmailTemplateRegistry, systemEmailTemplateRef)) {
1534
+ throw new Error(
1535
+ `Resource operation "${ownerLabel}" ${slotPath} "${systemEmailTemplateRef}" is not a member of SystemEmailTemplateRegistry. Use a SystemEmailTemplateRef enum value or register the template before this spec loads.`,
1536
+ );
1537
+ }
1538
+ }
1539
+
1540
+ /**
1541
+ * Iterate an operation map and validate every authored `communications` block.
1542
+ *
1543
+ * `ownerLabelPrefix` lets factories disambiguate which seam produced the error
1544
+ * (base-operation vs frontend-view), since `ResourceFrontendViewSpecification`
1545
+ * structurally extends `ResourceOperationSpecification` and can therefore
1546
+ * author communications too.
1547
+ */
1548
+ function validateResourceOperationsCommunications(
1549
+ ownerLabelPrefix: string,
1550
+ operations:
1551
+ | Record<string, ResourceOperationSpecification | ResourceFrontendViewSpecification | undefined>
1552
+ | undefined,
1553
+ resourcePrimaryScope?: ResourcePrimaryScope,
1554
+ ): void {
1555
+ if (!operations) {
1556
+ return;
1557
+ }
1558
+ for (const [operationId, operationSpec] of Object.entries(operations)) {
1559
+ if (!operationSpec) {
1560
+ continue;
1561
+ }
1562
+ validateResourceOperationCommunicationsSpecification(
1563
+ `${ownerLabelPrefix}${operationId}`,
1564
+ operationSpec.communications,
1565
+ resourcePrimaryScope,
1566
+ );
1567
+ }
1568
+ }
1569
+
1570
+ const registeredCustomBatchManifests = new Map<string, CustomBatchManifest>();
1571
+
1572
+ /**
1573
+ * Register custom-batch manifests with the spec-layer registry so authored
1574
+ * `scheduledExecution.customBatchRef` values can be cross-validated at
1575
+ * module load. Safe to call multiple times; re-registering the same
1576
+ * `batchRef` with an identical manifest is a no-op, but re-registering with
1577
+ * a divergent shape is a fail-closed error so silent drift between the
1578
+ * runtime batch and the spec layer is caught immediately.
1579
+ *
1580
+ * The framework registers its built-in batches when the public specification
1581
+ * package is loaded. Applications with custom batches should register them
1582
+ * from their specification bootstrap before evaluating a resource
1583
+ * specification that refers to them.
1584
+ *
1585
+ * **Import-order contract — read this if you author CUSTOM_BATCH specs.**
1586
+ * Registering built-in batches depends on loading the public package entry.
1587
+ * A consumer that reaches a low-level internal module first can evaluate a
1588
+ * CUSTOM_BATCH-bearing resource spec against an empty registry and fail closed
1589
+ * on the cross-link check at
1590
+ * {@link validateResourceOperationScheduledExecutionSpecification}. The
1591
+ * fix in that case is to either (a) ensure the engine barrel is imported
1592
+ * first (typically via `import '@wildo-ai/saas-specifications'`), or (b)
1593
+ * explicitly register the manifests required by that application's bootstrap.
1594
+ * Both paths make the contract explicit rather than leaving availability to
1595
+ * import order. Test suites that reset the registry must re-seed for the same
1596
+ * reason.
1597
+ */
1598
+ export function registerCustomBatchManifests(
1599
+ manifests: Iterable<CustomBatchManifest>,
1600
+ ): void {
1601
+ for (const manifest of manifests) {
1602
+ if (!manifest.batchRef || !manifest.batchRef.trim()) {
1603
+ throw new Error('registerCustomBatchManifests(): every manifest must carry a non-empty `batchRef`.');
1604
+ }
1605
+ if (!manifest.operationIdentifier || !manifest.operationIdentifier.trim()) {
1606
+ throw new Error(
1607
+ `registerCustomBatchManifests(): manifest for "${manifest.batchRef}" must declare a non-empty trimmed \`operationIdentifier\`.`,
1608
+ );
1609
+ }
1610
+ assertCustomBatchManifestKindArm(manifest);
1611
+ const existing = registeredCustomBatchManifests.get(manifest.batchRef);
1612
+ if (existing && !areCustomBatchManifestsEqual(existing, manifest)) {
1613
+ throw new Error(
1614
+ `registerCustomBatchManifests(): manifest for "${manifest.batchRef}" was registered twice with divergent shapes. Deduplicate the co-located manifest exports or update the spec-layer registration call.`,
1615
+ );
1616
+ }
1617
+ registeredCustomBatchManifests.set(manifest.batchRef, manifest);
1618
+ }
1619
+ }
1620
+
1621
+ /**
1622
+ * Per-arm structural validation for a {@link CustomBatchManifest} at
1623
+ * registration time. Mirrors the discriminated union split in
1624
+ * `ExecutionContextCreatorBackendService.createForInternalCustomBatch`:
1625
+ *
1626
+ * - `resource_anchored` — must declare a non-empty `resourceIdentifier`.
1627
+ * The spec layer does not (and should not) try to verify that the
1628
+ * identifier resolves to a registered resource — that cross-check lives
1629
+ * inside the runtime EC creator where the resources registry is the
1630
+ * source of truth and where a missing resource fails closed with the
1631
+ * same error message authors already see today.
1632
+ * - `scope_anchored` — must declare a `primaryScope` that is a member of
1633
+ * {@link ResourcePrimaryScope} (the runtime synthetic operation copies
1634
+ * this value into `resourcePrimaryScope`, so a typo would silently
1635
+ * widen or narrow downstream authorization). The `operationIdentifier`
1636
+ * must follow the `<domain>:<batch-ref>` convention so synthetic
1637
+ * operation labels stay grep-able alongside their batch ref — the
1638
+ * convention is also pinned by a dedicated unit test.
1639
+ *
1640
+ * Adding a future arm to {@link CustomBatchManifest} is a compile-time
1641
+ * error in the exhaustive `default` branch, forcing the author to extend
1642
+ * the per-arm rules instead of leaking an unchecked manifest into the
1643
+ * registry.
1644
+ */
1645
+ function assertCustomBatchManifestKindArm(manifest: CustomBatchManifest): void {
1646
+ switch (manifest.kind) {
1647
+ case CustomBatchManifestKind.RESOURCE_ANCHORED: {
1648
+ if (!manifest.resourceIdentifier || !manifest.resourceIdentifier.trim()) {
1649
+ throw new Error(
1650
+ `registerCustomBatchManifests(): resource_anchored manifest for "${manifest.batchRef}" must declare a non-empty trimmed \`resourceIdentifier\`.`,
1651
+ );
1652
+ }
1653
+ return;
1654
+ }
1655
+ case CustomBatchManifestKind.SCOPE_ANCHORED: {
1656
+ const allowedPrimaryScopes = Object.values(ResourcePrimaryScope) as readonly string[];
1657
+ if (!allowedPrimaryScopes.includes(manifest.primaryScope)) {
1658
+ throw new Error(
1659
+ `registerCustomBatchManifests(): scope_anchored manifest for "${manifest.batchRef}" declares unknown primaryScope "${manifest.primaryScope}". Use one of: ${allowedPrimaryScopes.join(', ')}.`,
1660
+ );
1661
+ }
1662
+ const colonIndex = manifest.operationIdentifier.indexOf(':');
1663
+ const domain = colonIndex >= 0 ? manifest.operationIdentifier.slice(0, colonIndex).trim() : '';
1664
+ const tail = colonIndex >= 0 ? manifest.operationIdentifier.slice(colonIndex + 1).trim() : '';
1665
+ if (colonIndex < 0 || !domain || tail !== manifest.batchRef) {
1666
+ throw new Error(
1667
+ `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.`,
1668
+ );
1669
+ }
1670
+ return;
1671
+ }
1672
+ default: {
1673
+ const exhaustiveCheck: never = manifest;
1674
+ throw new Error(
1675
+ `registerCustomBatchManifests(): unsupported CustomBatchManifest kind: ${JSON.stringify(exhaustiveCheck)}.`,
1676
+ );
1677
+ }
1678
+ }
1679
+ }
1680
+
1681
+ /**
1682
+ * Test-only helper that wipes the module-local custom-batch manifest registry.
1683
+ * Authored specifications should never call this at runtime — it exists only
1684
+ * so tests can exercise registration / cross-validation in isolation.
1685
+ */
1686
+ export function resetCustomBatchManifestRegistryForTesting(): void {
1687
+ registeredCustomBatchManifests.clear();
1688
+ }
1689
+
1690
+ /**
1691
+ * Structural equality for two {@link CustomBatchManifest} values, used by
1692
+ * {@link registerCustomBatchManifests} to detect divergent re-registration of
1693
+ * the same `batchRef` across the engine + app bootstrap seams.
1694
+ *
1695
+ * Comparison rules:
1696
+ * - Both manifests must declare the same `kind` discriminator. A
1697
+ * `resource_anchored` manifest is **never** equal to a `scope_anchored`
1698
+ * one even if their non-arm fields happen to align — the two arms model
1699
+ * structurally different bootstrap semantics in
1700
+ * `ExecutionContextCreatorBackendService.createForInternalCustomBatch` and
1701
+ * silently treating them as interchangeable would mask a real authoring
1702
+ * bug at registration time.
1703
+ * - Common fields (`batchRef`, `operationIdentifier`, `cronExpression`,
1704
+ * `cronExpressionConfigurable`) must match across both arms.
1705
+ * - The arm-specific identity field is then compared:
1706
+ * `resourceIdentifier` for `resource_anchored`, `primaryScope` for
1707
+ * `scope_anchored`. The exhaustive switch makes adding a future arm a
1708
+ * compile-time error here rather than a silent equality regression.
1709
+ */
1710
+ function areCustomBatchManifestsEqual(a: CustomBatchManifest, b: CustomBatchManifest): boolean {
1711
+ if (a.kind !== b.kind) {
1712
+ return false;
1713
+ }
1714
+ const commonEqual =
1715
+ a.batchRef === b.batchRef
1716
+ && a.operationIdentifier === b.operationIdentifier
1717
+ && a.cronExpression === b.cronExpression
1718
+ && Boolean(a.cronExpressionConfigurable) === Boolean(b.cronExpressionConfigurable);
1719
+ if (!commonEqual) {
1720
+ return false;
1721
+ }
1722
+ switch (a.kind) {
1723
+ case CustomBatchManifestKind.RESOURCE_ANCHORED:
1724
+ return a.resourceIdentifier
1725
+ === (b as ResourceAnchoredCustomBatchManifest).resourceIdentifier;
1726
+ case CustomBatchManifestKind.SCOPE_ANCHORED:
1727
+ return a.primaryScope
1728
+ === (b as ScopeAnchoredCustomBatchManifest).primaryScope;
1729
+ default: {
1730
+ const exhaustiveCheck: never = a;
1731
+ throw new Error(
1732
+ `areCustomBatchManifestsEqual(): unsupported CustomBatchManifest kind: ${JSON.stringify(exhaustiveCheck)}.`,
1733
+ );
1734
+ }
1735
+ }
1736
+ }
1737
+
1738
+ /**
1739
+ * Validation entry point used by the resource specification factory to assert
1740
+ * that an authored `scheduledExecution` block is internally consistent and,
1741
+ * for custom-batch arms, cross-checks against the declarative
1742
+ * {@link CustomBatchManifest} registry so typos or unregistered refs fail at
1743
+ * module load rather than silently at runtime.
1744
+ *
1745
+ * Each arm of the discriminated union enforces its own fail-closed contract:
1746
+ * - `NATIVE_CRON_JOB`: `cronExpression` must be a non-empty trimmed string.
1747
+ * - `NATIVE_BATCH_JOB`: no schedule or batch ref is permitted.
1748
+ * - `CUSTOM_BATCH`: `customBatchRef` must resolve to a registered manifest;
1749
+ * when the manifest declares a fixed cron the spec must echo it; when the
1750
+ * manifest is `cronExpressionConfigurable: true` the spec only needs to
1751
+ * carry a non-empty cron (divergence from the manifest default is allowed
1752
+ * because the runtime cron comes from app config); when the manifest omits
1753
+ * a cron entirely the spec must omit it too.
1754
+ *
1755
+ * Cross-validation is opt-in by design: the spec layer is built around a
1756
+ * declarative `CustomBatchManifest` registry seeded by the engine (and
1757
+ * optionally by app bootstraps) rather than an imperative dependency on
1758
+ * runtime service instances. If no manifest has been registered for a
1759
+ * `customBatchRef`, validation fails closed with an actionable message.
1760
+ *
1761
+ * **Test-suite seeding contract.** The framework registers built-in batches
1762
+ * when the public package entry is imported. Test files that
1763
+ * (a) reset the registry via {@link resetCustomBatchManifestRegistryForTesting}
1764
+ * and (b) need engine batches available afterwards must re-seed by calling
1765
+ * `registerCustomBatchManifests(ENGINE_CUSTOM_BATCH_MANIFESTS)` in `beforeAll`
1766
+ * or `beforeEach`. The current test suites either scope their reset to
1767
+ * test-only manifests or never reach built-in batches, so this remains an
1768
+ * explicit test setup contract.
1769
+ *
1770
+ * @param ownerLabel Stable identifier of the owning operation (used in error
1771
+ * messages so authors can locate the broken spec immediately).
1772
+ */
1773
+ export function validateResourceOperationScheduledExecutionSpecification(
1774
+ ownerLabel: string,
1775
+ scheduledExecution: ResourceOperationScheduledExecutionSpecification | undefined,
1776
+ ): void {
1777
+ if (!scheduledExecution) {
1778
+ return;
1779
+ }
1780
+ assertNonEmptyScheduledExecutionProseSlot(ownerLabel, 'purpose', scheduledExecution.purpose);
1781
+ assertNonEmptyScheduledExecutionProseSlot(ownerLabel, 'outcome', scheduledExecution.outcome);
1782
+ assertOptionalNonEmptyProseSlot(
1783
+ ownerLabel,
1784
+ 'scheduledExecution.useWhen',
1785
+ scheduledExecution.useWhen,
1786
+ );
1787
+ assertOptionalNonEmptyProseSlot(
1788
+ ownerLabel,
1789
+ 'scheduledExecution.avoidWhen',
1790
+ scheduledExecution.avoidWhen,
1791
+ );
1792
+ assertOptionalNonEmptyStringList(
1793
+ ownerLabel,
1794
+ 'scheduledExecution.businessConstraints',
1795
+ scheduledExecution.businessConstraints,
1796
+ );
1797
+ assertOptionalNonEmptyStringList(
1798
+ ownerLabel,
1799
+ 'scheduledExecution.codeHandling.notes',
1800
+ scheduledExecution.codeHandling?.notes,
1801
+ );
1802
+
1803
+ switch (scheduledExecution.variantType) {
1804
+ case ResourceOperationScheduledExecutionVariantType.NATIVE_CRON_JOB:
1805
+ assertNativeCronJobArm(ownerLabel, scheduledExecution);
1806
+ return;
1807
+ case ResourceOperationScheduledExecutionVariantType.NATIVE_BATCH_JOB:
1808
+ assertNativeBatchJobArm(ownerLabel, scheduledExecution);
1809
+ return;
1810
+ case ResourceOperationScheduledExecutionVariantType.CUSTOM_BATCH:
1811
+ assertCustomBatchArm(ownerLabel, scheduledExecution);
1812
+ return;
1813
+ default: {
1814
+ const exhaustiveCheck: never = scheduledExecution;
1815
+ throw new Error(
1816
+ `Resource operation "${ownerLabel}" scheduledExecution carries an unsupported variantType: ${JSON.stringify(exhaustiveCheck)}.`,
1817
+ );
1818
+ }
1819
+ }
1820
+ }
1821
+
1822
+ function assertNonEmptyScheduledExecutionProseSlot(
1823
+ ownerLabel: string,
1824
+ slotLabel: 'purpose' | 'outcome',
1825
+ value: string | undefined,
1826
+ ): void {
1827
+ if (!value || !value.trim()) {
1828
+ throw new Error(
1829
+ `Resource operation "${ownerLabel}" scheduledExecution.${slotLabel} must be a non-empty prose slot so companion prompts have grounded cron-run semantics.`,
1830
+ );
1831
+ }
1832
+ }
1833
+
1834
+ /**
1835
+ * Defense-in-depth runtime guards for the NATIVE_CRON_JOB arm.
1836
+ *
1837
+ * The static type already requires `cronExpression: string` and does **not**
1838
+ * declare `customBatchRef`, so well-typed authoring sites cannot reach an
1839
+ * invalid state. We still trim-check `cronExpression` and structurally reject
1840
+ * a smuggled `customBatchRef` so authoring sites that bypass type narrowing
1841
+ * (`as never`, `as any`, dynamic data, custom factories) cannot leak a blank
1842
+ * schedule or a foreign field into companion prompts. Symmetric with
1843
+ * {@link assertNativeBatchJobArm} so every arm enforces the same defensive
1844
+ * discipline.
1845
+ */
1846
+ function assertNativeCronJobArm(
1847
+ ownerLabel: string,
1848
+ arm: NativeCronJobScheduledExecutionSpecification,
1849
+ ): void {
1850
+ if (!arm.cronExpression || !arm.cronExpression.trim()) {
1851
+ throw new Error(
1852
+ `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).`,
1853
+ );
1854
+ }
1855
+ if ('customBatchRef' in arm && (arm as unknown as { customBatchRef?: unknown }).customBatchRef !== undefined) {
1856
+ throw new Error(
1857
+ `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.`,
1858
+ );
1859
+ }
1860
+ }
1861
+
1862
+ /**
1863
+ * Defense-in-depth runtime guards for the NATIVE_BATCH_JOB arm.
1864
+ *
1865
+ * The static type does **not** declare `cronExpression` or `customBatchRef`,
1866
+ * so well-typed authoring sites cannot reach this state. The structural
1867
+ * `'<key>' in arm` checks back the `// @ts-expect-error` test cases and
1868
+ * protect against dynamic data or `as any` bypasses at authoring sites — if
1869
+ * an author silences TypeScript to attach a stray field to a batch-job arm,
1870
+ * the validator still rejects it at module load.
1871
+ */
1872
+ function assertNativeBatchJobArm(
1873
+ ownerLabel: string,
1874
+ arm: NativeBatchJobScheduledExecutionSpecification,
1875
+ ): void {
1876
+ if ('cronExpression' in arm && (arm as unknown as { cronExpression?: unknown }).cronExpression !== undefined) {
1877
+ throw new Error(
1878
+ `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.`,
1879
+ );
1880
+ }
1881
+ if ('customBatchRef' in arm && (arm as unknown as { customBatchRef?: unknown }).customBatchRef !== undefined) {
1882
+ throw new Error(
1883
+ `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.`,
1884
+ );
1885
+ }
1886
+ }
1887
+
1888
+ /**
1889
+ * Validates the CUSTOM_BATCH arm against the spec-layer manifest registry.
1890
+ *
1891
+ * Cron-echo policy:
1892
+ * - **Fixed-cron manifest** (`cronExpressionConfigurable !== true` and
1893
+ * `cronExpression` declared): the authored spec must echo the manifest's
1894
+ * cron exactly, so companion prompts and the runtime cannot drift.
1895
+ * - **Configurable-cron manifest** (`cronExpressionConfigurable === true`):
1896
+ * the authored spec must still carry a non-empty cron (companion prompts
1897
+ * need a cadence) but is free to diverge from the manifest's runtime
1898
+ * default — divergence is the whole point of configurability.
1899
+ * - **Event-triggered manifest** (`cronExpression` undefined): the spec
1900
+ * must omit `cronExpression` so it does not invent a schedule the runtime
1901
+ * never honors.
1902
+ */
1903
+ function assertCustomBatchArm(
1904
+ ownerLabel: string,
1905
+ arm: CustomBatchScheduledExecutionSpecification,
1906
+ ): void {
1907
+ if (!arm.customBatchRef || !arm.customBatchRef.trim()) {
1908
+ throw new Error(
1909
+ `Resource operation "${ownerLabel}" scheduledExecution.customBatchRef must be a non-empty trimmed batch ref for the CUSTOM_BATCH arm (for example "files-cleanup").`,
1910
+ );
1911
+ }
1912
+ if (
1913
+ 'cronExpression' in arm
1914
+ && arm.cronExpression !== undefined
1915
+ && (!arm.cronExpression || !arm.cronExpression.trim())
1916
+ ) {
1917
+ throw new Error(
1918
+ `Resource operation "${ownerLabel}" scheduledExecution.cronExpression must be a non-empty trimmed cron expression when provided (authors must not declare an empty schedule).`,
1919
+ );
1920
+ }
1921
+
1922
+ const manifest = registeredCustomBatchManifests.get(arm.customBatchRef);
1923
+ if (!manifest) {
1924
+ throw new Error(
1925
+ `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.`,
1926
+ );
1927
+ }
1928
+ if (manifest.cronExpression && !arm.cronExpression) {
1929
+ throw new Error(
1930
+ `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.`,
1931
+ );
1932
+ }
1933
+ if (!manifest.cronExpression && arm.cronExpression) {
1934
+ throw new Error(
1935
+ `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.`,
1936
+ );
1937
+ }
1938
+ if (
1939
+ manifest.cronExpression
1940
+ && arm.cronExpression
1941
+ && !manifest.cronExpressionConfigurable
1942
+ && manifest.cronExpression !== arm.cronExpression
1943
+ ) {
1944
+ throw new Error(
1945
+ `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.`,
1946
+ );
1947
+ }
1948
+ }
1949
+
1950
+ /**
1951
+ * Iterate an operation map and validate every authored `scheduledExecution`
1952
+ * block. Same dual-seam rationale as communications: base-operation and
1953
+ * frontend-operation both structurally carry the slot, and both seams must
1954
+ * fail closed at module load.
1955
+ */
1956
+ function validateResourceOperationsScheduledExecution(
1957
+ ownerLabelPrefix: string,
1958
+ operations:
1959
+ | Record<string, ResourceOperationSpecification | ResourceFrontendViewSpecification | undefined>
1960
+ | undefined,
1961
+ ): void {
1962
+ if (!operations) {
1963
+ return;
1964
+ }
1965
+ for (const [operationId, operationSpec] of Object.entries(operations)) {
1966
+ if (!operationSpec) {
1967
+ continue;
1968
+ }
1969
+ validateResourceOperationScheduledExecutionSpecification(
1970
+ `${ownerLabelPrefix}${operationId}`,
1971
+ operationSpec.scheduledExecution,
1972
+ );
1973
+ }
1974
+ }
1975
+
1976
+ export type ResourceOperationSpecificationMap<
1977
+ TCustomOp extends EnumLikeType | undefined = any,
1978
+ TCoreOp extends Partial<CoreResourceOperation> | undefined = any,
1979
+ > = Partial<Record<ValidOperationKeys<TCustomOp, TCoreOp>, ResourceOperationSpecification>>;
1980
+ ```
1981
+ ## Import Origins
1982
+
1983
+ - `@wildo-ai/saas-specifications`
1984
+
1985
+ ## Source Excerpts
1986
+
1987
+ ### Origin Package: `@wildo-ai/saas-specifications`
1988
+
1989
+ ```typescript
1990
+ *
1991
+ * Frontend aspect distilled from `ResourceUIBehavior` for specification / companion layers.
1992
+ */
1993
+ export interface ResourceFrontendLabelAspect {
1994
+ strategy: 'field-paths' | 'computed';
1995
+ fieldNames?: string[];
1996
+ }
1997
+
1998
+ export interface ResourceFrontendLayoutAspect {
1999
+ refs?: LayoutRefManifest;
2000
+ hasDisplayTemplate: boolean;
2001
+ hasSummaryTemplate: boolean;
2002
+ hasEditTemplate: boolean;
2003
+ }
2004
+
2005
+ export interface ResourceFrontendConfigurationAspect<
2006
+ TCustomOp extends EnumLikeType | undefined,
2007
+ TCoreOp extends Partial<CoreResourceOperation> | undefined,
2008
+ TSchema extends z.ZodTypeAny,
2009
+ > {
2010
+ schema: TSchema;
2011
+ label?: ResourceFrontendLabelAspect;
2012
+ emptyState?: ResourceUIBehavior_EmptyState;
2013
+ layout?: ResourceFrontendLayoutAspect;
2014
+ guidance?: Record<string, ResourceUIBehavior_GuidanceFlow>;
2015
+ relationshipOverrides?: NonNullable<ResourceUIBehaviorConfig<TCustomOp, TCoreOp, TSchema>['relationshipOverrides']>;
2016
+ surfacedOperations: ResourceSpecificationSurfacedOperationMap<TCustomOp, TCoreOp>;
2017
+ operations: ResourceFrontendOperationSurfaceMap<TCustomOp, TCoreOp>;
2018
+ }
2019
+ ```
2020
+ ## Import Origins
2021
+
2022
+ - `@wildo-ai/saas-specifications`
2023
+
2024
+ ## Source Excerpts
2025
+
2026
+ ### Origin Package: `@wildo-ai/saas-specifications`
2027
+
2028
+ ```typescript
2029
+ *
2030
+ * Prose slots for resource specification `frontend` slice (label, layout, empty state, guidance, operations).
2031
+ */
2032
+ export interface ResourceFrontendLabelSpecification {
2033
+ purpose: string;
2034
+ textSlots?: TranslationSlotSpecificationMap;
2035
+ }
2036
+
2037
+ export type ResourceFrontendStructuralSlotSpecification = StructuralTranslationSlotSpecification;
2038
+
2039
+ export interface ResourceFrontendLayoutSpecification {
2040
+ purpose?: string;
2041
+ displayPurpose?: string;
2042
+ summaryPurpose?: string;
2043
+ editPurpose?: string;
2044
+ /**
2045
+ * Intent of the resource's `layout.header` template — the record's IDENTITY
2046
+ * LINE in the READ page header (accent swatch / name / status / visibility
2047
+ * chips, in whatever order the resource composes them).
2048
+ *
2049
+ * Documented separately from `displayPurpose` because the two answer
2050
+ * different questions and, once a header template exists, must not repeat
2051
+ * each other: the header states WHICH record this is and what state it is in,
2052
+ * the display body states everything else about it.
2053
+ */
2054
+ headerPurpose?: string;
2055
+ sections?: Record<string, ResourceFrontendStructuralSlotSpecification>;
2056
+ wizardSteps?: Record<string, ResourceFrontendStructuralSlotSpecification>;
2057
+ groups?: Record<string, ResourceFrontendStructuralSlotSpecification>;
2058
+ }
2059
+
2060
+ export interface ResourceFrontendEmptyStateSpecification {
2061
+ purpose: string;
2062
+ primaryActionPurpose?: string;
2063
+ secondaryActionPurpose?: string;
2064
+ }
2065
+
2066
+ export interface ResourceFrontendGuidanceFlowSpecification {
2067
+ purpose: string;
2068
+ whenToTrigger?: string;
2069
+ textSlots?: TranslationSlotSpecificationMap;
2070
+ elements?: Record<string, {
2071
+ purpose: string;
2072
+ whenToUse?: string;
2073
+ textSlots?: TranslationSlotSpecificationMap;
2074
+ }>;
2075
+ }
2076
+
2077
+ /**
2078
+ * Which separate view family an operation links to in addition to its main host.
2079
+ *
2080
+ * These families will later gain their own dedicated DTO registries; the
2081
+ * resource specification keeps the operation-owned linkage close to the
2082
+ * resource/runtime seam for now.
2083
+ */
2084
+ export enum ResourceOperationOtherViewKind {
2085
+ EXECUTION = 'execution',
2086
+ CHART = 'chart',
2087
+ COMPOSITE = 'composite',
2088
+ FULL_CUSTOM = 'full-custom',
2089
+ }
2090
+
2091
+ /**
2092
+ * Resource-owned direct host override selected through
2093
+ * `operationFrontendConfig.customView`.
2094
+ */
2095
+ export interface ResourceOperationCustomViewSpecification {
2096
+ /** Why this direct operation host exists beyond the default resource shell. */
2097
+ purpose: string;
2098
+ /** Situations where this host override is the intended authoring choice. */
2099
+ whenToUse?: string;
2100
+ /** Meaning of the host-level translatable slots such as title and description. */
2101
+ textSlots?: TranslationSlotSpecificationMap;
2102
+ /** Optional preset/base shell that the custom view composes or extends. */
2103
+ basedOnPreset?: string;
2104
+ /** Public symbol exposing the actual custom host component. */
2105
+ implementationSymbol: CodeSymbolRef;
2106
+ /** Preferred public import surface when different from the implementation. */
2107
+ consumerFacingSymbol?: CodeSymbolRef;
2108
+ /** Public declarations where this custom view is authored/selected. */
2109
+ declarationSymbols?: CodeSymbolRef[];
2110
+ /** Extra caveats for companion/transposer layers. */
2111
+ notes?: string[];
2112
+ }
2113
+
2114
+ /**
2115
+ * Additional non-host resource-owned views rendered inside a resource
2116
+ * operation host.
2117
+ *
2118
+ * These views are resolved by the framework directly from the resource UI
2119
+ * behavior's view declarations (`compositeViews[*].operationLike`,
2120
+ * `chartViews[*].operationLike`, `executionViews[*].surfaceInOperations`)
2121
+ * — there is no operation-level `additionalViews` authoring seam. The
2122
+ * specification layer simply mirrors, per operation, the set of resource-owned
2123
+ * views that target that operation host, for labelling/translation/authoring
2124
+ * documentation purposes.
2125
+ */
2126
+ export interface ResourceOperationOtherViewSpecification {
2127
+ /** Stable referenced view identifier as declared by the resource UI behavior. */
2128
+ viewRef: string;
2129
+ /** Which view family owns the referenced view. */
2130
+ viewKind: ResourceOperationOtherViewKind;
2131
+ /** Why this extra linked view exists in the workflow. */
2132
+ purpose: string;
2133
+ /** Situations where the linked view should be used. */
2134
+ whenToUse?: string;
2135
+ /** Meaning of the linked-view translatable slots such as title and description. */
2136
+ textSlots?: TranslationSlotSpecificationMap;
2137
+ /** Extra caveats for companion/transposer layers. */
2138
+ notes?: string[];
2139
+ }
2140
+
2141
+ /**
2142
+ * Operation-owned view seams layered on top of the semantic operation meaning.
2143
+ */
2144
+ export interface ResourceOperationViewSpecification {
2145
+ /** Direct replacement host selected through `customView`, if any. */
2146
+ customView?: ResourceOperationCustomViewSpecification;
2147
+ /** Additional linked views exposed alongside the main operation host. */
2148
+ otherViews?: ResourceOperationOtherViewSpecification[];
2149
+ }
2150
+
2151
+ /**
2152
+ * The frontend "view" of a single resource operation — the UI-side overlay
2153
+ * for an operation declared in `base.operations`.
2154
+ *
2155
+ * Structurally extends {@link ResourceOperationSpecification} so the same
2156
+ * intent/outcome/communications fields can be authored at this layer when
2157
+ * needed (the validators re-fire on every overlay seam — see
2158
+ * {@link resourceSpecificationFromFrontendConfiguration}). Adds variant
2159
+ * overlays and per-variant view-host configuration.
2160
+ *
2161
+ * Naming nuance: the inner `views?:` slot here is the *view-host* map (per
2162
+ * variant), distinct from the OUTER `frontend.views` map keyed by operation
2163
+ * id. Same word at two nesting levels — outer = "views by operation",
2164
+ * inner = "view-hosts by variant". Both are correct in their own right.
2165
+ */
2166
+ export interface ResourceFrontendViewSpecification
2167
+ extends Omit<
2168
+ ResourceOperationSpecification,
2169
+ 'variants' | 'responseStatuses' | 'errorScenarios' | 'idempotent' | 'rateLimitNote' | 'examples'
2170
+ > {
2171
+ /** Variant-specific UI semantics layered under the same logical operation id. */
2172
+ variants?: ResourceFrontendViewSpecificationVariants;
2173
+ /**
2174
+ * Per-variant view-host configuration (`customView`, `otherViews`).
2175
+ * The "view-hosts" of this view, in other words. Naming overlap with the
2176
+ * outer `frontend.views` map is intentional — see interface JSDoc.
2177
+ */
2178
+ views?: {
2179
+ default?: ResourceOperationViewSpecification;
2180
+ variants?: Record<string, ResourceOperationViewSpecification>;
2181
+ };
2182
+ }
2183
+
2184
+ export type ResourceFrontendViewSpecificationMap<
2185
+ TCustomOp extends EnumLikeType | undefined = any,
2186
+ TCoreOp extends Partial<CoreResourceOperation> | undefined = any,
2187
+ > = Partial<Record<ValidOperationKeys<TCustomOp, TCoreOp>, ResourceFrontendViewSpecification>>;
2188
+ ```
2189
+ ## Import Origins
2190
+
2191
+ - `@wildo-ai/saas-specifications`
2192
+
2193
+ ## Source Excerpts
2194
+
2195
+ ### Origin Package: `@wildo-ai/saas-specifications`
2196
+
2197
+ ```typescript
2198
+ *
2199
+ * Frontend-facing semantic additions layered on top of the base resource
2200
+ * specification.
2201
+ *
2202
+ * This slice is authored from a resolved `ResourceUIBehaviorConfig`, so it
2203
+ * should describe how the resource is surfaced to users, not restate structural
2204
+ * backend semantics that already live in the base specification.
2205
+ */
2206
+ export type ResourceSpecificationFrontendConfig<
2207
+ TCustomOp extends EnumLikeType | undefined = any,
2208
+ TCoreOp extends Partial<CoreResourceOperation> | undefined = any,
2209
+ > = {
2210
+ /** Why this resource label strategy exists in surfaced UI. */
2211
+ label?: ResourceFrontendLabelSpecification;
2212
+ /** How the frontend layout organizes the resource meaning. */
2213
+ layout?: ResourceFrontendLayoutSpecification;
2214
+ /** Why the empty state is framed the way it is. */
2215
+ emptyState?: ResourceFrontendEmptyStateSpecification;
2216
+ /** Semantic intent of resource-owned guidance flows. */
2217
+ guidance?: Record<string, ResourceFrontendGuidanceFlowSpecification>;
2218
+ /**
2219
+ * Per-operation frontend overlays — the UI-side "views" of each domain
2220
+ * operation declared in `base.operations`.
2221
+ *
2222
+ * Keys are the same operation identifiers as `base.operations`. Each value
2223
+ * supplies frontend-specific prose (purpose, whenToUse, importance, variant
2224
+ * overlays) and view-host configuration. The base entry remains the domain
2225
+ * truth; this map says HOW that operation surfaces in the UI.
2226
+ *
2227
+ * Renamed from `operations` to `views` (April 2026): the previous name
2228
+ * suggested a duplicate domain-operations declaration, when the real intent
2229
+ * is "the views of the operations". The base operations map remains
2230
+ * `operations`; this UI overlay is `views`.
2231
+ *
2232
+ * Note on inner naming: each entry can declare a nested `views?:` slot that
2233
+ * holds per-variant view-host configuration (`customView`, `otherViews`).
2234
+ * The outer `views` (here) is "views BY operation"; the inner `views`
2235
+ * (inside each entry) is "view-hosts BY variant" — same word, different
2236
+ * nesting level, both correct in their own right.
2237
+ */
2238
+ views?: ResourceFrontendViewSpecificationMap<TCustomOp, TCoreOp>;
2239
+ };
2240
+ ```
2241
+ ## Import Origins
2242
+
2243
+ - `@wildo-ai/saas-specifications`
2244
+
2245
+ ## Source Excerpts
2246
+
2247
+ ### Origin Package: `@wildo-ai/saas-specifications`
2248
+
2249
+ ```typescript
2250
+ *
2251
+ * Import-oriented references that help downstream prompt/transposition layers
2252
+ * write truthful code against this resource.
2253
+ */
2254
+ export interface ResourceSpecificationCodeHandling {
2255
+ /** Public schema symbol that owns the resource main shape. */
2256
+ mainSchema: CodeSymbolRef;
2257
+ /** Public factory symbol that owns the resource structural contract. */
2258
+ resourceFactory?: CodeSymbolRef;
2259
+ /** Truthful locator when the resource factory lives inside a public collection export. */
2260
+ resourceFactoryCollectionEntry?: CodeCollectionEntryRef;
2261
+ /**
2262
+ * Public enum member representing this resource type.
2263
+ * Required: every resource specification identifies the same public resource
2264
+ * enum member used by its runtime factory. This lets coding and companion
2265
+ * workflows generate discriminated resource logic without guessing or
2266
+ * silently dropping the resource identity.
2267
+ */
2268
+ resourceType: CodeEnumMemberRef;
2269
+ /**
2270
+ * Public enums that define the operation identifier vocabulary.
2271
+ * Required whenever the resource has operations. Coding and companion
2272
+ * workflows use `coreEnum` / `customEnum` as the authoritative vocabulary
2273
+ * for emitted operation branches, so the declaration must be complete rather
2274
+ * than leaving the runtime to infer missing cases.
2275
+ */
2276
+ operationVocabulary: ResourceSpecificationOperationVocabulary;
2277
+ /**
2278
+ * Public frontend contribution symbols used to build the merged
2279
+ * `resourceFrontendConfiguration()` input.
2280
+ */
2281
+ frontendConfigurationSources?: CodeSymbolRef[];
2282
+ /** Truthful locators when frontend UI behavior leaves live inside public collections. */
2283
+ frontendConfigurationSourceEntries?: CodeCollectionEntryRef[];
2284
+ /** Extra caveats for downstream coding/transposition consumers. */
2285
+ notes?: string[];
2286
+ }
2287
+ ```
2288
+ ## Import Origins
2289
+
2290
+ - `@wildo-ai/saas-specifications`
2291
+
2292
+ ## Source Excerpts
2293
+
2294
+ ### Origin Package: `@wildo-ai/saas-specifications`
2295
+
2296
+ ```typescript
2297
+ *
2298
+ * Callback parameter type for `resourceSpecification()`.
2299
+ *
2300
+ * Mirrors `ResourceUIBehaviorCallbackParams` — the factory resolves the schema
2301
+ * shape so that `{primitive}Spec()` decorators can be called with type safety.
2302
+ */
2303
+ export type ResourceSpecificationCallbackParams<
2304
+ TCustomOp extends EnumLikeType | undefined,
2305
+ TCoreOp extends Partial<CoreResourceOperation> | undefined,
2306
+ TSchema extends z.ZodTypeAny,
2307
+ > = {
2308
+ /** The raw Zod schema (e.g., `TodoSchema`). */
2309
+ schema: TSchema;
2310
+ /** Pre-resolved shape — each key is a schema field ready for decorator chaining. */
2311
+ schemaShape: ObjectShape<TSchema>;
2312
+ };
2313
+
2314
+ /**
2315
+ * Return type of the base `resourceSpecification()` callback.
2316
+ *
2317
+ * Resource-level prose lives here alongside the per-field decorator container.
2318
+ * The `fields` property works identically to `ResourceUIBehaviorConfig.fields`:
2319
+ * calling `{primitive}Spec()` on a shape field mutates its metadata in place;
2320
+ * the property itself exists for type safety and declaration.
2321
+ *
2322
+ * **Validator-entry contract — read this before constructing this object
2323
+ * directly (M5-9).** The cross-cutting fail-closed validators that protect
2324
+ * spec → runtime parity (`validateResourceOperationsCommunications`,
2325
+ * `validateResourceOperationsScheduledExecution`, and the per-delivery,
2326
+ * per-slot, per-field assertions they fan out to) ONLY fire from inside
2327
+ * the two authoring factories:
2328
+ *
2329
+ * 1. {@link resourceSpecification} — runs the validators on
2330
+ * `config.operations` and `config.frontend?.views` after the
2331
+ * callback returns.
2332
+ * 2. {@link resourceSpecificationFromFrontendConfiguration} — runs the
2333
+ * validators on `base.operations`, `base.frontend?.views`, and the
2334
+ * callback's `frontend.views` (the `base` revalidation forecloses
2335
+ * a hand-built-base regression silently bypassing the contract).
2336
+ *
2337
+ * If a future caller constructs a `ResourceSpecificationConfig` literal
2338
+ * by hand and exports it WITHOUT routing it through one of those two
2339
+ * factories, NONE of the per-delivery / per-slot / per-channel uniqueness
2340
+ * / system-email cross-link / m2m runtime-identity / M2MNotificationLevel
2341
+ * enum-membership / scheduledExecution custom-batch cross-link checks
2342
+ * will run — the spec would compile and ship, and the dispatch-side
2343
+ * contract violations would only surface as runtime errors at companion
2344
+ * render time or, worse, at user-facing dispatch time. Always author via
2345
+ * the two factories above; treat this type as the factory return shape,
2346
+ * not as a raw spec authoring surface.
2347
+ */
2348
+ export type ResourceSpecificationConfig<
2349
+ TCustomOp extends EnumLikeType | undefined = any,
2350
+ TCoreOp extends Partial<CoreResourceOperation> | undefined = any,
2351
+ TSchema extends z.ZodTypeAny = z.ZodAny,
2352
+ > = {
2353
+ /** Why this resource exists in the domain. */
2354
+ purpose: string;
2355
+ /** Functional role played by the resource inside the business architecture. */
2356
+ businessRole: string;
2357
+ /** How the resource evolves over time (lifecycle semantics). */
2358
+ lifecycleRole?: string;
2359
+ /**
2360
+ * Intended READER of this resource's generated labels — the register the label
2361
+ * generator should adopt: {@link LabelAudience.END_USER} for consumer surfaces
2362
+ * (todos, lists, profile), {@link LabelAudience.ADMIN} for operator /
2363
+ * back-office resources (users, organizations, billing, roles, audit),
2364
+ * {@link LabelAudience.DEVELOPER} for integration / technical resources (API
2365
+ * keys, webhooks, M2M, SCIM/SIEM). An operation may override it per-operation
2366
+ * via {@link ResourceOperationVariantSpecification.audienceOverride}.
2367
+ *
2368
+ * **Required.** Every resource spec must declare its audience so the label
2369
+ * generator picks the correct register (product copy vs operator console vs
2370
+ * technical / integration voice) without guessing from field names. The
2371
+ * labelling projector still keeps an end-user-normalizing fallback for the
2372
+ * rare hand-built config paths that bypass the authoring factories, but the
2373
+ * type contract now forces authors to make the choice explicitly.
2374
+ */
2375
+ audience: LabelAudience;
2376
+ /**
2377
+ * The resource's primary scope — **factory-set, never author-set**.
2378
+ *
2379
+ * The specification author declares scope via the fourth `options` argument
2380
+ * to {@link resourceSpecification}; the factory writes that resolved scope
2381
+ * here so downstream consumers, including
2382
+ * {@link resourceSpecificationFromFrontendConfiguration}'s re-validation
2383
+ * passes, can read it from `base.resourcePrimaryScope`.
2384
+ *
2385
+ * Optional only as a soft-fail concession to hand-built spec configs
2386
+ * that bypass both authoring factories — those paths intentionally
2387
+ * forfeit the m2m channel × scope cross-check on the re-validation
2388
+ * seams. Every spec produced by either factory carries this field.
2389
+ *
2390
+ * There is no local drift check between this declared value and the
2391
+ * registry-assembled `resourcePrimaryScope`: this layer cannot observe the
2392
+ * real `ResourceRelationship[]` needed to make that comparison. The
2393
+ * registry/companion assembly layer performs that cross-check when both
2394
+ * signals are available.
2395
+ */
2396
+ resourcePrimaryScope?: ResourcePrimaryScope;
2397
+ /** Public-import-oriented metadata for downstream code-handling prompts. */
2398
+ codeHandling?: ResourceSpecificationCodeHandling;
2399
+
2400
+ /**
2401
+ * Per-field specification decorators for the resource's `mainSchema`.
2402
+ *
2403
+ * Keys are field names of `TMainSchema`; values are decorated Zod schemas
2404
+ * from the same shape (e.g., `shape.status.enumSpec({ ... })`).
2405
+ *
2406
+ * The merge happens at **module evaluation time** — calling `.enumSpec()`
2407
+ * on a shape field mutates its metadata in place. The `fields` property
2408
+ * exists primarily for type safety (`keyof ObjectShape<TMainSchema>`) and
2409
+ * as a declaration container — same semantics as `ResourceUIBehavior.fields`.
2410
+ */
2411
+ fields?: {
2412
+ [K in keyof ObjectShape<TSchema>]?: ObjectShape<TSchema>[K];
2413
+ };
2414
+ /**
2415
+ * Explicit field metadata entries that do not live on `mainSchema`.
2416
+ *
2417
+ * Use this for inherited/variant-only fields or any companion-facing field
2418
+ * semantics that should not depend on cross-package schema singleton sharing.
2419
+ */
2420
+ additionalFieldSpecs?: ExtractedFieldSpec[];
2421
+
2422
+ /** Semantic clarification for operations. */
2423
+ operations?: ResourceOperationSpecificationMap<TCustomOp, TCoreOp>;
2424
+ /** Generated PDF field semantics exposed to companion/spec consumers. */
2425
+ pdfTemplates?: ResourcePdfTemplateSpecification[];
2426
+ /** CSV/JSON export companions derived from LIST/SEARCH `collectionExport` declarations. */
2427
+ collectionExports?: ResourceCollectionExportSpecification[];
2428
+ /** Frontend-facing semantic layer derived from UI behavior leaves. */
2429
+ frontend?: ResourceSpecificationFrontendConfig<TCustomOp, TCoreOp>;
2430
+ /** Domain caveats not encoded structurally elsewhere. */
2431
+ businessConstraints?: string[];
2432
+ };
2433
+
2434
+ export type AnyResourceSpecificationConfig = ResourceSpecificationConfig<any, any, any>;
2435
+
2436
+ /**
2437
+ * Resource specification overlay — keyed by resource type.
2438
+ * Same structural pattern as `ResourceUIBehavior = Record<string, ResourceUIBehaviorConfig>`.
2439
+ */
2440
+ export type ResourceSpecification = Record<string, AnyResourceSpecificationConfig>;
2441
+ ```
2442
+ ## Import Origins
2443
+
2444
+ - `@wildo-ai/saas-specifications`
2445
+
2446
+ ## Source Excerpts
2447
+
2448
+ ### Origin Package: `@wildo-ai/saas-specifications`
2449
+
2450
+ ```typescript
2451
+ *
2452
+ * Type-safe factory for authoring a `ResourceSpecificationConfig`.
2453
+ *
2454
+ * Mirrors `resourceUIBehavior()` — the `_factory` parameter is for type
2455
+ * inference only and is never invoked by the spec layer. The schema is
2456
+ * used to resolve `ObjectShape` so that `{primitive}Spec()` decorators
2457
+ * are type-checked against real fields.
2458
+ *
2459
+ * The callback runs immediately at module evaluation time. In the companion
2460
+ * context (where specifications are imported), this attaches `{primitive}Spec`
2461
+ * metadata to the schema's `customFieldMetadata`. In the frontend context
2462
+ * (where specifications are never imported), this code never runs, so no
2463
+ * semantic prose ends up in the browser bundle.
2464
+ *
2465
+ * **Explicit scope declaration.** The fourth `options` argument carries an
2466
+ * explicit `resourcePrimaryScope`. TypeScript enforces its presence at compile
2467
+ * time, so every specification call site declares scope.
2468
+ * That declared value is then:
2469
+ *
2470
+ * 1. Threaded into every `validateResourceOperationsCommunications` call
2471
+ * so the M2M channel × scope cross-check fires end-to-end on
2472
+ * every operation block, including the re-validation paths inside
2473
+ * {@link resourceSpecificationFromFrontendConfiguration}.
2474
+ * 2. Folded into the returned config (`resourcePrimaryScope` field) so
2475
+ * the frontend-config sibling can read it from `base`, preserving scope
2476
+ * context across the base → frontend handoff.
2477
+ *
2478
+ * **No local drift-check.** Calling a resource configuration factory with an
2479
+ * empty relationships array produces its empty-input fallback, not the real
2480
+ * scope for `APPLICATION`, `USER_SELF` or `ANONYMOUS` resources. This layer
2481
+ * therefore lacks the real `ResourceRelationship[]` inputs required for a
2482
+ * meaningful comparison and must not manufacture one.
2483
+ *
2484
+ * The genuine cross-check between this declared scope and the registry-
2485
+ * assembled scope happens at the registry/companion assembly layer, where
2486
+ * both signals coexist.
2487
+ *
2488
+ * @param _factory - The resource configuration factory (function form) or
2489
+ * a pre-built configuration object. Used purely for TypeScript inference
2490
+ * of `TCustomOp` / `TCoreOp` / `TSchema` for most validation. PDF-template
2491
+ * operation validation does materialize this factory with an empty
2492
+ * relationships array to inspect generated regenerate operations; that check
2493
+ * is limited to operation shape and must not be used as a registry-scope
2494
+ * drift signal.
2495
+ * @param schema - The resource's main Zod schema.
2496
+ * @param configFactory - Callback producing the specification content.
2497
+ * @param options - REQUIRED: declares the resource's `resourcePrimaryScope`.
2498
+ * See {@link ResourceSpecificationOptions} for the rationale.
2499
+ *
2500
+ * @example
2501
+ * ```ts
2502
+ * export const todosSpec = resourceSpecification(
2503
+ * todosFactory, TodoSchema,
2504
+ * ({ schemaShape }) => ({
2505
+ * purpose: 'Central entity for task tracking',
2506
+ * businessRole: 'Primary work item',
2507
+ * fields: {
2508
+ * status: schemaShape.status.enumSpec({
2509
+ * meaning: 'Current lifecycle state',
2510
+ * values: { pending: { meaning: 'Created but not started' } },
2511
+ * }),
2512
+ * },
2513
+ * operations: {
2514
+ * create: {
2515
+ * purpose: 'Create a new work item.',
2516
+ * },
2517
+ * },
2518
+ * }),
2519
+ * { resourcePrimaryScope: ResourcePrimaryScope.ORGANIZATIONS },
2520
+ * );
2521
+ * ```
2522
+ */
2523
+ export function resourceSpecification<
2524
+ TCustomOp extends EnumLikeType | undefined,
2525
+ TCoreOp extends Partial<CoreResourceOperation> | undefined,
2526
+ TSchema extends z.ZodTypeAny,
2527
+ >(
2528
+ _factory: ResourceConfigLike<TCustomOp, TCoreOp, TSchema>,
2529
+ schema: TSchema,
2530
+ configFactory: (
2531
+ params: ResourceSpecificationCallbackParams<TCustomOp, TCoreOp, TSchema>,
2532
+ ) => ResourceSpecificationConfig<TCustomOp, TCoreOp, TSchema>,
2533
+ options: ResourceSpecificationOptions,
2534
+ ): ResourceSpecificationConfig<TCustomOp, TCoreOp, TSchema> {
2535
+ const schemaShape = (
2536
+ schema && 'shape' in schema
2537
+ ? (schema as unknown as z.ZodObject<any>).shape
2538
+ : getZodObjectShape(schema)
2539
+ ) as ObjectShape<TSchema>;
2540
+
2541
+ const config = configFactory({ schema, schemaShape });
2542
+
2543
+ // Resolve scope and the runtime config used by the pdfTemplates validator
2544
+ // from whichever signal the spec author supplied. `resourceRelationships`
2545
+ // is the preferred path — it materializes the resource configuration once
2546
+ // with the real registry rels, so scope derives from the same
2547
+ // `isPrimaryScope: true` signal the runtime uses, AND the validator gets
2548
+ // a pre-resolved config (avoiding the failing `_factory([])` call for
2549
+ // resources whose primary scope comes from a parent rel).
2550
+ const { declaredScope, validatorResourceConfig } = resolveScopeAndValidatorConfig(
2551
+ _factory,
2552
+ options,
2553
+ );
2554
+
2555
+ validateResourceOperationsCommunications(
2556
+ 'operations.',
2557
+ config.operations as Record<string, ResourceOperationSpecification | undefined> | undefined,
2558
+ declaredScope,
2559
+ );
2560
+ validateResourceOperationsCommunications(
2561
+ 'frontend.views.',
2562
+ config.frontend?.views as Record<string, ResourceFrontendViewSpecification | undefined> | undefined,
2563
+ declaredScope,
2564
+ );
2565
+ validateResourceOperationsScheduledExecution(
2566
+ 'operations.',
2567
+ config.operations as Record<string, ResourceOperationSpecification | undefined> | undefined,
2568
+ );
2569
+ validateResourceOperationsScheduledExecution(
2570
+ 'frontend.views.',
2571
+ config.frontend?.views as Record<string, ResourceFrontendViewSpecification | undefined> | undefined,
2572
+ );
2573
+ validateResourcePdfTemplates('', config.pdfTemplates, schema, validatorResourceConfig);
2574
+ validateResourceCollectionExports('', config.collectionExports, Object.keys(config.operations ?? {}));
2575
+
2576
+ // Fail-closed shape validator for `fields` /
2577
+ // `additionalFieldSpecs`. Runs at module-load time so authors see
2578
+ // structural mistakes (`meaning` blank, `enumDeclaration` missing,
2579
+ // `arraySpec.elementMeaning` blank, ENUM-element array missing
2580
+ // `elementType.enumDeclaration`, etc.) at the call site rather than
2581
+ // inside a downstream rendered prompt. Registry-presence for
2582
+ // `foreignKeySpec` is intentionally NOT checked here — `_core` does
2583
+ // not see `ResourceRelationship[]`; the companion-level completeness
2584
+ // validator owns that cross-check.
2585
+ //
2586
+ // The resource-type hint in the prefix comes from `_factory` (either
2587
+ // the function's `name` stripped of the `_ResourceConfiguration_
2588
+ // InitializationFactory` suffix, or — for rare object-form factories —
2589
+ // the `resourceType` slot directly). Best-effort: when the hint cannot
2590
+ // be derived, the prefix falls back to the bare `resourceSpecification():`
2591
+ // label, matching the pre-hint behaviour.
2592
+ const resourceTypeHint = extractResourceTypeHintFromFactory(_factory);
2593
+ const fieldShapesPrefix = resourceTypeHint.length > 0
2594
+ ? `resourceSpecification(${resourceTypeHint}): `
2595
+ : 'resourceSpecification(): ';
2596
+ validateFieldShapes(fieldShapesPrefix, {
2597
+ fields: config.fields as Record<string, z.ZodTypeAny> | undefined,
2598
+ additionalFieldSpecs: config.additionalFieldSpecs,
2599
+ });
2600
+
2601
+ // Attach the resolved scope so the frontend-config sibling
2602
+ // (`resourceSpecificationFromFrontendConfiguration`) can read it from
2603
+ // `base.resourcePrimaryScope` and thread it into its own re-validation
2604
+ // passes without losing base → frontend scope context.
2605
+ return {
2606
+ ...config,
2607
+ resourcePrimaryScope: declaredScope,
2608
+ } as ResourceSpecificationConfig<TCustomOp, TCoreOp, TSchema>;
2609
+ }
2610
+ ```