@mobileaidev/ai-app-bridge 0.2.15 → 0.3.0-rc.2

package/bin/shared-kernel/native-target.js

@@ -0,0 +1,156 @@
+'use strict';
+
+const { checkExecution } = require('./execution-scope');
+
+// The top non-hidden Android window owns all semantic selection. Unknown or
+// disabled foreground roots block controls in earlier windows.
+
+function visible(node) {
+  return node && (node.effectiveVisible === true || node.visible === true)
+    && node.effectiveVisible !== false && node.visible !== false && node.enabled !== false
+    && node.visibility !== 'gone' && node.visibility !== 'invisible' && node.alpha !== 0;
+}
+
+function validBounds(bounds) {
+  return bounds && ['left', 'top', 'right', 'bottom'].every((key) => Number.isFinite(bounds[key]))
+    && bounds.right > bounds.left && bounds.bottom > bounds.top;
+}
+
+function foregroundNativeWindow(rawTree) {
+  if (!rawTree || typeof rawTree !== 'object') return null;
+  const windows = Array.isArray(rawTree.windows) ? rawTree.windows : [];
+  if (windows.length) {
+    const index = windows.findLastIndex(item => !explicitlyHidden(item?.root));
+    if (index < 0) return null;
+    const window = windows[index];
+    return { index, root: window?.root, type: window?.type, windowId: window?.windowId,
+      bounds: window && Object.hasOwn(window, 'bounds') ? window.bounds : window?.root?.bounds };
+  }
+  return rawTree.root ? { index: null, root: rawTree.root, bounds: rawTree.root.bounds, type: 'activity' } : null;
+}
+
+function nativeWindow(rawTree) {
+  const window = foregroundNativeWindow(rawTree);
+  return window && visible(window.root) && validBounds(window.bounds) ? window : null;
+}
+
+function explicitlyHidden(node) {
+  return node && (node.effectiveVisible === false || node.visible === false
+    || node.visibility === 'gone' || node.visibility === 'invisible' || node.alpha === 0);
+}
+
+function selectNativeNode(rawTree, spec, editable) {
+  const reject = (error) => ({ ok: false, error, dispatched: false });
+  const window = nativeWindow(rawTree);
+  if (!window) return reject('visible_observed_window_required');
+  const selector = spec.selector || (typeof spec.text === 'string' ? { text: spec.text } : null);
+  if (spec.exact === false || (spec.selector && spec.text != null)) return reject('explicit_native_selector_required');
+  const keys = Object.keys(selector || {}).filter(key => key !== 'within');
+  if (keys.length !== 1 || !['resourceName', 'text', 'contentDescription'].includes(keys[0]) || typeof selector[keys[0]] !== 'string' || !selector[keys[0]]) return reject('explicit_native_selector_required');
+  const hasScope = Object.hasOwn(selector, 'within');
+  const scope = selector.within;
+  let anchorKey;
+  let ancestorKey;
+  let ancestorParentKey;
+  if (hasScope) {
+    if (!scope || typeof scope !== 'object' || Array.isArray(scope)) return reject('invalid_native_scope');
+    const anchorKeys = Object.keys(scope).filter(key => key !== 'ancestor');
+    if (anchorKeys.length !== 1 || !['resourceName', 'text', 'contentDescription'].includes(anchorKeys[0])
+      || typeof scope[anchorKeys[0]] !== 'string' || !scope[anchorKeys[0]]) return reject('invalid_native_scope');
+    const ancestor = scope.ancestor;
+    if (!ancestor || typeof ancestor !== 'object' || Array.isArray(ancestor)) return reject('invalid_native_scope');
+    const ancestorKeys = Object.keys(ancestor).filter(key => key !== 'parent');
+    if (ancestorKeys.length !== 1 || !['className', 'resourceName'].includes(ancestorKeys[0])
+      || typeof ancestor[ancestorKeys[0]] !== 'string' || !ancestor[ancestorKeys[0]]) return reject('invalid_native_scope');
+    if (Object.hasOwn(ancestor, 'parent')) {
+      const parent = ancestor.parent;
+      if (!parent || typeof parent !== 'object' || Array.isArray(parent)) return reject('invalid_native_scope');
+      const parentKeys = Object.keys(parent);
+      if (parentKeys.length !== 1 || !['className', 'resourceName'].includes(parentKeys[0])
+        || typeof parent[parentKeys[0]] !== 'string' || !parent[parentKeys[0]]) return reject('invalid_native_scope');
+      [ancestorParentKey] = parentKeys;
+    }
+    [anchorKey] = anchorKeys;
+    [ancestorKey] = ancestorKeys;
+  }
+  const eligible = [];
+  const visit = (node, ancestors = []) => {
+    if (!visible(node)) return;
+    const bounds = node.bounds;
+    if (validBounds(bounds)) {
+      const x = Math.round((bounds.left + bounds.right) / 2);
+      const y = Math.round((bounds.top + bounds.bottom) / 2);
+      const inViewport = x >= window.bounds.left && x < window.bounds.right && y >= window.bounds.top && y < window.bounds.bottom;
+      // effectiveVisible does not prove the chosen center survives RecyclerView clipping.
+      // Without clipChildren/clipToPadding geometry, conservatively require every ancestor.
+      const inAncestors = ancestors.every(ancestor => validBounds(ancestor.bounds) && pointInsideBounds({ x, y }, ancestor.bounds));
+      if (inViewport && inAncestors) eligible.push({ node, x, y, ancestors });
+    }
+    for (const child of node.children || []) visit(child, [...ancestors, node]);
+  };
+  visit(window.root);
+  let scopeRoot;
+  if (hasScope) {
+    const anchors = eligible.filter(item => item.node[anchorKey] === scope[anchorKey]);
+    if (anchors.length !== 1) return reject(anchors.length ? 'native_scope_anchor_ambiguous' : 'native_scope_anchor_not_found');
+    const anchor = anchors[0];
+    const ancestors = anchor.ancestors.filter((node, index) => visible(node) && validBounds(node.bounds)
+      && node[ancestorKey] === scope.ancestor[ancestorKey]
+      && (!ancestorParentKey || anchor.ancestors[index - 1]?.[ancestorParentKey] === scope.ancestor.parent[ancestorParentKey]));
+    // A named row type/resource must resolve once. Never choose a nearest arbitrary ancestor.
+    if (ancestors.length !== 1) return reject(ancestors.length ? 'native_scope_ancestor_ambiguous' : 'native_scope_ancestor_not_found');
+    [scopeRoot] = ancestors;
+    if (!pointInsideBounds(anchor, scopeRoot.bounds)) return reject('native_scope_anchor_out_of_bounds');
+  }
+  const matches = eligible.filter(item => item.node[keys[0]] === selector[keys[0]]
+    && (!scopeRoot || ((item.node === scopeRoot || item.ancestors.includes(scopeRoot)) && pointInsideBounds(item, scopeRoot.bounds))));
+  if (matches.length !== 1) return reject(matches.length ? 'native_selector_ambiguous' : 'native_selector_not_found');
+  const selected = matches[0];
+  if (editable && selected.node.editable !== true) return reject('native_target_not_editable');
+  return { ok: true, ...selected, windowBounds: window.bounds, window };
+}
+
+function nativeNodeIdentity(node) {
+  return Object.fromEntries(['className', 'resourceName', 'id', 'text', 'contentDescription', 'editable', 'targetRef']
+    .map(key => [key, node?.[key] ?? null]));
+}
+
+function nativeWindowIdentity(window) {
+  return { type: window?.type ?? null, index: window?.index ?? null, windowId: window?.windowId ?? null, root: nativeNodeIdentity(window?.root) };
+}
+
+function nativeTargetRequest(node, selector) {
+  const ref = node?.targetRef;
+  const reject = error => ({ ok: false, error, dispatched: false, ambiguous: false,
+    message: 'Native semantic actions require a current SDK target reference. Update the app SDK and observe again.' });
+  if (!ref || ref.schemaVersion !== 'aab.native-target/v1') return reject('native_atomic_target_unavailable');
+  const fields = ['schemaVersion', 'runtimeEpoch', 'windowId', 'viewId', 'guard'];
+  if (Object.keys(ref).length !== fields.length || fields.some(key => typeof ref[key] !== 'string' || !ref[key])
+    || !/^[a-f0-9]{64}$/.test(ref.guard)) return reject('invalid_native_target_reference');
+  return { ok: true, request: { selector: structuredClone(selector), targetRef: { ...ref } } };
+}
+
+function nativeSelectionIdentity(selection) {
+  return { window: nativeWindowIdentity(selection.window), node: nativeNodeIdentity(selection.node),
+    ancestors: selection.ancestors.map(nativeNodeIdentity) };
+}
+
+async function revalidateNativeNode(readTree, rawTree, spec, editable = false) {
+  const observed = selectNativeNode(rawTree, spec, editable);
+  if (!observed.ok) return observed;
+  checkExecution();
+  const current = selectNativeNode(await readTree(), spec, editable);
+  checkExecution();
+  if (!current.ok) return current;
+  if (JSON.stringify(nativeSelectionIdentity(observed)) !== JSON.stringify(nativeSelectionIdentity(current))) {
+    return { ok: false, error: 'reobserve_required', dispatched: false };
+  }
+  return current;
+}
+
+function pointInsideBounds(point, bounds) {
+  return point.x >= bounds.left && point.x < bounds.right && point.y >= bounds.top && point.y < bounds.bottom;
+}
+
+module.exports = { foregroundNativeWindow, nativeWindow, visible, explicitlyHidden, validBounds, selectNativeNode,
+  pointInsideBounds, nativeNodeIdentity, nativeWindowIdentity, revalidateNativeNode, nativeTargetRequest };

