@rkmodules/rules 0.0.170 → 0.0.172

package/dist/lib/Engine/cache.d.ts

@@ -0,0 +1,58 @@
+import { Tree } from "../DataTree";
+import { CacheInfo, ClearCacheOptions, FunctionCall, PrimitiveFunction, RecOfTrees, RunOptions, VarRef } from "./types";
+export declare const cachePath: (path: string[]) => string;
+export declare function sameRecord(a: Record<string, any>, b: Record<string, any>): boolean;
+/** Compare immutable graph configuration, never runtime dependency trees.
+ * Preserve key order (interpolation observes it); opaque objects retain identity
+ * semantics. Cyclic configurations conservatively miss instead of recursing forever.
+ */
+export declare function sameConfiguration(a: any, b: any, ancestors?: Set<object>): boolean;
+interface PortMemo {
+    raw: VarRef;
+    paths: string[];
+    dependencies: unknown[];
+    tree: Tree<any>;
+}
+interface InterpolationMemo {
+    ports: Map<string, PortMemo>;
+    result: RecOfTrees;
+}
+interface ResultEntry {
+    definition: PrimitiveFunction;
+    impl: PrimitiveFunction["impl"];
+    metadata: Record<string, any>;
+    inputs: RecOfTrees;
+    params: Record<string, any>;
+    result: RecOfTrees;
+    info: CacheInfo;
+}
+interface Scope {
+    graph: string;
+    cacheKey: string;
+    generation: number;
+    run: number;
+    interpolation: Map<string, InterpolationMemo>;
+    pure: Map<string, ResultEntry>;
+    preview: Map<string, ResultEntry>;
+}
+export interface CacheRun {
+    scope: Scope;
+    generation: number;
+    run: number;
+    options: RunOptions;
+    visited: Set<string>;
+}
+/** Engine-owned caches; execution state is carried explicitly across async boundaries. */
+export declare class ExecutionCache {
+    private scopes;
+    begin(graph: string, options: RunOptions): CacheRun;
+    private current;
+    clear(options?: ClearCacheOptions): void;
+    visit(run: CacheRun, path: string[]): void;
+    finish(run: CacheRun): void;
+    interpolate(run: CacheRun, path: string[], raw: Record<string, VarRef>, scope: Record<string, RecOfTrees>, configuration?: boolean): RecOfTrees;
+    key(call: FunctionCall): Record<string, any>;
+    get(run: CacheRun, path: string[], kind: CacheInfo["kind"], fn: PrimitiveFunction, call: FunctionCall, inputs: RecOfTrees, params: Record<string, any>): ResultEntry | undefined;
+    set(run: CacheRun, path: string[], kind: CacheInfo["kind"], fn: PrimitiveFunction, call: FunctionCall, inputs: RecOfTrees, params: Record<string, any>, result: RecOfTrees, impl: PrimitiveFunction["impl"], createdAt: number): void;
+}
+export {};

package/dist/lib/Engine/index.d.ts

@@ -1,5 +1,5 @@
 import { Tree } from "../DataTree";
