@unrdf/hooks 26.4.4 → 26.4.7

package/README.md

@@ -3,7 +3,7 @@
 ![Version](https://img.shields.io/badge/version-6.0.0-blue) ![Production Ready](https://img.shields.io/badge/production-ready-green)
 
 > Production-grade policy definition and execution framework for RDF knowledge graphs
-> 
+>
 > Implements 9 condition kinds, deterministic receipt chaining, SPARQL transformations, SHACL enforcement, N3 forward-chaining inference, and Datalog logic programming
 
 ## Overview
@@ -36,7 +36,7 @@ const store = createStore();
 const engine = new KnowledgeHookEngine(store);
 const context = createContext({
   nodeId: 'my-app',
-  t_ns: BigInt(Date.now() * 1000000)
+  t_ns: BigInt(Date.now() * 1000000),
 });
 
 // Define a hook with SHACL condition (soft-fail annotation)
@@ -45,11 +45,12 @@ const hook = createKnowledgeHook({
   condition: {
     kind: 'shacl',
     ref: { uri: 'file:///shapes/compliance.ttl' },
-    enforcementMode: 'annotate'  // Log violations but don't block
+    enforcementMode: 'annotate', // Log violations but don't block
   },
-  effects: [{
-    kind: 'sparql-construct',
-    query: `
+  effects: [
+    {
+      kind: 'sparql-construct',
+      query: `
       CONSTRUCT {
         ?s ex:status ex:Valid ;
            ex:validatedAt ?now .
@@ -58,17 +59,18 @@ const hook = createKnowledgeHook({
         ?s ?p ?o .
         BIND (NOW() as ?now)
       }
-    `
-  }]
+    `,
+    },
+  ],
 });
 
 // Execute with receipt chaining
 const result = await engine.execute(context, [hook]);
 
 // Access deterministic receipt chain
-console.log('Receipt Hash:', result.receipt.receiptHash);        // BLAKE3(entire receipt)
-console.log('Input Hash:', result.receipt.input_hash);          // BLAKE3(store before)
-console.log('Output Hash:', result.receipt.output_hash);        // BLAKE3(store after)
+console.log('Receipt Hash:', result.receipt.receiptHash); // BLAKE3(entire receipt)
+console.log('Input Hash:', result.receipt.input_hash); // BLAKE3(store before)
+console.log('Output Hash:', result.receipt.output_hash); // BLAKE3(store after)
 console.log('Previous Hash:', result.receipt.previousReceiptHash); // Links to prior op
 ```
 
@@ -114,6 +116,7 @@ Validates store against SHACL shape. Three enforcement modes for soft-fail gover
 ```
 
 **Enforcement Modes**:
+
 - `block`: Fail if violations exist (strict governance)
 - `annotate`: Execute but add violations as RDF triples (soft-fail + audit trail)
 - `repair`: Auto-fix via SPARQL CONSTRUCT then re-validate (self-healing)
@@ -265,10 +268,10 @@ Execute custom logic. Included for backwards compatibility.
 Prevents hook execution if SHACL validation fails. Strict governance.
 
 ```javascript
-{ 
-  kind: 'shacl', 
+{
+  kind: 'shacl',
   ref: { uri: 'file:///shapes/strict.ttl' },
-  enforcementMode: 'block' 
+  enforcementMode: 'block'
 }
 // Hook blocked if shape violations exist
 // Result: Clean state or error
@@ -306,9 +309,9 @@ Auto-repairs violations via SPARQL CONSTRUCT, then re-validates.
       ?violation ex:repaired true .
       ?entity ex:status ex:Repaired .
     }
-    WHERE { 
-      ?violation a sh:ValidationResult . 
-      ?violation sh:focusNode ?entity 
+    WHERE {
+      ?violation a sh:ValidationResult .
+      ?violation sh:focusNode ?entity
     }
   `
 }
@@ -348,7 +351,7 @@ const receipt1 = await engine.execute(ctx1, hooks1);
 const receipt2 = await engine.execute(
   createContext({
     ...ctx2,
-    previousReceiptHash: receipt1.receipt.receiptHash
+    previousReceiptHash: receipt1.receipt.receiptHash,
   }),
   hooks2
 );
@@ -423,7 +426,7 @@ const bridge = new HooksBridge(store);
 const hookId = await bridge.registerHook({
   name: 'erlang-compliance',
   condition: { kind: 'shacl', ref: { uri: '...' } },
-  effects: [{ kind: 'sparql-construct', query: '...' }]
+  effects: [{ kind: 'sparql-construct', query: '...' }],
 });
 
 // From Erlang: evaluate condition
@@ -431,7 +434,7 @@ const result = await bridge.evaluateCondition({
   kind: 'datalog',
   facts: ['user(alice)'],
   rules: ['allowed(X) :- user(X)'],
-  goal: 'allowed(alice)'
+  goal: 'allowed(alice)',
 });
 
 // Full workflow with receipt
@@ -440,15 +443,15 @@ const receipt = await bridge.executeHooks(context, [hook]);
 
 ## Performance Characteristics
 
-| Operation | Latency | Notes |
-|-----------|---------|-------|
-| Receipt Creation | <1ms | BLAKE3 hashing |
-| SPARQL ASK | 1-5ms | Depends on query complexity |
-| SPARQL SELECT | 2-8ms | Result binding overhead |
-| SHACL Validation | 5-15ms | Shape size dependent |
-| N3 Inference | 10-100ms | Rule complexity & triple count |
-| Datalog Goal | 1-30ms | Fixpoint iterations |
-| Full Hook Execution | <150ms | All conditions + effects + receipt |
+| Operation           | Latency  | Notes                              |
+| ------------------- | -------- | ---------------------------------- |
+| Receipt Creation    | <1ms     | BLAKE3 hashing                     |
+| SPARQL ASK          | 1-5ms    | Depends on query complexity        |
+| SPARQL SELECT       | 2-8ms    | Result binding overhead            |
+| SHACL Validation    | 5-15ms   | Shape size dependent               |
+| N3 Inference        | 10-100ms | Rule complexity & triple count     |
+| Datalog Goal        | 1-30ms   | Fixpoint iterations                |
+| Full Hook Execution | <150ms   | All conditions + effects + receipt |
 
 ## Architecture
 
@@ -529,18 +532,18 @@ pnpm benchmark
 class KnowledgeHookEngine {
   // Register a hook with 6 priorities
   registerHook(hook: KnowledgeHook): string;
-  
+
   // Evaluate any of 9 condition kinds
   async evaluateCondition(
     condition: Condition
   ): Promise<boolean>;
-  
+
   // Execute hooks with receipt chaining
   async execute(
     context: ExecutionContext,
     hooks: KnowledgeHook[]
   ): Promise<ExecutionResult>;
-  
+
   // Get receipt chain (BLAKE3 linked)
   getReceiptChain(): Receipt[];
 }
@@ -564,6 +567,7 @@ See [API-REFERENCE.md](./API-REFERENCE.md) for complete schema.
 See [CONTRIBUTING.md](./docs/CONTRIBUTING.md) for development guidelines.
 
 All code follows:
+
 - 100% ESM (.mjs)
 - JSDoc documentation
 - Zod validation
@@ -586,10 +590,10 @@ MIT — see [LICENSE](./LICENSE) for full text.
 
 This package depends on the following notable third-party libraries:
 
-| Dependency | License | Purpose |
-|------------|---------|---------|
-| [eyereasoner](https://github.com/eyereasoner/eye-js) | MIT | N3 forward-chaining inference via EYE reasoner (WebAssembly) |
-| [swipl-wasm](https://github.com/nickmcdowall/swipl-wasm) | BSD-2-Clause | SWI-Prolog runtime bundled by eyereasoner |
-| [@noble/hashes](https://github.com/paulmillr/noble-hashes) | MIT | BLAKE3 cryptographic hashing for receipt chains |
+| Dependency                                                 | License      | Purpose                                                      |
+| ---------------------------------------------------------- | ------------ | ------------------------------------------------------------ |
+| [eyereasoner](https://github.com/eyereasoner/eye-js)       | MIT          | N3 forward-chaining inference via EYE reasoner (WebAssembly) |
+| [swipl-wasm](https://github.com/nickmcdowall/swipl-wasm)   | BSD-2-Clause | SWI-Prolog runtime bundled by eyereasoner                    |
+| [@noble/hashes](https://github.com/paulmillr/noble-hashes) | MIT          | BLAKE3 cryptographic hashing for receipt chains              |
 
 All dependencies use permissive open-source licenses compatible with MIT.

package/examples/hook-chains/package.json

@@ -11,8 +11,8 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@unrdf/core": "26.4.3",
-    "@unrdf/hooks": "26.4.3",
+    "@unrdf/core": "26.4.4",
+    "@unrdf/hooks": "26.4.4",
     "n3": "^1.26.0",
     "zod": "^4.1.13"
   },

package/examples/policy-hooks/README.md

@@ -80,14 +80,10 @@ const aclPolicy = defineHook({
   name: 'acl-policy',
   trigger: 'before-add',
   validate: quad => {
-    const trustedNamespaces = [
-      'http://example.org/',
-      'http://xmlns.com/foaf/0.1/',
-    ];
+    const trustedNamespaces = ['http://example.org/', 'http://xmlns.com/foaf/0.1/'];
     // Check subject and predicate IRIs
-    return trustedNamespaces.some(ns =>
-      quad.subject.value.startsWith(ns) ||
-      quad.predicate.value.startsWith(ns)
+    return trustedNamespaces.some(
+      ns => quad.subject.value.startsWith(ns) || quad.predicate.value.startsWith(ns)
     );
   },
 });
@@ -162,8 +158,8 @@ registerHook(registry, privacyPolicy);
 registerHook(registry, provenancePolicy);
 
 // Execute all policies
-const results = executeHooksByTrigger(registry, store, 'before-add', quad);
-console.log(`Passed: ${results.passed.length}/${results.total}`);
+const result = await executeHooksByTrigger(registry, 'before-add', quad);
+console.log(`Valid: ${result.valid}, hooks run: ${result.results.length}`);
 ```
 
 ## Testing

package/examples/policy-hooks/package.json

@@ -11,8 +11,8 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@unrdf/core": "26.4.3",
-    "@unrdf/hooks": "26.4.3",
+    "@unrdf/core": "26.4.4",
+    "@unrdf/hooks": "26.4.4",
     "n3": "^1.26.0",
     "zod": "^4.1.13"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unrdf/hooks",
-  "version": "26.4.4",
+  "version": "26.4.7",
   "description": "UNRDF Knowledge Hooks - Policy Definition and Execution Framework",
   "type": "module",
   "bin": {
@@ -57,6 +57,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.10.1",
+    "@unrdf/test-utils": "workspace:*",
     "vitest": "^4.0.15"
   },
   "engines": {

package/src/hooks/builtin-hooks.mjs

@@ -256,7 +256,8 @@ export const normalizeLanguageTagPooled = defineHook({
       quad.subject,
       quad.predicate,
       {
-        ...quad.object,
+        value: quad.object.value,
+        datatype: quad.object.datatype,
         language: quad.object.language.toLowerCase(),
       },
       quad.graph
@@ -287,8 +288,9 @@ export const trimLiteralsPooled = defineHook({
       quad.subject,
       quad.predicate,
       {
-        ...quad.object,
         value: trimmed,
+        datatype: quad.object.datatype,
+        language: quad.object.language,
       },
       quad.graph
     );

package/src/hooks/condition-evaluator.mjs

@@ -47,8 +47,7 @@ export const SparqlParamSchema = z.union([
 export function validateSparqlVariableName(name) {
   if (typeof name !== 'string' || !SAFE_SPARQL_VAR_RE.test(name)) {
     throw new Error(
-      `Invalid SPARQL variable name: "${String(name)}". ` +
-        'Must match /^[a-zA-Z_][a-zA-Z0-9_]*$/.'
+      `Invalid SPARQL variable name: "${String(name)}". ` + 'Must match /^[a-zA-Z_][a-zA-Z0-9_]*$/.'
     );
   }
   return name;
@@ -107,9 +106,7 @@ export function bindSparqlParams(queryTemplate, params = {}) {
 
     const result = SparqlParamSchema.safeParse(value);
     if (!result.success) {
-      throw new Error(
-        `Invalid SPARQL parameter value for ?${varName}: ${result.error.message}`
-      );
+      throw new Error(`Invalid SPARQL parameter value for ?${varName}: ${result.error.message}`);
     }
     replacements.set(varName, toRdfTerm(value));
   }

package/src/hooks/effect-executor.mjs

@@ -477,14 +477,10 @@ export function createHardenedContext() {
 export function createSafeFunctionProxy() {
   const handler = {
     construct() {
-      throw new Error(
-        'SecurityError: Function constructor is disabled in sandbox'
-      );
+      throw new Error('SecurityError: Function constructor is disabled in sandbox');
     },
     apply() {
-      throw new Error(
-        'SecurityError: Function execution is disabled in sandbox'
-      );
+      throw new Error('SecurityError: Function execution is disabled in sandbox');
     },
     get(target, prop) {
       if (prop === 'constructor' || prop === 'prototype' || prop === '__proto__') {
@@ -496,27 +492,19 @@ export function createSafeFunctionProxy() {
       return undefined;
     },
     set() {
-      throw new Error(
-        'SecurityError: Cannot modify SafeFunction proxy'
-      );
+      throw new Error('SecurityError: Cannot modify SafeFunction proxy');
     },
     defineProperty() {
-      throw new Error(
-        'SecurityError: Cannot define properties on SafeFunction proxy'
-      );
+      throw new Error('SecurityError: Cannot define properties on SafeFunction proxy');
     },
     deleteProperty() {
-      throw new Error(
-        'SecurityError: Cannot delete properties on SafeFunction proxy'
-      );
+      throw new Error('SecurityError: Cannot delete properties on SafeFunction proxy');
     },
     getPrototypeOf() {
       return null;
     },
     setPrototypeOf() {
-      throw new Error(
-        'SecurityError: Cannot set prototype on SafeFunction proxy'
-      );
+      throw new Error('SecurityError: Cannot set prototype on SafeFunction proxy');
     },
   };
 
@@ -555,9 +543,9 @@ export function logInjectionAttempt(code, violations, log = []) {
 
   console.warn(
     `[EffectExecutor] INJECTION ATTEMPT BLOCKED:\n` +
-    `  Violations: ${violations.join(', ')}\n` +
-    `  Code hash: ${attempt.codeHash}\n` +
-    `  Timestamp: ${attempt.timestamp.toISOString()}`
+      `  Violations: ${violations.join(', ')}\n` +
+      `  Code hash: ${attempt.codeHash}\n` +
+      `  Timestamp: ${attempt.timestamp.toISOString()}`
   );
 
   return attempt;

package/src/hooks/hook-chain-compiler.mjs

@@ -110,7 +110,6 @@ export function compileHookChain(hooks) {
     .filter(Boolean)
     .join('\n    ');
 
-
   // Compile the chain function
   const fnBody = `
     ${validationSteps}

package/src/hooks/hook-executor.mjs

@@ -219,7 +219,11 @@ export function executeHooksByTrigger(hooksOrRegistry, trigger, quad) {
   let hooks;
 
   // Handle registry object
-  if (hooksOrRegistry && typeof hooksOrRegistry === 'object' && hooksOrRegistry.hooks instanceof Map) {
+  if (
+    hooksOrRegistry &&
+    typeof hooksOrRegistry === 'object' &&
+    hooksOrRegistry.hooks instanceof Map
+  ) {
     // Extract hooks for the specific trigger from registry
     const triggerSet = hooksOrRegistry.triggerIndex.get(trigger);
     if (!triggerSet) {

package/src/hooks/self-play-autonomics.mjs

@@ -14,6 +14,7 @@ import { randomUUID } from 'crypto';
 import { evaluateCondition } from './condition-evaluator.mjs';
 import { KnowledgeHookEngine } from './knowledge-hook-engine.mjs';
 import { ask, select, construct } from './query.mjs';
+import { withPipelineSpan, withLLMSpan } from '../../../../src/lib/telemetry.mjs';
 
 /**
  * Build a self-play toolRegistry from knowledge hooks
@@ -29,81 +30,114 @@ export function buildHooksToolRegistry(store, _hooks = []) {
   return {
     hooks_evaluate_conditions: {
       handler: async ({ store: evalStore, hooks: evalHooks }) => {
-        // Evaluate all conditions and collect results
-        const conditionResults = [];
-        const satisfied = [];
-
-        for (const hook of evalHooks) {
-          try {
-            const result = await evaluateCondition(hook.condition, evalStore);
-            conditionResults.push({
-              hookName: hook.name,
-              condition: hook.condition,
-              satisfied: result,
-            });
-
-            if (result) {
-              satisfied.push(hook);
+        return withLLMSpan('hooks-evaluate-conditions', async span => {
+          span.setAttributes({
+            'llm.provider': 'unrdf-hooks',
+            'llm.model': 'condition-evaluator',
+            'gen_ai.operation.name': 'hooks-evaluate-conditions',
+            'unrdf.hook.hooks_total': evalHooks.length,
+          });
+
+          // Evaluate all conditions and collect results
+          const conditionResults = [];
+          const satisfied = [];
+
+          for (const hook of evalHooks) {
+            try {
+              const result = await evaluateCondition(hook.condition, evalStore);
+              conditionResults.push({
+                hookName: hook.name,
+                condition: hook.condition,
+                satisfied: result,
+              });
+
+              if (result) {
+                satisfied.push(hook);
+              }
+            } catch (err) {
+              conditionResults.push({
+                hookName: hook.name,
+                condition: hook.condition,
+                satisfied: false,
+                error: err.message,
+              });
             }
-          } catch (err) {
-            conditionResults.push({
-              hookName: hook.name,
-              condition: hook.condition,
-              satisfied: false,
-              error: err.message,
-            });
           }
-        }
 
-        const successRate = evalHooks.length > 0 ? satisfied.length / evalHooks.length : 0;
+          const successRate = evalHooks.length > 0 ? satisfied.length / evalHooks.length : 0;
 
-        return {
-          conditionResults,
-          satisfied,
-          successRate,
-        };
+          span.setAttributes({
+            'unrdf.hook.hooks_satisfied': satisfied.length,
+            'unrdf.hook.satisfied': satisfied.length > 0,
+          });
+
+          return {
+            conditionResults,
+            satisfied,
+            successRate,
+          };
+        });
       },
     },
 
     hooks_execute_effects: {
       handler: async ({ store: _execStore, hooks: execHooks, delta: _delta }) => {
-        // Execute hooks with receipt chaining
-        const context = {
-          nodeId: 'self-play-autonomics',
-          t_ns: BigInt(Date.now() * 1000000),
-        };
+        return withLLMSpan('hooks-execute-effects', async span => {
+          span.setAttributes({
+            'llm.provider': 'unrdf-hooks',
+            'llm.model': 'knowledge-hook-engine',
+            'gen_ai.operation.name': 'hooks-execute-effects',
+            'unrdf.hook.hooks_total': execHooks.length,
+          });
+
+          // Execute hooks with receipt chaining
+          const context = {
+            nodeId: 'self-play-autonomics',
+            t_ns: BigInt(Date.now() * 1000000),
+          };
 
-        try {
-          const result = await engine.execute(context, execHooks);
+          try {
+            const result = await engine.execute(context, execHooks);
 
-          return {
-            executionResults: execHooks.map(h => ({
-              hookName: h.name,
-              status: 'executed',
-            })),
-            receipt: {
-              receiptHash: result.receipt.receiptHash,
-              input_hash: result.receipt.input_hash,
-              output_hash: result.receipt.output_hash,
-              previousReceiptHash: result.receipt.previousReceiptHash || null,
-              hooksExecuted: result.successful + result.failed,
-              successful: result.successful,
-              failed: result.failed,
-              delta: result.receipt.delta,
-              timestamp: result.receipt.timestamp,
-            },
-          };
-        } catch (err) {
-          return {
-            executionResults: execHooks.map(h => ({
-              hookName: h.name,
-              status: 'failed',
+            span.setAttributes({
+              'pipeline.repairs.applied': result.successful,
+              'pipeline.repairs.failed': result.failed,
+            });
+
+            return {
+              executionResults: execHooks.map(h => ({
+                hookName: h.name,
+                status: 'executed',
+              })),
+              receipt: {
+                receiptHash: result.receipt.receiptHash,
+                input_hash: result.receipt.input_hash,
+                output_hash: result.receipt.output_hash,
+                previousReceiptHash: result.receipt.previousReceiptHash || null,
+                hooksExecuted: result.successful + result.failed,
+                successful: result.successful,
+                failed: result.failed,
+                delta: result.receipt.delta,
+                timestamp: result.receipt.timestamp,
+              },
+            };
+          } catch (err) {
+            span.setAttributes({
+              'pipeline.repairs.applied': 0,
+              'pipeline.repairs.failed': execHooks.length,
+            });
+
+            return {
+              executionResults: execHooks.map(h => ({
+                hookName: h.name,
+                status: 'failed',
+                error: err.message,
+              })),
+              receipt: null,
               error: err.message,
-            })),
-            receipt: null,
-            error: err.message,
-          };
-        }
+            };
+          }
+        });
       },
     },
 
@@ -260,164 +294,171 @@ class ReceiptChainNode {
  * @returns {Promise<Object>} { episodes, finalStore, receiptChain, stats }
  */
 export async function runHooksAutonomics(store, hookDefinitions = [], options = {}) {
-  const {
-    goalCondition = async () => false,
-    episodeCount = 3,
-    maxStepsPerEpisode = 10,
-    onEpisodeEnd = () => {},
-  } = options;
-
-  // Build tool registry
-  const toolRegistry = buildHooksToolRegistry(store, hookDefinitions);
-
-  // Create decision policy
-  const decisionFn = createHooksAwarePolicy(goalCondition);
-
-  // Track receipt chain
-  const receiptChain = [];
-  let previousReceiptNode = null;
-
-  const episodes = [];
-
-  for (let e = 0; e < episodeCount; e++) {
-    const episode = {
-      episodeId: randomUUID(),
-      stepCount: 0,
-      stepResults: [],
-      feedback: [],
-      terminated: false,
-      terminationReason: null,
-      timestamp: new Date().toISOString(),
-    };
-
-    const context = {
-      store,
-      hooks: hookDefinitions,
-    };
-
-    let previousResult = null;
+  return withPipelineSpan('observe', async span => {
+    const {
+      goalCondition = async () => false,
+      episodeCount = 3,
+      maxStepsPerEpisode = 10,
+      onEpisodeEnd = () => {},
+    } = options;
+
+    // Build tool registry
+    const toolRegistry = buildHooksToolRegistry(store, hookDefinitions);
+
+    // Create decision policy
+    const decisionFn = createHooksAwarePolicy(goalCondition);
+
+    // Track receipt chain
+    const receiptChain = [];
+    let previousReceiptNode = null;
+
+    const episodes = [];
+
+    for (let e = 0; e < episodeCount; e++) {
+      const episode = {
+        episodeId: randomUUID(),
+        stepCount: 0,
+        stepResults: [],
+        feedback: [],
+        terminated: false,
+        terminationReason: null,
+        timestamp: new Date().toISOString(),
+      };
 
-    for (let step = 0; step < maxStepsPerEpisode; step++) {
-      if (episode.terminated) break;
+      const context = {
+        store,
+        hooks: hookDefinitions,
+      };
 
-      // Decide next tool
-      const decision = await decisionFn(
-        {
-          steps: episode.stepResults,
-          context,
-          recordFeedback: (s, r) => episode.feedback.push({ signal: s, reason: r }),
-        },
-        previousResult
-      );
+      let previousResult = null;
 
-      if (!decision) {
-        episode.terminated = true;
-        episode.terminationReason = 'no more decisions';
-        episode.feedback.push({ signal: 0, reason: 'terminated: no more decisions' });
-        break;
-      }
+      for (let step = 0; step < maxStepsPerEpisode; step++) {
+        if (episode.terminated) break;
 
-      const { toolName, input } = decision;
+        // Decide next tool
+        const decision = await decisionFn(
+          {
+            steps: episode.stepResults,
+            context,
+            recordFeedback: (s, r) => episode.feedback.push({ signal: s, reason: r }),
+          },
+          previousResult
+        );
 
-      // Execute tool
-      const stepStartTime = Date.now();
-      try {
-        const tool = toolRegistry[toolName];
-        if (!tool) {
+        if (!decision) {
           episode.terminated = true;
-          episode.terminationReason = `unknown tool: ${toolName}`;
-          episode.feedback.push({ signal: -1, reason: `unknown tool: ${toolName}` });
+          episode.terminationReason = 'no more decisions';
+          episode.feedback.push({ signal: 0, reason: 'terminated: no more decisions' });
           break;
         }
 
-        const result = await tool.handler(input);
-        const duration = Date.now() - stepStartTime;
-
-        episode.stepResults.push({
-          stepId: randomUUID(),
-          toolName,
-          input,
-          output: result,
-          duration,
-          timestamp: new Date().toISOString(),
-          success: true,
-        });
+        const { toolName, input } = decision;
+
+        // Execute tool
+        const stepStartTime = Date.now();
+        try {
+          const tool = toolRegistry[toolName];
+          if (!tool) {
+            episode.terminated = true;
+            episode.terminationReason = `unknown tool: ${toolName}`;
+            episode.feedback.push({ signal: -1, reason: `unknown tool: ${toolName}` });
+            break;
+          }
+
+          const result = await tool.handler(input);
+          const duration = Date.now() - stepStartTime;
+
+          episode.stepResults.push({
+            stepId: randomUUID(),
+            toolName,
+            input,
+            output: result,
+            duration,
+            timestamp: new Date().toISOString(),
+            success: true,
+          });
 
-        previousResult = result;
+          previousResult = result;
+
+          // Record receipt if present
+          if (result?.receipt) {
+            const receiptNode = new ReceiptChainNode(result.receipt, previousReceiptNode);
+            receiptChain.push(receiptNode.toJSON());
+            previousReceiptNode = receiptNode;
+          }
+
+          // Compute feedback
+          const feedback = computeHooksFeedback(result, previousResult);
+          episode.feedback.push({
+            signal: feedback,
+            reason: `${toolName} succeeded`,
+          });
+        } catch (err) {
+          const duration = Date.now() - stepStartTime;
+
+          episode.stepResults.push({
+            stepId: randomUUID(),
+            toolName,
+            input,
+            output: null,
+            duration,
+            timestamp: new Date().toISOString(),
+            success: false,
+            error: err.message,
+          });
 
-        // Record receipt if present
-        if (result?.receipt) {
-          const receiptNode = new ReceiptChainNode(result.receipt, previousReceiptNode);
-          receiptChain.push(receiptNode.toJSON());
-          previousReceiptNode = receiptNode;
+          episode.terminated = true;
+          episode.terminationReason = `tool failed: ${toolName}`;
+          episode.feedback.push({ signal: -0.5, reason: `${toolName} failed: ${err.message}` });
         }
 
-        // Compute feedback
-        const feedback = computeHooksFeedback(result, previousResult);
-        episode.feedback.push({
-          signal: feedback,
-          reason: `${toolName} succeeded`,
-        });
-      } catch (err) {
-        const duration = Date.now() - stepStartTime;
-
-        episode.stepResults.push({
-          stepId: randomUUID(),
-          toolName,
-          input,
-          output: null,
-          duration,
-          timestamp: new Date().toISOString(),
-          success: false,
-          error: err.message,
-        });
+        episode.stepCount++;
+      }
 
+      if (!episode.terminated && episode.stepCount >= maxStepsPerEpisode) {
         episode.terminated = true;
-        episode.terminationReason = `tool failed: ${toolName}`;
-        episode.feedback.push({ signal: -0.5, reason: `${toolName} failed: ${err.message}` });
+        episode.terminationReason = 'max steps reached';
+        episode.feedback.push({ signal: 0, reason: 'max steps reached' });
       }
 
-      episode.stepCount++;
-    }
+      // Calculate metrics
+      const totalFeedback = episode.feedback.reduce((sum, f) => sum + f.signal, 0);
+      const avgFeedback = episode.feedback.length > 0 ? totalFeedback / episode.feedback.length : 0;
+
+      episode.metrics = {
+        stepCount: episode.stepCount,
+        feedbackCount: episode.feedback.length,
+        totalFeedback,
+        avgFeedback,
+      };
 
-    if (!episode.terminated && episode.stepCount >= maxStepsPerEpisode) {
-      episode.terminated = true;
-      episode.terminationReason = 'max steps reached';
-      episode.feedback.push({ signal: 0, reason: 'max steps reached' });
+      episodes.push(episode);
+      await onEpisodeEnd(episode);
     }
 
-    // Calculate metrics
-    const totalFeedback = episode.feedback.reduce((sum, f) => sum + f.signal, 0);
-    const avgFeedback = episode.feedback.length > 0 ? totalFeedback / episode.feedback.length : 0;
+    // Calculate stats
+    const totalFeedback = episodes.reduce((sum, ep) => sum + ep.metrics.totalFeedback, 0);
+    const successCount = episodes.filter(ep => ep.metrics.totalFeedback > 0).length;
 
-    episode.metrics = {
-      stepCount: episode.stepCount,
-      feedbackCount: episode.feedback.length,
+    const stats = {
+      totalEpisodes: episodes.length,
+      successCount,
+      successRate: episodes.length > 0 ? successCount / episodes.length : 0,
       totalFeedback,
-      avgFeedback,
+      avgFeedback: episodes.length > 0 ? totalFeedback / episodes.length : 0,
+      receiptChainLength: receiptChain.length,
     };
 
-    episodes.push(episode);
-    await onEpisodeEnd(episode);
-  }
-
-  // Calculate stats
-  const totalFeedback = episodes.reduce((sum, ep) => sum + ep.metrics.totalFeedback, 0);
-  const successCount = episodes.filter(ep => ep.metrics.totalFeedback > 0).length;
-
-  const stats = {
-    totalEpisodes: episodes.length,
-    successCount,
-    successRate: episodes.length > 0 ? successCount / episodes.length : 0,
-    totalFeedback,
-    avgFeedback: episodes.length > 0 ? totalFeedback / episodes.length : 0,
-    receiptChainLength: receiptChain.length,
-  };
+    span.setAttributes({
+      'pipeline.stage': 'observe',
+      'pipeline.input.count': hookDefinitions.length,
+    });
 
-  return {
-    episodes,
-    finalStore: store,
-    receiptChain,
-    stats,
-  };
+    return {
+      episodes,
+      finalStore: store,
+      receiptChain,
+      stats,
+    };
+  });
 }