package/bin/shared-kernel/provider-command-contracts.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const { object, integer, text, milliseconds } = require('./argument-schema');
+const { variants, exactlyOne, jsonObject, flutterSelector } = require('./execution-contracts');
+
+const coordinate = { type: 'number', minimum: 0, maximum: 2147483647 };
+const delta = { type: 'number', minimum: -2147483647, maximum: 2147483647 };
+const pairedCoordinates = { anyOf: [{ required: ['x', 'y'] }, { not: { anyOf: [{ required: ['x'] }, { required: ['y'] }] } }] };
+
+function flutterActionSchema() {
+  const h5 = require('./flutter-h5-target');
+  const action = (name, properties = {}, required = []) => object({ action: { const: name }, ...properties }, ['action', ...required]);
+  return variants('action', [
+    action('tapAt', { x: coordinate, y: coordinate }, ['x', 'y']),
+    action('tapText', { text }, ['text']),
+    action('tapTarget', { selector: flutterSelector }, ['selector']),
+    { ...action('inputText', { text: { type: 'string' }, selector: flutterSelector, x: coordinate, y: coordinate }, ['text']), allOf: [pairedCoordinates,
+      { not: { required: ['selector'], anyOf: [{ required: ['x'] }, { required: ['y'] }] } }] },
+    action('swipe', { startX: coordinate, startY: coordinate, endX: coordinate, endY: coordinate }, ['startX', 'startY', 'endX', 'endY']),
+    action('scrollBy', { delta, selector: flutterSelector }, ['delta']),
+    action('scrollUntilText', { text, selector: flutterSelector, maxSwipes: { ...integer(0, 1000), default: 12 } }, ['text']),
+    ...['hideKeyboard', 'back', 'openHarness', 'h5Adapters'].map(name => action(name)),
+    action('h5Dom', { adapterId: text }),
+    action('h5Eval', { script: text, expectedPage: h5.pageSchema }, ['script', 'expectedPage']),
+    { ...action('h5Control', { operation: { enum: ['click', 'input', 'scroll', 'scrollBy'] },
+      expectedTarget: h5.expectedTargetSchema, expectedPage: h5.pageSchema,
+      text: { type: 'string', maxLength: 16384 }, deltaX: delta, deltaY: delta }, ['operation']), oneOf: [
+      { properties: { operation: { enum: ['click', 'scroll'] }, expectedPage: false, text: false, deltaX: false, deltaY: false }, required: ['expectedTarget'] },
+      { properties: { operation: { const: 'input' }, expectedPage: false, deltaX: false, deltaY: false }, required: ['expectedTarget', 'text'] },
+      { properties: { operation: { const: 'scrollBy' }, expectedTarget: false, text: false }, required: ['expectedPage', 'deltaX', 'deltaY'],
+        not: { properties: { deltaX: { const: 0 }, deltaY: { const: 0 } } } },
+    ] },
+  ]);
+}
+
+function webCommandSchema(common) {
+  const command = (name, args, required = []) => object({ ...common, name: { const: name }, arguments: args }, ['sessionId', 'name', ...required]);
+  const { selectorSchema, expectedTargetSchema } = require('./web-dom-target');
+  const selector = { selector: selectorSchema, expectedTarget: expectedTargetSchema };
+  return variants('name', [
+    command('domSnapshot', object({ selector: text, maxControls: integer(1, 1000) })),
+    command('click', object(selector, ['selector']), ['arguments']),
+    command('input', object({ ...selector, value: { type: 'string', maxLength: 16384 } }, ['selector', 'value']), ['arguments']),
+    command('key', object({ ...selector, key: { enum: ['Enter', 'Escape'] } }, ['selector', 'key']), ['arguments']),
+    command('waitFor', exactlyOne({ selector: selectorSchema, targetText: text, timeoutMs: { ...milliseconds, default: 5000 }, intervalMs: { ...milliseconds, default: 250 } }, ['selector', 'targetText']), ['arguments']),
+    command('scroll', { ...object({ ...selector, mode: { enum: ['into-view', 'by'] }, deltaX: delta, deltaY: delta }, ['mode']),
+      oneOf: [{ properties: { mode: { const: 'into-view' }, deltaX: false, deltaY: false }, required: ['selector'] },
+        { properties: { mode: { const: 'by' } }, anyOf: [{ required: ['deltaX'] }, { required: ['deltaY'] }] }],
+      allOf: [{ if: { required: ['expectedTarget'] }, then: { required: ['selector'] } }] }, ['arguments']),
+    command('state', object({})),
+    command('action', object({ name: text, arguments: { ...jsonObject, description: 'Arguments for the explicitly named registered App action.' } }, ['name', 'arguments']), ['arguments']),
+  ]);
+}
+
+module.exports = { flutterActionSchema, webCommandSchema };