-import { GraphedFunction, NormalizedVarDef, PrimitiveFunction, AnyFunction, VarDef, VarRef, RecOfTrees, FunctionCall, ExecutionContext } from "./types";
+import { GraphedFunction, NormalizedVarDef, PrimitiveFunction, AnyFunction, VarDef, VarRef, RecOfTrees, FunctionCall, ExecutionContext, RunOptions, ClearCacheOptions, CacheInfo } from "./types";
 export * from "./types";
 export * from "./util";
 export interface Ref {
@@ -10,7 +10,13 @@ export interface Ref {
     refField: string;
 }
 export declare function normalizeVarDef(varDef: VarDef): NormalizedVarDef;
-export declare function getReferences(inputs: Record<string, VarRef>): Ref[];
+export declare function getReferences(inputs: Record<string, VarRef>): {
+    name: string;
+    path: string;
+    parts: string[];
+    refNode: string;
+    refField: string;
+}[];
 export declare function topSort(fn: GraphedFunction): GraphedFunction;
 export interface EngineStartEvent {
     name: string;
@@ -22,6 +28,8 @@ export interface EngineStartEvent {
     startTime: number;
 }
 export interface EngineEndEvent extends EngineStartEvent {
+    cached?: boolean;
+    cache?: CacheInfo;
     result: RecOfTrees;
     endTime: number;
     duration: number;
@@ -30,13 +38,19 @@ export type EngineEvent = EngineStartEvent | EngineEndEvent;
 export type EngineEventName = "result" | "functionCall" | "functionResult";
 export declare class Engine<Env extends Record<string, any> = Record<string, any>> {
     private fnIndex;
+    private graphDefinitions;
+    private automaticMounts;
     private listeners;
     private cache;
-    private cacheMiss;
+    private graphRunners;
+    private executions;
+    private latestRuns;
     private context;
     env: Env;
     constructor(morePrimitives?: Record<string, PrimitiveFunction>, env?: Env);
-    private checkCache;
+    /** Clear successful results; running calls finish but cannot refill invalidated entries. */
+    clearCache(options?: ClearCacheOptions): void;
+    private executeCall;
     private runGraph;
     /**
      * creates an function that can be evaluated by calling its implementation
@@ -45,7 +59,7 @@ export declare class Engine<Env extends Record<string, any> = Record<string, any
      * @returns
      */
     build(node: AnyFunction, id?: string): PrimitiveFunction;
-    mount(node: PrimitiveFunction): void | (() => void) | undefined;
+    mount(node: PrimitiveFunction, inputs?: Record<string, VarRef>, options?: RunOptions): void | (() => void) | undefined;
     getContext(): ExecutionContext | null;
     subscribe(eventName: "result", listener: (event: EngineEndEvent) => void): () => void;
     subscribe(eventName: "functionCall", listener: (event: EngineStartEvent) => void): () => void;
@@ -53,8 +67,8 @@ export declare class Engine<Env extends Record<string, any> = Record<string, any
     fireEvent(eventName: "result", event: EngineEndEvent): void;
     fireEvent(eventName: "functionCall", event: EngineStartEvent): void;
     fireEvent(eventName: "functionResult", event: EngineEndEvent): void;
-    run(node: AnyFunction, inputs?: Record<string, VarRef>): any;
-    runDetailed(node: AnyFunction, inputs?: Record<string, VarRef>): Promise<EngineEndEvent>;
+    run(node: AnyFunction, inputs?: Record<string, VarRef>, options?: RunOptions): Promise<RecOfTrees>;
+    runDetailed(node: AnyFunction, inputs?: Record<string, VarRef>, options?: RunOptions): Promise<EngineEndEvent>;
     getFunction(name: string): PrimitiveFunction | undefined;
     applyNodeDelete(oldFn: GraphedFunction, nodeIds: string[]): GraphedFunction;
     applyEdgeDelete(oldFn: GraphedFunction, fromNode: string, toNode: string, fromField: string, toField: string): GraphedFunction;

package/dist/lib/Engine/types.d.ts

@@ -34,6 +34,10 @@ export type RecOfTrees = Record<string, Tree<any>>;
  */
 export type PrimitiveFunction = {
     name: string;
+    /** Deterministic from immutable inputs, params and own call metadata; no side effects. */
+    pure?: boolean;
+    /** Allow stale results in explicit preview runs (e.g. external reads, never writes). */
+    previewCache?: boolean;
     label?: string;
     nodeType?: string | {
         name: string;
@@ -64,6 +68,10 @@ export type FunctionCall = {
 export type GraphedFunction = {
     name: string;
     label?: string;
+    nodeType?: string | {
+        name: string;
+        props: Record<string, any>;
+    };
     description?: string;
     params?: Record<string, VarDef>;
     inputs?: Record<string, VarDef>;
@@ -79,3 +87,19 @@ export interface ExecutionContext {
     timings: Record<string, number>;
     activations: Record<string, boolean>;
 }
+/** Preview caching is opt-in per run; cacheKey isolates external environments/sessions. */
+export interface RunOptions {
+    mode?: "normal" | "preview";
+    cacheKey?: string;
+}
+export interface ClearCacheOptions {
+    kind?: "all" | "pure" | "preview";
+    /** Root graph/function name, including all of its nested calls. */
+    graph?: string;
+    cacheKey?: string;
+}
+export interface CacheInfo {
+    kind: "pure" | "preview";
+    /** Wall-clock time at which the original successful execution completed. */
+    createdAt: number;
+}

package/dist/lib/Engine/util.d.ts

@@ -4,6 +4,8 @@ export declare function mergeWithOrder(...objects: Record<string, any>[]): Recor
 export declare function isReference(value: any): value is string;
 export declare function hasReference(value: any): value is string;
 export declare function parseReference(ref: string): string;
+/** Reference paths using the same literal-array and token rules as interpolation. */
+export declare function getReferencePaths(value: unknown): string[];
 export declare function uid(): string;
 export declare function getValue(obj: Record<string, any>, path: string): any;
 export declare function safeName(name: string): string;

package/dist/lib/hooks/useFunction.d.ts

@@ -1,18 +1,11 @@
-import { Engine, GraphedFunction } from "../Engine";
-/**
- * using functions
- *
- * in React context
- * - use useFunction. This will build the function, mount it if needed and provides a run function.
- *
- *
- * in Vanilla context
- * - use engine.build(fn) to build the function
- * - use engine.mount(fn) to mount the function (if it has a mount function)
- * - use await engine.run(fn, inputs) to run the function and get the result
+import { Engine, GraphedFunction, RunOptions } from "../Engine";
+/** Build a graph, optionally subscribe to triggers, and retain the latest run inputs.
+ * Preview caching requires { mode: "preview" }; refresh clears external preview
+ * results for this graph/session and reruns with the latest inputs.
  */
-export declare function useFunction(engine: Engine, fn: GraphedFunction, mount?: boolean): {
+export declare function useFunction(engine: Engine, fn: GraphedFunction, mount?: boolean, options?: RunOptions): {
     fn: import("../Engine").PrimitiveFunction;
-    run: (inputs?: Record<string, any>) => Promise<any>;
+    run: (inputs?: Record<string, any>) => Promise<import("../Engine").RecOfTrees>;
+    refresh: () => Promise<import("../Engine").RecOfTrees>;
     result: any;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rkmodules/rules",
-    "version": "0.0.170",
+    "version": "0.0.172",
     "main": "dist/index.cjs.js",
     "module": "dist/index.esm.mjs",
     "types": "./dist/index.d.ts",

package/readme.md

@@ -278,6 +278,30 @@ in Vanilla context
 - use engine.mount(fn) to mount the function (if it has a mount function)
 - use engine.run(fn, inputs) to run the function
 
+When passing a `GraphedFunction` directly to `engine.run`, treat the definition
+as immutable. A new graph object replaces the registered definition even when
+its name is unchanged; passing the same object again reuses its compiled
+function. The engine's graph-editing helpers return new graph objects.
+
+If you retain the compiled function returned by `engine.build`, passing that
+compiled function to `engine.run` continues to run its original graph version.
+Running an edited graph replaces subscriptions that the engine mounted
+automatically. If you call `engine.mount` yourself, use its returned cleanup
+callback to manage that subscription.
+
+Graph compilation discovers dependencies in node inputs, including references
+inside arrays, objects, data trees, and template strings. Calls execute after
+their dependencies regardless of their order in `body`, including when node IDs
+are numeric. The original graph is not reordered or mutated. Arrays of arrays
+remain literal data, matching interpolation.
+
+Missing referenced nodes, cycles, malformed reference paths, and unknown callable
+functions are rejected before the graph is registered, mounted, or executed.
+Custom functions must therefore be registered before building graphs that call
+them. Output references are checked too. Runtime input names and dynamic output
+fields do not require static port definitions. Node IDs must be distinct after
+`safeName` escaping, and `inputs` is reserved for the graph's public input scope.
+
 # considerations
 
 For Supa Lipu we have quite a lot of functions that need to be called on various events
@@ -297,3 +321,160 @@ For Supa Lipu we have quite a lot of functions that need to be called on various
 # Entries
 
 - in finance I had filterLine(on, match) function that filters return a boolean if any of the lines match. This is a hardcoded solition, which is ok for finance. But we might come up with something more generic
+
+## Execution caching and editor previews
+
+The engine memoizes interpolation and successful primitive results in memory.
+Custom primitives execute every time unless they explicitly opt in:
+
+```ts
+const lookupCustomer: PrimitiveFunction = {
+    name: "lookupCustomer",
+    pure: false,
+    previewCache: true,
+    impl: async ({ id }, params, engine) => ({
+        customer: { 0: [await engine.env.loadCustomer(id[0][0])] },
+    }),
+};
+
+// Normal execution: pure nodes may reuse results; external reads execute.
+await engine.run(rule, inputs);
+
+// Interactive editing: explicitly permitted external reads may also reuse results.
+const options = {
+    mode: "preview",
+    cacheKey: "editor-session/customer-account",
+} as const;
+await engine.run(rule, inputs, options);
+
+// Refresh external data, retaining independent pure results, then rerun.
+engine.clearCache({
+    kind: "preview",
+    graph: rule.name,
+    cacheKey: options.cacheKey,
+});
+await engine.run(rule, inputs, options);
+
+// Release all interpolation and result entries in this engine.
+engine.clearCache();
+```
+
+`pure: true` promises that the result depends only on immutable inputs, parameters,
+and the node's own call metadata (including dynamic port definitions). It must not
+read mutable environment state, the clock, randomness, or unrelated execution
+context, and must not perform side effects. Async functions can be pure. All 67
+built-in primitives have been audited: 60 are marked pure, and seven remain
+explicitly impure. See the inventory below. Custom primitives remain uncached
+unless they opt in.
+
+`previewCache: true` explicitly permits stale results during preview execution.
+Use it for external reads where stale values are acceptable, not writes, messages,
+or other actions that must happen on every run. Preview entries have no automatic
+expiry: refresh them explicitly. Normal runs never consume or replace preview-only
+entries. Pure entries may be reused in either mode. Nested graph wrappers always
+execute; their individual primitive children follow these policies.
+
+Treat graph definitions, inputs, parameters, and returned trees as immutable,
+including inside unmarked primitives and event listeners. Do not mutate cached
+outputs or upstream inputs. Update an object/array by replacing its reference.
+Graph input/output expressions, call parameters, and call metadata use `Object.is`
+first, then recursive value comparison for arrays and plain objects. Reloading an
+unchanged graph from JSON can therefore reuse cached results. Property and array
+order remain significant; opaque objects (such as class instances) retain identity
+semantics, and distinct cyclic configurations conservatively miss.
+Runtime inputs, evaluated defaults, and upstream dependency trees still use identity
+comparison: a new outer input map with the same port values can hit, but a newly
+allocated runtime object/array value misses even if deeply equal. Unchanged graph
+expressions retain their reference paths and skip repeated recursive discovery.
+Function-valued graph input defaults still execute each run before their returned
+values are memoized. In-place mutations are not detected.
+
+Caches belong to an engine, root graph/function name, and optional `cacheKey`.
+Nested invocation paths distinguish two uses of the same child graph. Use distinct
+keys for independent editor sessions or external environments, such as different
+accounts or credentials; the engine does not inspect environment changes. Change
+the key or clear the relevant cache when that environment changes. Graph names are
+registry identities: use distinct names for independent rules sharing an engine.
+Immutable graph edits retain unchanged node entries; changed inputs, params,
+implementation, or own call metadata cause misses. Removed locations are pruned
+after the latest successful run.
+
+Each scope keeps one previous successful entry per location and cache kind. There
+are at most 32 recently used root/key scopes, with up to 1,024 entries each for
+interpolation, pure results, and preview results. These are entry limits, not byte
+limits. Large trees can still retain substantial memory. `clearCache` also accepts
+`kind: "pure"` or `"all"`, plus optional `graph` and `cacheKey` filters.
+
+Only fulfilled results are stored. Overlapping misses execute independently;
+in-flight requests are not deduplicated or cancelled. An older run cannot overwrite
+a newer run's entries, and clearing a scope prevents its pending runs from refilling
+it. Those pending runs still return to their original callers. Invalidation is
+conservative: a run already in flight cannot add further entries of either kind
+in that scope. Events from overlapping runs can still arrive out of order; use
+execution IDs when correlating them. `runDetailed` returns its own execution's
+response directly.
+
+Cache hits emit `functionResult` with `cached: true` and
+`cache: { kind, createdAt }`, and populate the current execution context. The
+`createdAt` timestamp identifies the original successful computation. Event
+`duration` and context timings measure this run's work, not the original cached
+computation. `functionCall` fires only when a node executes. Direct primitive runs
+now also emit these events and a final `result` event. Graph result events continue
+to describe the current traversal rather than a cached whole graph.
+
+React editors can use the fourth `useFunction` argument:
+
+```tsx
+const { run, refresh, result } = useFunction(engine, rule, true, {
+    mode: "preview",
+    cacheKey: editorSessionId,
+});
+// Call run(inputs) when the rule or inputs change.
+// refresh() clears preview entries and reruns using this hook's latest inputs.
+<button onClick={() => refresh()}>Refresh external data</button>;
+```
+
+Calling the hook's `run()` without inputs also reuses its latest inputs. Mounted
+triggers retain that hook's latest inputs and options. For non-React callers,
+`engine.mount(compiled, initialInputs, options)` uses these values until a run of
+that compiled function supplies newer ones. Automatic mounts similarly use the
+latest run's inputs and options. The example editor and finance pages use preview
+mode and expose the refresh button; generic node previews show cache origin/time.
+
+### Built-in purity audit
+
+These classifications assume immutable data, parameters, and call definitions,
+including deterministic property access and value conversions. Functions may
+allocate objects, modify newly allocated local objects, and return references to
+immutable input branches. Those operations do not introduce external side effects.
+
+| Family   | Pure functions                                                                                                                                                        |
+| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Math     | `add`, `subtract`, `multiply`, `divide`, `modulo`, `pow`, `ceil`, `floor`, `round`, `sqrt`, `sinDeg`, `cosDeg`, `tanDeg`, `sum`, `equalTo`, `greaterThan`, `lessThan` |
+| Logic    | `booleanAnd`, `booleanOr`, `booleanNot`, `groupAnd`, `groupOr`, `groupStats`                                                                                          |
+| String   | `joinStrings`, `stringEqualTo`, `stringTemplate`, `toString`                                                                                                          |
+| List     | `listInput`, `listItem`, `listLength`, `filterList`, `relativeItem`, `relativeItems`, `concat`, `coalesce`, `uniqueItems`, `destructureList`                          |
+| Group    | `splitGroup`, `mergeGroup`, `groupAll`, `filterTree`, `treeItem`, `simplifyTree`, `normalizeTree`, `cartesianGroups`, `mergeTree`                                     |
+| JSON     | `object`, `setField`, `listToArray`, `arrayToList`, `mergeObject`, `objectEntries`, `explodeObject`, `destructureObject`                                              |
+| Sequence | `series`                                                                                                                                                              |
+| Util     | `value`, `getType`, `getValue`                                                                                                                                        |
+| I/O      | `inputs`, `output` (their implementations return empty output maps)                                                                                                   |
+| Date     | `duration` (arithmetic only)                                                                                                                                          |
+
+| Impure function | Why it remains uncached                                                                                                                                           |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `log`           | Console logging must occur on every evaluation. Its output tree retains the input identity, so downstream pure nodes can still hit their caches.                  |
+| `calc`          | MathJS expressions can use randomness, and failed evaluations log diagnostics. Pure expressions would need a separate restricted evaluator or eligibility policy. |
+| `today`         | Reads the current clock.                                                                                                                                          |
+| `parseDate`     | Falls back to the current clock for empty input, uses host date interpretation, and logs parsing.                                                                 |
+| `formatDate`    | Falls back to the current clock; omitted locale/timezone options depend on the host.                                                                              |
+| `isoDate`       | Falls back to the current clock for empty input.                                                                                                                  |
+
+`stringTemplate` reads its own dynamic input labels; these are already included
+in the result cache key. `mergeObject` only mutates freshly allocated output
+objects, and `setField` copies input objects before assigning fields.
+
+Purity does not imply correctness for every input: the existing out-of-order path
+normalization bug remains tracked separately, even though `normalizeTree` is
+deterministic and does not mutate its inputs. Date-default and other open
+regressions are likewise unchanged by this audit.