solve-engine 2.1.0 → 2.3.0

package/dist/{Configuration-B6W0-T67.d.cts → Configuration-Culg8H_o.d.cts}

@@ -171,6 +171,21 @@ interface DiagnosticConfig {
     /** Enable VM trace mode, emits per-opcode execution events (very verbose; disables some optimizations) */
     readonly vmTraceEnabled: boolean;
 }
+/**
+ * Proactive background refresh of live async values.
+ *
+ * Off by default. When a live value (a stock quote, an FX rate) has gone
+ * stale, today it only refetches on the next re-evaluation (a keystroke), so a
+ * note left open silently ages. With this enabled, the engine drives a refetch
+ * on each such value's own cadence (the resolver's `refetchIntervalMs`) for the
+ * values currently on screen, and pushes the fresh result to the host through
+ * the same event stream the pull path uses. It needs timers and a live editor
+ * consuming that stream, so a headless or batch host leaves it off.
+ */
+interface BackgroundRefreshConfig {
+    /** Master switch. When false, no timers run and every value refreshes only on re-evaluation. */
+    readonly enabled: boolean;
+}
 /**
  * Virtual Machine configuration.
  * Controls the internal bytecode VM that executes compiled expressions.
@@ -283,6 +298,8 @@ interface EngineConfig {
     readonly worker: WorkerConfig;
     /** Diagnostic pipeline configuration */
     readonly diagnostic: DiagnosticConfig;
+    /** Proactive background refresh of live async values */
+    readonly backgroundRefresh: BackgroundRefreshConfig;
 }
 /**
  * A partial {@link EngineConfig} override, one section at a time.

package/dist/{Configuration-B6W0-T67.d.ts → Configuration-Culg8H_o.d.ts}

@@ -171,6 +171,21 @@ interface DiagnosticConfig {
     /** Enable VM trace mode, emits per-opcode execution events (very verbose; disables some optimizations) */
     readonly vmTraceEnabled: boolean;
 }
+/**
+ * Proactive background refresh of live async values.
+ *
+ * Off by default. When a live value (a stock quote, an FX rate) has gone
+ * stale, today it only refetches on the next re-evaluation (a keystroke), so a
+ * note left open silently ages. With this enabled, the engine drives a refetch
+ * on each such value's own cadence (the resolver's `refetchIntervalMs`) for the
+ * values currently on screen, and pushes the fresh result to the host through
+ * the same event stream the pull path uses. It needs timers and a live editor
+ * consuming that stream, so a headless or batch host leaves it off.
+ */
+interface BackgroundRefreshConfig {
+    /** Master switch. When false, no timers run and every value refreshes only on re-evaluation. */
+    readonly enabled: boolean;
+}
 /**
  * Virtual Machine configuration.
  * Controls the internal bytecode VM that executes compiled expressions.
@@ -283,6 +298,8 @@ interface EngineConfig {
     readonly worker: WorkerConfig;
     /** Diagnostic pipeline configuration */
     readonly diagnostic: DiagnosticConfig;