package/bin/shared-kernel/recorded-payload-archive.js

@@ -0,0 +1,195 @@
+'use strict';
+
+const { canonicalJson, checksumOf } = require('./evidence-schema');
+const { capturePageMetadata } = require('./live-capture-query');
+const { requireValue, sha256, jsonHash, checkPng, PAYLOAD_SCHEMA, MAX_FILE_BYTES,
+  MAX_RECORDING_BYTES } = require('./evidence-recording');
+
+const same = (a, b) => canonicalJson(a) === canonicalJson(b);
+const portableName = (file, extension) => `payload-${file.sha256}.${extension}`;
+
+// The same analysis runs while exporting and offline. readFile chooses only the
+// source location; no payload identities or coverage claims come from a manifest.
+function analyzeRecordedPayloads(facts, readFile) {
+  const records = facts.map(f => f.payload);
+  const byId = new Map(records.map(r => [r.evidenceId, r]));
+  const positions = new Map(facts.map(f => [f.payload.evidenceId, f.globalSeq]));
+  const calls = new Map();
+  const callIds = new Set();
+  const sequences = new Set();
+  const files = new Map();
+  const attachments = [];
+  const missingReferences = [];
+  const counts = { scriptCalls: 0, assertions: { passed: 0, failed: 0, inconclusive: 0 },
+    screenshots: 0, mobilePages: 0, mobileItems: 0, boundMobileItems: 0,
+    webPages: 0, webItems: 0, boundWebItems: 0, redactedPayloads: 0 };
+  let totalBytes = 0;
+  function read(record, file, extension) {
+    requireValue(file && /^[a-f0-9]{64}$/.test(file.sha256)
+      && Number.isSafeInteger(file.bytes) && file.bytes > 0 && file.bytes <= MAX_FILE_BYTES, 'invalid_attachment_file');
+    const name = portableName(file, extension);
+    const bytes = readFile(record, file, name);
+    requireValue(bytes.length === file.bytes && sha256(bytes) === file.sha256, 'attachment_checksum_mismatch', record.evidenceId);
+    if (!files.has(name)) {
+      totalBytes += bytes.length;
+      requireValue(totalBytes <= MAX_RECORDING_BYTES, 'archive_limit_exceeded');
+      files.set(name, { path: name, bytes: file.bytes, sha256: file.sha256 });
+    }
+    return bytes;
+  }
+  for (const record of records) {
+    if (record.kind !== 'attachment') continue;
+    requireValue(Number.isSafeInteger(record.sequence) && record.sequence > 0
+      && record.file.name === `${record.sequence}.json`, 'invalid_attachment_sequence');
+    const key = `${record.recordingId}:${record.sequence}`;
+    requireValue(!sequences.has(key), 'duplicate_attachment');
+    sequences.add(key);
+    const doc = JSON.parse(read(record, record.file, 'json'));
+    requireValue(doc.schemaVersion === PAYLOAD_SCHEMA && doc.namespace === record.namespace
+      && doc.operationId === record.operationId && doc.recordingId === record.recordingId
+      && doc.sequence === record.sequence && doc.kind === record.payloadKind
+      && same(doc.target, record.target), 'attachment_binding_mismatch', record.evidenceId);
+    requireValue(jsonHash(doc.data) === record.dataSha256 && /^[a-f0-9]{64}$/.test(record.originalSha256),
+      'attachment_data_mismatch');
+    requireValue(record.representation === (record.originalSha256 === record.dataSha256 ? 'original-json' : 'redacted-json'),
+      'attachment_representation_mismatch');
+    if (record.representation === 'redacted-json') counts.redactedPayloads += 1;
+    requireValue(Array.isArray(record.screenshots) && Array.isArray(doc.screenshots)
+      && record.screenshots.length === doc.screenshots.length, 'invalid_screenshot_reference');
+    const screenshotFiles = [];
+    for (let i = 0; i < record.screenshots.length; i += 1) {
+      const file = record.screenshots[i];
+      const { ref, ...metadata } = doc.screenshots[i];
+      requireValue(file.name === `${record.sequence}-${i + 1}.png` && same(file, metadata)
+        && ref?.sha256 === file.sha256, 'invalid_screenshot_reference');
+      checkPng(read(record, file, 'png'));
+      screenshotFiles.push(portableName(file, 'png'));
+      counts.screenshots += 1;
+    }
+    attachments.push({ evidenceId: record.evidenceId, path: portableName(record.file, 'json'), screenshots: screenshotFiles });
+    if (doc.kind === 'script-call') {
+      requireValue(record.namespace === 'script', 'attachment_binding_mismatch');
+      const { command, args, envelope } = doc.data;
+      requireValue(envelope?.command === command && (envelope.execution?.executionId === record.operationId
+        || (envelope.ok === false && envelope.execution?.executionId === undefined)), 'call_binding_mismatch');
+      if (envelope.execution?.callId) {
+        requireValue(!callIds.has(envelope.execution.callId), 'duplicate_call_id');
+        callIds.add(envelope.execution.callId);
+      }
+      const evidence = envelope.evidence;
+      if (evidence?.source) {
+        requireValue(evidence.source.command === command && evidence.source.scope === 'execution'
+          && evidence.source.payloadSha256 === record.sourcePayload?.originalSha256
+          && jsonHash(envelope.result) === record.sourcePayload?.archivedSha256, 'call_source_mismatch');
+      }
+      if (evidence?.observationId) {
+        requireValue(!calls.has(evidence.observationId), 'duplicate_observation_id');
+        calls.set(evidence.observationId, evidence);
+      }
+      const screenshotRefs = (evidence?.refs || []).filter(ref => ref.stream === 'screenshot');
+      requireValue(same(screenshotRefs, doc.screenshots.map(s => s.ref)), 'invalid_screenshot_reference');
+      const actionId = envelope.execution?.actionId;
+      if (actionId) {
+        const marker = records.find(r => r.kind === 'dispatch-marker' && r.actionId === actionId);
+        if (!marker) missingReferences.push({ evidenceId: record.evidenceId, field: 'actionId', value: actionId });
+        else requireValue(positions.get(marker.evidenceId) < positions.get(record.evidenceId)
+          && same(marker.target, record.target) && (record.representation === 'redacted-json'
+          || marker.actionSpecHash === checksumOf({ command, args })), 'call_action_mismatch');
+      }
+      if (evidence?.capture) {
+        analyzeCapturePage({ ...evidence.capture, stream: command.replace(/^web-/, ''),
+          window: evidence.window, coverage: evidence.coverage,
+          refs: evidence.refs, items: envelope.result.items }, counts, doc.target);
+      }
+      counts.scriptCalls += 1;
+    } else if (doc.kind === 'script-assertion') {
+      requireValue(record.namespace === 'script' && doc.screenshots.length === 0, 'attachment_binding_mismatch');
+      const { assertion, result } = doc.data;
+      requireValue(['passed', 'failed', 'inconclusive'].includes(result?.verdict), 'invalid_recorded_assertion');
+      counts.assertions[result.verdict] += 1;
+      // Preserve rejected assertion attempts too. A child-supplied predicate is
+      // a claim; this verifier checks its Host evidence association, not business truth.
+      if (result.scope === 'device' && result.verdict !== 'inconclusive') {
+        const id = assertion.evidence?.observationId;
+        const evidence = calls.get(id);
+        if (!evidence) missingReferences.push({ evidenceId: record.evidenceId, field: 'observationId', value: id ?? null });
+        else for (const field of ['observationId', 'source', 'window', 'coverage', 'refs', 'capture']) {
+          requireValue(same(assertion.evidence[field], evidence[field]), 'assertion_binding_mismatch', field);
+        }
+      }
+    } else if (doc.kind === 'intent-capture') {
+      requireValue(record.namespace === 'intent' && doc.screenshots.length === 0, 'attachment_binding_mismatch');
+      const { capture, rawTreeId } = doc.data;
+      requireValue(Array.isArray(capture?.pages), 'invalid_recorded_capture');
+      const observation = byId.get(record.parentFactId);
+      if (observation) {
+        requireValue(observation.kind === 'observation' && observation.rawTreeId === rawTreeId
+          && observation.revision === record.revision && same(observation.captureRefs, capture.refs)
+          && same(observation.captureCoverage, capture.coverage), 'capture_observation_mismatch');
+        requireValue(same(observation.capturePages, capture.pages.map(capturePageMetadata)), 'capture_observation_mismatch');
+      }
+      requireValue(same(capture.refs, capture.pages.flatMap(p => p.refs))
+        && same(capture.items, capture.pages.flatMap(p => p.items)), 'capture_page_mismatch');
+      for (const page of capture.pages) analyzeCapturePage(page, counts, doc.target);
+    } else requireValue(false, 'unsupported_recorded_payload');
+  }
+  return { scope: 'retained-recorded-payloads', priorHistoryComplete: 'unknown',
+    executionStatus: 'not-inferred', businessVerdict: 'not-evaluated',
+    referenceClosure: missingReferences.length ? 'partial' : 'complete', missingReferences,
+    attachmentCount: attachments.length, bytes: totalBytes, counts, attachments, files: [...files.values()],
+    exclusions: ['unrecorded-calls-and-screenshots', 'unqueried-mobile-facts', 'in-memory-events'] };
+}
+
+function analyzeCapturePage(page, counts, target) {
+  requireValue(Array.isArray(page.items) && Array.isArray(page.refs)
+    && ['complete', 'partial', 'unavailable'].includes(page.coverage?.status), 'invalid_recorded_capture');
+  if (target.platform === 'web') return analyzeWebPage(page, counts, target);
+  counts.mobilePages += 1;
+  counts.mobileItems += page.items.length;
+  // Uncommitted/memory-only pages remain inspectable without strong fact refs.
+  if (page.coverage.committed !== true) return;
+  requireValue(page.refs.length === page.items.length, 'capture_ref_count_mismatch');
+  const ids = new Set();
+  for (let i = 0; i < page.refs.length; i += 1) {
+    const ref = page.refs[i];
+    const item = page.items[i];
+    requireValue(typeof ref.mobileFactId === 'string' && ref.mobileFactId.length > 0 && !ids.has(ref.mobileFactId)
+      && typeof ref.runtimeEpoch === 'string' && ref.runtimeEpoch.length > 0
+      && ref.targetKey === page.targetKey && ref.captureId === item.id && ref.capturedAtMs === item.timestampMs
+      && ({ logs: 'log', network: 'network', state: 'state', events: 'event' })[ref.stream] === item.type,
+    'capture_ref_binding_mismatch');
+    // Connected history may include older epochs; its page epoch is the current
+    // runtime. Only an explicitly filtered window restricts each fact's epoch.
+    if (page.window?.runtimeEpoch != null) requireValue(ref.runtimeEpoch === page.window.runtimeEpoch, 'capture_epoch_mismatch');
+    ids.add(ref.mobileFactId);
+    counts.boundMobileItems += 1;
+  }
+}
+
+function analyzeWebPage(page, counts, target) {
+  counts.webPages += 1; counts.webItems += page.items.length;
+  if (page.coverage.committed !== true) return;
+  requireValue(['logs', 'network', 'state', 'events'].includes(page.stream), 'invalid_web_capture_stream');
+  const targetKey = `web:${JSON.stringify([target.sessionId, target.targetId, page.stream])}`;
+  requireValue(page.targetKey === targetKey && page.runtimeEpoch === target.runtimeEpoch
+    && page.refs.length === page.items.length, 'web_capture_target_mismatch');
+  const ids = new Set();
+  for (let index = 0; index < page.items.length; index++) {
+    const item = page.items[index], ref = page.refs[index];
+    requireValue(ref.source === 'host-fact-store' && ref.stream === page.stream
+      && ref.targetKey === targetKey && ref.runtimeEpoch === target.runtimeEpoch
+      && Number.isSafeInteger(ref.globalSeq) && ref.globalSeq > 0 && !ids.has(ref.globalSeq)
+      && ref.globalSeq === item.id && same(ref, item.ref)
+      && item.sessionId === target.sessionId && item.targetId === target.targetId && item.runtimeEpoch === target.runtimeEpoch
+      && typeof item.captureId === 'string' && item.captureId.length > 0
+      && Number.isSafeInteger(item.sourceSequence) && item.sourceSequence > 0,
+    'web_capture_ref_binding_mismatch');
+    requireValue(item.association === 'unattributed' ? item.actionId === null
+      : ['explicit', 'synchronous'].includes(item.association) && typeof item.actionId === 'string' && item.actionId.length > 0,
+    'web_capture_action_binding_mismatch');
+    if (page.window?.afterActionId != null) requireValue(item.actionId === page.window.afterActionId, 'web_capture_action_binding_mismatch');
+    ids.add(ref.globalSeq); counts.boundWebItems += 1;
+  }
+}
+
+module.exports = { analyzeRecordedPayloads };

