@rasputin-ai/node 0.5.0-alpha.6 → 0.5.0-alpha.7

package/dist/index.js

@@ -133,7 +133,7 @@ var definitionFromEncodedPlan = (plan) => {
 var estimatedCallBytesFor = (functionId) => EVENT_PAIR_BASE_ESTIMATED_BYTES + Buffer.byteLength(functionId, "utf8") * 2;
 
 // src/auto-instrumentation/instrumentation-manifest-registry.ts
-var INSTRUMENTATION_MANIFEST_SYMBOL = "rasputin.instrumentation.manifest.v2";
+var INSTRUMENTATION_MANIFEST_SYMBOL = "rasputin.instrumentation.manifest.v3";
 var registrySymbol = Symbol.for(INSTRUMENTATION_MANIFEST_SYMBOL);
 var getRegistry = () => {
   const existing = Reflect.get(globalThis, registrySymbol);
@@ -190,6 +190,7 @@ var snapshotInstrumentationManifest = (options = {}) => {
   const functions = [];
   const callSites = [];
   const destructures = [];
+  const derivationPlans = [];
   for (const delta of getRegistry().files.values()) {
     for (const fn of delta.functions) {
       const definition = definitionFromEncodedPlan(fn.plan);
@@ -241,6 +242,7 @@ var snapshotInstrumentationManifest = (options = {}) => {
         binding: destructure.binding
       });
     }
+    derivationPlans.push(...delta.derivationPlans ?? []);
   }
   const registry = getRegistry();
   if (registry.prebuilt && registry.files.size === 0) {
@@ -268,7 +270,8 @@ var snapshotInstrumentationManifest = (options = {}) => {
     } : {},
     functions,
     callSites,
-    destructures
+    destructures,
+    derivationPlans
   };
 };
 var markInstrumentationManifestUploaded = (generation) => {
@@ -384,7 +387,12 @@ var scheduleInstrumentationManifestUpload = (options) => {
 
 // src/execution-recorder/execution-recorder.ts
 import { AsyncLocalStorage } from "node:async_hooks";
-import { runtimeFunctionId as runtimeFunctionId2 } from "@rasputin-ai/core";
+import {
+  capturedValueCompleteness,
+  hashInstrumentationManifest,
+  rasputinOmitted,
+  runtimeFunctionId as runtimeFunctionId2
+} from "@rasputin-ai/core";
 
 // src/execution-recorder/execution-journal.ts
 var KIND_ENTER = 1;
@@ -1415,6 +1423,7 @@ var createSourceExclusionMatcher = (exclusions) => {
 
 // src/execution-recorder/execution-recorder.ts
 var DEFAULT_MAX_ACTIVE_MEMORY_BYTES = 64 * 1024 * 1024;
+var DERIVATION_ROOT_RECORD_BYTES = 64;
 var phaseTimingEnabled = process.env.RASPUTIN_RECORDER_PHASE_TIMING === "1";
 var manualFunctionDefinition = (value) => {
   const located = /^(.+):([^:@]+)@(\d+):(\d+)$/.exec(value);
@@ -1527,7 +1536,16 @@ var emptyStats = {
   journalPoolHits: 0,
   journalPoolMisses: 0,
   journalPoolSize: 0,
-  journalAllocatedCapacity: 0
+  journalAllocatedCapacity: 0,
+  derivationCandidateFunctions: 0,
+  derivationElidedFunctionCalls: 0,
+  derivationRootsCaptured: 0,
+  derivationControlFactsCaptured: 0,
+  derivationValuesAvoided: 0,
+  derivationFallbackFunctions: 0,
+  derivationFallbackExpressions: 0,
+  derivationFallbackReasons: {},
+  derivationRootBytes: 0
 };
 var noOpExecution = {
   createScope: () => ({
@@ -1543,7 +1561,8 @@ var noOpExecution = {
   prepareFunctionPlans: () => [],
   runPreparedFunction: (_plan, _args, callback) => callback(),
   trace: (_functionId, fn) => fn,
-  getStats: () => ({ ...emptyStats })
+  getStats: () => ({ ...emptyStats, derivationFallbackReasons: {} }),
+  captureDerivationRoot: (_rootId, value) => value
 };
 var mergeExecutionMetadata = (target, metadata) => {
   if (metadata.kind) target.kind = metadata.kind;
@@ -1608,7 +1627,16 @@ var createExecutionRecorder = (options) => {
     partialErrorSnapshots: 0,
     measuredExecutions: 0,
     totalInlineWallTimeMs: 0,
-    maxInlineWallTimeMs: 0
+    maxInlineWallTimeMs: 0,
+    derivationCandidateFunctions: 0,
+    derivationElidedFunctionCalls: 0,
+    derivationRootsCaptured: 0,
+    derivationControlFactsCaptured: 0,
+    derivationValuesAvoided: 0,
+    derivationFallbackFunctions: 0,
+    derivationFallbackExpressions: 0,
+    derivationFallbackReasons: {},
+    derivationRootBytes: 0
   };
   const addPhase = (key, nanoseconds) => {
     if (phases && nanoseconds > 0n) phases[key] += nanoseconds;
@@ -1660,17 +1688,56 @@ var createExecutionRecorder = (options) => {
     preparedModules.set(plans, prepared);
     return prepared;
   };
+  const derivationMetrics = (recording) => {
+    const manifest = snapshotInstrumentationManifest();
+    const plans = manifest?.derivationPlans ?? [];
+    const reasons = { ...stats.derivationFallbackReasons };
+    return {
+      derivationCandidateFunctions: plans.filter((plan) => !plan.fallbackReason).length,
+      derivationElidedFunctionCalls: stats.derivationElidedFunctionCalls,
+      derivationRootsCaptured: recording.derivationRoots.length,
+      derivationControlFactsCaptured: stats.derivationControlFactsCaptured,
+      derivationValuesAvoided: stats.derivationValuesAvoided,
+      derivationFallbackFunctions: plans.filter((plan) => plan.fallbackReason).length,
+      derivationFallbackExpressions: recording.derivationRoots.length,
+      derivationFallbackReasons: reasons,
+      derivationRootBytes: recording.derivationRootBytes
+    };
+  };
+  const resolveCaptureMode = (recording) => {
+    if (recording.derivationRoots.length > 0) return "derivation";
+    const plans = snapshotInstrumentationManifest()?.derivationPlans ?? [];
+    if (recording.sawAutomatic && plans.some(
+      (plan) => !plan.fallbackReason && recording.executedFunctionIds.has(plan.functionId)
+    )) {
+      return "derivation";
+    }
+    if (recording.sawAutomatic) return "automatic-full";
+    if (recording.sawManual) return "manual";
+    return "scope-only";
+  };
+  const derivationCapture = (recording) => {
+    const manifest = snapshotInstrumentationManifest();
+    if (!manifest) return void 0;
+    return {
+      manifestHash: hashInstrumentationManifest(manifest),
+      roots: recording.derivationRoots.slice(),
+      controlFacts: []
+    };
+  };
   const stateFrom = (recording, endedAtNs = process.hrtime.bigint()) => {
     const recorderStartedAtNs = process.hrtime.bigint();
     let events = [];
     let functions = [];
     let truncated;
     let capture;
+    let derivation;
     if (recording.cachedState) {
       events = recording.cachedState.events;
       functions = recording.cachedState.functions;
       truncated = recording.cachedState.truncated;
       capture = recording.cachedState.capture;
+      derivation = recording.cachedState.derivation;
     } else {
       if (recording.journal) {
         const materialized = recording.journal.materialize(plansByRuntimeId, recording.startedAtNs);
@@ -1684,18 +1751,20 @@ var createExecutionRecorder = (options) => {
         valuesDropped: recording.memory.valuesDropped,
         eventsDropped: recording.memory.eventsDropped
       } : void 0;
+      derivation = derivationCapture(recording);
       if (recording.finished && recording.inFlightCalls === 0 && recording.journal) {
-        recording.cachedState = { events, functions, truncated, capture };
+        recording.cachedState = { events, functions, truncated, capture, derivation };
         journalPool.release(recording.journal);
         recording.journal = void 0;
       }
     }
     const state = {
-      version: 2,
+      version: 3,
+      captureMode: resolveCaptureMode(recording),
       executionId: recording.executionId,
       startedAt: recording.startedAt,
       durationMs: elapsedMs2(recording.startedAtNs, endedAtNs),
-      recorder: { inlineWallTimeMs: 0 },
+      recorder: { inlineWallTimeMs: 0, derivation: derivationMetrics(recording) },
       execution: {
         ...recording.execution,
         ...recording.execution.request ? { request: { ...recording.execution.request } } : {}
@@ -1703,12 +1772,16 @@ var createExecutionRecorder = (options) => {
       functions: functions.slice(),
       events: events.slice(),
       ...truncated ? { truncated: { ...truncated } } : {},
-      ...capture ? { capture: { ...capture } } : {}
+      ...capture ? { capture: { ...capture } } : {},
+      ...derivation ? { derivation: { ...derivation, roots: derivation.roots.slice() } } : {}
     };
     if (phaseTimingEnabled)
       addPhase("materializeNs", process.hrtime.bigint() - recorderStartedAtNs);
     addRecorderTime(recording, process.hrtime.bigint() - recorderStartedAtNs);
-    state.recorder = { inlineWallTimeMs: roundedMilliseconds2(recording.inlineRecorderTimeNs) };
+    state.recorder = {
+      inlineWallTimeMs: roundedMilliseconds2(recording.inlineRecorderTimeNs),
+      derivation: derivationMetrics(recording)
+    };
     return state;
   };
   const rememberError = (error, recording) => {
@@ -1893,7 +1966,12 @@ var createExecutionRecorder = (options) => {
         finished: false,
         hasError: false,
         memory: memoryBudget.startExecution(),
-        partialSnapshotCounted: false
+        partialSnapshotCounted: false,
+        derivationRoots: [],
+        derivationRootBytes: 0,
+        sawAutomatic: false,
+        sawManual: false,
+        executedFunctionIds: /* @__PURE__ */ new Set()
       };
       stats.activeExecutions++;
       stats.peakActiveExecutions = Math.max(stats.peakActiveExecutions, stats.activeExecutions);
@@ -1955,7 +2033,7 @@ var createExecutionRecorder = (options) => {
       return void 0;
     }
   };
-  const runPreparedFunction = (plan, args, callback) => {
+  const runPreparedFunction = (plan, args, callback, omitValues) => {
     const store = storage.getStore();
     if (!store || store.recording.finished) return callback();
     stats.functionCallsObserved++;
@@ -2064,7 +2142,7 @@ var createExecutionRecorder = (options) => {
     }
     const callId = ++recording.nextCallId;
     const enterTimestampNs = process.hrtime.bigint() - recording.startedAtNs;
-    const capturedArgs = Array.from(args, (argument) => captureValue(recording, argument));
+    const capturedArgs = omitValues ? Array.from(args, () => rasputinOmitted()) : Array.from(args, (argument) => captureValue(recording, argument));
     journal.startCall(plan.runtimePlanId, callId, parentCallId, enterTimestampNs, capturedArgs);
     const callStore = { recording, currentCallId: callId };
     return runStore(
@@ -2077,7 +2155,7 @@ var createExecutionRecorder = (options) => {
           if (recording.journal) {
             const timestampNs = process.hrtime.bigint() - recording.startedAtNs;
             const durationNs = process.hrtime.bigint() - startedAtNs;
-            const returnValue = captureValue(recording, value);
+            const returnValue = omitValues ? rasputinOmitted() : captureValue(recording, value);
             recording.journal.finishCall(KIND_EXIT, callId, timestampNs, durationNs, returnValue);
             stats.functionCallsCaptured++;
           }
@@ -2105,19 +2183,60 @@ var createExecutionRecorder = (options) => {
       )
     );
   };
-  const runFunction = (input, args, callback) => runPreparedFunction(preparePlan(normalizeFunctionDefinition(input)), args, callback);
-  const runFunctionPlans = (plans, planIndex, args, callback) => {
+  const runFunction = (input, args, callback) => {
+    const store = storage.getStore();
+    if (store && !store.recording.finished) store.recording.sawManual = true;
+    return runPreparedFunction(preparePlan(normalizeFunctionDefinition(input)), args, callback);
+  };
+  const runFunctionPlans = (plans, planIndex, args, callback, omitValues) => {
+    const store = storage.getStore();
     const plan = preparedPlansFor(plans)[planIndex];
-    return plan ? runPreparedFunction(plan, args, callback) : callback();
+    if (store && !store.recording.finished) {
+      store.recording.sawAutomatic = true;
+      if (plan) store.recording.executedFunctionIds.add(plan.functionId);
+    }
+    return plan ? runPreparedFunction(plan, args, callback, omitValues) : callback();
   };
   const prepareFunctionPlans = (plans) => preparedPlansFor(plans);
   function trace(input, fn) {
     const definition = typeof input === "string" ? manualFunctionDefinition(input) : { ...input, functionId: runtimeFunctionId2(input) };
     const plan = preparePlan(definition);
     return function traced(...args) {
+      const store = storage.getStore();
+      if (store && !store.recording.finished) store.recording.sawManual = true;
       return runPreparedFunction(plan, args, () => fn.apply(this, args));
     };
   }
+  const captureDerivationRoot = (rootId, value) => {
+    const store = storage.getStore();
+    if (!store || store.recording.finished || store.suppressCapture) return value;
+    const recording = store.recording;
+    if (recording.memory.mode !== "full") return value;
+    if (recording.derivationRoots.length >= maxEventsPerExecution) return value;
+    const recorderStartedAtNs = process.hrtime.bigint();
+    try {
+      const serialized = captureValue(recording, value);
+      if (recording.memory.mode !== "full") return value;
+      if (!memoryBudget.reserveStorage(recording.memory, DERIVATION_ROOT_RECORD_BYTES)) {
+        return value;
+      }
+      const completeness = capturedValueCompleteness(serialized);
+      const bytes = jsonLiteralUtf8Bytes(serialized);
+      recording.derivationRoots.push({
+        rootId,
+        callId: store.currentCallId ?? 0,
+        value: serialized,
+        completeness
+      });
+      recording.derivationRootBytes += bytes;
+      stats.derivationRootsCaptured++;
+      stats.derivationRootBytes += bytes;
+      stats.derivationFallbackExpressions++;
+      return value;
+    } finally {
+      addRecorderTime(recording, process.hrtime.bigint() - recorderStartedAtNs);
+    }
+  };
   return {
     createScope,
     run,
@@ -2127,21 +2246,30 @@ var createExecutionRecorder = (options) => {
     prepareFunctionPlans,
     runPreparedFunction,
     trace,
-    getStats: () => ({
-      ...stats,
-      ...memoryBudget.getStats(),
-      ...journalPool.stats(),
-      ...phases ? {
-        phaseAlsNs: Number(phases.alsNs),
-        phaseMaterializeNs: Number(phases.materializeNs)
-      } : {}
-    })
+    captureDerivationRoot,
+    getStats: () => {
+      const manifest = snapshotInstrumentationManifest();
+      const plans = manifest?.derivationPlans ?? [];
+      return {
+        ...stats,
+        ...memoryBudget.getStats(),
+        ...journalPool.stats(),
+        derivationCandidateFunctions: plans.filter((plan) => !plan.fallbackReason).length,
+        derivationFallbackFunctions: plans.filter((plan) => plan.fallbackReason).length,
+        derivationFallbackReasons: { ...stats.derivationFallbackReasons },
+        ...phases ? {
+          phaseAlsNs: Number(phases.alsNs),
+          phaseMaterializeNs: Number(phases.materializeNs)
+        } : {}
+      };
+    }
   };
 };
 
 // src/execution-recorder/automatic-runtime.ts
 var AUTOMATIC_RUNTIME_SYMBOL = "rasputin.execution.runtime.v2";
 var runtimeSymbol = Symbol.for(AUTOMATIC_RUNTIME_SYMBOL);
+var passthroughCapture = (_rootId, value) => value;
 var passthrough = (_planIndex, _args, callback) => callback();
 var bindPassthrough = (module) => {
   module.cell.run = passthrough;
@@ -2152,12 +2280,13 @@ var registerModule = (registry, plans) => {
   const module = { plans, cell };
   registry.modules.push(module);
   registry.runtimes.at(-1)?.bind(module);
-  return (planIndex, args, callback) => cell.run(planIndex, args, callback);
+  return (planIndex, args, callback, omitValues) => cell.run(planIndex, args, callback, omitValues);
 };
 var createRegistry = () => {
   const registry = {
     runtimes: [],
     modules: [],
+    captureRoot: passthroughCapture,
     register(plans) {
       return registerModule(registry, plans);
     }
@@ -2166,7 +2295,12 @@ var createRegistry = () => {
 };
 var getAutomaticRuntimeRegistry = () => {
   const existing = Reflect.get(globalThis, runtimeSymbol);
-  if (existing && typeof existing === "object" && isRegistry(existing)) return existing;
+  if (existing && typeof existing === "object" && isRegistry(existing)) {
+    if (typeof existing.captureRoot !== "function") {
+      existing.captureRoot = passthroughCapture;
+    }
+    return existing;
+  }
   const registry = createRegistry();
   Reflect.set(globalThis, runtimeSymbol, registry);
   return registry;
@@ -2175,19 +2309,18 @@ var installAutomaticExecutionRuntime = (execution) => {
   const registry = getAutomaticRuntimeRegistry();
   const runtime = {
     bind(module) {
-      const prepared = execution.prepareFunctionPlans(module.plans);
-      module.cell.run = (planIndex, args, callback) => {
-        const plan = prepared[planIndex];
-        return plan ? execution.runPreparedFunction(plan, args, callback) : callback();
-      };
-    }
+      module.cell.run = (planIndex, args, callback, omitValues) => execution.runFunctionPlans(module.plans, planIndex, args, callback, omitValues);
+    },
+    captureRoot: (rootId, value) => execution.captureDerivationRoot(rootId, value)
   };
   registry.runtimes.push(runtime);
+  registry.captureRoot = runtime.captureRoot;
   for (const module of registry.modules) runtime.bind(module);
   return () => {
     const index = registry.runtimes.lastIndexOf(runtime);
     if (index >= 0) registry.runtimes.splice(index, 1);
     const current = registry.runtimes.at(-1);
+    registry.captureRoot = current?.captureRoot ?? passthroughCapture;
     for (const module of registry.modules) {
       if (current) current.bind(module);
       else bindPassthrough(module);
@@ -2252,7 +2385,7 @@ import {
 
 // src/sdk-meta.ts
 var SDK_NAME = "@rasputin-ai/node";
-var SDK_VERSION = "0.5.0-alpha.6";
+var SDK_VERSION = "0.5.0-alpha.7";
 
 // src/rasputin-init.ts
 var withExecution = (client, execution, installRuntime, manifest) => {