+    /** Proactive background refresh of live async values */
+    readonly backgroundRefresh: BackgroundRefreshConfig;
 }
 /**
  * A partial {@link EngineConfig} override, one section at a time.

package/dist/{PackageCompatibility-Bn5jnBtA.d.cts → PackageCompatibility-CN-2CVhu.d.cts}

@@ -1,4 +1,4 @@
-import { I as IEnginePackage } from './PackageRegistry-dpdurBVO.cjs';
+import { I as IEnginePackage } from './PackageRegistry-DXsvmpQN.cjs';
 
 /**
  * Package load-time compatibility checking, the "detect overlapping

package/dist/{PackageCompatibility-CIvq2MP5.d.ts → PackageCompatibility-DbpyKYOe.d.ts}

@@ -1,4 +1,4 @@
-import { I as IEnginePackage } from './PackageRegistry-DzeiWcv4.js';
+import { I as IEnginePackage } from './PackageRegistry-jqdAsm6U.js';
 
 /**
  * Package load-time compatibility checking, the "detect overlapping

package/dist/{PackageRegistry-dpdurBVO.d.cts → PackageRegistry-DXsvmpQN.d.cts}

@@ -3,13 +3,13 @@ import { V as Value, b as ValueType } from './Value-CCi_Eecs.cjs';
 import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-B4C1qHXu.cjs';
 import { IAsyncResolver } from './resolvers.cjs';
 import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-DnlL7_8c.cjs';
-import { a as DependencyGraph, V as VM, D as DagSnapshot, b as EngineContext, S as ScopeManager, P as PluginFunctionHandler } from './ScopeManager-D7uMXbhS.cjs';
+import { D as DependencyGraph, V as VM, a as DagSnapshot, b as EngineContext, S as ScopeManager, P as PluginFunctionHandler } from './ScopeManager-t6SnP6Ce.cjs';
 import { a as BytecodeProgram } from './BytecodeBuilder-DGGeByAP.cjs';
 import { QueryClient } from '@tanstack/query-core';
 import { E as EngineError } from './EngineError-Ce1lPkjZ.cjs';
 import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-DCQicwWX.cjs';
 import { T as Token } from './Token-CbP_OutD.cjs';
-import { E as EngineConfigOverride, a as EngineConfig } from './Configuration-B6W0-T67.cjs';
+import { E as EngineConfigOverride, a as EngineConfig } from './Configuration-Culg8H_o.cjs';
 
 /**
  * One line's compiled bytecode, plus the variables it reads and writes.
@@ -1629,6 +1629,13 @@ declare class ExpressionEngine {
      * {@link makeLineContext} has something to read from.
      */
     setDocumentModel(doc: DocumentModel | null): void;
+    /**
+     * The `DocumentModel` this engine is currently wired to, or `null` when it
+     * is not driving one. Lets a caller that borrows the engine for a one-off
+     * incremental pass (see {@link evaluateDocument}) put back whatever a host
+     * had set, rather than assuming it was `null`.
+     */
+    getDocumentModel(): DocumentModel | null;
     /**
      * Build the {@link LineExecutionContext} passed to `executeBytecode()`
      * for a given line. `lineNumber = -1` (the existing sentinel
@@ -1683,6 +1690,17 @@ declare class ExpressionEngine {
      * DAG walk + re-evaluation pass. Replaces the old single-callback pattern.
      */
     private batcher;
+    /**
+     * Drives proactive background refresh of live values, or `null` when the
+     * host has not enabled it (the default). See {@link BackgroundRefreshManager}.
+     */
+    private readonly backgroundRefresh;
+    /**
+     * The signal a background re-evaluation is dispatched under. Never aborted
+     * (a background refetch is not tied to a keystroke), so the batcher treats
+     * its results as current; the manager's own timers are what stop the work.
+     */
+    private readonly backgroundRefreshSignal;
     /** Post-lexer token normalizer for phrase fusion, implicit multiply, etc. */
     private normalizer;
     /**
@@ -1841,6 +1859,18 @@ declare class ExpressionEngine {
      *    and fires typed events to all listeners.
      */
     private resolveAsync;
