@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.
- package/dist/esm/.tsbuildinfo +1 -1
- package/dist/esm/claude-cli/models/coding-agent-dispatch.models.d.ts +12 -1
- package/dist/esm/claude-cli/models/coding-agent-dispatch.models.d.ts.map +1 -1
- package/dist/esm/claude-cli/models/coding-agent-dispatch.models.js +11 -0
- package/dist/esm/claude-cli/models/coding-agent-dispatch.models.js.map +1 -1
- package/dist/esm/claude-cli/services/coding-agent-dispatch.companion.service.d.ts +153 -1
- package/dist/esm/claude-cli/services/coding-agent-dispatch.companion.service.d.ts.map +1 -1
- package/dist/esm/claude-cli/services/coding-agent-dispatch.companion.service.js +419 -41
- package/dist/esm/claude-cli/services/coding-agent-dispatch.companion.service.js.map +1 -1
- package/dist/esm/claude-cli/services/research-agent-dispatch.companion.service.d.ts +25 -10
- package/dist/esm/claude-cli/services/research-agent-dispatch.companion.service.d.ts.map +1 -1
- package/dist/esm/claude-cli/services/research-agent-dispatch.companion.service.js +65 -24
- package/dist/esm/claude-cli/services/research-agent-dispatch.companion.service.js.map +1 -1
- package/dist/esm/claude-cli/services/research-evidence-store.companion.d.ts +86 -0
- package/dist/esm/claude-cli/services/research-evidence-store.companion.d.ts.map +1 -0
- package/dist/esm/claude-cli/services/research-evidence-store.companion.js +127 -0
- package/dist/esm/claude-cli/services/research-evidence-store.companion.js.map +1 -0
- package/dist/esm/companion-api/companion-api.schemas.d.ts +59 -2
- package/dist/esm/companion-api/companion-api.schemas.d.ts.map +1 -1
- package/dist/esm/companion-api/companion-api.schemas.js +60 -0
- package/dist/esm/companion-api/companion-api.schemas.js.map +1 -1
- package/dist/esm/companion-api/controllers/companion.controller.d.ts +63 -1
- package/dist/esm/companion-api/controllers/companion.controller.d.ts.map +1 -1
- package/dist/esm/companion-api/controllers/companion.controller.js +322 -21
- package/dist/esm/companion-api/controllers/companion.controller.js.map +1 -1
- package/dist/esm/core/inject/models/container.d.ts.map +1 -1
- package/dist/esm/core/inject/models/container.js +11 -0
- package/dist/esm/core/inject/models/container.js.map +1 -1
- package/dist/esm/core/inject/models/service-types.d.ts +5 -0
- package/dist/esm/core/inject/models/service-types.d.ts.map +1 -1
- package/dist/esm/core/inject/models/service-types.js +5 -0
- package/dist/esm/core/inject/models/service-types.js.map +1 -1
- package/dist/esm/core/introspection/behaviors/companion-introspection-behavior-definitions.d.ts.map +1 -1
- package/dist/esm/core/introspection/behaviors/companion-introspection-behavior-definitions.js +81 -0
- package/dist/esm/core/introspection/behaviors/companion-introspection-behavior-definitions.js.map +1 -1
- package/dist/esm/core/introspection/models/companion-introspection.models.d.ts +11 -1
- package/dist/esm/core/introspection/models/companion-introspection.models.d.ts.map +1 -1
- package/dist/esm/core/introspection/models/companion-introspection.models.js +39 -0
- package/dist/esm/core/introspection/models/companion-introspection.models.js.map +1 -1
- package/dist/esm/core/introspection/resources/creation-plane-dispatch.custom-impl.companion.service.d.ts +8 -0
- package/dist/esm/core/introspection/resources/creation-plane-dispatch.custom-impl.companion.service.d.ts.map +1 -0
- package/dist/esm/core/introspection/resources/creation-plane-dispatch.custom-impl.companion.service.js +317 -0
- package/dist/esm/core/introspection/resources/creation-plane-dispatch.custom-impl.companion.service.js.map +1 -0
- package/dist/esm/core/introspection/resources/creation-plane-projection.companion.service.d.ts +45 -0
- package/dist/esm/core/introspection/resources/creation-plane-projection.companion.service.d.ts.map +1 -0
- package/dist/esm/core/introspection/resources/creation-plane-projection.companion.service.js +250 -0
- package/dist/esm/core/introspection/resources/creation-plane-projection.companion.service.js.map +1 -0
- package/dist/esm/core/introspection/resources/introspection-resource-notifier.companion.service.d.ts +123 -0
- package/dist/esm/core/introspection/resources/introspection-resource-notifier.companion.service.d.ts.map +1 -0
- package/dist/esm/core/introspection/resources/introspection-resource-notifier.companion.service.js +298 -0
- package/dist/esm/core/introspection/resources/introspection-resource-notifier.companion.service.js.map +1 -0
- package/dist/esm/core/introspection/resources/introspection-resource-source.companion.service.d.ts +78 -1
- package/dist/esm/core/introspection/resources/introspection-resource-source.companion.service.d.ts.map +1 -1
- package/dist/esm/core/introspection/resources/introspection-resource-source.companion.service.js +155 -6
- package/dist/esm/core/introspection/resources/introspection-resource-source.companion.service.js.map +1 -1
- package/dist/esm/core/introspection/services/companion-introspection.companion.service.d.ts +131 -2
- package/dist/esm/core/introspection/services/companion-introspection.companion.service.d.ts.map +1 -1
- package/dist/esm/core/introspection/services/companion-introspection.companion.service.js +259 -9
- package/dist/esm/core/introspection/services/companion-introspection.companion.service.js.map +1 -1
- package/dist/esm/core/introspection/services/introspection-derivation-state.companion.service.d.ts +243 -0
- package/dist/esm/core/introspection/services/introspection-derivation-state.companion.service.d.ts.map +1 -0
- package/dist/esm/core/introspection/services/introspection-derivation-state.companion.service.js +417 -0
- package/dist/esm/core/introspection/services/introspection-derivation-state.companion.service.js.map +1 -0
- package/dist/esm/core/introspection/services/introspection-source-state.companion.service.d.ts +186 -0
- package/dist/esm/core/introspection/services/introspection-source-state.companion.service.d.ts.map +1 -0
- package/dist/esm/core/introspection/services/introspection-source-state.companion.service.js +368 -0
- package/dist/esm/core/introspection/services/introspection-source-state.companion.service.js.map +1 -0
- package/dist/esm/core/introspection/services/introspection-source-watcher.companion.service.d.ts +101 -0
- package/dist/esm/core/introspection/services/introspection-source-watcher.companion.service.d.ts.map +1 -0
- package/dist/esm/core/introspection/services/introspection-source-watcher.companion.service.js +278 -0
- package/dist/esm/core/introspection/services/introspection-source-watcher.companion.service.js.map +1 -0
- package/dist/esm/core/introspection/subprocess/application-domain-model.behavior.d.ts +365 -0
- package/dist/esm/core/introspection/subprocess/application-domain-model.behavior.d.ts.map +1 -0
- package/dist/esm/core/introspection/subprocess/application-domain-model.behavior.js +167 -0
- package/dist/esm/core/introspection/subprocess/application-domain-model.behavior.js.map +1 -0
- package/dist/esm/core/introspection/subprocess/companion-introspection-behavior-handlers.d.ts.map +1 -1
- package/dist/esm/core/introspection/subprocess/companion-introspection-behavior-handlers.js +332 -3
- package/dist/esm/core/introspection/subprocess/companion-introspection-behavior-handlers.js.map +1 -1
- package/dist/esm/core/introspection/subprocess/family-aspects.behavior.d.ts +19 -0
- package/dist/esm/core/introspection/subprocess/family-aspects.behavior.d.ts.map +1 -0
- package/dist/esm/core/introspection/subprocess/family-aspects.behavior.js +164 -0
- package/dist/esm/core/introspection/subprocess/family-aspects.behavior.js.map +1 -0
- package/dist/esm/core/introspection/subprocess/openapi-generation-input.behavior.d.ts +3 -1
- package/dist/esm/core/introspection/subprocess/openapi-generation-input.behavior.d.ts.map +1 -1
- package/dist/esm/core/introspection/subprocess/openapi-generation-input.behavior.js +36 -23
- package/dist/esm/core/introspection/subprocess/openapi-generation-input.behavior.js.map +1 -1
- package/dist/esm/core/introspection/subprocess/specification-artifacts.behavior.d.ts +51 -0
- package/dist/esm/core/introspection/subprocess/specification-artifacts.behavior.d.ts.map +1 -0
- package/dist/esm/core/introspection/subprocess/specification-artifacts.behavior.js +391 -0
- package/dist/esm/core/introspection/subprocess/specification-artifacts.behavior.js.map +1 -0
- package/dist/esm/core/runtime/companion-startup-assembly.d.ts.map +1 -1
- package/dist/esm/core/runtime/companion-startup-assembly.js +5 -0
- package/dist/esm/core/runtime/companion-startup-assembly.js.map +1 -1
- package/dist/esm/core/runtime/dev-compile-quiet.companion.d.ts +103 -0
- package/dist/esm/core/runtime/dev-compile-quiet.companion.d.ts.map +1 -0
- package/dist/esm/core/runtime/dev-compile-quiet.companion.js +124 -0
- package/dist/esm/core/runtime/dev-compile-quiet.companion.js.map +1 -0
- package/dist/esm/core/runtime/services/start-companion-application.service.d.ts +39 -2
- package/dist/esm/core/runtime/services/start-companion-application.service.d.ts.map +1 -1
- package/dist/esm/core/runtime/services/start-companion-application.service.js +122 -11
- package/dist/esm/core/runtime/services/start-companion-application.service.js.map +1 -1
- package/dist/esm/core/specifications/non-composite-view-specification-context.shared.d.ts +6 -0
- package/dist/esm/core/specifications/non-composite-view-specification-context.shared.d.ts.map +1 -1
- package/dist/esm/core/specifications/non-composite-view-specification-context.shared.js.map +1 -1
- package/dist/esm/core/specifications/specification-context-factory.shared.d.ts +23 -0
- package/dist/esm/core/specifications/specification-context-factory.shared.d.ts.map +1 -1
- package/dist/esm/core/specifications/specification-context-factory.shared.js +26 -4
- package/dist/esm/core/specifications/specification-context-factory.shared.js.map +1 -1
- package/dist/esm/executions/services/companion-executions.companion.service.d.ts +82 -3
- package/dist/esm/executions/services/companion-executions.companion.service.d.ts.map +1 -1
- package/dist/esm/executions/services/companion-executions.companion.service.js +126 -12
- package/dist/esm/executions/services/companion-executions.companion.service.js.map +1 -1
- package/dist/esm/i18n/components/APP_LAYOUTS_MAIN_CONTAINER.en.d.ts +12 -0
- package/dist/esm/i18n/components/APP_LAYOUTS_MAIN_CONTAINER.en.d.ts.map +1 -0
- package/dist/esm/i18n/components/APP_LAYOUTS_MAIN_CONTAINER.en.js +12 -0
- package/dist/esm/i18n/components/APP_LAYOUTS_MAIN_CONTAINER.en.js.map +1 -0
- package/dist/esm/i18n/components/LOW_LEVEL_FORM_FIELD.en.d.ts +1 -1
- package/dist/esm/i18n/components/LOW_LEVEL_FORM_FIELD.en.js +1 -1
- package/dist/esm/i18n/components/LOW_LEVEL_FORM_FIELD.en.js.map +1 -1
- package/dist/esm/i18n/composite_views/app.creation-board.en.d.ts +13 -0
- package/dist/esm/i18n/composite_views/app.creation-board.en.d.ts.map +1 -0
- package/dist/esm/i18n/composite_views/app.creation-board.en.js +91 -0
- package/dist/esm/i18n/composite_views/app.creation-board.en.js.map +1 -0
- package/dist/esm/i18n/composite_views/app.domain-model.en.d.ts +38 -0
- package/dist/esm/i18n/composite_views/app.domain-model.en.d.ts.map +1 -0
- package/dist/esm/i18n/composite_views/app.domain-model.en.js +41 -0
- package/dist/esm/i18n/composite_views/app.domain-model.en.js.map +1 -0
- package/dist/esm/i18n/index.d.ts +3 -3
- package/dist/esm/i18n/index.js +3 -3
- package/dist/esm/i18n/index.js.map +1 -1
- package/dist/esm/i18n/resources/wildoApplicationActorSystemExecutions.en.d.ts +24 -0
- package/dist/esm/i18n/resources/wildoApplicationActorSystemExecutions.en.d.ts.map +1 -0
- package/dist/esm/i18n/resources/wildoApplicationActorSystemExecutions.en.js +20 -0
- package/dist/esm/i18n/resources/wildoApplicationActorSystemExecutions.en.js.map +1 -0
- package/dist/esm/i18n/resources/wildoApplicationActorTasks.en.d.ts +31 -0
- package/dist/esm/i18n/resources/wildoApplicationActorTasks.en.d.ts.map +1 -0
- package/dist/esm/i18n/resources/wildoApplicationActorTasks.en.js +27 -0
- package/dist/esm/i18n/resources/wildoApplicationActorTasks.en.js.map +1 -0
- package/dist/esm/i18n/resources/wildoApplicationFlowSystemExecutions.en.d.ts +24 -0
- package/dist/esm/i18n/resources/wildoApplicationFlowSystemExecutions.en.d.ts.map +1 -0
- package/dist/esm/i18n/resources/wildoApplicationFlowSystemExecutions.en.js +20 -0
- package/dist/esm/i18n/resources/wildoApplicationFlowSystemExecutions.en.js.map +1 -0
- package/dist/esm/i18n/resources/workbenchBuildPlanTasks.en.d.ts +28 -0
- package/dist/esm/i18n/resources/workbenchBuildPlanTasks.en.d.ts.map +1 -0
- package/dist/esm/i18n/resources/workbenchBuildPlanTasks.en.js +24 -0
- package/dist/esm/i18n/resources/workbenchBuildPlanTasks.en.js.map +1 -0
- package/dist/esm/i18n/resources/workbenchDomainResources.en.d.ts +138 -0
- package/dist/esm/i18n/resources/workbenchDomainResources.en.d.ts.map +1 -0
- package/dist/esm/i18n/resources/workbenchDomainResources.en.js +100 -0
- package/dist/esm/i18n/resources/workbenchDomainResources.en.js.map +1 -0
- package/dist/esm/i18n/resources/workbenchPlaybooks.en.d.ts +29 -0
- package/dist/esm/i18n/resources/workbenchPlaybooks.en.d.ts.map +1 -0
- package/dist/esm/i18n/resources/workbenchPlaybooks.en.js +25 -0
- package/dist/esm/i18n/resources/workbenchPlaybooks.en.js.map +1 -0
- package/dist/esm/i18n/resources/workbenchRunWriteRecords.en.d.ts +27 -0
- package/dist/esm/i18n/resources/workbenchRunWriteRecords.en.d.ts.map +1 -0
- package/dist/esm/i18n/resources/workbenchRunWriteRecords.en.js +23 -0
- package/dist/esm/i18n/resources/workbenchRunWriteRecords.en.js.map +1 -0
- package/dist/esm/i18n/resources/workbenchSpecificationArtifacts.en.d.ts +806 -0
- package/dist/esm/i18n/resources/workbenchSpecificationArtifacts.en.d.ts.map +1 -0
- package/dist/esm/i18n/resources/workbenchSpecificationArtifacts.en.js +326 -0
- package/dist/esm/i18n/resources/workbenchSpecificationArtifacts.en.js.map +1 -0
- package/dist/esm/i18n/resources/workbenchTraceSessions.en.d.ts +26 -0
- package/dist/esm/i18n/resources/workbenchTraceSessions.en.d.ts.map +1 -0
- package/dist/esm/i18n/resources/workbenchTraceSessions.en.js +22 -0
- package/dist/esm/i18n/resources/workbenchTraceSessions.en.js.map +1 -0
- package/dist/esm/i18n/system_enums/market.en.d.ts +202 -0
- package/dist/esm/i18n/system_enums/market.en.d.ts.map +1 -0
- package/dist/esm/i18n/system_enums/market.en.js +209 -0
- package/dist/esm/i18n/system_enums/market.en.js.map +1 -0
- package/dist/esm/meta-workflows/models/application-coding-agent.actors-system.definitions.d.ts +112 -2
- package/dist/esm/meta-workflows/models/application-coding-agent.actors-system.definitions.d.ts.map +1 -1
- package/dist/esm/meta-workflows/models/application-coding-agent.actors-system.definitions.js +201 -34
- package/dist/esm/meta-workflows/models/application-coding-agent.actors-system.definitions.js.map +1 -1
- package/dist/esm/meta-workflows/models/application-research-agent.actors-system.definitions.d.ts +31 -3
- package/dist/esm/meta-workflows/models/application-research-agent.actors-system.definitions.d.ts.map +1 -1
- package/dist/esm/meta-workflows/models/application-research-agent.actors-system.definitions.js +48 -12
- package/dist/esm/meta-workflows/models/application-research-agent.actors-system.definitions.js.map +1 -1
- package/dist/esm/meta-workflows/models/brief-adequacy.actors-system.definitions.d.ts +36 -0
- package/dist/esm/meta-workflows/models/brief-adequacy.actors-system.definitions.d.ts.map +1 -0
- package/dist/esm/meta-workflows/models/brief-adequacy.actors-system.definitions.js +75 -0
- package/dist/esm/meta-workflows/models/brief-adequacy.actors-system.definitions.js.map +1 -0
- package/dist/esm/meta-workflows/services/application-build-dispatch.companion.service.d.ts +105 -7
- package/dist/esm/meta-workflows/services/application-build-dispatch.companion.service.d.ts.map +1 -1
- package/dist/esm/meta-workflows/services/application-build-dispatch.companion.service.js +298 -24
- package/dist/esm/meta-workflows/services/application-build-dispatch.companion.service.js.map +1 -1
- package/dist/esm/meta-workflows/services/application-build-generation-step.companion.service.d.ts +46 -3
- package/dist/esm/meta-workflows/services/application-build-generation-step.companion.service.d.ts.map +1 -1
- package/dist/esm/meta-workflows/services/application-build-generation-step.companion.service.js +95 -2
- package/dist/esm/meta-workflows/services/application-build-generation-step.companion.service.js.map +1 -1
- package/dist/esm/meta-workflows/services/execution-trace-read.companion.service.d.ts +9 -0
- package/dist/esm/meta-workflows/services/execution-trace-read.companion.service.d.ts.map +1 -1
- package/dist/esm/meta-workflows/services/execution-trace-read.companion.service.js +13 -0
- package/dist/esm/meta-workflows/services/execution-trace-read.companion.service.js.map +1 -1
- package/dist/esm/meta-workflows/services/playbook-run-write-register.companion.service.d.ts +12 -0
- package/dist/esm/meta-workflows/services/playbook-run-write-register.companion.service.d.ts.map +1 -1
- package/dist/esm/meta-workflows/services/playbook-run-write-register.companion.service.js +23 -0
- package/dist/esm/meta-workflows/services/playbook-run-write-register.companion.service.js.map +1 -1
- package/dist/esm/meta-workflows/services/playbook-run.companion.service.d.ts +120 -3
- package/dist/esm/meta-workflows/services/playbook-run.companion.service.d.ts.map +1 -1
- package/dist/esm/meta-workflows/services/playbook-run.companion.service.js +636 -81
- package/dist/esm/meta-workflows/services/playbook-run.companion.service.js.map +1 -1
- package/dist/esm/meta-workflows/services/playbook-suspended-run.companion.service.d.ts +40 -0
- package/dist/esm/meta-workflows/services/playbook-suspended-run.companion.service.d.ts.map +1 -1
- package/dist/esm/meta-workflows/services/playbook-suspended-run.companion.service.js +63 -1
- package/dist/esm/meta-workflows/services/playbook-suspended-run.companion.service.js.map +1 -1
- package/dist/esm/technical-doc/services/technical-doc.companion.service.d.ts +21 -0
- package/dist/esm/technical-doc/services/technical-doc.companion.service.d.ts.map +1 -1
- package/dist/esm/technical-doc/services/technical-doc.companion.service.js +86 -2
- package/dist/esm/technical-doc/services/technical-doc.companion.service.js.map +1 -1
- package/dist/esm/technical-doc/services/technical-documentation-application-derivation.companion.service.d.ts +12 -1
- package/dist/esm/technical-doc/services/technical-documentation-application-derivation.companion.service.d.ts.map +1 -1
- package/dist/esm/technical-doc/services/technical-documentation-application-derivation.companion.service.js +47 -1
- package/dist/esm/technical-doc/services/technical-documentation-application-derivation.companion.service.js.map +1 -1
- package/package.json +17 -17
- package/dist/esm/.builder.pid +0 -9
- package/dist/esm/i18n/resources/workbenchApplicationModules.en.d.ts +0 -36
- package/dist/esm/i18n/resources/workbenchApplicationModules.en.d.ts.map +0 -1
- package/dist/esm/i18n/resources/workbenchApplicationModules.en.js +0 -32
- package/dist/esm/i18n/resources/workbenchApplicationModules.en.js.map +0 -1
- package/dist/esm/i18n/resources/workbenchResourceRelationships.en.d.ts +0 -29
- package/dist/esm/i18n/resources/workbenchResourceRelationships.en.d.ts.map +0 -1
- package/dist/esm/i18n/resources/workbenchResourceRelationships.en.js +0 -25
- package/dist/esm/i18n/resources/workbenchResourceRelationships.en.js.map +0 -1
package/dist/esm/core/introspection/services/introspection-derivation-state.companion.service.d.ts
ADDED
|
@@ -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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"}
|
package/dist/esm/core/introspection/services/introspection-derivation-state.companion.service.js
ADDED
|
@@ -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
|