@wildo-ai/dev-companion 1.1.1 → 1.1.3

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 (212) 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 +408 -38
  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 +70 -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 +110 -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 +62 -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 +295 -19
  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 +243 -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 +370 -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 +40 -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 +126 -0
  82. package/dist/esm/core/introspection/subprocess/family-aspects.behavior.js.map +1 -0
  83. package/dist/esm/core/introspection/subprocess/specification-artifacts.behavior.d.ts +51 -0
  84. package/dist/esm/core/introspection/subprocess/specification-artifacts.behavior.d.ts.map +1 -0
  85. package/dist/esm/core/introspection/subprocess/specification-artifacts.behavior.js +391 -0
  86. package/dist/esm/core/introspection/subprocess/specification-artifacts.behavior.js.map +1 -0
  87. package/dist/esm/core/runtime/dev-compile-quiet.companion.d.ts +103 -0
  88. package/dist/esm/core/runtime/dev-compile-quiet.companion.d.ts.map +1 -0
  89. package/dist/esm/core/runtime/dev-compile-quiet.companion.js +124 -0
  90. package/dist/esm/core/runtime/dev-compile-quiet.companion.js.map +1 -0
  91. package/dist/esm/core/runtime/services/start-companion-application.service.d.ts +39 -2
  92. package/dist/esm/core/runtime/services/start-companion-application.service.d.ts.map +1 -1
  93. package/dist/esm/core/runtime/services/start-companion-application.service.js +122 -11
  94. package/dist/esm/core/runtime/services/start-companion-application.service.js.map +1 -1
  95. package/dist/esm/core/specifications/non-composite-view-specification-context.shared.d.ts +6 -0
  96. package/dist/esm/core/specifications/non-composite-view-specification-context.shared.d.ts.map +1 -1
  97. package/dist/esm/core/specifications/non-composite-view-specification-context.shared.js.map +1 -1
  98. package/dist/esm/core/specifications/specification-context-factory.shared.d.ts +23 -0
  99. package/dist/esm/core/specifications/specification-context-factory.shared.d.ts.map +1 -1
  100. package/dist/esm/core/specifications/specification-context-factory.shared.js +26 -4
  101. package/dist/esm/core/specifications/specification-context-factory.shared.js.map +1 -1
  102. package/dist/esm/executions/services/companion-executions.companion.service.d.ts.map +1 -1
  103. package/dist/esm/executions/services/companion-executions.companion.service.js +13 -8
  104. package/dist/esm/executions/services/companion-executions.companion.service.js.map +1 -1
  105. package/dist/esm/i18n/components/APP_LAYOUTS_MAIN_CONTAINER.en.d.ts +12 -0
  106. package/dist/esm/i18n/components/APP_LAYOUTS_MAIN_CONTAINER.en.d.ts.map +1 -0
  107. package/dist/esm/i18n/components/APP_LAYOUTS_MAIN_CONTAINER.en.js +12 -0
  108. package/dist/esm/i18n/components/APP_LAYOUTS_MAIN_CONTAINER.en.js.map +1 -0
  109. package/dist/esm/i18n/components/LOW_LEVEL_FORM_FIELD.en.d.ts +1 -1
  110. package/dist/esm/i18n/components/LOW_LEVEL_FORM_FIELD.en.js +1 -1
  111. package/dist/esm/i18n/components/LOW_LEVEL_FORM_FIELD.en.js.map +1 -1
  112. package/dist/esm/i18n/composite_views/app.creation-board.en.d.ts +13 -0
  113. package/dist/esm/i18n/composite_views/app.creation-board.en.d.ts.map +1 -0
  114. package/dist/esm/i18n/composite_views/app.creation-board.en.js +91 -0
  115. package/dist/esm/i18n/composite_views/app.creation-board.en.js.map +1 -0
  116. package/dist/esm/i18n/composite_views/app.domain-model.en.d.ts +38 -0
  117. package/dist/esm/i18n/composite_views/app.domain-model.en.d.ts.map +1 -0
  118. package/dist/esm/i18n/composite_views/app.domain-model.en.js +41 -0
  119. package/dist/esm/i18n/composite_views/app.domain-model.en.js.map +1 -0
  120. package/dist/esm/i18n/index.d.ts +3 -3
  121. package/dist/esm/i18n/index.js +3 -3
  122. package/dist/esm/i18n/index.js.map +1 -1
  123. package/dist/esm/i18n/resources/wildoApplicationActorSystemExecutions.en.d.ts +24 -0
  124. package/dist/esm/i18n/resources/wildoApplicationActorSystemExecutions.en.d.ts.map +1 -0
  125. package/dist/esm/i18n/resources/wildoApplicationActorSystemExecutions.en.js +20 -0
  126. package/dist/esm/i18n/resources/wildoApplicationActorSystemExecutions.en.js.map +1 -0
  127. package/dist/esm/i18n/resources/wildoApplicationActorTasks.en.d.ts +31 -0
  128. package/dist/esm/i18n/resources/wildoApplicationActorTasks.en.d.ts.map +1 -0
  129. package/dist/esm/i18n/resources/wildoApplicationActorTasks.en.js +27 -0
  130. package/dist/esm/i18n/resources/wildoApplicationActorTasks.en.js.map +1 -0
  131. package/dist/esm/i18n/resources/wildoApplicationFlowSystemExecutions.en.d.ts +24 -0
  132. package/dist/esm/i18n/resources/wildoApplicationFlowSystemExecutions.en.d.ts.map +1 -0
  133. package/dist/esm/i18n/resources/wildoApplicationFlowSystemExecutions.en.js +20 -0
  134. package/dist/esm/i18n/resources/wildoApplicationFlowSystemExecutions.en.js.map +1 -0
  135. package/dist/esm/i18n/resources/workbenchBuildPlanTasks.en.d.ts +28 -0
  136. package/dist/esm/i18n/resources/workbenchBuildPlanTasks.en.d.ts.map +1 -0
  137. package/dist/esm/i18n/resources/workbenchBuildPlanTasks.en.js +24 -0
  138. package/dist/esm/i18n/resources/workbenchBuildPlanTasks.en.js.map +1 -0
  139. package/dist/esm/i18n/resources/workbenchDomainResources.en.d.ts +138 -0
  140. package/dist/esm/i18n/resources/workbenchDomainResources.en.d.ts.map +1 -0
  141. package/dist/esm/i18n/resources/workbenchDomainResources.en.js +100 -0
  142. package/dist/esm/i18n/resources/workbenchDomainResources.en.js.map +1 -0
  143. package/dist/esm/i18n/resources/workbenchPlaybooks.en.d.ts +29 -0
  144. package/dist/esm/i18n/resources/workbenchPlaybooks.en.d.ts.map +1 -0
  145. package/dist/esm/i18n/resources/workbenchPlaybooks.en.js +25 -0
  146. package/dist/esm/i18n/resources/workbenchPlaybooks.en.js.map +1 -0
  147. package/dist/esm/i18n/resources/workbenchRunWriteRecords.en.d.ts +27 -0
  148. package/dist/esm/i18n/resources/workbenchRunWriteRecords.en.d.ts.map +1 -0
  149. package/dist/esm/i18n/resources/workbenchRunWriteRecords.en.js +23 -0
  150. package/dist/esm/i18n/resources/workbenchRunWriteRecords.en.js.map +1 -0
  151. package/dist/esm/i18n/resources/workbenchSpecificationArtifacts.en.d.ts +806 -0
  152. package/dist/esm/i18n/resources/workbenchSpecificationArtifacts.en.d.ts.map +1 -0
  153. package/dist/esm/i18n/resources/workbenchSpecificationArtifacts.en.js +326 -0
  154. package/dist/esm/i18n/resources/workbenchSpecificationArtifacts.en.js.map +1 -0
  155. package/dist/esm/i18n/resources/workbenchTraceSessions.en.d.ts +26 -0
  156. package/dist/esm/i18n/resources/workbenchTraceSessions.en.d.ts.map +1 -0
  157. package/dist/esm/i18n/resources/workbenchTraceSessions.en.js +22 -0
  158. package/dist/esm/i18n/resources/workbenchTraceSessions.en.js.map +1 -0
  159. package/dist/esm/i18n/system_enums/market.en.d.ts +202 -0
  160. package/dist/esm/i18n/system_enums/market.en.d.ts.map +1 -0
  161. package/dist/esm/i18n/system_enums/market.en.js +209 -0
  162. package/dist/esm/i18n/system_enums/market.en.js.map +1 -0
  163. package/dist/esm/meta-workflows/models/application-coding-agent.actors-system.definitions.d.ts +31 -0
  164. package/dist/esm/meta-workflows/models/application-coding-agent.actors-system.definitions.d.ts.map +1 -1
  165. package/dist/esm/meta-workflows/models/application-coding-agent.actors-system.definitions.js +91 -8
  166. package/dist/esm/meta-workflows/models/application-coding-agent.actors-system.definitions.js.map +1 -1
  167. package/dist/esm/meta-workflows/models/application-research-agent.actors-system.definitions.d.ts +4 -2
  168. package/dist/esm/meta-workflows/models/application-research-agent.actors-system.definitions.d.ts.map +1 -1
  169. package/dist/esm/meta-workflows/models/application-research-agent.actors-system.definitions.js +10 -7
  170. package/dist/esm/meta-workflows/models/application-research-agent.actors-system.definitions.js.map +1 -1
  171. package/dist/esm/meta-workflows/services/application-build-dispatch.companion.service.d.ts +80 -7
  172. package/dist/esm/meta-workflows/services/application-build-dispatch.companion.service.d.ts.map +1 -1
  173. package/dist/esm/meta-workflows/services/application-build-dispatch.companion.service.js +261 -24
  174. package/dist/esm/meta-workflows/services/application-build-dispatch.companion.service.js.map +1 -1
  175. package/dist/esm/meta-workflows/services/application-build-generation-step.companion.service.d.ts +46 -3
  176. package/dist/esm/meta-workflows/services/application-build-generation-step.companion.service.d.ts.map +1 -1
  177. package/dist/esm/meta-workflows/services/application-build-generation-step.companion.service.js +95 -2
  178. package/dist/esm/meta-workflows/services/application-build-generation-step.companion.service.js.map +1 -1
  179. package/dist/esm/meta-workflows/services/execution-trace-read.companion.service.d.ts +9 -0
  180. package/dist/esm/meta-workflows/services/execution-trace-read.companion.service.d.ts.map +1 -1
  181. package/dist/esm/meta-workflows/services/execution-trace-read.companion.service.js +13 -0
  182. package/dist/esm/meta-workflows/services/execution-trace-read.companion.service.js.map +1 -1
  183. package/dist/esm/meta-workflows/services/playbook-run-write-register.companion.service.d.ts +12 -0
  184. package/dist/esm/meta-workflows/services/playbook-run-write-register.companion.service.d.ts.map +1 -1
  185. package/dist/esm/meta-workflows/services/playbook-run-write-register.companion.service.js +23 -0
  186. package/dist/esm/meta-workflows/services/playbook-run-write-register.companion.service.js.map +1 -1
  187. package/dist/esm/meta-workflows/services/playbook-run.companion.service.d.ts +113 -1
  188. package/dist/esm/meta-workflows/services/playbook-run.companion.service.d.ts.map +1 -1
  189. package/dist/esm/meta-workflows/services/playbook-run.companion.service.js +517 -54
  190. package/dist/esm/meta-workflows/services/playbook-run.companion.service.js.map +1 -1
  191. package/dist/esm/meta-workflows/services/playbook-suspended-run.companion.service.d.ts +40 -0
  192. package/dist/esm/meta-workflows/services/playbook-suspended-run.companion.service.d.ts.map +1 -1
  193. package/dist/esm/meta-workflows/services/playbook-suspended-run.companion.service.js +63 -1
  194. package/dist/esm/meta-workflows/services/playbook-suspended-run.companion.service.js.map +1 -1
  195. package/dist/esm/technical-doc/services/technical-doc.companion.service.d.ts +21 -0
  196. package/dist/esm/technical-doc/services/technical-doc.companion.service.d.ts.map +1 -1
  197. package/dist/esm/technical-doc/services/technical-doc.companion.service.js +84 -2
  198. package/dist/esm/technical-doc/services/technical-doc.companion.service.js.map +1 -1
  199. package/dist/esm/technical-doc/services/technical-documentation-application-derivation.companion.service.d.ts +10 -1
  200. package/dist/esm/technical-doc/services/technical-documentation-application-derivation.companion.service.d.ts.map +1 -1
  201. package/dist/esm/technical-doc/services/technical-documentation-application-derivation.companion.service.js +10 -1
  202. package/dist/esm/technical-doc/services/technical-documentation-application-derivation.companion.service.js.map +1 -1
  203. package/package.json +17 -17
  204. package/dist/esm/.builder.pid +0 -9
  205. package/dist/esm/i18n/resources/workbenchApplicationModules.en.d.ts +0 -36
  206. package/dist/esm/i18n/resources/workbenchApplicationModules.en.d.ts.map +0 -1
  207. package/dist/esm/i18n/resources/workbenchApplicationModules.en.js +0 -32
  208. package/dist/esm/i18n/resources/workbenchApplicationModules.en.js.map +0 -1
  209. package/dist/esm/i18n/resources/workbenchResourceRelationships.en.d.ts +0 -29
  210. package/dist/esm/i18n/resources/workbenchResourceRelationships.en.d.ts.map +0 -1
  211. package/dist/esm/i18n/resources/workbenchResourceRelationships.en.js +0 -25
  212. package/dist/esm/i18n/resources/workbenchResourceRelationships.en.js.map +0 -1