+    /**
+     * Start refreshing a value in the background if it declared a cadence and the
+     * host enabled background refresh. A no-op otherwise, so the pull path is
+     * unchanged for a headless host or a value that never wants it.
+     */
+    private registerBackgroundRefresh;
+    /**
+     * How many live values are currently being refreshed in the background.
+     * Zero when the host has not enabled background refresh. For hosts that want
+     * to surface it, and for tests.
+     */
+    getBackgroundRefreshCount(): number;
     /**
      * Unified parsing method that handles different input types and returns comprehensive results
      * with precise coordinate mapping for inline solves.
@@ -3087,4 +3117,4 @@ interface IEnginePackage {
     asConverters?: Record<string, (value: Value) => Value>;
 }
 
-export { type ApplyChangesResult as A, type BatcherMetrics as B, type CacheSnapshot as C, DocumentModel as D, ExpressionEngine as E, LanguageService as F, type LanguageServiceOptions as G, type SemanticToken as H, type IEnginePackage as I, type ParsingResult as J, type LineChange as L, type ParsedLine as P, SNAPSHOT_FORMAT as S, type UnifiedParsingOptions as U, type ViewportRange as V, type EngineOptions as a, type EngineRestoreOptions as b, type EngineSnapshot as c, type Explanation as d, type ExplanationStep as e, SNAPSHOT_VERSION as f, type SerializedAnonymousBody as g, type SerializedBytecode as h, type SerializedDecimal as i, type SerializedLineCacheEntry as j, type SerializedNumber as k, type SerializedRational as l, type SerializedUserFunction as m, type SerializedValue as n, SnapshotErrorCodes as o, type InlineSolvePosition as p, type AsyncCachePackageInfo as q, type AsyncErrorEvent as r, AsyncResolutionBatcher as s, type AsyncResolutionEvent as t, type BytecodeCacheEntry as u, type CheckpointSnapshot as v, type LineCacheEntryInfo as w, type LineState as x, type LinesUpdatedEvent as y, type CompletionItem as z };
+export { type ApplyChangesResult as A, type BatcherMetrics as B, type CompletionItem as C, DocumentModel as D, ExpressionEngine as E, type LineCacheEntryInfo as F, type LineState as G, type LinesUpdatedEvent as H, type IEnginePackage as I, type ParsedLine as J, LanguageService as L, type ParsingResult as P, SNAPSHOT_FORMAT as S, type UnifiedParsingOptions as U, type ViewportRange as V, type EngineOptions as a, type EngineRestoreOptions as b, type EngineSnapshot as c, type Explanation as d, type ExplanationStep as e, SNAPSHOT_VERSION as f, type SerializedAnonymousBody as g, type SerializedBytecode as h, type SerializedDecimal as i, type SerializedLineCacheEntry as j, type SerializedNumber as k, type SerializedRational as l, type SerializedUserFunction as m, type SerializedValue as n, SnapshotErrorCodes as o, type LanguageServiceOptions as p, type SemanticToken as q, type LineChange as r, type InlineSolvePosition as s, type AsyncCachePackageInfo as t, type AsyncErrorEvent as u, AsyncResolutionBatcher as v, type AsyncResolutionEvent as w, type BytecodeCacheEntry as x, type CacheSnapshot as y, type CheckpointSnapshot as z };

package/dist/{PackageRegistry-DzeiWcv4.d.ts → PackageRegistry-jqdAsm6U.d.ts}

@@ -3,13 +3,13 @@ import { V as Value, b as ValueType } from './Value-CCi_Eecs.js';
 import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-DKMlj7Sy.js';
 import { IAsyncResolver } from './resolvers.js';
 import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-DCWdZjGz.js';
-import { a as DependencyGraph, V as VM, D as DagSnapshot, b as EngineContext, S as ScopeManager, P as PluginFunctionHandler } from './ScopeManager-C2LDOrDx.js';
+import { D as DependencyGraph, V as VM, a as DagSnapshot, b as EngineContext, S as ScopeManager, P as PluginFunctionHandler } from './ScopeManager-DkpnlKuz.js';
 import { a as BytecodeProgram } from './BytecodeBuilder-DGGeByAP.js';
 import { QueryClient } from '@tanstack/query-core';
 import { E as EngineError } from './EngineError-Ce1lPkjZ.js';
 import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-72QmQlGx.js';
 import { T as Token } from './Token-CbP_OutD.js';
-import { E as EngineConfigOverride, a as EngineConfig } from './Configuration-B6W0-T67.js';
+import { E as EngineConfigOverride, a as EngineConfig } from './Configuration-Culg8H_o.js';
 
 /**
  * One line's compiled bytecode, plus the variables it reads and writes.
@@ -1629,6 +1629,13 @@ declare class ExpressionEngine {
      * {@link makeLineContext} has something to read from.
      */
     setDocumentModel(doc: DocumentModel | null): void;
+    /**
+     * The `DocumentModel` this engine is currently wired to, or `null` when it
+     * is not driving one. Lets a caller that borrows the engine for a one-off
+     * incremental pass (see {@link evaluateDocument}) put back whatever a host
+     * had set, rather than assuming it was `null`.
+     */
+    getDocumentModel(): DocumentModel | null;
     /**
      * Build the {@link LineExecutionContext} passed to `executeBytecode()`
      * for a given line. `lineNumber = -1` (the existing sentinel
@@ -1683,6 +1690,17 @@ declare class ExpressionEngine {
      * DAG walk + re-evaluation pass. Replaces the old single-callback pattern.
      */
     private batcher;