package/bin/shared-kernel/request-context.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const path = require('node:path');
+const { AsyncLocalStorage } = require('node:async_hooks');
+const context = new AsyncLocalStorage();
+
+const requestDirectory = () => context.getStore()?.cwd ?? process.cwd();
+const resolveRequestPath = value => path.resolve(requestDirectory(), value);
+const inRequestDirectory = (cwd, action) => context.run({ cwd }, action);
+const localPaths = ['outFile', 'artifactDir', 'apkPath', 'appPath', 'recordingDir', 'outputDir', 'archiveDir', 'wdaProjectPath', 'agentModule'];
+const executables = ['adb', 'aaptPath', 'apksignerPath', 'devicectl', 'xcodebuild', 'pythonPath'];
+
+// Only contract-defined filesystem fields are resolved. Web URL paths, source
+// text and arbitrary Script inputs keep their original values.
+function resolveExecutablePaths(args) {
+  const resolved = { ...args };
+  for (const field of executables) {
+    if (typeof resolved[field] === 'string' && /[\\/]/.test(resolved[field])) resolved[field] = resolveRequestPath(resolved[field]);
+  }
+  return resolved;
+}
+
+function resolveCommandPaths(command, args) {
+  const resolved = resolveExecutablePaths(args);
+  for (const field of localPaths) {
+    if (typeof resolved[field] === 'string') resolved[field] = resolveRequestPath(resolved[field]);
+  }
+  if (command === 'script' && args.operation === 'start') {
+    resolved.script = { ...args.script, cwd: resolveRequestPath(args.script.cwd ?? requestDirectory()) };
+    if (args.script.sourcePath !== undefined) resolved.script.sourcePath = resolveRequestPath(args.script.sourcePath);
+  }
+  return resolved;
+}
+
+module.exports = { requestDirectory, resolveRequestPath, inRequestDirectory, resolveCommandPaths, resolveExecutablePaths };

