@nebulacomponents/citable 1.18.2 → 1.19.0

package/src/observations/browser/stateCollector.js

@@ -0,0 +1,386 @@
+import { sha256 } from '../../shared/io.js';
+import {
+  sanitizeQueryParams,
+  isSensitiveKey,
+  isSensitiveValue,
+  REDACTED_MARKER,
+} from './sanitizer.js';
+
+export class StateCollector {
+  constructor(options = {}) {
+    const {
+      statePolicy = {},
+      correlationTracker,
+      planId,
+      profileId,
+    } = options;
+
+    this.policy = statePolicy;
+    this.enabled = Boolean(this.policy.enabled);
+    this.planId = planId || 'plan-unspecified';
+    this.profileId = profileId || 'profile-unspecified';
+    this.tracker = correlationTracker;
+
+    this.checkpointsConfig = this.policy.checkpoints || ['final'];
+    this.captureUrl = this.policy.capture_url !== false;
+    this.allowedQueryParams = this.policy.allowed_query_params || null;
+    this.captureReferrer = Boolean(this.policy.capture_referrer);
+    this.captureNavigation = Boolean(this.policy.capture_navigation);
+    this.cookiesPolicy = this.policy.cookies || null;
+    this.localStoragePolicy = this.policy.local_storage || null;
+    this.sessionStoragePolicy = this.policy.session_storage || null;
+    this.globalsConfig = this.policy.globals || [];
+    this.domQueriesConfig = this.policy.dom_queries || [];
+    this.maxObservations = Math.min(this.policy.max_observations || 100, 500);
+    this.maxValueLength = Math.min(this.policy.max_value_length || 1024, 4096);
+
+    this.checkpoints = [];
+    this.summary = {
+      total_checkpoints: 0,
+      total_observations: 0,
+      truncated: false,
+      truncation_reason: null,
+    };
+  }
+
+  shouldCaptureCheckpoint(type) {
+    if (!this.enabled) return false;
+    return this.checkpointsConfig.includes(type);
+  }
+
+  async observeCheckpoint(page, context, checkpointId, checkpointType) {
+    if (!this.enabled) return null;
+
+    if (this.checkpoints.length >= this.maxObservations) {
+      this.summary.truncated = true;
+      this.summary.truncation_reason = 'max_observations_exceeded';
+      return null;
+    }
+
+    const seq = this.tracker.nextSequence();
+    const timing = this.tracker.timing();
+    const correlation = this.tracker.getCorrelation(checkpointId);
+    let redactedCount = 0;
+    const unavailableItems = [];
+
+    // 1. URL & query params
+    const rawUrl = page.url();
+    let sanitizedQuery = null;
+    if (this.allowedQueryParams) {
+      const queryResult = sanitizeQueryParams(rawUrl, this.allowedQueryParams);
+      sanitizedQuery = queryResult.query;
+      redactedCount += queryResult.redactedCount;
+    }
+
+    // 2. Referrer & Navigation
+    let referrer = null;
+    let navType = null;
+    try {
+      if (this.captureReferrer || this.captureNavigation) {
+        const meta = await page.evaluate(() => ({
+          referrer: document.referrer || null,
+          navType: (performance.getEntriesByType('navigation')[0] && performance.getEntriesByType('navigation')[0].type) || null,
+        }));
+        if (this.captureReferrer) referrer = meta.referrer;
+        if (this.captureNavigation) navType = meta.navType;
+      }
+    } catch {
+      unavailableItems.push('referrer_or_navigation');
+    }
+
+    // 3. Cookies (explicitly governed only)
+    let cookiesObs = null;
+    if (this.cookiesPolicy && Array.isArray(this.cookiesPolicy.allowed_names) && this.cookiesPolicy.allowed_names.length > 0) {
+      cookiesObs = {};
+      const mode = this.cookiesPolicy.mode || 'presence_only';
+      try {
+        const cookies = await context.cookies([rawUrl]);
+        const cookieMap = new Map(cookies.map((c) => [c.name, c]));
+        for (const name of this.cookiesPolicy.allowed_names) {
+          if (!cookieMap.has(name)) {
+            cookiesObs[name] = { exists: false };
+            continue;
+          }
+          const c = cookieMap.get(name);
+          const val = c.value ?? '';
+          const len = val.length;
+          const isHttpOnly = Boolean(c.httpOnly);
+          const isSecure = Boolean(c.secure);
+          const sameSite = c.sameSite || null;
+
+          const baseInfo = {
+            exists: true,
+            length: len,
+            http_only: isHttpOnly,
+            secure: isSecure,
+            same_site: sameSite,
+          };
+
+          if (mode === 'presence_only') {
+            cookiesObs[name] = baseInfo;
+          } else if (mode === 'hash_only') {
+            cookiesObs[name] = { ...baseInfo, value_hash: sha256(val) };
+          } else if (mode === 'allowlist_values') {
+            if (isHttpOnly) {
+              // Policy restricts raw HttpOnly values from plaintext exposure
+              cookiesObs[name] = { ...baseInfo, value: '[POLICY_RESTRICTED_HTTPONLY]', disposition: 'policy_restricted' };
+            } else if (isSensitiveKey(name) || isSensitiveValue(val)) {
+              cookiesObs[name] = { ...baseInfo, value: REDACTED_MARKER };
+              redactedCount++;
+            } else {
+              const bounded = val.length > this.maxValueLength ? val.slice(0, this.maxValueLength) + '...[TRUNCATED]' : val;
+              cookiesObs[name] = { ...baseInfo, value: bounded };
+            }
+          }
+        }
+      } catch {
+        unavailableItems.push('cookies:context_error');
+        cookiesObs = null;
+      }
+    }
+
+    // 4. Local Storage (explicitly governed only)
+    let localObs = null;
+    if (this.localStoragePolicy && Array.isArray(this.localStoragePolicy.allowed_keys) && this.localStoragePolicy.allowed_keys.length > 0) {
+      localObs = {};
+      const mode = this.localStoragePolicy.mode || 'presence_only';
+      try {
+        const entries = await page.evaluate((keys) => {
+          const res = {};
+          for (const k of keys) {
+            try {
+              res[k] = window.localStorage.getItem(k);
+            } catch {
+              res[k] = null;
+            }
+          }
+          return res;
+        }, this.localStoragePolicy.allowed_keys);
+
+        for (const key of this.localStoragePolicy.allowed_keys) {
+          const val = entries[key];
+          if (val === null || val === undefined) {
+            localObs[key] = { exists: false };
+            continue;
+          }
+          const len = val.length;
+          if (mode === 'presence_only') {
+            localObs[key] = { exists: true, length: len };
+          } else if (mode === 'hash_only') {
+            localObs[key] = { exists: true, length: len, value_hash: sha256(val) };
+          } else if (mode === 'allowlist_values') {
+            if (isSensitiveKey(key) || isSensitiveValue(val)) {
+              localObs[key] = { exists: true, length: len, value: REDACTED_MARKER };
+              redactedCount++;
+            } else {
+              const bounded = val.length > this.maxValueLength ? val.slice(0, this.maxValueLength) + '...[TRUNCATED]' : val;
+              localObs[key] = { exists: true, length: len, value: bounded };
+            }
+          }
+        }
+      } catch {
+        unavailableItems.push('local_storage');
+        localObs = null;
+      }
+    }
+
+    // 5. Session Storage (explicitly governed only)
+    let sessionObs = null;
+    if (this.sessionStoragePolicy && Array.isArray(this.sessionStoragePolicy.allowed_keys) && this.sessionStoragePolicy.allowed_keys.length > 0) {
+      sessionObs = {};
+      const mode = this.sessionStoragePolicy.mode || 'presence_only';
+      try {
+        const entries = await page.evaluate((keys) => {
+          const res = {};
+          for (const k of keys) {
+            try {
+              res[k] = window.sessionStorage.getItem(k);
+            } catch {
+              res[k] = null;
+            }
+          }
+          return res;
+        }, this.sessionStoragePolicy.allowed_keys);
+
+        for (const key of this.sessionStoragePolicy.allowed_keys) {
+          const val = entries[key];
+          if (val === null || val === undefined) {
+            sessionObs[key] = { exists: false };
+            continue;
+          }
+          const len = val.length;
+          if (mode === 'presence_only') {
+            sessionObs[key] = { exists: true, length: len };
+          } else if (mode === 'hash_only') {
+            sessionObs[key] = { exists: true, length: len, value_hash: sha256(val) };
+          } else if (mode === 'allowlist_values') {
+            if (isSensitiveKey(key) || isSensitiveValue(val)) {
+              sessionObs[key] = { exists: true, length: len, value: REDACTED_MARKER };
+              redactedCount++;
+            } else {
+              const bounded = val.length > this.maxValueLength ? val.slice(0, this.maxValueLength) + '...[TRUNCATED]' : val;
+              sessionObs[key] = { exists: true, length: len, value: bounded };
+            }
+          }
+        }
+      } catch {
+        unavailableItems.push('session_storage');
+        sessionObs = null;
+      }
+    }
+
+    // 6. Globals (safe expressions only)
+    let globalsObs = null;
+    if (this.globalsConfig && this.globalsConfig.length > 0) {
+      globalsObs = {};
+      for (const item of this.globalsConfig) {
+        // Enforce safe expression regex
+        if (!/^[a-zA-Z0-9_$.[\]'"]+$/.test(item.expression)) {
+          unavailableItems.push(`global:${item.name}:unsafe_expression`);
+          continue;
+        }
+        try {
+          const evalRes = await page.evaluate((expr) => {
+            try {
+              // Safe evaluation using Function or window path traversal
+              const parts = expr.replace(/^window\./, '').split('.');
+              let curr = window;
+              for (const part of parts) {
+                if (curr == null) return { exists: false };
+                curr = curr[part];
+              }
+              if (curr === undefined) return { exists: false };
+              const type = typeof curr;
+              if (type === 'string' || type === 'number' || type === 'boolean') {
+                return { exists: true, type, value: String(curr) };
+              }
+              if (curr === null) return { exists: true, type: 'null', value: 'null' };
+              return { exists: true, type, value: JSON.stringify(curr) };
+            } catch {
+              return { exists: false };
+            }
+          }, item.expression);
+
+          if (!evalRes.exists) {
+            globalsObs[item.name] = { exists: false };
+            continue;
+          }
+
+          const mode = item.mode || 'presence_only';
+          if (mode === 'presence_only') {
+            globalsObs[item.name] = { exists: true };
+          } else if (mode === 'type_only') {
+            globalsObs[item.name] = { exists: true, type: evalRes.type };
+          } else if (mode === 'hash_only') {
+            globalsObs[item.name] = { exists: true, type: evalRes.type, value_hash: sha256(evalRes.value) };
+          } else if (mode === 'scalar_value') {
+            if (isSensitiveKey(item.name) || isSensitiveValue(evalRes.value)) {
+              globalsObs[item.name] = { exists: true, type: evalRes.type, value: REDACTED_MARKER };
+              redactedCount++;
+            } else {
+              const bounded = evalRes.value.length > this.maxValueLength ? evalRes.value.slice(0, this.maxValueLength) + '...[TRUNCATED]' : evalRes.value;
+              globalsObs[item.name] = { exists: true, type: evalRes.type, value: bounded };
+            }
+          }
+        } catch {
+          unavailableItems.push(`global:${item.name}`);
+        }
+      }
+    }
+
+    // 7. DOM Queries
+    let domObs = null;
+    if (this.domQueriesConfig && this.domQueriesConfig.length > 0) {
+      domObs = {};
+      for (const query of this.domQueriesConfig) {
+        try {
+          const locator = page.locator(query.selector).first();
+          const count = await locator.count();
+          if (count === 0) {
+            domObs[query.name] = { exists: false };
+            continue;
+          }
+
+          if (query.property === 'presence') {
+            domObs[query.name] = { exists: true };
+          } else if (query.property === 'visible') {
+            const isVisible = await locator.isVisible();
+            domObs[query.name] = { exists: true, visible: isVisible };
+          } else if (query.property === 'text_content') {
+            const text = await locator.innerText();
+            if (isSensitiveValue(text)) {
+              domObs[query.name] = { exists: true, text: REDACTED_MARKER };
+              redactedCount++;
+            } else {
+              const bounded = text.length > this.maxValueLength ? text.slice(0, this.maxValueLength) + '...[TRUNCATED]' : text;
+              domObs[query.name] = { exists: true, text: bounded };
+            }
+          } else if (query.property === 'text_length') {
+            const text = await locator.innerText();
+            domObs[query.name] = { exists: true, text_length: text.length };
+          } else if (query.property === 'text_hash') {
+            const text = await locator.innerText();
+            domObs[query.name] = { exists: true, text_hash: sha256(text) };
+          } else if (query.property === 'attribute_value' && query.attribute_name) {
+            const attr = await locator.getAttribute(query.attribute_name);
+            if (attr === null) {
+              domObs[query.name] = { exists: true, attribute: null };
+            } else if (isSensitiveKey(query.attribute_name) || isSensitiveValue(attr)) {
+              domObs[query.name] = { exists: true, attribute: REDACTED_MARKER };
+              redactedCount++;
+            } else {
+              const bounded = attr.length > this.maxValueLength ? attr.slice(0, this.maxValueLength) + '...[TRUNCATED]' : attr;
+              domObs[query.name] = { exists: true, attribute: bounded };
+            }
+          }
+        } catch {
+          unavailableItems.push(`dom:${query.name}`);
+        }
+      }
+    }
+
+    const checkpointRecord = {
+      checkpoint_id: checkpointId,
+      sequence: seq,
+      timing,
+      correlation: {
+        step_id: correlation.step_id,
+        step_sequence: correlation.step_sequence,
+      },
+      state: {
+        url: rawUrl,
+        query_params: sanitizedQuery,
+        referrer,
+        navigation_type: navType,
+        cookies: cookiesObs,
+        local_storage: localObs,
+        session_storage: sessionObs,
+        globals: globalsObs,
+        dom_queries: domObs,
+      },
+      disposition: {
+        observation_status: unavailableItems.length > 0 ? 'partially_observed' : 'observed',
+        redacted_count: redactedCount,
+        unavailable_items: unavailableItems,
+      },
+    };
+
+    this.checkpoints.push(checkpointRecord);
+    this.summary.total_checkpoints++;
+    this.summary.total_observations += 1;
+    return checkpointRecord;
+  }
+
+  toArtifact() {
+    this.summary.collector_status = this.summary.truncated ? 'truncated' : 'complete';
+    return {
+      schema_version: 1,
+      plan_id: this.planId,
+      profile_id: this.profileId,
+      collected_at: this.tracker.timing().timestamp,
+      capture_policy: this.policy,
+      summary: this.summary,
+      checkpoints: this.checkpoints,
+    };
+  }
+}

package/src/observations/browserJourney.js

@@ -3,8 +3,13 @@ import { fetchUrl, handlePublicBrowserRoute, validatePublicUrl } from '../crawle
 import { sha256 } from '../shared/io.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
 import { analyzeRenderParity } from './renderParity.js';
+import { CorrelationTracker } from './browser/correlation.js';
+import { NetworkCollector } from './browser/networkCollector.js';
+import { StateCollector } from './browser/stateCollector.js';
+import { RuntimeEventCollector } from './browser/runtimeEventCollector.js';
 
 async function executeStep(page, step, lookup) {
+  if (step.action === 'checkpoint') return;
   const locator = step.locator ? page.locator(step.locator).first() : null;
   if (step.action === 'navigate') {
     await validatePublicUrl(step.url, lookup ? { lookup } : {});
@@ -30,6 +35,34 @@ async function playwrightCapture(profile, plan, playwright, lookup) {
   if (profile.authentication_state !== 'anonymous') throw new Error(`authentication state ${profile.authentication_state} requires a disclosed custom adapter`);
   const browserType = playwright[profile.browser.engine];
   if (!browserType) throw new Error(`Playwright engine ${profile.browser.engine} is unavailable`);
+
+  const correlationTracker = new CorrelationTracker();
+  const networkPolicy = profile.network_policy || plan.network_policy || { enabled: false };
+  const statePolicy = profile.state_policy || plan.state_policy || { enabled: false };
+  const runtimeEventPolicy = profile.runtime_event_policy || plan.runtime_event_policy || { enabled: false };
+
+  const networkCollector = new NetworkCollector({
+    networkPolicy,
+    targetUrl: plan.target,
+    correlationTracker,
+    planId: plan.plan_id,
+    profileId: profile.profile_id,
+  });
+
+  const stateCollector = new StateCollector({
+    statePolicy,
+    correlationTracker,
+    planId: plan.plan_id,
+    profileId: profile.profile_id,
+  });
+
+  const runtimeEventCollector = new RuntimeEventCollector({
+    runtimeEventPolicy,
+    correlationTracker,
+    planId: plan.plan_id,
+    profileId: profile.profile_id,
+  });
+
   const browser = await browserType.launch({ headless: true });
   try {
     const context = await browser.newContext({
@@ -40,28 +73,86 @@ async function playwrightCapture(profile, plan, playwright, lookup) {
     });
     try {
       await context.route('**/*', (route) => handlePublicBrowserRoute(route, lookup ? { lookup } : {}));
+
+      const initScript = runtimeEventCollector.getInitScript();
+      if (initScript && typeof context.addInitScript === 'function') {
+        await context.addInitScript(initScript);
+      }
+
       const page = await context.newPage();
+      networkCollector.attachToPage(page);
+
       const consoleErrors = [], networkFailures = [], steps = [], stepScreenshots = {};
       page.on('console', (message) => { if (message.type() === 'error') consoleErrors.push(message.text()); });
       page.on('requestfailed', (request) => networkFailures.push({ url: request.url(), error: request.failure()?.errorText || 'unknown' }));
+
       const response = await page.goto(plan.target, { waitUntil: 'networkidle' });
-      for (const step of profile.steps) {
+      await runtimeEventCollector.installOnPage(page);
+      await runtimeEventCollector.drainEvents(page);
+
+      if (stateCollector.shouldCaptureCheckpoint('initial')) {
+        await stateCollector.observeCheckpoint(page, context, 'initial', 'initial');
+      }
+
+      for (let i = 0; i < profile.steps.length; i++) {
+        const step = profile.steps[i];
+        const stepSequence = i + 1;
+        correlationTracker.startStep(step, stepSequence);
         const record = { step_id: step.step_id, action: step.action, status: 'completed', failure: null, screenshot_ref: null };
         try {
-          await executeStep(page, step, lookup);
+          if (step.action === 'checkpoint') {
+            const chkId = step.checkpoint_id || `step_${step.step_id}`;
+            await stateCollector.observeCheckpoint(page, context, chkId, 'step');
+          } else {
+            await executeStep(page, step, lookup);
+          }
+
           if (step.capture_screenshot) {
             record.screenshot_ref = `journeys/${profile.profile_id}/steps/${step.step_id}.png`;
             stepScreenshots[record.screenshot_ref] = await page.screenshot({ fullPage: true });
           }
+
+          await runtimeEventCollector.drainEvents(page);
+
+          if (step.action !== 'checkpoint' && (step.checkpoint_id || step.state_checkpoint || stateCollector.shouldCaptureCheckpoint('step'))) {
+            const chkId = step.checkpoint_id || `step_${step.step_id}`;
+            await stateCollector.observeCheckpoint(page, context, chkId, 'step');
+          }
         } catch (error) {
           record.status = 'failed';
           record.failure = error.message;
           steps.push(record);
-          if (step.required) throw Object.assign(new Error(`required step ${step.step_id} failed: ${error.message}`), { steps, stepScreenshots });
+          correlationTracker.endStep(step, stepSequence);
+          if (step.required) {
+            throw Object.assign(new Error(`required step ${step.step_id} failed: ${error.message}`), {
+              steps,
+              stepScreenshots,
+              network_events: networkCollector.enabled ? networkCollector.toArtifact() : null,
+              state_observations: stateCollector.enabled ? stateCollector.toArtifact() : null,
+              runtime_events: runtimeEventCollector.enabled ? runtimeEventCollector.toArtifact() : null,
+            });
+          }
           continue;
         }
         steps.push(record);
+        correlationTracker.endStep(step, stepSequence);
       }
+
+      correlationTracker.finishJourney();
+      await runtimeEventCollector.drainEvents(page);
+
+      const settlingTimeout = networkPolicy.settling_timeout_ms || 0;
+      if (settlingTimeout > 0) {
+        try {
+          await page.waitForTimeout(Math.min(settlingTimeout, 5000));
+          await runtimeEventCollector.drainEvents(page);
+        } catch {}
+      }
+
+      if (stateCollector.shouldCaptureCheckpoint('final')) {
+        await stateCollector.observeCheckpoint(page, context, 'final', 'final');
+      }
+
       const dom = await page.content();
       const text = await page.locator('body').innerText();
       const accessibilityTree = typeof page.locator('body').ariaSnapshot === 'function' ? await page.locator('body').ariaSnapshot() : null;
@@ -69,6 +160,9 @@ async function playwrightCapture(profile, plan, playwright, lookup) {
         final_url: page.url(), status: response?.status() ?? null, browser_version: browser.version(),
         dom, text, accessibility_tree: accessibilityTree, screenshot: await page.screenshot({ fullPage: true }),
         console_errors: consoleErrors, network_failures: networkFailures, steps, step_screenshots: stepScreenshots,
+        network_events: networkCollector.enabled ? networkCollector.toArtifact() : null,
+        state_observations: stateCollector.enabled ? stateCollector.toArtifact() : null,
+        runtime_events: runtimeEventCollector.enabled ? runtimeEventCollector.toArtifact() : null,
       };
     } finally {
       await context.close();
@@ -95,6 +189,8 @@ export async function observeBrowserPlan(root, options) {
       if (step.action === 'navigate') {
         if (!step.url) throw new Error(`${profile.profile_id}/${step.step_id}: navigate requires url`);
         if (new URL(step.url).origin !== targetOrigin) throw new Error(`${profile.profile_id}/${step.step_id}: cross-origin navigation is not allowed`);
+      } else if (step.action === 'checkpoint') {
+        // checkpoint does not require locator
       } else if (!step.locator) throw new Error(`${profile.profile_id}/${step.step_id}: ${step.action} requires locator`);
       if (['fill', 'select_option'].includes(step.action) && !step.value_env) throw new Error(`${profile.profile_id}/${step.step_id}: ${step.action} requires value_env`);
       if (step.action === 'press' && !step.key) throw new Error(`${profile.profile_id}/${step.step_id}: press requires key`);
@@ -131,6 +227,9 @@ export async function observeBrowserPlan(root, options) {
         screenshot: `${prefix}/final.png`,
         failures: `${prefix}/failures.json`,
         interactions: `${prefix}/steps.json`,
+        network_events: capture.network_events ? `${prefix}/network-events.json` : null,
+        browser_state: capture.state_observations ? `${prefix}/state-observations.json` : null,
+        runtime_events: capture.runtime_events ? `${prefix}/runtime-events.json` : null,
       };
       artifacts[refs.rendered_dom] = capture.dom;
       artifacts[refs.rendered_text] = capture.text;
@@ -138,6 +237,23 @@ export async function observeBrowserPlan(root, options) {
       artifacts[refs.screenshot] = capture.screenshot;
       artifacts[refs.failures] = { console_errors: capture.console_errors || [], network_failures: capture.network_failures || [] };
       artifacts[refs.interactions] = capture.steps || [];
+
+      if (capture.network_events) {
+        const checkNet = validateAgainst('browser-network-events.schema.json', capture.network_events);
+        if (!checkNet.valid) throw new Error(`network events artifact violates contract: ${checkNet.errors.join('; ')}`);
+        artifacts[refs.network_events] = capture.network_events;
+      }
+      if (capture.state_observations) {
+        const checkState = validateAgainst('browser-state-observations.schema.json', capture.state_observations);
+        if (!checkState.valid) throw new Error(`state observations artifact violates contract: ${checkState.errors.join('; ')}`);
+        artifacts[refs.browser_state] = capture.state_observations;
+      }
+      if (capture.runtime_events) {
+        const checkEvents = validateAgainst('browser-runtime-events.schema.json', capture.runtime_events);
+        if (!checkEvents.valid) throw new Error(`runtime events artifact violates contract: ${checkEvents.errors.join('; ')}`);
+        artifacts[refs.runtime_events] = capture.runtime_events;
+      }
+
       for (const [name, value] of Object.entries(capture.step_screenshots || {})) {
         if (!name.startsWith(`${prefix}/steps/`) || name.includes('..')) throw new Error(`browser adapter returned unsafe artifact path: ${name}`);
         artifacts[name] = value;
@@ -151,6 +267,9 @@ export async function observeBrowserPlan(root, options) {
         consent_state: profile.consent_state, authentication_state: profile.authentication_state,
         final_url: capture.final_url, status: capture.status, dom_hash: sha256(capture.dom), text_hash: sha256(capture.text),
         steps: capture.steps || [], artifact_refs: refs,
+        network_summary: capture.network_events ? capture.network_events.summary : null,
+        state_summary: capture.state_observations ? capture.state_observations.summary : null,
+        runtime_events_summary: capture.runtime_events ? capture.runtime_events.summary : null,
         render_parity: renderParity,
         interpretation_boundary: 'Observed differences do not establish semantic, retrieval, citation, ranking, or business impact.',
       };
@@ -161,6 +280,15 @@ export async function observeBrowserPlan(root, options) {
       incomplete.push(`${profile.profile_id}: ${error.message}`);
       const failureRef = `${prefix}/failure.json`;
       artifacts[failureRef] = { profile_id: profile.profile_id, error: error.message, completed_steps: error.steps || [] };
+      if (error.network_events) {
+        artifacts[`${prefix}/network-events.json`] = error.network_events;
+      }
+      if (error.state_observations) {
+        artifacts[`${prefix}/state-observations.json`] = error.state_observations;
+      }
+      if (error.runtime_events) {
+        artifacts[`${prefix}/runtime-events.json`] = error.runtime_events;
+      }
       for (const [name, value] of Object.entries(error.stepScreenshots || {})) artifacts[name] = value;
       observations.push(envelope('browser_journey', {
         plan_id: plan.plan_id, target: plan.target, profile_id: profile.profile_id, browser: profile.browser,

package/src/reporting/executiveCroReport.js

@@ -522,7 +522,7 @@ export async function buildExecutiveCroReport(root, options = {}) {
 
   const generationProvenance = {
     generated_at: generatedAt,
-    generator_version: '1.18.2',
+    generator_version: '1.19.0',
     generation_mode: resolved.generation_mode,
     source_type: resolved.source_type,
     source_identifier: resolved.source_identifier,

package/src/reporting/executiveSearchReport.js

@@ -613,7 +613,7 @@ export async function buildExecutiveSearchReport(root, options = {}) {
 
   const generationProvenance = {
     generated_at: generatedAt,
-    generator_version: '1.18.2',
+    generator_version: '1.19.0',
     generation_mode: resolved.generation_mode,
     source_type: resolved.source_type,
     source_identifier: resolved.source_identifier,

package/src/sow/generateSow.js

@@ -763,7 +763,7 @@ export async function generateSow(root, {
     // Machine-readable Provenance Envelope
     generation_provenance: {
       generated_at: generatedAt,
-      generator_version: '1.18.2',
+      generator_version: '1.19.0',
       generation_mode: generationMode,
       source_type: sourceProvenance.source_type || 'UNKNOWN',
       source_identifier: sourceProvenance.source_identifier || null,