@@ -0,0 +1,243 @@
1
+ import type { LoggerService } from '@wildo-ai/saas-backend-lib';
2
+ import type { CompanionContext } from '../../context/companion-context';
3
+ import { IntrospectionSourceStateObserver } from './introspection-source-state.companion.service';
4
+ import type { CompanionIntrospectionResult, CompanionIntrospectionSuccessResult } from '../models/companion-introspection.models';
5
+ /**
6
+ * How a derivation's freshness is currently decided.
7
+ *
8
+ * The two modes are not a preference. `OBSERVE_PER_READ` is exactly the behaviour issue #159 shipped
9
+ * — sweep the source on every read, serve the memo only when the token still matches — and it is the
10
+ * FALLBACK, kept because it is correct without any collaborator. `PUSH` is the mode this service
11
+ * exists for: a freshness authority (the source watcher) tells the state when the source moved, so a
12
+ * read consults nothing but memory.
13
+ *
14
+ * The service starts in `OBSERVE_PER_READ` and is promoted only when an authority registers. That
15
+ * ordering is deliberate: a companion whose watcher failed to start, or a unit test that wires none,
16
+ * degrades to slow-and-correct rather than to fast-and-stale.
17
+ */
18
+ export declare enum IntrospectionFreshnessMode {
19
+ /** No authority registered. Every read sweeps, exactly as issue #159 left it. */
20
+ OBSERVE_PER_READ = "observe-per-read",
21
+ /** An authority is live. Reads consult memory; the authority drives recompilation. */
22
+ PUSH = "push"
23
+ }
24
+ /** Why a recompilation was triggered, carried into the log line and the change report. */
25
+ export declare enum IntrospectionRecompileReason {
26
+ /** The freshness authority saw the source move. */
27
+ SOURCE_MUTATION = "source-mutation",
28
+ /** The periodic reconciliation sweep found a token the authority had not reported. */
29
+ RECONCILIATION = "reconciliation",
30
+ /** Startup warming, before anybody has asked. */
31
+ BOOT_WARM = "boot-warm",
32
+ /** A read found no compiled state at all. */
33
+ COLD_READ = "cold-read"
34
+ }
35
+ /**
36
+ * One compiled derivation, and everything a consumer needs to talk about it without recompiling.
37
+ */
38
+ export interface IntrospectionCompiledDerivation {
39
+ /**
40
+ * The child's answer, exactly as `requestInfo` would have returned it.
41
+ *
42
+ * Typed as the SUCCESS result rather than the union, because only a success is ever retained —
43
+ * see `store`. That is not a narrowing for convenience: `servedFromCache` exists only on the
44
+ * success arm, so a union here would make the flag unassignable, and the type is the place that
45
+ * says a failure is never held.
46
+ */
47
+ readonly result: CompanionIntrospectionSuccessResult;
48
+ /** The source-state token this was compiled against. */
49
+ readonly sourceStateToken: string;
50
+ /**
51
+ * A monotonically increasing stamp for this derivation, used as the WebSocket sync `version`.
52
+ *
53
+ * **It must never go backwards, including across a companion restart.** `ResourceMutationManager`
54
+ * drops any pushed update whose `version <= this._version`, so a counter that resets to zero on
55
+ * restart makes every browser tab that stayed open ignore every later update — silently, with no
56
+ * error and no refetch, leaving a permanently frozen view. Wall-clock milliseconds cannot regress
57
+ * across a restart, which is the whole reason they are used here rather than a counter.
58
+ */
59
+ readonly generation: number;
60
+ /** When this was compiled, for the debug line that explains a lookup's age. */
61
+ readonly compiledAt: number;
62
+ }
63
+ /** What one recompilation did, per derivation, so a caller can emit a diff without re-reading. */
64
+ export interface IntrospectionRecompileOutcome {
65
+ readonly cacheKey: string;
66
+ readonly behavior: string;
67
+ readonly serviceKey: string;
68
+ /** The state before, absent on a first compile. */
69
+ readonly previous: IntrospectionCompiledDerivation | undefined;
70
+ /** The state after. Absent when the recompilation FAILED and the previous state was kept. */
71
+ readonly next: IntrospectionCompiledDerivation | undefined;
72
+ /** `false` when the recompilation produced a byte-identical payload — nothing to notify about. */
73
+ readonly changed: boolean;
74
+ }
75
+ /**
76
+ * Owns COMPILED introspection state, so that reading one is not the act that compiles it.
77
+ *
78
+ * ## Why this is a separate service rather than a better cache
79
+ *
80
+ * Before this, compilation and retrieval were the same code path: `requestInfo` observed the source,
81
+ * compared a token, and compiled on a miss — all inside the caller's request. That fusion has three
82
+ * consequences that no amount of cache tuning removes.
83
+ *
84
+ * 1. **Every read pays the freshness probe.** Measured on wonder-crm, 2026-09-02: a warm
85
+ * `LIST /api/v1/workbench-domain-resources` answered in 200–270 ms, of which the source sweep is
86
+ * 180–225 ms. The cache was working perfectly and almost all of the remaining latency was the act
87
+ * of asking whether it could be used.
88
+ * 2. **A miss is charged to whoever happened to ask.** Same session: a cold `LIST` cost 8.95 s and an
89
+ * addressed `READ` cost 44.4 s, then 500. In a tree with the engine's `tsc-watch` fleet running,
90
+ * the token moves constantly, so a miss is the NORMAL case rather than the exception.
91
+ * 3. **Nothing can be notified.** A pull-shaped cache learns that the source moved only while
92
+ * somebody is waiting for an answer, so there is no moment at which it could tell a frontend that
93
+ * a row changed. Push requires knowing BEFORE the read.
94
+ *
95
+ * Separating the two makes each answerable on its own terms: compilation is triggered by the source
96
+ * moving, retrieval is a map lookup, and the moment between them is where a notification can exist.
97
+ *
98
+ * ## What this holds is TIME, never TRUTH
99
+ *
100
+ * `one-source-of-truth.md` Rule 5: this is per-run runtime state. Deleting all of it costs a
101
+ * recompilation and changes no answer — {@link clear} is the proof obligation, and the byte-identical
102
+ * payload across it is the test. Nothing here is a ledger, nothing is persisted, and no decision
103
+ * anywhere may be made from the absence of an entry.
104
+ */
105
+ export declare class IntrospectionDerivationStateCompanionService {
106
+ private readonly logger;
107
+ private readonly companionContext;
108
+ private readonly logDebug;
109
+ private readonly state;
110
+ private readonly known;
111
+ /** Recompilations currently running, so two triggers cannot compile the same question twice. */
112
+ private readonly inFlight;
113
+ private readonly observer;
114
+ private freshnessMode;
115
+ private freshnessAuthorityName;
116
+ /** The token the state was last compiled against, in `PUSH` mode. */
117
+ private currentToken;
118
+ private lastGeneration;
119
+ constructor(logger: LoggerService, companionContext: CompanionContext);
120
+ get mode(): IntrospectionFreshnessMode;
121
+ /**
122
+ * Promote the service out of per-read observation.
123
+ *
124
+ * Called by the source watcher once it is actually watching. The name is carried so an operator
125
+ * reading a log line can tell WHICH authority is responsible for freshness, and so a second
126
+ * registration is visible rather than silent.
127
+ */
128
+ registerFreshnessAuthority(name: string): void;
129
+ /**
130
+ * Demote back to per-read observation.
131
+ *
132
+ * The watcher calls this when it errors or closes. Demoting is always safe and never wrong — it
133
+ * only costs time — whereas staying in `PUSH` with a dead authority serves a tree that has moved.
134
+ */
135
+ noteFreshnessAuthorityLost(reason: string): void;
136
+ /**
137
+ * Read a derivation, compiling only when there is nothing to read.
138
+ *
139
+ * `compile` is retained against the cache key on first sight, which is what lets a later
140
+ * source mutation recompile this question with no caller present. That is the whole mechanism by
141
+ * which retrieval stops driving compilation: the FIRST read teaches the service the question, and
142
+ * every subsequent answer — including the ones nobody asked for yet — is produced by the source
143
+ * moving instead.
144
+ *
145
+ * In `OBSERVE_PER_READ` mode the freshness probe still runs here, because without an authority
146
+ * there is nothing else that could run it.
147
+ */
148
+ read(identity: {
149
+ readonly cacheKey: string;
150
+ readonly behavior: string;
151
+ readonly serviceKey: string;
152
+ }, compile: () => Promise<CompanionIntrospectionResult>): Promise<CompanionIntrospectionResult>;
153
+ /**
154
+ * The pre-#159-separation path, kept verbatim in behaviour for the no-authority case.
155
+ *
156
+ * A read observes the source, serves the held derivation when the token still matches, and
157
+ * compiles otherwise. Slower by exactly one sweep per read, and correct with no collaborator.
158
+ */
159
+ private readWithPerReadObservation;
160
+ /**
161
+ * Recompile everything this service knows about, if the source has actually moved.
162
+ *
163
+ * Returns one outcome per known derivation, with `changed` telling the caller whether anything
164
+ * downstream needs to hear about it. A recompilation that produces a byte-identical payload is
165
+ * reported as unchanged, because an operator saving a file that alters nothing observable must not
166
+ * produce a wave of notifications.
167
+ *
168
+ * A FAILED recompilation keeps the previous state rather than dropping it. The dominant failure
169
+ * here is an application mid-build, and answering "could not look" for the seconds a `tsc` takes —
170
+ * when a correct answer from one second ago is in hand — is worse than answering slightly late.
171
+ */
172
+ recompileIfSourceMoved(reason: IntrospectionRecompileReason): Promise<{
173
+ readonly moved: boolean;
174
+ readonly outcomes: readonly IntrospectionRecompileOutcome[];
175
+ }>;
176
+ /**
177
+ * How many derivations are currently held.
178
+ *
179
+ * A diagnostic, and the pin for the pruning invariant: the map is bounded by the distinct
180
+ * questions asked since the last source change, not by every question ever asked.
181
+ */
182
+ get compiledDerivationCount(): number;
183
+ /** The generation currently held for a derivation, for a caller stamping a notification. */
184
+ generationOf(cacheKey: string): number | undefined;
185
+ /**
186
+ * Drop every compiled derivation.
187
+ *
188
+ * Costs a recompilation and changes no answer. That property is what makes this state rather than
189
+ * a ledger, so it is exercised by a test rather than merely asserted here.
190
+ */
191
+ clear(): void;
192
+ /**
193
+ * Test seam: drop ONE compiled entry, to reproduce a single-key compile against a partly-empty
194
+ * state. Production never evicts a single entry — see the note in `store`.
195
+ */
196
+ clearOneForTesting(cacheKey: string): void;
197
+ /** Test seam: replace the source observer with a fake. Production always observes real trees. */
198
+ setSourceStateObserverForTesting(observer: IntrospectionSourceStateObserver): void;
199
+ /**
200
+ * Compile one known derivation into the state, joining an identical in-flight compilation.
201
+ *
202
+ * The join matters more here than in a request-shaped cache: a watcher burst and a cold read can
203
+ * arrive within the same millisecond, and a subprocess that imports the whole application is the
204
+ * most expensive thing this process does.
205
+ */
206
+ private compileInto;
207
+ /** Write a compiled derivation into the state under a fresh, never-decreasing generation. */
208
+ private store;
209
+ }
210
+ /**
211
+ * Whether two derivations carry the same answer.
212
+ *
213
+ * Compared on the DATA the child returned, not on the envelope: a result carries timing and a
214
+ * `servedFromCache` flag that differ between two compilations of an unchanged application, and
215
+ * comparing those would report every recompilation as a change.
216
+ *
217
+ * A stable stringify is deliberately NOT used. The child's payload is produced by one code path from
218
+ * one imported module graph, so key order is stable between two runs of the same bytes; and an
219
+ * ordering difference that did appear would mean the application's own output was non-deterministic,
220
+ * which is a change worth reporting rather than hiding.
221
+ *
222
+ * ## This OVER-reports, deliberately, and the row diff is the real decision
223
+ *
224
+ * Measured on wonder-crm 2026-09-02, by recompiling three times against byte-identical sources: two
225
+ * of three derivations reported `changed` every time. Diffing two payloads leaf by leaf found exactly
226
+ * one differing value — `specification-artifacts` stamps `trace.evaluatedAt` with the wall-clock
227
+ * instant of the derivation, so its payload can never compare equal to its predecessor.
228
+ * (`application-domain-model` differed in **0** leaves, so the volatility is per-behavior, not
229
+ * general.)
230
+ *
231
+ * That is safe, and it is safe for a specific reason rather than by luck: `changed` only decides
232
+ * whether the notifier is INVITED to look. What it publishes is decided by `diffProjectedRows` over
233
+ * the projected ROWS, and `trace` sits outside this behavior's `rowsPath`. The live check confirms
234
+ * it — three touch-only recompilations produced `changedCount: 2` and **zero** publications.
235
+ *
236
+ * The alternative — excluding known-volatile keys here — was rejected: it would be a second, drifting
237
+ * description of what a row contains, when the projection already owns that answer. **But the
238
+ * guarantee rests on volatile fields staying OUT of the projected rows.** A behavior that put a
239
+ * timestamp INSIDE a row would push an update for every row on every recompilation, and nothing here
240
+ * would catch it — the diff would be correct and the data would be noise.
241
+ */
242
+ export declare function areDerivationPayloadsEqual(left: CompanionIntrospectionSuccessResult | undefined, right: CompanionIntrospectionSuccessResult | undefined): boolean;
243
+ //# sourceMappingURL=introspection-derivation-state.companion.service.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"introspection-derivation-state.companion.service.d.ts","sourceRoot":"","sources":["../../../../../../src/core/introspection/services/introspection-derivation-state.companion.service.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,417 @@
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 { inject, injectable } from 'inversify';
14
+ import { SAAS_SERVICE_TYPES } from '@wildo-ai/saas-backend-lib';
15
+ import { COMPANION_SERVICE_TYPES } from '../../inject/models/service-types.js';
16
+ import { IntrospectionSourceStateObserver } from './introspection-source-state.companion.service.js';
17
+ /**
18
+ * How a derivation's freshness is currently decided.
19
+ *
20
+ * The two modes are not a preference. `OBSERVE_PER_READ` is exactly the behaviour issue #159 shipped
21
+ * — sweep the source on every read, serve the memo only when the token still matches — and it is the
22
+ * FALLBACK, kept because it is correct without any collaborator. `PUSH` is the mode this service
23
+ * exists for: a freshness authority (the source watcher) tells the state when the source moved, so a
24
+ * read consults nothing but memory.
25
+ *
26
+ * The service starts in `OBSERVE_PER_READ` and is promoted only when an authority registers. That
27
+ * ordering is deliberate: a companion whose watcher failed to start, or a unit test that wires none,
28
+ * degrades to slow-and-correct rather than to fast-and-stale.
29
+ */
30
+ export var IntrospectionFreshnessMode;
31
+ (function (IntrospectionFreshnessMode) {
32
+ /** No authority registered. Every read sweeps, exactly as issue #159 left it. */
33
+ IntrospectionFreshnessMode["OBSERVE_PER_READ"] = "observe-per-read";
34
+ /** An authority is live. Reads consult memory; the authority drives recompilation. */
35
+ IntrospectionFreshnessMode["PUSH"] = "push";
36
+ })(IntrospectionFreshnessMode || (IntrospectionFreshnessMode = {}));
37
+ /** Why a recompilation was triggered, carried into the log line and the change report. */
38
+ export var IntrospectionRecompileReason;
39
+ (function (IntrospectionRecompileReason) {
40
+ /** The freshness authority saw the source move. */
41
+ IntrospectionRecompileReason["SOURCE_MUTATION"] = "source-mutation";
42
+ /** The periodic reconciliation sweep found a token the authority had not reported. */
43
+ IntrospectionRecompileReason["RECONCILIATION"] = "reconciliation";
44
+ /** Startup warming, before anybody has asked. */
45
+ IntrospectionRecompileReason["BOOT_WARM"] = "boot-warm";
46
+ /** A read found no compiled state at all. */
47
+ IntrospectionRecompileReason["COLD_READ"] = "cold-read";
48
+ })(IntrospectionRecompileReason || (IntrospectionRecompileReason = {}));
49
+ /**
50
+ * Owns COMPILED introspection state, so that reading one is not the act that compiles it.
51
+ *
52
+ * ## Why this is a separate service rather than a better cache
53
+ *
54
+ * Before this, compilation and retrieval were the same code path: `requestInfo` observed the source,
55
+ * compared a token, and compiled on a miss — all inside the caller's request. That fusion has three
56
+ * consequences that no amount of cache tuning removes.
57
+ *
58
+ * 1. **Every read pays the freshness probe.** Measured on wonder-crm, 2026-09-02: a warm
59
+ * `LIST /api/v1/workbench-domain-resources` answered in 200–270 ms, of which the source sweep is
60
+ * 180–225 ms. The cache was working perfectly and almost all of the remaining latency was the act
61
+ * of asking whether it could be used.
62
+ * 2. **A miss is charged to whoever happened to ask.** Same session: a cold `LIST` cost 8.95 s and an
63
+ * addressed `READ` cost 44.4 s, then 500. In a tree with the engine's `tsc-watch` fleet running,
64
+ * the token moves constantly, so a miss is the NORMAL case rather than the exception.
65
+ * 3. **Nothing can be notified.** A pull-shaped cache learns that the source moved only while
66
+ * somebody is waiting for an answer, so there is no moment at which it could tell a frontend that
67
+ * a row changed. Push requires knowing BEFORE the read.
68
+ *
69
+ * Separating the two makes each answerable on its own terms: compilation is triggered by the source
70
+ * moving, retrieval is a map lookup, and the moment between them is where a notification can exist.
71
+ *
72
+ * ## What this holds is TIME, never TRUTH
73
+ *
74
+ * `one-source-of-truth.md` Rule 5: this is per-run runtime state. Deleting all of it costs a
75
+ * recompilation and changes no answer — {@link clear} is the proof obligation, and the byte-identical
76
+ * payload across it is the test. Nothing here is a ledger, nothing is persisted, and no decision
77
+ * anywhere may be made from the absence of an entry.
78
+ */
79
+ let IntrospectionDerivationStateCompanionService = class IntrospectionDerivationStateCompanionService {
80
+ logger;
81
+ companionContext;
82
+ logDebug;
83
+ state = new Map();
84
+ known = new Map();
85
+ /** Recompilations currently running, so two triggers cannot compile the same question twice. */
86
+ inFlight = new Map();
87
+ observer;
88
+ freshnessMode = IntrospectionFreshnessMode.OBSERVE_PER_READ;
89
+ freshnessAuthorityName;
90
+ /** The token the state was last compiled against, in `PUSH` mode. */
91
+ currentToken;
92
+ lastGeneration = 0;
93
+ constructor(logger, companionContext) {
94
+ this.logger = logger;
95
+ this.companionContext = companionContext;
96
+ this.logDebug = this.logger.debugByType('IntrospectionDerivationState');
97
+ this.logger.setDebugTypeLogging('IntrospectionDerivationState', true);
98
+ this.observer = new IntrospectionSourceStateObserver(this.companionContext);
99
+ }
100
+ get mode() {
101
+ return this.freshnessMode;
102
+ }
103
+ /**
104
+ * Promote the service out of per-read observation.
105
+ *
106
+ * Called by the source watcher once it is actually watching. The name is carried so an operator
107
+ * reading a log line can tell WHICH authority is responsible for freshness, and so a second
108
+ * registration is visible rather than silent.
109
+ */
110
+ registerFreshnessAuthority(name) {
111
+ this.freshnessAuthorityName = name;
112
+ this.freshnessMode = IntrospectionFreshnessMode.PUSH;
113
+ this.logger.info('Introspection derivation state promoted to push freshness', { authority: name });
114
+ }
115
+ /**
116
+ * Demote back to per-read observation.
117
+ *
118
+ * The watcher calls this when it errors or closes. Demoting is always safe and never wrong — it
119
+ * only costs time — whereas staying in `PUSH` with a dead authority serves a tree that has moved.
120
+ */
121
+ noteFreshnessAuthorityLost(reason) {
122
+ if (this.freshnessMode === IntrospectionFreshnessMode.OBSERVE_PER_READ)
123
+ return;
124
+ this.freshnessMode = IntrospectionFreshnessMode.OBSERVE_PER_READ;
125
+ this.logger.warn('Introspection freshness authority lost; falling back to per-read source observation', {
126
+ authority: this.freshnessAuthorityName,
127
+ reason,
128
+ });
129
+ this.freshnessAuthorityName = undefined;
130
+ }
131
+ /**
132
+ * Read a derivation, compiling only when there is nothing to read.
133
+ *
134
+ * `compile` is retained against the cache key on first sight, which is what lets a later
135
+ * source mutation recompile this question with no caller present. That is the whole mechanism by
136
+ * which retrieval stops driving compilation: the FIRST read teaches the service the question, and
137
+ * every subsequent answer — including the ones nobody asked for yet — is produced by the source
138
+ * moving instead.
139
+ *
140
+ * In `OBSERVE_PER_READ` mode the freshness probe still runs here, because without an authority
141
+ * there is nothing else that could run it.
142
+ */
143
+ async read(identity, compile) {
144
+ if (!this.known.has(identity.cacheKey)) {
145
+ this.known.set(identity.cacheKey, { ...identity, compile });
146
+ }
147
+ if (this.freshnessMode === IntrospectionFreshnessMode.OBSERVE_PER_READ) {
148
+ return this.readWithPerReadObservation(identity, compile);
149
+ }
150
+ const held = this.state.get(identity.cacheKey);
151
+ if (held) {
152
+ this.logDebug('Introspection derivation served from compiled state', {
153
+ behavior: identity.behavior,
154
+ serviceKey: identity.serviceKey,
155
+ ageMs: Date.now() - held.compiledAt,
156
+ generation: held.generation,
157
+ });
158
+ return { ...held.result, servedFromCache: true };
159
+ }
160
+ return (await this.compileInto(identity.cacheKey, IntrospectionRecompileReason.COLD_READ))
161
+ ?? compile();
162
+ }
163
+ /**
164
+ * The pre-#159-separation path, kept verbatim in behaviour for the no-authority case.
165
+ *
166
+ * A read observes the source, serves the held derivation when the token still matches, and
167
+ * compiles otherwise. Slower by exactly one sweep per read, and correct with no collaborator.
168
+ */
169
+ async readWithPerReadObservation(identity, compile) {
170
+ const observation = await this.observer.observe(Date.now());
171
+ const held = this.state.get(identity.cacheKey);
172
+ if (held && held.sourceStateToken === observation.token) {
173
+ this.logDebug('Introspection derivation served from compiled state (per-read observation)', {
174
+ behavior: identity.behavior,
175
+ serviceKey: identity.serviceKey,
176
+ sourceObservationMs: observation.durationMs,
177
+ });
178
+ return { ...held.result, servedFromCache: true };
179
+ }
180
+ /*
181
+ * Routed through `compileInto` rather than calling the closure here, because that is where the
182
+ * in-flight join lives. `maxConcurrency` caps how many subprocesses run at once; it does not
183
+ * notice that two of them are asking the identical question. Two concurrent reads of one
184
+ * behavior must cost ONE subprocess, and calling the closure directly would silently
185
+ * reintroduce the second child.
186
+ *
187
+ * `bounded: false` means the sweep gave up before seeing the whole tree, so its token says
188
+ * nothing about whether the source moved. Compiling is still correct; RETAINING against that
189
+ * token would not be — which is why the token is handed over only when the sweep completed.
190
+ */
191
+ return (await this.compileInto(identity.cacheKey, IntrospectionRecompileReason.COLD_READ, observation.bounded ? observation.token : undefined)) ?? compile();
192
+ }
193
+ /**
194
+ * Recompile everything this service knows about, if the source has actually moved.
195
+ *
196
+ * Returns one outcome per known derivation, with `changed` telling the caller whether anything
197
+ * downstream needs to hear about it. A recompilation that produces a byte-identical payload is
198
+ * reported as unchanged, because an operator saving a file that alters nothing observable must not
199
+ * produce a wave of notifications.
200
+ *
201
+ * A FAILED recompilation keeps the previous state rather than dropping it. The dominant failure
202
+ * here is an application mid-build, and answering "could not look" for the seconds a `tsc` takes —
203
+ * when a correct answer from one second ago is in hand — is worse than answering slightly late.
204
+ */
205
+ async recompileIfSourceMoved(reason) {
206
+ const observation = await this.observer.observe(Date.now());
207
+ if (!observation.bounded) {
208
+ this.logger.warn('Introspection source observation exceeded its ceiling; recompiling without remembering', {
209
+ reason,
210
+ observedEntryCount: observation.observedEntryCount,
211
+ });
212
+ }
213
+ if (this.currentToken === observation.token && observation.bounded) {
214
+ return { moved: false, outcomes: [] };
215
+ }
216
+ this.currentToken = observation.bounded ? observation.token : undefined;
217
+ /*
218
+ * Snapshot every previous state BEFORE compiling any of them.
219
+ *
220
+ * `store` prunes entries taken against a superseded token, so the FIRST compilation of this loop
221
+ * deletes every OTHER derivation's previous state — they still carry the old token. Reading
222
+ * `previous` inside the loop therefore returned `undefined` for every derivation after the first,
223
+ * and each one reported its whole row set as CREATED.
224
+ *
225
+ * Measured before the fix on wonder-crm: 180 publications in three minutes, every one of them
226
+ * `created: N, updated: 0, deleted: 0` — a full-repaint storm, the exact opposite of what the
227
+ * diff exists to produce. Found by reading the live log rather than by a test, which is why the
228
+ * regression pin below compares TWO derivations rather than one.
229
+ */
230
+ const previousByKey = new Map();
231
+ for (const entry of this.known.values()) {
232
+ const held = this.state.get(entry.cacheKey);
233
+ if (held)
234
+ previousByKey.set(entry.cacheKey, held);
235
+ }
236
+ const outcomes = [];
237
+ for (const entry of this.known.values()) {
238
+ const previous = previousByKey.get(entry.cacheKey);
239
+ await this.compileInto(entry.cacheKey, reason, observation.token);
240
+ const next = this.state.get(entry.cacheKey);
241
+ outcomes.push({
242
+ cacheKey: entry.cacheKey,
243
+ behavior: entry.behavior,
244
+ serviceKey: entry.serviceKey,
245
+ previous,
246
+ next,
247
+ changed: next !== undefined && next !== previous
248
+ && !areDerivationPayloadsEqual(previous?.result, next.result),
249
+ });
250
+ }
251
+ this.logDebug('Introspection source moved; recompiled known derivations', {
252
+ reason,
253
+ derivationCount: outcomes.length,
254
+ changedCount: outcomes.filter((outcome) => outcome.changed).length,
255
+ sourceObservationMs: observation.durationMs,
256
+ });
257
+ return { moved: true, outcomes };
258
+ }
259
+ /**
260
+ * How many derivations are currently held.
261
+ *
262
+ * A diagnostic, and the pin for the pruning invariant: the map is bounded by the distinct
263
+ * questions asked since the last source change, not by every question ever asked.
264
+ */
265
+ get compiledDerivationCount() {
266
+ return this.state.size;
267
+ }
268
+ /** The generation currently held for a derivation, for a caller stamping a notification. */
269
+ generationOf(cacheKey) {
270
+ return this.state.get(cacheKey)?.generation;
271
+ }
272
+ /**
273
+ * Drop every compiled derivation.
274
+ *
275
+ * Costs a recompilation and changes no answer. That property is what makes this state rather than
276
+ * a ledger, so it is exercised by a test rather than merely asserted here.
277
+ */
278
+ clear() {
279
+ this.state.clear();
280
+ this.currentToken = undefined;
281
+ }
282
+ /**
283
+ * Test seam: drop ONE compiled entry, to reproduce a single-key compile against a partly-empty
284
+ * state. Production never evicts a single entry — see the note in `store`.
285
+ */
286
+ clearOneForTesting(cacheKey) {
287
+ this.state.delete(cacheKey);
288
+ }
289
+ /** Test seam: replace the source observer with a fake. Production always observes real trees. */
290
+ setSourceStateObserverForTesting(observer) {
291
+ this.observer = observer;
292
+ }
293
+ /**
294
+ * Compile one known derivation into the state, joining an identical in-flight compilation.
295
+ *
296
+ * The join matters more here than in a request-shaped cache: a watcher burst and a cold read can
297
+ * arrive within the same millisecond, and a subprocess that imports the whole application is the
298
+ * most expensive thing this process does.
299
+ */
300
+ async compileInto(cacheKey, reason, tokenOverride) {
301
+ const existing = this.inFlight.get(cacheKey);
302
+ if (existing)
303
+ return existing;
304
+ const entry = this.known.get(cacheKey);
305
+ if (!entry)
306
+ return undefined;
307
+ const run = (async () => {
308
+ let token = tokenOverride;
309
+ if (token === undefined) {
310
+ const observation = await this.observer.observe(Date.now());
311
+ token = observation.bounded ? observation.token : undefined;
312
+ }
313
+ const result = await entry.compile();
314
+ if (!result.success || token === undefined) {
315
+ /*
316
+ * A failure is never retained, and the reasoning is the same as before the split: the
317
+ * dominant failure here is an application whose `dist` is not built, whose remedy moves the
318
+ * source and would invalidate anyway; and a transient failure — a timeout on a loaded
319
+ * machine — would otherwise stick to an unchanged tree and be served as the answer forever.
320
+ */
321
+ this.logDebug('Introspection compilation not retained', {
322
+ behavior: entry.behavior,
323
+ serviceKey: entry.serviceKey,
324
+ reason,
325
+ success: result.success,
326
+ hasToken: token !== undefined,
327
+ });
328
+ return result;
329
+ }
330
+ this.store(cacheKey, result, token);
331
+ return result;
332
+ })().finally(() => {
333
+ this.inFlight.delete(cacheKey);
334
+ });
335
+ this.inFlight.set(cacheKey, run);
336
+ return run;
337
+ }
338
+ /** Write a compiled derivation into the state under a fresh, never-decreasing generation. */
339
+ store(cacheKey, result, sourceStateToken) {
340
+ const compiledAt = Date.now();
341
+ // Wall-clock is monotone across a restart; the `+1` only breaks a tie between two compilations
342
+ // landing inside the same millisecond, which a browser tab would otherwise read as a stale push.
343
+ this.lastGeneration = Math.max(compiledAt, this.lastGeneration + 1);
344
+ const compiled = {
345
+ result,
346
+ sourceStateToken,
347
+ generation: this.lastGeneration,
348
+ compiledAt,
349
+ };
350
+ /*
351
+ * NOTHING IS PRUNED HERE, and that REVERSES what issue #159's cache did — deliberately.
352
+ *
353
+ * That cache dropped every entry taken against a superseded token, on the reasoning that such an
354
+ * entry "describes a tree that no longer exists, so it can never be served again". The first half
355
+ * is still true; the conclusion is not, because an entry now has a SECOND job. It is the basis
356
+ * the next recompilation diffs against, and being unservable as an ANSWER does not make it
357
+ * useless as a BASELINE.
358
+ *
359
+ * Pruning here cost exactly that: compiling ONE derivation evicted every other derivation's
360
+ * baseline, so the next recompile-all saw no previous state for them and reported their whole row
361
+ * sets as CREATED. Measured on wonder-crm before the fix — 180 publications in three minutes,
362
+ * every one a full repaint.
363
+ *
364
+ * The growth the pruning guarded against cannot occur any more either: this map holds ONE entry
365
+ * per cache key, and a recompilation OVERWRITES that key rather than adding a second entry. Its
366
+ * size is bounded by the number of distinct questions in {@link known}, which is the same bound
367
+ * that map already carries.
368
+ */
369
+ this.state.set(cacheKey, compiled);
370
+ return compiled;
371
+ }
372
+ };
373
+ IntrospectionDerivationStateCompanionService = __decorate([
374
+ injectable(),
375
+ __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
376
+ __param(1, inject(COMPANION_SERVICE_TYPES.CompanionContext)),
377
+ __metadata("design:paramtypes", [Function, Object])
378
+ ], IntrospectionDerivationStateCompanionService);
379
+ export { IntrospectionDerivationStateCompanionService };
380
+ /**
381
+ * Whether two derivations carry the same answer.
382
+ *
383
+ * Compared on the DATA the child returned, not on the envelope: a result carries timing and a
384
+ * `servedFromCache` flag that differ between two compilations of an unchanged application, and
385
+ * comparing those would report every recompilation as a change.
386
+ *
387
+ * A stable stringify is deliberately NOT used. The child's payload is produced by one code path from
388
+ * one imported module graph, so key order is stable between two runs of the same bytes; and an
389
+ * ordering difference that did appear would mean the application's own output was non-deterministic,
390
+ * which is a change worth reporting rather than hiding.
391
+ *
392
+ * ## This OVER-reports, deliberately, and the row diff is the real decision
393
+ *
394
+ * Measured on wonder-crm 2026-09-02, by recompiling three times against byte-identical sources: two
395
+ * of three derivations reported `changed` every time. Diffing two payloads leaf by leaf found exactly
396
+ * one differing value — `specification-artifacts` stamps `trace.evaluatedAt` with the wall-clock
397
+ * instant of the derivation, so its payload can never compare equal to its predecessor.
398
+ * (`application-domain-model` differed in **0** leaves, so the volatility is per-behavior, not
399
+ * general.)
400
+ *
401
+ * That is safe, and it is safe for a specific reason rather than by luck: `changed` only decides
402
+ * whether the notifier is INVITED to look. What it publishes is decided by `diffProjectedRows` over
403
+ * the projected ROWS, and `trace` sits outside this behavior's `rowsPath`. The live check confirms
404
+ * it — three touch-only recompilations produced `changedCount: 2` and **zero** publications.
405
+ *
406
+ * The alternative — excluding known-volatile keys here — was rejected: it would be a second, drifting
407
+ * description of what a row contains, when the projection already owns that answer. **But the
408
+ * guarantee rests on volatile fields staying OUT of the projected rows.** A behavior that put a
409
+ * timestamp INSIDE a row would push an update for every row on every recompilation, and nothing here
410
+ * would catch it — the diff would be correct and the data would be noise.
411
+ */
412
+ export function areDerivationPayloadsEqual(left, right) {
413
+ if (left === undefined || right === undefined)
414
+ return false;
415
+ return JSON.stringify(left.data) === JSON.stringify(right.data);
416
+ }
417
+ //# sourceMappingURL=introspection-derivation-state.companion.service.js.map