package/bin/shared-kernel/semantic-node.js

@@ -0,0 +1,55 @@
+'use strict';
+
+function semanticNode({
+  nodeId,
+  sourceIndex,
+  rawTreeId,
+  screenshotId = null,
+  role,
+  text = null,
+  label = null,
+  hint,
+  errorText,
+  bounds = null,
+  enabled = true,
+  checked = null,
+  selected = null,
+  clickable = false,
+  resourceName,
+  editable,
+  interaction,
+  visible,
+  effectiveVisible,
+  accessibilityId,
+  elementId,
+  elementType,
+  targetRef,
+}) {
+  return {
+    nodeId: String(nodeId),
+    sourceIndex,
+    rawTreeId,
+    screenshotId,
+    role,
+    text,
+    label,
+    bounds,
+    enabled,
+    checked,
+    selected,
+    clickable,
+    ...(typeof hint === 'string' ? { hint } : {}),
+    ...(typeof errorText === 'string' ? { errorText } : {}),
+    ...(typeof resourceName === 'string' ? { resourceName } : {}),
+    ...(typeof editable === 'boolean' ? { editable } : {}),
+    ...(interaction === undefined ? {} : { interaction }),
+    ...(typeof visible === 'boolean' ? { visible } : {}),
+    ...(typeof effectiveVisible === 'boolean' ? { effectiveVisible } : {}),
+    ...(typeof accessibilityId === 'string' ? { accessibilityId } : {}),
+    ...(typeof elementId === 'string' ? { elementId } : {}),
+    ...(typeof elementType === 'string' ? { elementType } : {}),
+    ...(targetRef === undefined ? {} : { targetRef }),
+  };
+}
+
+module.exports = { semanticNode };