@wildo-ai/dev-companion 1.1.1 → 1.1.2

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 (224) hide show
  1. package/dist/esm/.tsbuildinfo +1 -1
  2. package/dist/esm/claude-cli/models/coding-agent-dispatch.models.d.ts +12 -1
  3. package/dist/esm/claude-cli/models/coding-agent-dispatch.models.d.ts.map +1 -1
  4. package/dist/esm/claude-cli/models/coding-agent-dispatch.models.js +11 -0
  5. package/dist/esm/claude-cli/models/coding-agent-dispatch.models.js.map +1 -1
  6. package/dist/esm/claude-cli/services/coding-agent-dispatch.companion.service.d.ts +153 -1
  7. package/dist/esm/claude-cli/services/coding-agent-dispatch.companion.service.d.ts.map +1 -1
  8. package/dist/esm/claude-cli/services/coding-agent-dispatch.companion.service.js +419 -41
  9. package/dist/esm/claude-cli/services/coding-agent-dispatch.companion.service.js.map +1 -1
  10. package/dist/esm/claude-cli/services/research-agent-dispatch.companion.service.d.ts +25 -10
  11. package/dist/esm/claude-cli/services/research-agent-dispatch.companion.service.d.ts.map +1 -1
  12. package/dist/esm/claude-cli/services/research-agent-dispatch.companion.service.js +65 -24
  13. package/dist/esm/claude-cli/services/research-agent-dispatch.companion.service.js.map +1 -1
  14. package/dist/esm/claude-cli/services/research-evidence-store.companion.d.ts +86 -0
  15. package/dist/esm/claude-cli/services/research-evidence-store.companion.d.ts.map +1 -0
  16. package/dist/esm/claude-cli/services/research-evidence-store.companion.js +127 -0
  17. package/dist/esm/claude-cli/services/research-evidence-store.companion.js.map +1 -0
  18. package/dist/esm/companion-api/companion-api.schemas.d.ts +59 -2
  19. package/dist/esm/companion-api/companion-api.schemas.d.ts.map +1 -1
  20. package/dist/esm/companion-api/companion-api.schemas.js +60 -0
  21. package/dist/esm/companion-api/companion-api.schemas.js.map +1 -1
  22. package/dist/esm/companion-api/controllers/companion.controller.d.ts +63 -1
  23. package/dist/esm/companion-api/controllers/companion.controller.d.ts.map +1 -1
  24. package/dist/esm/companion-api/controllers/companion.controller.js +322 -21
  25. package/dist/esm/companion-api/controllers/companion.controller.js.map +1 -1
  26. package/dist/esm/core/inject/models/container.d.ts.map +1 -1
  27. package/dist/esm/core/inject/models/container.js +11 -0
  28. package/dist/esm/core/inject/models/container.js.map +1 -1
  29. package/dist/esm/core/inject/models/service-types.d.ts +5 -0
  30. package/dist/esm/core/inject/models/service-types.d.ts.map +1 -1
  31. package/dist/esm/core/inject/models/service-types.js +5 -0
  32. package/dist/esm/core/inject/models/service-types.js.map +1 -1
  33. package/dist/esm/core/introspection/behaviors/companion-introspection-behavior-definitions.d.ts.map +1 -1
  34. package/dist/esm/core/introspection/behaviors/companion-introspection-behavior-definitions.js +81 -0
  35. package/dist/esm/core/introspection/behaviors/companion-introspection-behavior-definitions.js.map +1 -1
  36. package/dist/esm/core/introspection/models/companion-introspection.models.d.ts +11 -1
  37. package/dist/esm/core/introspection/models/companion-introspection.models.d.ts.map +1 -1
  38. package/dist/esm/core/introspection/models/companion-introspection.models.js +39 -0
  39. package/dist/esm/core/introspection/models/companion-introspection.models.js.map +1 -1
  40. package/dist/esm/core/introspection/resources/creation-plane-dispatch.custom-impl.companion.service.d.ts +8 -0
  41. package/dist/esm/core/introspection/resources/creation-plane-dispatch.custom-impl.companion.service.d.ts.map +1 -0
  42. package/dist/esm/core/introspection/resources/creation-plane-dispatch.custom-impl.companion.service.js +317 -0
  43. package/dist/esm/core/introspection/resources/creation-plane-dispatch.custom-impl.companion.service.js.map +1 -0
  44. package/dist/esm/core/introspection/resources/creation-plane-projection.companion.service.d.ts +45 -0
  45. package/dist/esm/core/introspection/resources/creation-plane-projection.companion.service.d.ts.map +1 -0
  46. package/dist/esm/core/introspection/resources/creation-plane-projection.companion.service.js +250 -0
  47. package/dist/esm/core/introspection/resources/creation-plane-projection.companion.service.js.map +1 -0
  48. package/dist/esm/core/introspection/resources/introspection-resource-notifier.companion.service.d.ts +123 -0
  49. package/dist/esm/core/introspection/resources/introspection-resource-notifier.companion.service.d.ts.map +1 -0
  50. package/dist/esm/core/introspection/resources/introspection-resource-notifier.companion.service.js +298 -0
  51. package/dist/esm/core/introspection/resources/introspection-resource-notifier.companion.service.js.map +1 -0
  52. package/dist/esm/core/introspection/resources/introspection-resource-source.companion.service.d.ts +78 -1
  53. package/dist/esm/core/introspection/resources/introspection-resource-source.companion.service.d.ts.map +1 -1
  54. package/dist/esm/core/introspection/resources/introspection-resource-source.companion.service.js +155 -6
  55. package/dist/esm/core/introspection/resources/introspection-resource-source.companion.service.js.map +1 -1
  56. package/dist/esm/core/introspection/services/companion-introspection.companion.service.d.ts +131 -2
  57. package/dist/esm/core/introspection/services/companion-introspection.companion.service.d.ts.map +1 -1
  58. package/dist/esm/core/introspection/services/companion-introspection.companion.service.js +259 -9
  59. package/dist/esm/core/introspection/services/companion-introspection.companion.service.js.map +1 -1
  60. package/dist/esm/core/introspection/services/introspection-derivation-state.companion.service.d.ts +243 -0
  61. package/dist/esm/core/introspection/services/introspection-derivation-state.companion.service.d.ts.map +1 -0
  62. package/dist/esm/core/introspection/services/introspection-derivation-state.companion.service.js +417 -0
  63. package/dist/esm/core/introspection/services/introspection-derivation-state.companion.service.js.map +1 -0
  64. package/dist/esm/core/introspection/services/introspection-source-state.companion.service.d.ts +186 -0
  65. package/dist/esm/core/introspection/services/introspection-source-state.companion.service.d.ts.map +1 -0
  66. package/dist/esm/core/introspection/services/introspection-source-state.companion.service.js +368 -0
  67. package/dist/esm/core/introspection/services/introspection-source-state.companion.service.js.map +1 -0
  68. package/dist/esm/core/introspection/services/introspection-source-watcher.companion.service.d.ts +101 -0
  69. package/dist/esm/core/introspection/services/introspection-source-watcher.companion.service.d.ts.map +1 -0
  70. package/dist/esm/core/introspection/services/introspection-source-watcher.companion.service.js +278 -0
  71. package/dist/esm/core/introspection/services/introspection-source-watcher.companion.service.js.map +1 -0
  72. package/dist/esm/core/introspection/subprocess/application-domain-model.behavior.d.ts +365 -0
  73. package/dist/esm/core/introspection/subprocess/application-domain-model.behavior.d.ts.map +1 -0
  74. package/dist/esm/core/introspection/subprocess/application-domain-model.behavior.js +167 -0
  75. package/dist/esm/core/introspection/subprocess/application-domain-model.behavior.js.map +1 -0
  76. package/dist/esm/core/introspection/subprocess/companion-introspection-behavior-handlers.d.ts.map +1 -1
  77. package/dist/esm/core/introspection/subprocess/companion-introspection-behavior-handlers.js +332 -3
  78. package/dist/esm/core/introspection/subprocess/companion-introspection-behavior-handlers.js.map +1 -1
  79. package/dist/esm/core/introspection/subprocess/family-aspects.behavior.d.ts +19 -0
  80. package/dist/esm/core/introspection/subprocess/family-aspects.behavior.d.ts.map +1 -0
  81. package/dist/esm/core/introspection/subprocess/family-aspects.behavior.js +164 -0
  82. package/dist/esm/core/introspection/subprocess/family-aspects.behavior.js.map +1 -0
  83. package/dist/esm/core/introspection/subprocess/openapi-generation-input.behavior.d.ts +3 -1
  84. package/dist/esm/core/introspection/subprocess/openapi-generation-input.behavior.d.ts.map +1 -1
  85. package/dist/esm/core/introspection/subprocess/openapi-generation-input.behavior.js +36 -23
  86. package/dist/esm/core/introspection/subprocess/openapi-generation-input.behavior.js.map +1 -1
  87. package/dist/esm/core/introspection/subprocess/specification-artifacts.behavior.d.ts +51 -0
  88. package/dist/esm/core/introspection/subprocess/specification-artifacts.behavior.d.ts.map +1 -0
  89. package/dist/esm/core/introspection/subprocess/specification-artifacts.behavior.js +391 -0
  90. package/dist/esm/core/introspection/subprocess/specification-artifacts.behavior.js.map +1 -0
  91. package/dist/esm/core/runtime/companion-startup-assembly.d.ts.map +1 -1
  92. package/dist/esm/core/runtime/companion-startup-assembly.js +5 -0
  93. package/dist/esm/core/runtime/companion-startup-assembly.js.map +1 -1
  94. package/dist/esm/core/runtime/dev-compile-quiet.companion.d.ts +103 -0
  95. package/dist/esm/core/runtime/dev-compile-quiet.companion.d.ts.map +1 -0
  96. package/dist/esm/core/runtime/dev-compile-quiet.companion.js +124 -0
  97. package/dist/esm/core/runtime/dev-compile-quiet.companion.js.map +1 -0
  98. package/dist/esm/core/runtime/services/start-companion-application.service.d.ts +39 -2
  99. package/dist/esm/core/runtime/services/start-companion-application.service.d.ts.map +1 -1
  100. package/dist/esm/core/runtime/services/start-companion-application.service.js +122 -11
  101. package/dist/esm/core/runtime/services/start-companion-application.service.js.map +1 -1
  102. package/dist/esm/core/specifications/non-composite-view-specification-context.shared.d.ts +6 -0
  103. package/dist/esm/core/specifications/non-composite-view-specification-context.shared.d.ts.map +1 -1
  104. package/dist/esm/core/specifications/non-composite-view-specification-context.shared.js.map +1 -1
  105. package/dist/esm/core/specifications/specification-context-factory.shared.d.ts +23 -0
  106. package/dist/esm/core/specifications/specification-context-factory.shared.d.ts.map +1 -1
  107. package/dist/esm/core/specifications/specification-context-factory.shared.js +26 -4
  108. package/dist/esm/core/specifications/specification-context-factory.shared.js.map +1 -1
  109. package/dist/esm/executions/services/companion-executions.companion.service.d.ts +82 -3
  110. package/dist/esm/executions/services/companion-executions.companion.service.d.ts.map +1 -1
  111. package/dist/esm/executions/services/companion-executions.companion.service.js +126 -12
  112. package/dist/esm/executions/services/companion-executions.companion.service.js.map +1 -1
  113. package/dist/esm/i18n/components/APP_LAYOUTS_MAIN_CONTAINER.en.d.ts +12 -0
  114. package/dist/esm/i18n/components/APP_LAYOUTS_MAIN_CONTAINER.en.d.ts.map +1 -0
  115. package/dist/esm/i18n/components/APP_LAYOUTS_MAIN_CONTAINER.en.js +12 -0
  116. package/dist/esm/i18n/components/APP_LAYOUTS_MAIN_CONTAINER.en.js.map +1 -0
  117. package/dist/esm/i18n/components/LOW_LEVEL_FORM_FIELD.en.d.ts +1 -1
  118. package/dist/esm/i18n/components/LOW_LEVEL_FORM_FIELD.en.js +1 -1
  119. package/dist/esm/i18n/components/LOW_LEVEL_FORM_FIELD.en.js.map +1 -1
  120. package/dist/esm/i18n/composite_views/app.creation-board.en.d.ts +13 -0
  121. package/dist/esm/i18n/composite_views/app.creation-board.en.d.ts.map +1 -0
  122. package/dist/esm/i18n/composite_views/app.creation-board.en.js +91 -0
  123. package/dist/esm/i18n/composite_views/app.creation-board.en.js.map +1 -0
  124. package/dist/esm/i18n/composite_views/app.domain-model.en.d.ts +38 -0
  125. package/dist/esm/i18n/composite_views/app.domain-model.en.d.ts.map +1 -0
  126. package/dist/esm/i18n/composite_views/app.domain-model.en.js +41 -0
  127. package/dist/esm/i18n/composite_views/app.domain-model.en.js.map +1 -0
  128. package/dist/esm/i18n/index.d.ts +3 -3
  129. package/dist/esm/i18n/index.js +3 -3
  130. package/dist/esm/i18n/index.js.map +1 -1
  131. package/dist/esm/i18n/resources/wildoApplicationActorSystemExecutions.en.d.ts +24 -0
  132. package/dist/esm/i18n/resources/wildoApplicationActorSystemExecutions.en.d.ts.map +1 -0
  133. package/dist/esm/i18n/resources/wildoApplicationActorSystemExecutions.en.js +20 -0
  134. package/dist/esm/i18n/resources/wildoApplicationActorSystemExecutions.en.js.map +1 -0
  135. package/dist/esm/i18n/resources/wildoApplicationActorTasks.en.d.ts +31 -0
  136. package/dist/esm/i18n/resources/wildoApplicationActorTasks.en.d.ts.map +1 -0
  137. package/dist/esm/i18n/resources/wildoApplicationActorTasks.en.js +27 -0
  138. package/dist/esm/i18n/resources/wildoApplicationActorTasks.en.js.map +1 -0
  139. package/dist/esm/i18n/resources/wildoApplicationFlowSystemExecutions.en.d.ts +24 -0
  140. package/dist/esm/i18n/resources/wildoApplicationFlowSystemExecutions.en.d.ts.map +1 -0
  141. package/dist/esm/i18n/resources/wildoApplicationFlowSystemExecutions.en.js +20 -0
  142. package/dist/esm/i18n/resources/wildoApplicationFlowSystemExecutions.en.js.map +1 -0
  143. package/dist/esm/i18n/resources/workbenchBuildPlanTasks.en.d.ts +28 -0
  144. package/dist/esm/i18n/resources/workbenchBuildPlanTasks.en.d.ts.map +1 -0
  145. package/dist/esm/i18n/resources/workbenchBuildPlanTasks.en.js +24 -0
  146. package/dist/esm/i18n/resources/workbenchBuildPlanTasks.en.js.map +1 -0
  147. package/dist/esm/i18n/resources/workbenchDomainResources.en.d.ts +138 -0
  148. package/dist/esm/i18n/resources/workbenchDomainResources.en.d.ts.map +1 -0
  149. package/dist/esm/i18n/resources/workbenchDomainResources.en.js +100 -0
  150. package/dist/esm/i18n/resources/workbenchDomainResources.en.js.map +1 -0
  151. package/dist/esm/i18n/resources/workbenchPlaybooks.en.d.ts +29 -0
  152. package/dist/esm/i18n/resources/workbenchPlaybooks.en.d.ts.map +1 -0
  153. package/dist/esm/i18n/resources/workbenchPlaybooks.en.js +25 -0
  154. package/dist/esm/i18n/resources/workbenchPlaybooks.en.js.map +1 -0
  155. package/dist/esm/i18n/resources/workbenchRunWriteRecords.en.d.ts +27 -0
  156. package/dist/esm/i18n/resources/workbenchRunWriteRecords.en.d.ts.map +1 -0
  157. package/dist/esm/i18n/resources/workbenchRunWriteRecords.en.js +23 -0
  158. package/dist/esm/i18n/resources/workbenchRunWriteRecords.en.js.map +1 -0
  159. package/dist/esm/i18n/resources/workbenchSpecificationArtifacts.en.d.ts +806 -0
  160. package/dist/esm/i18n/resources/workbenchSpecificationArtifacts.en.d.ts.map +1 -0
  161. package/dist/esm/i18n/resources/workbenchSpecificationArtifacts.en.js +326 -0
  162. package/dist/esm/i18n/resources/workbenchSpecificationArtifacts.en.js.map +1 -0
  163. package/dist/esm/i18n/resources/workbenchTraceSessions.en.d.ts +26 -0
  164. package/dist/esm/i18n/resources/workbenchTraceSessions.en.d.ts.map +1 -0
  165. package/dist/esm/i18n/resources/workbenchTraceSessions.en.js +22 -0
  166. package/dist/esm/i18n/resources/workbenchTraceSessions.en.js.map +1 -0
  167. package/dist/esm/i18n/system_enums/market.en.d.ts +202 -0
  168. package/dist/esm/i18n/system_enums/market.en.d.ts.map +1 -0
  169. package/dist/esm/i18n/system_enums/market.en.js +209 -0
  170. package/dist/esm/i18n/system_enums/market.en.js.map +1 -0
  171. package/dist/esm/meta-workflows/models/application-coding-agent.actors-system.definitions.d.ts +112 -2
  172. package/dist/esm/meta-workflows/models/application-coding-agent.actors-system.definitions.d.ts.map +1 -1
  173. package/dist/esm/meta-workflows/models/application-coding-agent.actors-system.definitions.js +201 -34
  174. package/dist/esm/meta-workflows/models/application-coding-agent.actors-system.definitions.js.map +1 -1
  175. package/dist/esm/meta-workflows/models/application-research-agent.actors-system.definitions.d.ts +31 -3
  176. package/dist/esm/meta-workflows/models/application-research-agent.actors-system.definitions.d.ts.map +1 -1
  177. package/dist/esm/meta-workflows/models/application-research-agent.actors-system.definitions.js +48 -12
  178. package/dist/esm/meta-workflows/models/application-research-agent.actors-system.definitions.js.map +1 -1
  179. package/dist/esm/meta-workflows/models/brief-adequacy.actors-system.definitions.d.ts +36 -0
  180. package/dist/esm/meta-workflows/models/brief-adequacy.actors-system.definitions.d.ts.map +1 -0
  181. package/dist/esm/meta-workflows/models/brief-adequacy.actors-system.definitions.js +75 -0
  182. package/dist/esm/meta-workflows/models/brief-adequacy.actors-system.definitions.js.map +1 -0
  183. package/dist/esm/meta-workflows/services/application-build-dispatch.companion.service.d.ts +105 -7
  184. package/dist/esm/meta-workflows/services/application-build-dispatch.companion.service.d.ts.map +1 -1
  185. package/dist/esm/meta-workflows/services/application-build-dispatch.companion.service.js +298 -24
  186. package/dist/esm/meta-workflows/services/application-build-dispatch.companion.service.js.map +1 -1
  187. package/dist/esm/meta-workflows/services/application-build-generation-step.companion.service.d.ts +46 -3
  188. package/dist/esm/meta-workflows/services/application-build-generation-step.companion.service.d.ts.map +1 -1
  189. package/dist/esm/meta-workflows/services/application-build-generation-step.companion.service.js +95 -2
  190. package/dist/esm/meta-workflows/services/application-build-generation-step.companion.service.js.map +1 -1
  191. package/dist/esm/meta-workflows/services/execution-trace-read.companion.service.d.ts +9 -0
  192. package/dist/esm/meta-workflows/services/execution-trace-read.companion.service.d.ts.map +1 -1
  193. package/dist/esm/meta-workflows/services/execution-trace-read.companion.service.js +13 -0
  194. package/dist/esm/meta-workflows/services/execution-trace-read.companion.service.js.map +1 -1
  195. package/dist/esm/meta-workflows/services/playbook-run-write-register.companion.service.d.ts +12 -0
  196. package/dist/esm/meta-workflows/services/playbook-run-write-register.companion.service.d.ts.map +1 -1
  197. package/dist/esm/meta-workflows/services/playbook-run-write-register.companion.service.js +23 -0
  198. package/dist/esm/meta-workflows/services/playbook-run-write-register.companion.service.js.map +1 -1
  199. package/dist/esm/meta-workflows/services/playbook-run.companion.service.d.ts +120 -3
  200. package/dist/esm/meta-workflows/services/playbook-run.companion.service.d.ts.map +1 -1
  201. package/dist/esm/meta-workflows/services/playbook-run.companion.service.js +636 -81
  202. package/dist/esm/meta-workflows/services/playbook-run.companion.service.js.map +1 -1
  203. package/dist/esm/meta-workflows/services/playbook-suspended-run.companion.service.d.ts +40 -0
  204. package/dist/esm/meta-workflows/services/playbook-suspended-run.companion.service.d.ts.map +1 -1
  205. package/dist/esm/meta-workflows/services/playbook-suspended-run.companion.service.js +63 -1
  206. package/dist/esm/meta-workflows/services/playbook-suspended-run.companion.service.js.map +1 -1
  207. package/dist/esm/technical-doc/services/technical-doc.companion.service.d.ts +21 -0
  208. package/dist/esm/technical-doc/services/technical-doc.companion.service.d.ts.map +1 -1
  209. package/dist/esm/technical-doc/services/technical-doc.companion.service.js +86 -2
  210. package/dist/esm/technical-doc/services/technical-doc.companion.service.js.map +1 -1
  211. package/dist/esm/technical-doc/services/technical-documentation-application-derivation.companion.service.d.ts +12 -1
  212. package/dist/esm/technical-doc/services/technical-documentation-application-derivation.companion.service.d.ts.map +1 -1
  213. package/dist/esm/technical-doc/services/technical-documentation-application-derivation.companion.service.js +47 -1
  214. package/dist/esm/technical-doc/services/technical-documentation-application-derivation.companion.service.js.map +1 -1
  215. package/package.json +17 -17
  216. package/dist/esm/.builder.pid +0 -9
  217. package/dist/esm/i18n/resources/workbenchApplicationModules.en.d.ts +0 -36
  218. package/dist/esm/i18n/resources/workbenchApplicationModules.en.d.ts.map +0 -1
  219. package/dist/esm/i18n/resources/workbenchApplicationModules.en.js +0 -32
  220. package/dist/esm/i18n/resources/workbenchApplicationModules.en.js.map +0 -1
  221. package/dist/esm/i18n/resources/workbenchResourceRelationships.en.d.ts +0 -29
  222. package/dist/esm/i18n/resources/workbenchResourceRelationships.en.d.ts.map +0 -1
  223. package/dist/esm/i18n/resources/workbenchResourceRelationships.en.js +0 -25
  224. package/dist/esm/i18n/resources/workbenchResourceRelationships.en.js.map +0 -1