+    /**
+     * Drives proactive background refresh of live values, or `null` when the
+     * host has not enabled it (the default). See {@link BackgroundRefreshManager}.
+     */
+    private readonly backgroundRefresh;
+    /**
+     * The signal a background re-evaluation is dispatched under. Never aborted
+     * (a background refetch is not tied to a keystroke), so the batcher treats
+     * its results as current; the manager's own timers are what stop the work.
+     */
+    private readonly backgroundRefreshSignal;
     /** Post-lexer token normalizer for phrase fusion, implicit multiply, etc. */
     private normalizer;
     /**
@@ -1841,6 +1859,18 @@ declare class ExpressionEngine {
      *    and fires typed events to all listeners.
      */
     private resolveAsync;
+    /**
+     * Start refreshing a value in the background if it declared a cadence and the
+     * host enabled background refresh. A no-op otherwise, so the pull path is
+     * unchanged for a headless host or a value that never wants it.
+     */
+    private registerBackgroundRefresh;
+    /**
+     * How many live values are currently being refreshed in the background.
+     * Zero when the host has not enabled background refresh. For hosts that want
+     * to surface it, and for tests.
+     */
+    getBackgroundRefreshCount(): number;
     /**
      * Unified parsing method that handles different input types and returns comprehensive results
      * with precise coordinate mapping for inline solves.
@@ -3087,4 +3117,4 @@ interface IEnginePackage {
     asConverters?: Record<string, (value: Value) => Value>;
 }
 
-export { type ApplyChangesResult as A, type BatcherMetrics as B, type CacheSnapshot as C, DocumentModel as D, ExpressionEngine as E, LanguageService as F, type LanguageServiceOptions as G, type SemanticToken as H, type IEnginePackage as I, type ParsingResult as J, type LineChange as L, type ParsedLine as P, SNAPSHOT_FORMAT as S, type UnifiedParsingOptions as U, type ViewportRange as V, type EngineOptions as a, type EngineRestoreOptions as b, type EngineSnapshot as c, type Explanation as d, type ExplanationStep as e, SNAPSHOT_VERSION as f, type SerializedAnonymousBody as g, type SerializedBytecode as h, type SerializedDecimal as i, type SerializedLineCacheEntry as j, type SerializedNumber as k, type SerializedRational as l, type SerializedUserFunction as m, type SerializedValue as n, SnapshotErrorCodes as o, type InlineSolvePosition as p, type AsyncCachePackageInfo as q, type AsyncErrorEvent as r, AsyncResolutionBatcher as s, type AsyncResolutionEvent as t, type BytecodeCacheEntry as u, type CheckpointSnapshot as v, type LineCacheEntryInfo as w, type LineState as x, type LinesUpdatedEvent as y, type CompletionItem as z };
+export { type ApplyChangesResult as A, type BatcherMetrics as B, type CompletionItem as C, DocumentModel as D, ExpressionEngine as E, type LineCacheEntryInfo as F, type LineState as G, type LinesUpdatedEvent as H, type IEnginePackage as I, type ParsedLine as J, LanguageService as L, type ParsingResult as P, SNAPSHOT_FORMAT as S, type UnifiedParsingOptions as U, type ViewportRange as V, type EngineOptions as a, type EngineRestoreOptions as b, type EngineSnapshot as c, type Explanation as d, type ExplanationStep as e, SNAPSHOT_VERSION as f, type SerializedAnonymousBody as g, type SerializedBytecode as h, type SerializedDecimal as i, type SerializedLineCacheEntry as j, type SerializedNumber as k, type SerializedRational as l, type SerializedUserFunction as m, type SerializedValue as n, SnapshotErrorCodes as o, type LanguageServiceOptions as p, type SemanticToken as q, type LineChange as r, type InlineSolvePosition as s, type AsyncCachePackageInfo as t, type AsyncErrorEvent as u, AsyncResolutionBatcher as v, type AsyncResolutionEvent as w, type BytecodeCacheEntry as x, type CacheSnapshot as y, type CheckpointSnapshot as z };

package/dist/{ScopeManager-C2LDOrDx.d.ts → ScopeManager-DkpnlKuz.d.ts}

@@ -674,4 +674,4 @@ declare class ScopeManager {
     clear(): void;
 }
 
-export { type Bytecode as B, type DagSnapshot as D, type ExpressionRecord as E, OpRegistry as O, type PluginFunctionHandler as P, ScopeManager as S, type VM as V, DependencyGraph as a, type EngineContext as b, createVM as c, executeBytecode as e, sharedOpRegistry as s };
+export { type Bytecode as B, DependencyGraph as D, type ExpressionRecord as E, OpRegistry as O, type PluginFunctionHandler as P, ScopeManager as S, type VM as V, type DagSnapshot as a, type EngineContext as b, createVM as c, executeBytecode as e, sharedOpRegistry as s };

package/dist/{ScopeManager-D7uMXbhS.d.cts → ScopeManager-t6SnP6Ce.d.cts}

@@ -674,4 +674,4 @@ declare class ScopeManager {
     clear(): void;
 }
 
-export { type Bytecode as B, type DagSnapshot as D, type ExpressionRecord as E, OpRegistry as O, type PluginFunctionHandler as P, ScopeManager as S, type VM as V, DependencyGraph as a, type EngineContext as b, createVM as c, executeBytecode as e, sharedOpRegistry as s };
+export { type Bytecode as B, DependencyGraph as D, type ExpressionRecord as E, OpRegistry as O, type PluginFunctionHandler as P, ScopeManager as S, type VM as V, type DagSnapshot as a, type EngineContext as b, createVM as c, executeBytecode as e, sharedOpRegistry as s };

package/dist/{VMCheckpoints-I9jg3jWR.d.cts → VMCheckpoints-C_jQvABf.d.cts}

@@ -1,5 +1,5 @@
 import { V as Value } from './Value-CCi_Eecs.cjs';
-import { V as VM } from './ScopeManager-D7uMXbhS.cjs';
+import { V as VM } from './ScopeManager-t6SnP6Ce.cjs';
 import { U as UserFunctionDef } from './BytecodeBuilder-DGGeByAP.cjs';
 
 /**
@@ -168,4 +168,4 @@ declare class VMCheckpointer {
     get vmInstance(): VM;
 }
 
-export { VMCheckpointer as V, type VMCheckpoint as a };
+export { type VMCheckpoint as V, VMCheckpointer as a };

package/dist/{VMCheckpoints-CGyFhivM.d.ts → VMCheckpoints-CsHmQVaD.d.ts}

@@ -1,5 +1,5 @@
 import { V as Value } from './Value-CCi_Eecs.js';
-import { V as VM } from './ScopeManager-C2LDOrDx.js';
+import { V as VM } from './ScopeManager-DkpnlKuz.js';
 import { U as UserFunctionDef } from './BytecodeBuilder-DGGeByAP.js';
 
 /**
@@ -168,4 +168,4 @@ declare class VMCheckpointer {
     get vmInstance(): VM;
 }
 
-export { VMCheckpointer as V, type VMCheckpoint as a };
+export { type VMCheckpoint as V, VMCheckpointer as a };

package/dist/{chunk-7GK3XEZF.js → chunk-7E7NXKQ5.js}

@@ -1,2 +1,2 @@
-var n=class{constructor(){this.resolvers=new Map;}register(e){this.resolvers.has(e.namespace)&&(console.warn(`[ResolverRegistry] Namespace "${e.namespace}" already registered. Destroying old resolver and overwriting. Use distinct namespaces (e.g., "${e.namespace}:sub1", "${e.namespace}:sub2") to avoid collisions when a package needs multiple async resolvers.`),this.resolvers.get(e.namespace).destroy()),this.resolvers.set(e.namespace,e);}unregister(e,r){let s=this.resolvers.get(e);s&&(s.destroy(),this.resolvers.delete(e)),r&&r.removeQueries({queryKey:[e]});}preflightAll(e,r,s,i,l){for(let t of this.resolvers.values()){if(!t.preflight)continue;let o=t.preflight(e,r,s,i,l);if(o)return o}return null}get(e){return this.resolvers.get(e)}get size(){return this.resolvers.size}has(e){return this.resolvers.has(e)}clear(){for(let e of this.resolvers.values())e.destroy();this.resolvers.clear();}};export{n as a};//# sourceMappingURL=chunk-7GK3XEZF.js.map
-//# sourceMappingURL=chunk-7GK3XEZF.js.map
+var n=class{constructor(){this.resolvers=new Map;}register(e){this.resolvers.has(e.namespace)&&(console.warn(`[ResolverRegistry] Namespace "${e.namespace}" already registered. Destroying old resolver and overwriting. Use distinct namespaces (e.g., "${e.namespace}:sub1", "${e.namespace}:sub2") to avoid collisions when a package needs multiple async resolvers.`),this.resolvers.get(e.namespace).destroy()),this.resolvers.set(e.namespace,e);}unregister(e,r){let s=this.resolvers.get(e);s&&(s.destroy(),this.resolvers.delete(e)),r&&r.removeQueries({queryKey:[e]});}preflightAll(e,r,s,i,l){for(let t of this.resolvers.values()){if(!t.preflight)continue;let o=t.preflight(e,r,s,i,l);if(o)return o}return null}get(e){return this.resolvers.get(e)}get size(){return this.resolvers.size}has(e){return this.resolvers.has(e)}clear(){for(let e of this.resolvers.values())e.destroy();this.resolvers.clear();}};export{n as a};//# sourceMappingURL=chunk-7E7NXKQ5.js.map
+//# sourceMappingURL=chunk-7E7NXKQ5.js.map

package/dist/chunk-7E7NXKQ5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resolvers/ResolverRegistry.ts"],"names":["ResolverRegistry","resolver","namespace","queryClient","tokens","bytecode","packageId","signal","result"],"mappings":"AAqFO,IAAMA,EAAN,KAAuB,CAAvB,WAAA,EAAA,CACN,IAAA,CAAQ,UAAY,IAAI,IAAA,CAWxB,QAAA,CAASC,CAAAA,CAAgC,CAEpC,IAAA,CAAK,SAAA,CAAU,GAAA,CAAIA,CAAAA,CAAS,SAAS,CAAA,GACxC,OAAA,CAAQ,IAAA,CACP,CAAA,8BAAA,EAAiCA,EAAS,SAAS,CAAA,+FAAA,EAExCA,CAAAA,CAAS,SAAS,YAAYA,CAAAA,CAAS,SAAS,CAAA,0EAAA,CAE5D,CAAA,CACA,KAAK,SAAA,CAAU,GAAA,CAAIA,CAAAA,CAAS,SAAS,EAAG,OAAA,EAAQ,CAAA,CAEjD,IAAA,CAAK,SAAA,CAAU,IAAIA,CAAAA,CAAS,SAAA,CAAWA,CAAQ,EAChD,CAMA,UAAA,CAAWC,CAAAA,CAAmBC,CAAAA,CAAiC,CAC9D,IAAMF,CAAAA,CAAW,IAAA,CAAK,SAAA,CAAU,GAAA,CAAIC,CAAS,CAAA,CACzCD,CAAAA,GACHA,CAAAA,CAAS,OAAA,GACT,IAAA,CAAK,SAAA,CAAU,MAAA,CAAOC,CAAS,GAI5BC,CAAAA,EACHA,CAAAA,CAAY,aAAA,CAAc,CAAE,SAAU,CAACD,CAAS,CAAE,CAAC,EAErD,CASA,YAAA,CAAaE,CAAAA,CAAiBC,CAAAA,CAA2BC,EAAmBC,CAAAA,CAAqBJ,CAAAA,CAAmD,CACnJ,IAAA,IAAWF,KAAY,IAAA,CAAK,SAAA,CAAU,MAAA,EAAO,CAAG,CAC/C,GAAI,CAACA,CAAAA,CAAS,SAAA,CAAW,SACzB,IAAMO,CAAAA,CAASP,CAAAA,CAAS,SAAA,CAAUG,EAAQC,CAAAA,CAAUC,CAAAA,CAAWC,CAAAA,CAAQJ,CAAW,EAClF,GAAIK,CAAAA,CAAQ,OAAOA,CACpB,CACA,OAAO,IACR,CAMA,GAAA,CAAIN,EAA+C,CAClD,OAAO,IAAA,CAAK,SAAA,CAAU,IAAIA,CAAS,CACpC,CAGA,IAAI,MAAe,CAClB,OAAO,IAAA,CAAK,SAAA,CAAU,IACvB,CAKA,GAAA,CAAIA,CAAAA,CAA4B,CAC/B,OAAO,IAAA,CAAK,SAAA,CAAU,GAAA,CAAIA,CAAS,CACpC,CAMA,KAAA,EAAc,CACb,IAAA,IAAWD,KAAY,IAAA,CAAK,SAAA,CAAU,MAAA,EAAO,CAC5CA,EAAS,OAAA,EAAQ,CAElB,KAAK,SAAA,CAAU,KAAA,GAChB,CACD","file":"chunk-7E7NXKQ5.js","sourcesContent":["import type { QueryClient } from \"@tanstack/query-core\";\nimport type { Token } from \"@solve-js/lexer\";\nimport type { BytecodeProgram } from \"@solve-js/parser/BytecodeBuilder\";\nimport type { Value } from \"@solve-js/vm/Value\";\n\n/**\n * Result from a resolver's preflight() check.\n * Returned when async data is needed, the orchestrator uses this\n * to subscribe to the resolver and return a Pending value immediately.\n */\nexport interface AsyncCheckResult {\n\t/** Unique cache key for deduplication (e.g., \"{packageId}:rates:USD:GBP\") */\n\tqueryKey: string;\n\t/** Promise that resolves to the final Value */\n\tresolver: Promise<Value>;\n\t/** Package owning this resolver */\n\tpackageId: string;\n\t/** AbortSignal for stale-data prevention */\n\tsignal: AbortSignal;\n\t/** Optional metadata for diagnostics */\n\tmetadata?: Record<string, unknown>;\n\t/**\n\t * Cadence, in ms, at which this value wants proactive background refresh\n\t * (a live quote every minute, an FX rate every few minutes). Absent, or\n\t * paired with no {@link refetch}, means pull-only: the value refreshes on\n\t * re-evaluation, never on its own. Only acted on when the host has enabled\n\t * background refresh; see {@link BackgroundRefreshConfig}.\n\t */\n\trefetchIntervalMs?: number;\n\t/**\n\t * Force a fresh fetch of this exact query, bypassing `staleTime`, and return\n\t * the new value. Supplied alongside {@link refetchIntervalMs} so the engine\n\t * can drive the background refresh without re-scanning bytecode.\n\t */\n\trefetch?: () => Promise<Value>;\n}\n\n/**\n * Interface for async resolvers registered by packages/plugins.\n *\n * Each resolver handles a domain of async data (currency rates,\n * weather, stock prices, etc.). The preflight() method is called\n * BEFORE VM execution to check if all data is cached. If not,\n * it returns an AsyncCheckResult and the engine skips the VM,\n * returning a Pending value instead.\n */\nexport interface IAsyncResolver {\n\t/** Unique namespace for cache key scoping (e.g., \"currency\", \"weather\") */\n\treadonly namespace: string;\n\n\t/**\n\t * Pre-flight check: called BEFORE VM execution.\n\t *\n\t * Returns null if all data for this expression is cached and ready.\n\t * Returns an AsyncCheckResult if async work is needed.\n\t *\n\t * This method is synchronous, it only checks caches, never fetches.\n\t * If data is missing, it creates a Promise and returns immediately.\n\t *\n\t * @param tokens - The lexed tokens for the expression\n\t * @param bytecode - The compiled bytecode program\n\t * @param pluginId - The plugin ID (for cache key scoping)\n\t * @param signal - AbortSignal for the current evaluation\n\t */\n\tpreflight?(tokens: Token[], bytecode: BytecodeProgram, packageId: string, signal: AbortSignal, queryClient: QueryClient): AsyncCheckResult | null;\n\n\t/**\n\t * Called when the resolver's namespace is being unregistered.\n\t * Clean up any in-flight promises, clear caches, unsubscribe.\n\t */\n\tdestroy(): void;\n}\n\n/**\n * Registry of async resolvers, keyed by namespace.\n *\n * Plugins/packages register resolvers alongside their parselets\n * and opcode handlers. The engine calls preflightAll() before\n * VM execution to short-circuit async expressions.\n *\n * Lifecycle:\n * - register(), when a package is loaded\n * - unregister(), when a package is unloaded (clears cache entries)\n * - clear(), on document switch (clears all resolvers)\n */\nexport class ResolverRegistry {\n\tprivate resolvers = new Map<string, IAsyncResolver>();\n\n\t/**\n\t * Register an async resolver.\n\t *\n\t * Each resolver must have a unique `namespace`. If a resolver with the\n\t * same namespace is already registered, the old one is destroyed and\n\t * replaced (with a console warning). Packages that need multiple async\n\t * operations should use `asyncResolvers: [...]` with distinct namespaces\n\t * (e.g., `\"weather:current\"`, `\"weather:forecast\"`).\n\t */\n\tregister(resolver: IAsyncResolver): void {\n\t\t// Clean up previous resolver with same namespace if any\n\t\tif (this.resolvers.has(resolver.namespace)) {\n\t\t\tconsole.warn(\n\t\t\t\t`[ResolverRegistry] Namespace \"${resolver.namespace}\" already registered. ` +\n\t\t\t\t`Destroying old resolver and overwriting. Use distinct namespaces ` +\n\t\t\t\t`(e.g., \"${resolver.namespace}:sub1\", \"${resolver.namespace}:sub2\") ` +\n\t\t\t\t`to avoid collisions when a package needs multiple async resolvers.`,\n\t\t\t);\n\t\t\tthis.resolvers.get(resolver.namespace)!.destroy();\n\t\t}\n\t\tthis.resolvers.set(resolver.namespace, resolver);\n\t}\n\n\t/**\n\t * Unregister a resolver by namespace.\n\t * Calls destroy() and clears all cache entries with that namespace prefix.\n\t */\n\tunregister(namespace: string, queryClient?: QueryClient): void {\n\t\tconst resolver = this.resolvers.get(namespace);\n\t\tif (resolver) {\n\t\t\tresolver.destroy();\n\t\t\tthis.resolvers.delete(namespace);\n\t\t}\n\t\t// Clear all cache entries for this namespace via TanStack Query\n\t\t// Hierarchical keys: [\"osrs\"] clears all [\"osrs\", ...] queries\n\t\tif (queryClient) {\n\t\t\tqueryClient.removeQueries({ queryKey: [namespace] });\n\t\t}\n\t}\n\n\t/**\n\t * Run all registered resolvers' preflight checks against compiled bytecode.\n\t *\n\t * Returns the first AsyncCheckResult found, or null if all data is ready.\n\t * Short-circuits on first pending, subsequent pending ops will be\n\t * discovered on re-evaluation when the first resolves.\n\t */\n\tpreflightAll(tokens: Token[], bytecode: BytecodeProgram, packageId: string, signal: AbortSignal, queryClient: QueryClient): AsyncCheckResult | null {\n\t\tfor (const resolver of this.resolvers.values()) {\n\t\t\tif (!resolver.preflight) continue;\n\t\t\tconst result = resolver.preflight(tokens, bytecode, packageId, signal, queryClient);\n\t\t\tif (result) return result;\n\t\t}\n\t\treturn null;\n\t}\n\n\t/**\n\t * Get a resolver by namespace.\n\t * Returns undefined if no resolver is registered for that namespace.\n\t */\n\tget(namespace: string): IAsyncResolver | undefined {\n\t\treturn this.resolvers.get(namespace);\n\t}\n\n\t/** Number of registered resolvers. */\n\tget size(): number {\n\t\treturn this.resolvers.size;\n\t}\n\n\t/**\n\t * Check if a resolver is registered for the given namespace.\n\t */\n\thas(namespace: string): boolean {\n\t\treturn this.resolvers.has(namespace);\n\t}\n\n\t/**\n\t * Clear all resolvers (document switch, engine reset).\n\t * Calls destroy() on each resolver and clears the map.\n\t */\n\tclear(): void {\n\t\tfor (const resolver of this.resolvers.values()) {\n\t\t\tresolver.destroy();\n\t\t}\n\t\tthis.resolvers.clear();\n\t}\n}\n"]}