@@ -0,0 +1 @@
1
+ {"version":3,"file":"introspection-source-state.companion.service.js","sourceRoot":"","sources":["../../../../../../src/core/introspection/services/introspection-source-state.companion.service.ts"],"names":[],"mappings":"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","sourcesContent":["import { promises as fsPromises } from 'node:fs';\nimport { join, resolve } from 'node:path';\nimport type { CompanionContext } from '../../context/companion-context';\n\n/**\n * How many directories are walked concurrently.\n *\n * Measured on `examples/wonder-crm` (23,758 files + 2,706 directories across the three application\n * package roots and the 19 distinct `@wildo-ai/*` roots they resolve to): 350 ms at concurrency 1,\n * **125 ms at 16**, 142 ms at 64, 134 ms at 128. The curve is flat past 16, so 16 is the point where\n * the walk stops being latency-bound without turning into an open-ended file-descriptor burst.\n *\n * The walk is deliberately ASYNC rather than the ~30 % faster synchronous form. A synchronous sweep\n * measured 175 ms on the same tree, but it holds the event loop for that whole time — and this runs\n * inside a long-lived HTTP server that is also serving the workbench.\n */\nconst DIRECTORY_WALK_CONCURRENCY = 16;\n\n/**\n * Directory names never descended into.\n *\n * `node_modules` is skipped during the walk and reached only through the explicit `@wildo-ai/*`\n * roots below: descending into it from an application package would sweep the app's entire\n * dependency graph (hundreds of thousands of files) to learn nothing the resolved engine roots do\n * not already say.\n */\nconst SKIPPED_DIRECTORY_NAMES = new Set(['node_modules', '.git']);\n\n/**\n * A ceiling on how much this observer will walk before it gives up on caching.\n *\n * Chosen ~10x above the measured 26k-entry dogfood application, so it can only be reached by a\n * pathological root (a `dist` holding a build cache, an application that vendored something large).\n * Crossing it does not disable the walk half-way and report a plausible number — it returns\n * `bounded: false`, which the caller MUST read as \"do not cache this derivation\". Failing toward\n * re-deriving is the only safe direction here: an under-observed token is a cache key that stops\n * moving when the source does.\n */\nconst MAXIMUM_OBSERVED_ENTRIES = 250_000;\n\n/**\n * What a completed sweep learned about the source that feeds an introspection derivation.\n */\nexport interface IntrospectionSourceStateObservation {\n /**\n * The comparable value. Two observations with the same token describe the same source tree; a\n * different token means SOMETHING moved and every cached derivation is void.\n */\n token: string;\n /**\n * `false` when the sweep hit {@link MAXIMUM_OBSERVED_ENTRIES}. The token is then deliberately\n * unique per observation, so a caller that ignores this flag still re-derives rather than serving\n * a stale answer.\n */\n bounded: boolean;\n /** Wall-clock cost of the sweep, for the debug line that explains a cache hit's latency. */\n durationMs: number;\n /** Number of roots actually walked (a root that does not exist yet is not one). */\n observedRootCount: number;\n /** Files plus directories visited. Reported so an operator can see why a sweep is slow. */\n observedEntryCount: number;\n /** The instant the sweep STARTED, which is the instant the token describes. */\n startedAt: number;\n}\n\ninterface SweepAccumulator {\n fileCount: number;\n directoryCount: number;\n maximumMtimeMs: number;\n exceededCeiling: boolean;\n}\n\n/**\n * Observes the state of every source tree an introspection derivation can read, as one comparable\n * token.\n *\n * ## Why a token rather than a watcher\n *\n * The companion has no file watcher and adding one would mean a new always-on dependency, a new\n * always-on process cost, and a new class of missed-event bug on the platforms this repository does\n * not test on. A sweep answers the same question on demand, costs ~125 ms against the largest\n * dogfood application, and cannot miss an event because it does not observe events at all — it\n * observes the tree.\n *\n * ## Why mtimes rather than content\n *\n * `.claude/rules/application-creation-directive.md` forbids digests, of any kind, for any purpose,\n * and `.claude/rules/one-source-of-truth.md` Rule 0 refuses anything that is not branchable on git.\n * A content hash compared against a stored one is exactly the second-source-of-truth shape both\n * rules exist to keep out. An mtime observation stores nothing about the application: it is a\n * reading taken now, compared against a reading taken earlier in the same process, and deleting it\n * costs a re-derivation and nothing else.\n *\n * ## What the token is made of, and what each part catches\n *\n * | Component | Catches |\n * |---|---|\n * | maximum file/directory mtime | a file written in place (the ordinary edit, and every `tsc` emit) |\n * | file count | a file added or deleted |\n * | directory count | a directory added or deleted |\n * | directory mtimes, in the maximum | a RENAME, which preserves the file's own mtime and would otherwise be invisible while the file count stayed equal |\n *\n * Directory mtimes are the non-obvious member and they are load-bearing: without them,\n * `mv a.ts b.ts` moves neither the count nor any file mtime, and the cache would keep answering\n * from the pre-rename derivation for as long as nothing else in the tree moved.\n *\n * The one mutation this cannot see is an mtime pushed BACKWARD in place on a file that is not the\n * newest in the tree (`touch -t 200001010000 <file>` on an already-old file). Nothing in a dev loop\n * does that; a real editor, `tsc`, `git checkout` and pnpm's hard-link relink all move an mtime\n * forward or move a directory. Recorded rather than papered over, because a reader who assumes the\n * token is total would be assuming something false.\n *\n * ## Which trees, and why the engine ones are in there\n *\n * An application resolving `@wildo-ai/*` through `file:` links — every dogfood app does — changes\n * its derivation when the engine is rebuilt, with no application file touched. The engine bytes the\n * child actually imports are the ones pnpm hard-linked into the app's store, NOT the ones in\n * `engine/<package>/dist`, and the two are reconciled at supervised (re)start rather than continuously. So\n * the framework signal has to be the injected snapshot itself. `.wildo-runtime-signals/dev-compile-status.json`\n * was considered and rejected for exactly this: it is a LEADING indicator, moving when the engine\n * compiles and therefore possibly before the bytes this process would import have changed — which\n * would let a derivation be cached against a token that has already advanced past it, and never\n * re-derived when the injection finally lands.\n *\n * For an application consuming published `@wildo-ai/*` tarballs the same roots are simply immutable\n * between installs, so the sweep costs a little and proves the same thing.\n *\n * ## What it costs, and one narrowing that was measured and REJECTED\n *\n * 176–225 ms against `examples/wonder-crm` (23 roots, 27,050 entries), versus a 3.1–4.2 s cold\n * import of that application's specifications package alone. So a cache hit is ~15x cheaper than\n * the cheapest possible miss.\n *\n * Skipping `*.d.ts` and `*.map` would roughly halve it — they are **55 %** of the swept files\n * (8,830 maps + 4,417 declarations of 24,243) and neither can change a runtime derivation. It was\n * rejected anyway: the saving is ~90 ms nobody can perceive, and it would buy that with an\n * assumption about what a future behavior may read. No behavior under `introspection/subprocess/`\n * imports `node:fs` at all today — every one of them is a pure function of the imported module\n * graph — but that is a fact about today, and the direction to be wrong in here is toward\n * re-deriving. Recorded so the next reader does not re-derive the numbers before reaching the same\n * conclusion.\n */\nexport class IntrospectionSourceStateObserver {\n private readonly companionContext: Pick<CompanionContext, 'saasRoot' | 'companionHome' | 'servicesByKey' | 'resolvedLibraries' | 'resolvedSpecifications'>;\n private observationSequence = 0;\n private inFlight: { startedAt: number; observation: Promise<IntrospectionSourceStateObservation> } | null = null;\n\n constructor(\n companionContext: Pick<CompanionContext, 'saasRoot' | 'companionHome' | 'servicesByKey' | 'resolvedLibraries' | 'resolvedSpecifications'>,\n ) {\n this.companionContext = companionContext;\n }\n\n /**\n * Take a reading of the source trees, reusing an in-flight one ONLY when that reading started at\n * or after the caller's own arrival.\n *\n * The condition is the whole point of the coalescing. A sweep takes ~125 ms; a request arriving\n * 100 ms into someone else's sweep and adopting its token would be answered from a picture of the\n * world taken 100 ms before it asked — a window in which the operator could have saved a file. So\n * a late arrival waits for the running sweep to finish and takes a fresh one, which is slower and\n * correct, while genuinely concurrent callers share one walk, which is what the coalescing is for.\n */\n public async observe(requestedAt: number = Date.now()): Promise<IntrospectionSourceStateObservation> {\n const current = this.inFlight;\n if (current !== null && current.startedAt >= requestedAt) {\n return current.observation;\n }\n\n if (current !== null) {\n // Let the running sweep finish before starting another; two concurrent walks of the same\n // trees would only contend for the same file descriptors.\n await current.observation.catch(() => undefined);\n return this.observe(requestedAt);\n }\n\n const startedAt = Date.now();\n const observation = this.runObservation(startedAt).finally(() => {\n if (this.inFlight?.startedAt === startedAt) {\n this.inFlight = null;\n }\n });\n this.inFlight = { startedAt, observation };\n return observation;\n }\n\n private async runObservation(startedAt: number): Promise<IntrospectionSourceStateObservation> {\n const roots = await this.resolveObservedRoots();\n const accumulator: SweepAccumulator = {\n fileCount: 0,\n directoryCount: 0,\n maximumMtimeMs: 0,\n exceededCeiling: false,\n };\n\n await this.observeApplicationRootManifests(accumulator);\n await this.walk(roots, accumulator);\n\n this.observationSequence += 1;\n const bounded = !accumulator.exceededCeiling;\n const token = bounded\n ? `roots:${roots.length}|files:${accumulator.fileCount}|dirs:${accumulator.directoryCount}|mtime:${accumulator.maximumMtimeMs}`\n : `unbounded:${this.observationSequence}`;\n\n return {\n token,\n bounded,\n durationMs: Date.now() - startedAt,\n observedRootCount: roots.length,\n observedEntryCount: accumulator.fileCount + accumulator.directoryCount,\n startedAt,\n };\n }\n\n /**\n * The two ROOT populations a derivation reads from, kept apart because a watcher treats them\n * differently.\n *\n * An APPLICATION root is a package the operator edits: its `src` moves first and its `dist` moves\n * second, and only the second changes what a derivation imports —\n * `resolvePackageCompanionEntryPath` resolves the package's `exports['./companion']`, which is\n * `./dist/esm/companion-exports.js` on every application package. A FRAMEWORK root is the injected\n * `@wildo-ai/*` copy in the application's own store: dist-only bytes, hard-linked at supervised\n * (re)start, carrying no runtime-signal files of its own.\n *\n * Exposed so the watcher and the sweep observe one population rather than two enumerations that\n * agree only until one side gains an entry.\n */\n public async resolveObservedRootPopulations(): Promise<{\n readonly applicationRoots: readonly string[];\n readonly frameworkRoots: readonly string[];\n }> {\n const applicationRoots = new Set<string>();\n for (const serviceDefinition of Object.values(this.companionContext.servicesByKey)) {\n applicationRoots.add(resolve(this.companionContext.saasRoot, serviceDefinition.path));\n }\n for (const resolvedLibrary of Object.values(this.companionContext.resolvedLibraries)) {\n applicationRoots.add(resolvedLibrary.packageRoot);\n }\n if (this.companionContext.resolvedSpecifications) {\n applicationRoots.add(this.companionContext.resolvedSpecifications.packageRoot);\n }\n\n const frameworkScopeOwners = [\n ...applicationRoots,\n this.companionContext.saasRoot,\n this.companionContext.companionHome,\n ];\n const frameworkRoots = new Set<string>();\n for (const owner of frameworkScopeOwners) {\n const scopeDirectory = join(owner, 'node_modules', '@wildo-ai');\n let scopeEntries: string[];\n try {\n scopeEntries = await fsPromises.readdir(scopeDirectory);\n } catch {\n continue;\n }\n for (const scopeEntry of scopeEntries) {\n try {\n frameworkRoots.add(await fsPromises.realpath(join(scopeDirectory, scopeEntry)));\n } catch {\n // A dangling link contributes nothing to observe; its disappearance shows up as a\n // directory-mtime change on the scope directory's owner instead.\n }\n }\n }\n\n return { applicationRoots: [...applicationRoots], frameworkRoots: [...frameworkRoots] };\n }\n\n /**\n * Every tree whose bytes can reach a derivation, de-duplicated by resolved real path.\n *\n * Two families, and the second is the one a reader would not think of:\n *\n * 1. The APPLICATION package roots — every declared service, every resolved library, and the\n * specifications package. Whole roots rather than `src/` alone, because\n * `resolvePackageCompanionEntryPath` prefers a package's built `./companion` export when it\n * exists, so the child commonly imports `dist/`, not source. Sweeping both means neither\n * resolution mode has a blind spot.\n * 2. The FRAMEWORK packages, reached by reading each of those roots' (and the companion home's)\n * `node_modules/@wildo-ai` scope directory and resolving each link to its real path. Reading\n * the scope directory rather than listing package names keeps this from becoming a second\n * enumeration of the engine's package set that could drift from the real one.\n *\n * The application root itself is NOT walked recursively — its interesting children are already in\n * family 1, and descending it would pull in `.wildo-saas` (the companion's own dist plus the\n * runtime-signal files that churn on a heartbeat, which would make every token unique and every\n * cache read a miss).\n */\n private async resolveObservedRoots(): Promise<string[]> {\n const { applicationRoots, frameworkRoots } = await this.resolveObservedRootPopulations();\n return [...new Set([...applicationRoots, ...frameworkRoots])];\n }\n\n /**\n * Fold the application root's own top-level FILES in, without descending it.\n *\n * These are `pnpm-lock.yaml`, `package.json` and `wildo.saas.config.ts` — the manifests that\n * decide which third-party bytes the child imports. Without them there is a narrow but real hole:\n * an install that moves a non-`@wildo-ai` dependency changes a derivation while touching nothing\n * inside a package root, because the walk enters `node_modules` only through the resolved\n * `@wildo-ai` scope. The lockfile moves on every such install, so one shallow read closes it.\n *\n * The root is NOT descended, because doing so would pull in `.wildo-saas` — the companion's own\n * dist and the runtime-signal files that are rewritten on a heartbeat, which would make every\n * token unique and every cache read a miss.\n */\n private async observeApplicationRootManifests(accumulator: SweepAccumulator): Promise<void> {\n let entries;\n try {\n entries = await fsPromises.readdir(this.companionContext.saasRoot, { withFileTypes: true });\n } catch {\n return;\n }\n\n await Promise.all(entries.map(async (entry) => {\n if (!entry.isFile()) return;\n accumulator.fileCount += 1;\n try {\n const entryStats = await fsPromises.stat(join(this.companionContext.saasRoot, entry.name));\n if (entryStats.mtimeMs > accumulator.maximumMtimeMs) {\n accumulator.maximumMtimeMs = entryStats.mtimeMs;\n }\n } catch {\n // Counted above; a file that vanished between readdir and stat is itself a change, and the\n // count will differ on the next observation.\n }\n }));\n }\n\n /**\n * Breadth-of-tree walk with a fixed directory concurrency.\n *\n * A worker-pool built over the ROOT list was written first and was wrong: it sizes its pool from\n * the number of roots, so a single-root application would walk its whole tree one directory at a\n * time, and a worker that finds the queue momentarily empty cannot tell \"finished\" from \"another\n * worker is about to push children\". The pump below sizes on IN-FLIGHT directories instead, which\n * is the quantity the concurrency limit is actually about, and terminates on the only condition\n * that means finished: nothing queued and nothing running.\n */\n private async walk(roots: readonly string[], accumulator: SweepAccumulator): Promise<void> {\n const pending: string[] = [...roots];\n let inFlightDirectories = 0;\n\n return new Promise<void>((resolveWalk) => {\n const pump = (): void => {\n while (\n !accumulator.exceededCeiling\n && inFlightDirectories < DIRECTORY_WALK_CONCURRENCY\n && pending.length > 0\n ) {\n const directory = pending.pop() as string;\n inFlightDirectories += 1;\n void this.visitDirectory(directory, accumulator, pending).then(() => {\n inFlightDirectories -= 1;\n pump();\n });\n }\n\n if (inFlightDirectories === 0 && (pending.length === 0 || accumulator.exceededCeiling)) {\n resolveWalk();\n }\n };\n\n pump();\n });\n }\n\n /**\n * Read one directory: count it, fold its own mtime in, stat its files, and queue its children.\n *\n * Never rejects. A directory that cannot be read (an unbuilt `dist`, a permission) contributes\n * nothing and is not an error — when it appears later it is a new directory, which moves the\n * counts and invalidates every cached derivation.\n */\n private async visitDirectory(\n directory: string,\n accumulator: SweepAccumulator,\n pending: string[],\n ): Promise<void> {\n let entries;\n try {\n entries = await fsPromises.readdir(directory, { withFileTypes: true });\n } catch {\n return;\n }\n\n accumulator.directoryCount += 1;\n try {\n const directoryStats = await fsPromises.stat(directory);\n if (directoryStats.mtimeMs > accumulator.maximumMtimeMs) {\n accumulator.maximumMtimeMs = directoryStats.mtimeMs;\n }\n } catch {\n // Counted above regardless: the directory demonstrably exists, we just read it.\n }\n\n const fileStats: Promise<void>[] = [];\n for (const entry of entries) {\n if (SKIPPED_DIRECTORY_NAMES.has(entry.name)) continue;\n const entryPath = join(directory, entry.name);\n if (entry.isDirectory()) {\n pending.push(entryPath);\n continue;\n }\n if (!entry.isFile()) {\n // A symlink is counted but never followed — following one inside a package tree can walk\n // back out into a dependency graph. Retargeting one rewrites its directory entry, which\n // moves the parent directory's mtime, so the change is still observed.\n accumulator.fileCount += 1;\n continue;\n }\n fileStats.push(\n fsPromises.stat(entryPath).then(\n (entryStats) => {\n accumulator.fileCount += 1;\n if (entryStats.mtimeMs > accumulator.maximumMtimeMs) {\n accumulator.maximumMtimeMs = entryStats.mtimeMs;\n }\n },\n () => {\n accumulator.fileCount += 1;\n },\n ),\n );\n }\n await Promise.all(fileStats);\n\n if (accumulator.fileCount + accumulator.directoryCount > MAXIMUM_OBSERVED_ENTRIES) {\n accumulator.exceededCeiling = true;\n }\n }\n}\n"]}
@@ -0,0 +1,101 @@
1
+ import type { LoggerService } from '@wildo-ai/saas-backend-lib';
2
+ import type { CompanionContext } from '../../context/companion-context';
3
+ import { IntrospectionRecompileReason, type IntrospectionDerivationStateCompanionService, type IntrospectionRecompileOutcome } from './introspection-derivation-state.companion.service';
4
+ /** A consumer notified after every recompilation that actually changed something. */
5
+ export type IntrospectionRecompileListener = (outcomes: readonly IntrospectionRecompileOutcome[], reason: IntrospectionRecompileReason) => void;
6
+ /**
7
+ * Watches the bytes an introspection derivation actually imports, and drives recompilation from
8
+ * them rather than from somebody asking for a read.
9
+ *
10
+ * ## Why this watches `dist`, and never `src`
11
+ *
12
+ * The introspection child imports a package's built `./companion` export:
13
+ * `resolvePackageCompanionEntryPath` is called with no options, so it resolves the package's
14
+ * `exports['./companion']`, which is `./dist/esm/companion-exports.js` on every application package.
15
+ * A derivation therefore cannot change until the emit lands.
16
+ *
17
+ * Watching `src` would fire on the operator's keystroke — BEFORE the input to the derivation exists.
18
+ * Under eager recompilation that means importing the previous `dist`, computing a diff against it,
19
+ * and publishing a change that describes a state the application was never in. The accepted-
20
+ * generation manifests and the emitted trees are TRAILING signals: they move after the bytes are
21
+ * final, which is the only moment at which recompiling answers the right question.
22
+ *
23
+ * ## Why the framework dimension is watched separately
24
+ *
25
+ * An application resolves `@wildo-ai/*` through `file:` links, and those bytes are hard-linked into
26
+ * the application's own pnpm store. That copy carries no `.wildo-runtime-signals` of its own
27
+ * (verified), so it has no completion signal to subscribe to and the injected bytes themselves are
28
+ * the only coincident evidence. This is also why the framework's own
29
+ * `.wildo-runtime-signals/dev-compile-status.json` is NOT used: it advances when the framework
30
+ * compiles, which is BEFORE the reconciliation that copies those bytes into the application — a
31
+ * leading indicator, and acting on it would cache a derivation against a token it has already
32
+ * passed.
33
+ *
34
+ * ## Why `node:fs` rather than chokidar
35
+ *
36
+ * `fs.watch({ recursive: true })` is supported on every platform this repository's Node baseline
37
+ * runs, and it is what chokidar itself sits on. Taking the dependency would put a package into the
38
+ * companion's RUNTIME closure, and the companion is delivered as a dist artifact into every
39
+ * generated application — so a convenience here becomes an install obligation for every application
40
+ * built with Wildo. The event coalescing chokidar is usually wanted for is
41
+ * {@link EVENT_SETTLE_MS} below, which is nine lines.
42
+ *
43
+ * ## What a missed event costs
44
+ *
45
+ * Nothing permanent, by construction. `fs.watch` is best-effort on every platform, so the watcher is
46
+ * never the only mechanism: {@link RECONCILIATION_INTERVAL_MS} re-observes on a timer, and the state
47
+ * service compares a source token before recompiling anything. A missed event delays a
48
+ * recompilation; it cannot make one wrong.
49
+ */
50
+ export declare class IntrospectionSourceWatcherCompanionService {
51
+ private readonly logger;
52
+ private readonly companionContext;
53
+ private readonly derivationState;
54
+ private readonly logDebug;
55
+ private readonly observer;
56
+ private readonly watchers;
57
+ private readonly listeners;
58
+ private settleTimer;
59
+ private reconcileTimer;
60
+ /** Guards against a reconciliation and a settle firing into the same recompilation. */
61
+ private recompiling;
62
+ private started;
63
+ constructor(logger: LoggerService, companionContext: CompanionContext, derivationState: IntrospectionDerivationStateCompanionService);
64
+ /** Register a consumer of recompilation outcomes — the seam the WebSocket notifier plugs into. */
65
+ onRecompiled(listener: IntrospectionRecompileListener): () => void;
66
+ /**
67
+ * Begin watching, and promote the derivation state out of per-read observation.
68
+ *
69
+ * Promotion happens only once at least one watch target was successfully established. A companion
70
+ * whose every target failed stays in `OBSERVE_PER_READ`, which is slower and correct, rather than
71
+ * claiming a freshness it does not have.
72
+ */
73
+ start(): Promise<void>;
74
+ /** Stop watching and hand freshness back to per-read observation. */
75
+ stop(): void;
76
+ /**
77
+ * The directories whose contents can change a derivation's answer.
78
+ *
79
+ * Application roots contribute their EMITTED surfaces only — `dist`, because that is what the
80
+ * child imports, and `.wildo-runtime-signals`, because that is where the accepted-generation
81
+ * manifest lands when an emit is finalized. The root itself is deliberately not watched
82
+ * recursively: it contains `src`, whose events lead the derivation (see the class docstring), and
83
+ * `.wildo-saas`, whose runtime-signal files churn on a heartbeat and would keep the settle window
84
+ * permanently open.
85
+ *
86
+ * Framework roots are watched whole, because the injected copy is dist-only already.
87
+ */
88
+ private resolveWatchTargets;
89
+ /** Restart the settle window. Called on every filesystem event, so it must stay trivial. */
90
+ private noteFilesystemEvent;
91
+ /**
92
+ * Recompile, at most one at a time.
93
+ *
94
+ * Serialized rather than queued: a second trigger arriving while a recompilation runs describes a
95
+ * tree the running recompilation may already have observed, and if it does not, the reconciliation
96
+ * sweep will see it. Queueing would let a burst of emits stack N full application imports behind
97
+ * each other, which is the cost this whole change exists to remove.
98
+ */
99
+ private recompile;
100
+ }
101
+ //# sourceMappingURL=introspection-source-watcher.companion.service.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"introspection-source-watcher.companion.service.d.ts","sourceRoot":"","sources":["../../../../../../src/core/introspection/services/introspection-source-watcher.companion.service.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAIhE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAExE,OAAO,EACL,4BAA4B,EAC5B,KAAK,4CAA4C,EACjD,KAAK,6BAA6B,EACnC,MAAM,oDAAoD,CAAC;AA6B5D,qFAAqF;AACrF,MAAM,MAAM,8BAA8B,GAAG,CAC3C,QAAQ,EAAE,SAAS,6BAA6B,EAAE,EAClD,MAAM,EAAE,4BAA4B,KACjC,IAAI,CAAC;AAEV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBACa,0CAA0C;IAYhB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACR,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAEnF,OAAO,CAAC,QAAQ,CAAC,eAAe;IAdlC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+D;IACxF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6C;IACvE,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,cAAc,CAA6B;IACnD,uFAAuF;IACvF,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,OAAO,CAAS;gBAG8B,MAAM,EAAE,aAAa,EACN,gBAAgB,EAAE,gBAAgB,EAEpF,eAAe,EAAE,4CAA4C;IAOhF,kGAAkG;IAC3F,YAAY,CAAC,QAAQ,EAAE,8BAA8B,GAAG,MAAM,IAAI;IAKzE;;;;;;OAMG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgDnC,qEAAqE;IAC9D,IAAI,IAAI,IAAI;IAkBnB;;;;;;;;;;;OAWG;YACW,mBAAmB;IAajC,4FAA4F;IAC5F,OAAO,CAAC,mBAAmB;IAS3B;;;;;;;OAOG;YACW,SAAS;CAsCxB"}
@@ -0,0 +1,278 @@
1
+ var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
2
+ var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
3
+ if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
4
+ else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
5
+ return c > 3 && r && Object.defineProperty(target, key, r), r;
6
+ };
7
+ var __metadata = (this && this.__metadata) || function (k, v) {
8
+ if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
9
+ };
10
+ var __param = (this && this.__param) || function (paramIndex, decorator) {
11
+ return function (target, key) { decorator(target, key, paramIndex); }
12
+ };
13
+ import { watch } from 'node:fs';
14
+ import { join } from 'node:path';
15
+ import { inject, injectable } from 'inversify';
16
+ import { SAAS_SERVICE_TYPES } from '@wildo-ai/saas-backend-lib';
17
+ import { COMPANION_SERVICE_TYPES } from '../../inject/models/service-types.js';
18
+ import { IntrospectionSourceStateObserver } from './introspection-source-state.companion.service.js';
19
+ import { IntrospectionRecompileReason, } from './introspection-derivation-state.companion.service.js';
20
+ /**
21
+ * How long a burst of filesystem events is allowed to settle before a recompilation starts.
22
+ *
23
+ * A `tsc` emit is not one event, it is hundreds — one per emitted file, arriving over the tens of
24
+ * milliseconds the write takes. Recompiling on the first would import a half-written `dist`. The
25
+ * window is measured from the LAST event rather than the first, so a long emit extends it rather
26
+ * than racing it.
27
+ *
28
+ * 300 ms is chosen against the thing being waited for, not by taste: it is comfortably longer than
29
+ * the gap between two files of one emit and far shorter than the 8.9 s a cold derivation costs, so
30
+ * the wait is invisible next to the work it protects.
31
+ */
32
+ const EVENT_SETTLE_MS = 300;
33
+ /**
34
+ * How often the reconciliation sweep runs when the watcher believes nothing has happened.
35
+ *
36
+ * This is the backstop for a missed event, and its period is a direct trade: it is the longest a
37
+ * missed mutation can go unnoticed. The sweep costs 180–225 ms of filesystem work on a dogfood
38
+ * application, so at 30 s it is a 0.7 % duty cycle — cheap enough to leave on permanently, which is
39
+ * the only kind of backstop that is actually running when it is needed.
40
+ */
41
+ const RECONCILIATION_INTERVAL_MS = 30_000;
42
+ /** The name this authority registers under, so a log line says which mechanism owns freshness. */
43
+ const FRESHNESS_AUTHORITY_NAME = 'introspection-source-watcher';
44
+ /**
45
+ * Watches the bytes an introspection derivation actually imports, and drives recompilation from
46
+ * them rather than from somebody asking for a read.
47
+ *
48
+ * ## Why this watches `dist`, and never `src`
49
+ *
50
+ * The introspection child imports a package's built `./companion` export:
51
+ * `resolvePackageCompanionEntryPath` is called with no options, so it resolves the package's
52
+ * `exports['./companion']`, which is `./dist/esm/companion-exports.js` on every application package.
53
+ * A derivation therefore cannot change until the emit lands.
54
+ *
55
+ * Watching `src` would fire on the operator's keystroke — BEFORE the input to the derivation exists.
56
+ * Under eager recompilation that means importing the previous `dist`, computing a diff against it,
57
+ * and publishing a change that describes a state the application was never in. The accepted-
58
+ * generation manifests and the emitted trees are TRAILING signals: they move after the bytes are
59
+ * final, which is the only moment at which recompiling answers the right question.
60
+ *
61
+ * ## Why the framework dimension is watched separately
62
+ *
63
+ * An application resolves `@wildo-ai/*` through `file:` links, and those bytes are hard-linked into
64
+ * the application's own pnpm store. That copy carries no `.wildo-runtime-signals` of its own
65
+ * (verified), so it has no completion signal to subscribe to and the injected bytes themselves are
66
+ * the only coincident evidence. This is also why the framework's own
67
+ * `.wildo-runtime-signals/dev-compile-status.json` is NOT used: it advances when the framework
68
+ * compiles, which is BEFORE the reconciliation that copies those bytes into the application — a
69
+ * leading indicator, and acting on it would cache a derivation against a token it has already
70
+ * passed.
71
+ *
72
+ * ## Why `node:fs` rather than chokidar
73
+ *
74
+ * `fs.watch({ recursive: true })` is supported on every platform this repository's Node baseline
75
+ * runs, and it is what chokidar itself sits on. Taking the dependency would put a package into the
76
+ * companion's RUNTIME closure, and the companion is delivered as a dist artifact into every
77
+ * generated application — so a convenience here becomes an install obligation for every application
78
+ * built with Wildo. The event coalescing chokidar is usually wanted for is
79
+ * {@link EVENT_SETTLE_MS} below, which is nine lines.
80
+ *
81
+ * ## What a missed event costs
82
+ *
83
+ * Nothing permanent, by construction. `fs.watch` is best-effort on every platform, so the watcher is
84
+ * never the only mechanism: {@link RECONCILIATION_INTERVAL_MS} re-observes on a timer, and the state
85
+ * service compares a source token before recompiling anything. A missed event delays a
86
+ * recompilation; it cannot make one wrong.
87
+ */
88
+ let IntrospectionSourceWatcherCompanionService = class IntrospectionSourceWatcherCompanionService {
89
+ logger;
90
+ companionContext;
91
+ derivationState;
92
+ logDebug;
93
+ observer;
94
+ watchers = [];
95
+ listeners = new Set();
96
+ settleTimer;
97
+ reconcileTimer;
98
+ /** Guards against a reconciliation and a settle firing into the same recompilation. */
99
+ recompiling;
100
+ started = false;
101
+ constructor(logger, companionContext, derivationState) {
102
+ this.logger = logger;
103
+ this.companionContext = companionContext;
104
+ this.derivationState = derivationState;
105
+ this.logDebug = this.logger.debugByType('IntrospectionSourceWatcher');
106
+ this.logger.setDebugTypeLogging('IntrospectionSourceWatcher', true);
107
+ this.observer = new IntrospectionSourceStateObserver(this.companionContext);
108
+ }
109
+ /** Register a consumer of recompilation outcomes — the seam the WebSocket notifier plugs into. */
110
+ onRecompiled(listener) {
111
+ this.listeners.add(listener);
112
+ return () => this.listeners.delete(listener);
113
+ }
114
+ /**
115
+ * Begin watching, and promote the derivation state out of per-read observation.
116
+ *
117
+ * Promotion happens only once at least one watch target was successfully established. A companion
118
+ * whose every target failed stays in `OBSERVE_PER_READ`, which is slower and correct, rather than
119
+ * claiming a freshness it does not have.
120
+ */
121
+ async start() {
122
+ if (this.started)
123
+ return;
124
+ this.started = true;
125
+ const targets = await this.resolveWatchTargets();
126
+ for (const target of targets) {
127
+ try {
128
+ const watcher = watch(target, { recursive: true, persistent: false }, () => this.noteFilesystemEvent());
129
+ watcher.on('error', (error) => {
130
+ this.logger.warn('Introspection source watcher target failed', {
131
+ target,
132
+ error: error instanceof Error ? error.message : String(error),
133
+ });
134
+ });
135
+ this.watchers.push(watcher);
136
+ }
137
+ catch (error) {
138
+ // A target that does not exist yet is normal — an application package whose `dist` has never
139
+ // been built has no directory to watch. It is picked up by the reconciliation sweep, and by
140
+ // the next start after it exists.
141
+ this.logDebug('Introspection source watch target not established', {
142
+ target,
143
+ error: error instanceof Error ? error.message : String(error),
144
+ });
145
+ }
146
+ }
147
+ if (this.watchers.length === 0) {
148
+ this.logger.warn('Introspection source watcher established no targets; derivation freshness stays on per-read observation', { attemptedTargetCount: targets.length });
149
+ return;
150
+ }
151
+ this.reconcileTimer = setInterval(() => {
152
+ void this.recompile(IntrospectionRecompileReason.RECONCILIATION);
153
+ }, RECONCILIATION_INTERVAL_MS);
154
+ this.reconcileTimer.unref?.();
155
+ this.derivationState.registerFreshnessAuthority(FRESHNESS_AUTHORITY_NAME);
156
+ this.logger.info('Introspection source watcher started', {
157
+ watchTargetCount: this.watchers.length,
158
+ attemptedTargetCount: targets.length,
159
+ settleMs: EVENT_SETTLE_MS,
160
+ reconciliationIntervalMs: RECONCILIATION_INTERVAL_MS,
161
+ });
162
+ }
163
+ /** Stop watching and hand freshness back to per-read observation. */
164
+ stop() {
165
+ if (!this.started)
166
+ return;
167
+ this.started = false;
168
+ if (this.settleTimer)
169
+ clearTimeout(this.settleTimer);
170
+ if (this.reconcileTimer)
171
+ clearInterval(this.reconcileTimer);
172
+ this.settleTimer = undefined;
173
+ this.reconcileTimer = undefined;
174
+ for (const watcher of this.watchers) {
175
+ try {
176
+ watcher.close();
177
+ }
178
+ catch {
179
+ // Closing an already-failed watcher is not a condition anybody can act on.
180
+ }
181
+ }
182
+ this.watchers.length = 0;
183
+ this.derivationState.noteFreshnessAuthorityLost('watcher stopped');
184
+ }
185
+ /**
186
+ * The directories whose contents can change a derivation's answer.
187
+ *
188
+ * Application roots contribute their EMITTED surfaces only — `dist`, because that is what the
189
+ * child imports, and `.wildo-runtime-signals`, because that is where the accepted-generation
190
+ * manifest lands when an emit is finalized. The root itself is deliberately not watched
191
+ * recursively: it contains `src`, whose events lead the derivation (see the class docstring), and
192
+ * `.wildo-saas`, whose runtime-signal files churn on a heartbeat and would keep the settle window
193
+ * permanently open.
194
+ *
195
+ * Framework roots are watched whole, because the injected copy is dist-only already.
196
+ */
197
+ async resolveWatchTargets() {
198
+ const { applicationRoots, frameworkRoots } = await this.observer.resolveObservedRootPopulations();
199
+ const targets = new Set();
200
+ for (const applicationRoot of applicationRoots) {
201
+ targets.add(join(applicationRoot, 'dist'));
202
+ targets.add(join(applicationRoot, '.wildo-runtime-signals'));
203
+ }
204
+ for (const frameworkRoot of frameworkRoots) {
205
+ targets.add(frameworkRoot);
206
+ }
207
+ return [...targets];
208
+ }
209
+ /** Restart the settle window. Called on every filesystem event, so it must stay trivial. */
210
+ noteFilesystemEvent() {
211
+ if (this.settleTimer)
212
+ clearTimeout(this.settleTimer);
213
+ this.settleTimer = setTimeout(() => {
214
+ this.settleTimer = undefined;
215
+ void this.recompile(IntrospectionRecompileReason.SOURCE_MUTATION);
216
+ }, EVENT_SETTLE_MS);
217
+ this.settleTimer.unref?.();
218
+ }
219
+ /**
220
+ * Recompile, at most one at a time.
221
+ *
222
+ * Serialized rather than queued: a second trigger arriving while a recompilation runs describes a
223
+ * tree the running recompilation may already have observed, and if it does not, the reconciliation
224
+ * sweep will see it. Queueing would let a burst of emits stack N full application imports behind
225
+ * each other, which is the cost this whole change exists to remove.
226
+ */
227
+ async recompile(reason) {
228
+ if (this.recompiling)
229
+ return this.recompiling;
230
+ this.recompiling = (async () => {
231
+ try {
232
+ const { moved, outcomes } = await this.derivationState.recompileIfSourceMoved(reason);
233
+ if (!moved)
234
+ return;
235
+ const changed = outcomes.filter((outcome) => outcome.changed);
236
+ this.logDebug('Introspection recompilation completed', {
237
+ reason,
238
+ derivationCount: outcomes.length,
239
+ changedCount: changed.length,
240
+ });
241
+ if (changed.length === 0)
242
+ return;
243
+ for (const listener of this.listeners) {
244
+ try {
245
+ listener(changed, reason);
246
+ }
247
+ catch (error) {
248
+ // A listener is a notifier. Its failure must not stop the recompilation that produced
249
+ // the state, nor the next listener from hearing about it.
250
+ this.logger.warn('Introspection recompile listener failed', {
251
+ reason,
252
+ error: error instanceof Error ? error.message : String(error),
253
+ });
254
+ }
255
+ }
256
+ }
257
+ catch (error) {
258
+ this.logger.warn('Introspection recompilation failed', {
259
+ reason,
260
+ error: error instanceof Error ? error.message : String(error),
261
+ });
262
+ }
263
+ finally {
264
+ this.recompiling = undefined;
265
+ }
266
+ })();
267
+ return this.recompiling;
268
+ }
269
+ };
270
+ IntrospectionSourceWatcherCompanionService = __decorate([
271
+ injectable(),
272
+ __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
273
+ __param(1, inject(COMPANION_SERVICE_TYPES.CompanionContext)),
274
+ __param(2, inject(COMPANION_SERVICE_TYPES.IntrospectionDerivationStateService)),
275
+ __metadata("design:paramtypes", [Function, Object, Function])
276
+ ], IntrospectionSourceWatcherCompanionService);
277
+ export { IntrospectionSourceWatcherCompanionService };
278
+ //# sourceMappingURL=introspection-source-watcher.companion.service.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"introspection-source-watcher.companion.service.js","sourceRoot":"","sources":["../../../../../../src/core/introspection/services/introspection-source-watcher.companion.service.ts"],"names":[],"mappings":"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","sourcesContent":["import { watch, type FSWatcher } from 'node:fs';\nimport { join } from 'node:path';\nimport { inject, injectable } from 'inversify';\nimport type { LoggerService } from '@wildo-ai/saas-backend-lib';\nimport { SAAS_SERVICE_TYPES } from '@wildo-ai/saas-backend-lib';\n\nimport { COMPANION_SERVICE_TYPES } from '../../inject/models/service-types';\nimport type { CompanionContext } from '../../context/companion-context';\nimport { IntrospectionSourceStateObserver } from './introspection-source-state.companion.service';\nimport {\n IntrospectionRecompileReason,\n type IntrospectionDerivationStateCompanionService,\n type IntrospectionRecompileOutcome,\n} from './introspection-derivation-state.companion.service';\n\n/**\n * How long a burst of filesystem events is allowed to settle before a recompilation starts.\n *\n * A `tsc` emit is not one event, it is hundreds — one per emitted file, arriving over the tens of\n * milliseconds the write takes. Recompiling on the first would import a half-written `dist`. The\n * window is measured from the LAST event rather than the first, so a long emit extends it rather\n * than racing it.\n *\n * 300 ms is chosen against the thing being waited for, not by taste: it is comfortably longer than\n * the gap between two files of one emit and far shorter than the 8.9 s a cold derivation costs, so\n * the wait is invisible next to the work it protects.\n */\nconst EVENT_SETTLE_MS = 300;\n\n/**\n * How often the reconciliation sweep runs when the watcher believes nothing has happened.\n *\n * This is the backstop for a missed event, and its period is a direct trade: it is the longest a\n * missed mutation can go unnoticed. The sweep costs 180–225 ms of filesystem work on a dogfood\n * application, so at 30 s it is a 0.7 % duty cycle — cheap enough to leave on permanently, which is\n * the only kind of backstop that is actually running when it is needed.\n */\nconst RECONCILIATION_INTERVAL_MS = 30_000;\n\n/** The name this authority registers under, so a log line says which mechanism owns freshness. */\nconst FRESHNESS_AUTHORITY_NAME = 'introspection-source-watcher';\n\n/** A consumer notified after every recompilation that actually changed something. */\nexport type IntrospectionRecompileListener = (\n outcomes: readonly IntrospectionRecompileOutcome[],\n reason: IntrospectionRecompileReason,\n) => void;\n\n/**\n * Watches the bytes an introspection derivation actually imports, and drives recompilation from\n * them rather than from somebody asking for a read.\n *\n * ## Why this watches `dist`, and never `src`\n *\n * The introspection child imports a package's built `./companion` export:\n * `resolvePackageCompanionEntryPath` is called with no options, so it resolves the package's\n * `exports['./companion']`, which is `./dist/esm/companion-exports.js` on every application package.\n * A derivation therefore cannot change until the emit lands.\n *\n * Watching `src` would fire on the operator's keystroke — BEFORE the input to the derivation exists.\n * Under eager recompilation that means importing the previous `dist`, computing a diff against it,\n * and publishing a change that describes a state the application was never in. The accepted-\n * generation manifests and the emitted trees are TRAILING signals: they move after the bytes are\n * final, which is the only moment at which recompiling answers the right question.\n *\n * ## Why the framework dimension is watched separately\n *\n * An application resolves `@wildo-ai/*` through `file:` links, and those bytes are hard-linked into\n * the application's own pnpm store. That copy carries no `.wildo-runtime-signals` of its own\n * (verified), so it has no completion signal to subscribe to and the injected bytes themselves are\n * the only coincident evidence. This is also why the framework's own\n * `.wildo-runtime-signals/dev-compile-status.json` is NOT used: it advances when the framework\n * compiles, which is BEFORE the reconciliation that copies those bytes into the application — a\n * leading indicator, and acting on it would cache a derivation against a token it has already\n * passed.\n *\n * ## Why `node:fs` rather than chokidar\n *\n * `fs.watch({ recursive: true })` is supported on every platform this repository's Node baseline\n * runs, and it is what chokidar itself sits on. Taking the dependency would put a package into the\n * companion's RUNTIME closure, and the companion is delivered as a dist artifact into every\n * generated application — so a convenience here becomes an install obligation for every application\n * built with Wildo. The event coalescing chokidar is usually wanted for is\n * {@link EVENT_SETTLE_MS} below, which is nine lines.\n *\n * ## What a missed event costs\n *\n * Nothing permanent, by construction. `fs.watch` is best-effort on every platform, so the watcher is\n * never the only mechanism: {@link RECONCILIATION_INTERVAL_MS} re-observes on a timer, and the state\n * service compares a source token before recompiling anything. A missed event delays a\n * recompilation; it cannot make one wrong.\n */\n@injectable()\nexport class IntrospectionSourceWatcherCompanionService {\n private readonly logDebug: (message: string, context?: Record<string, unknown>) => void;\n private readonly observer: IntrospectionSourceStateObserver;\n private readonly watchers: FSWatcher[] = [];\n private readonly listeners = new Set<IntrospectionRecompileListener>();\n private settleTimer: NodeJS.Timeout | undefined;\n private reconcileTimer: NodeJS.Timeout | undefined;\n /** Guards against a reconciliation and a settle firing into the same recompilation. */\n private recompiling: Promise<void> | undefined;\n private started = false;\n\n constructor(\n @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,\n @inject(COMPANION_SERVICE_TYPES.CompanionContext) private readonly companionContext: CompanionContext,\n @inject(COMPANION_SERVICE_TYPES.IntrospectionDerivationStateService)\n private readonly derivationState: IntrospectionDerivationStateCompanionService,\n ) {\n this.logDebug = this.logger.debugByType('IntrospectionSourceWatcher');\n this.logger.setDebugTypeLogging('IntrospectionSourceWatcher', true);\n this.observer = new IntrospectionSourceStateObserver(this.companionContext);\n }\n\n /** Register a consumer of recompilation outcomes — the seam the WebSocket notifier plugs into. */\n public onRecompiled(listener: IntrospectionRecompileListener): () => void {\n this.listeners.add(listener);\n return () => this.listeners.delete(listener);\n }\n\n /**\n * Begin watching, and promote the derivation state out of per-read observation.\n *\n * Promotion happens only once at least one watch target was successfully established. A companion\n * whose every target failed stays in `OBSERVE_PER_READ`, which is slower and correct, rather than\n * claiming a freshness it does not have.\n */\n public async start(): Promise<void> {\n if (this.started) return;\n this.started = true;\n\n const targets = await this.resolveWatchTargets();\n for (const target of targets) {\n try {\n const watcher = watch(target, { recursive: true, persistent: false }, () => this.noteFilesystemEvent());\n watcher.on('error', (error) => {\n this.logger.warn('Introspection source watcher target failed', {\n target,\n error: error instanceof Error ? error.message : String(error),\n });\n });\n this.watchers.push(watcher);\n } catch (error) {\n // A target that does not exist yet is normal — an application package whose `dist` has never\n // been built has no directory to watch. It is picked up by the reconciliation sweep, and by\n // the next start after it exists.\n this.logDebug('Introspection source watch target not established', {\n target,\n error: error instanceof Error ? error.message : String(error),\n });\n }\n }\n\n if (this.watchers.length === 0) {\n this.logger.warn(\n 'Introspection source watcher established no targets; derivation freshness stays on per-read observation',\n { attemptedTargetCount: targets.length },\n );\n return;\n }\n\n this.reconcileTimer = setInterval(() => {\n void this.recompile(IntrospectionRecompileReason.RECONCILIATION);\n }, RECONCILIATION_INTERVAL_MS);\n this.reconcileTimer.unref?.();\n\n this.derivationState.registerFreshnessAuthority(FRESHNESS_AUTHORITY_NAME);\n this.logger.info('Introspection source watcher started', {\n watchTargetCount: this.watchers.length,\n attemptedTargetCount: targets.length,\n settleMs: EVENT_SETTLE_MS,\n reconciliationIntervalMs: RECONCILIATION_INTERVAL_MS,\n });\n }\n\n /** Stop watching and hand freshness back to per-read observation. */\n public stop(): void {\n if (!this.started) return;\n this.started = false;\n if (this.settleTimer) clearTimeout(this.settleTimer);\n if (this.reconcileTimer) clearInterval(this.reconcileTimer);\n this.settleTimer = undefined;\n this.reconcileTimer = undefined;\n for (const watcher of this.watchers) {\n try {\n watcher.close();\n } catch {\n // Closing an already-failed watcher is not a condition anybody can act on.\n }\n }\n this.watchers.length = 0;\n this.derivationState.noteFreshnessAuthorityLost('watcher stopped');\n }\n\n /**\n * The directories whose contents can change a derivation's answer.\n *\n * Application roots contribute their EMITTED surfaces only — `dist`, because that is what the\n * child imports, and `.wildo-runtime-signals`, because that is where the accepted-generation\n * manifest lands when an emit is finalized. The root itself is deliberately not watched\n * recursively: it contains `src`, whose events lead the derivation (see the class docstring), and\n * `.wildo-saas`, whose runtime-signal files churn on a heartbeat and would keep the settle window\n * permanently open.\n *\n * Framework roots are watched whole, because the injected copy is dist-only already.\n */\n private async resolveWatchTargets(): Promise<readonly string[]> {\n const { applicationRoots, frameworkRoots } = await this.observer.resolveObservedRootPopulations();\n const targets = new Set<string>();\n for (const applicationRoot of applicationRoots) {\n targets.add(join(applicationRoot, 'dist'));\n targets.add(join(applicationRoot, '.wildo-runtime-signals'));\n }\n for (const frameworkRoot of frameworkRoots) {\n targets.add(frameworkRoot);\n }\n return [...targets];\n }\n\n /** Restart the settle window. Called on every filesystem event, so it must stay trivial. */\n private noteFilesystemEvent(): void {\n if (this.settleTimer) clearTimeout(this.settleTimer);\n this.settleTimer = setTimeout(() => {\n this.settleTimer = undefined;\n void this.recompile(IntrospectionRecompileReason.SOURCE_MUTATION);\n }, EVENT_SETTLE_MS);\n this.settleTimer.unref?.();\n }\n\n /**\n * Recompile, at most one at a time.\n *\n * Serialized rather than queued: a second trigger arriving while a recompilation runs describes a\n * tree the running recompilation may already have observed, and if it does not, the reconciliation\n * sweep will see it. Queueing would let a burst of emits stack N full application imports behind\n * each other, which is the cost this whole change exists to remove.\n */\n private async recompile(reason: IntrospectionRecompileReason): Promise<void> {\n if (this.recompiling) return this.recompiling;\n\n this.recompiling = (async () => {\n try {\n const { moved, outcomes } = await this.derivationState.recompileIfSourceMoved(reason);\n if (!moved) return;\n const changed = outcomes.filter((outcome) => outcome.changed);\n this.logDebug('Introspection recompilation completed', {\n reason,\n derivationCount: outcomes.length,\n changedCount: changed.length,\n });\n if (changed.length === 0) return;\n for (const listener of this.listeners) {\n try {\n listener(changed, reason);\n } catch (error) {\n // A listener is a notifier. Its failure must not stop the recompilation that produced\n // the state, nor the next listener from hearing about it.\n this.logger.warn('Introspection recompile listener failed', {\n reason,\n error: error instanceof Error ? error.message : String(error),\n });\n }\n }\n } catch (error) {\n this.logger.warn('Introspection recompilation failed', {\n reason,\n error: error instanceof Error ? error.message : String(error),\n });\n } finally {\n this.recompiling = undefined;\n }\n })();\n\n return this.recompiling;\n }\n}\n"]}