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

package/bin/intent/intent-entry.js

@@ -0,0 +1,226 @@
+'use strict';
+
+const { createMemoryEvidenceAdapter } = require('../shared-kernel/evidence-adapters');
+const { createAutonomousAgentAdapter, createIntentBudget } = require('./intent-autonomous-adapter');
+const { createProductionIntentDeviceAdapter } = require('./intent-production-adapter');
+const { createIOSIntentDeviceAdapter } = require('./ios-intent-adapter');
+const { createWebIntentDeviceAdapter } = require('./web-intent-adapter');
+const { intentError } = require('./intent-errors');
+const { intentProviderError } = require('./intent-provider');
+const { createIntentEvidenceStore } = require('./intent-evidence-store');
+const { createIntentWorker } = require('./intent-worker');
+const { createEvidenceRecording } = require('../shared-kernel/evidence-recording');
+const { normalizeIntentTarget, normalizeObservationTarget } = require('./intent-observation-target');
+
+const operations = new Map();
+const ledgers = new Map();
+const pendingStarts = new Set();
+const reservedIds = new Set();
+let closing = false;
+const MAX_OPERATIONS = 256;
+let sequence = 0;
+
+function handle(args = {}) {
+  const operation = args.operation || 'start';
+  if (operation === 'start') {
+    if (closing) return intentError('runtime_stopping');
+    const task = start(args);
+    pendingStarts.add(task);
+    task.then(() => pendingStarts.delete(task), () => pendingStarts.delete(task));
+    return task;
+  }
+  if (operation === 'decide') return read(args, (worker) => worker.decide(args.decision || args));
+  if (operation === 'status') return status(args);
+  if (operation === 'observe') return read(args, (worker) => {
+    if (worker.isManagedWorkflow && args.observationTarget !== undefined) return intentError('managed_intent_observation_target_fixed', {
+      operationId: args.operationId, field: 'observationTarget', dispatched: false, ambiguous: false,
+      message: 'Installation and permission workflows use their managed UIAutomator target.',
+    });
+    if (worker.isManagedWorkflow && args.provider !== undefined && args.provider !== 'uia') return intentError('managed_intent_provider_fixed', {
+      operationId: args.operationId, field: 'provider', provider: 'uia', dispatched: false, ambiguous: false,
+      message: 'Installation and permission workflows require UIAutomator observations.',
+    });
+    return worker.observe(args);
+  });
+  if (operation === 'pause') return read(args, (worker) => worker.pause());
+  if (operation === 'resume') return read(args, (worker) => worker.resume());
+  if (operation === 'cancel') return read(args, (worker) => worker.cancel());
+  if (operation === 'intervene') return read(args, (worker) => worker.intervene(args.reason || 'intervened'));
+  return intentError('invalid_operation', { operation });
+}
+
+async function start(args) {
+  if (!args.goal && !args.install && !args.permissionDialog) {
+    return intentError('invalid_intent');
+  }
+  let target = null, observationTarget = null;
+  if (!args.install && !args.permissionDialog) {
+    try {
+      target = normalizeIntentTarget(args.target);
+      observationTarget = normalizeObservationTarget(target, args.provider ?? 'native', args.observationTarget ?? null);
+    }
+    catch (error) { return intentError(error.code, { field: error.field, message: error.message, dispatched: false, ambiguous: false }); }
+    const providerError = intentProviderError(target, args.provider ?? 'native');
+    if (providerError) return intentError(providerError.error, { ...providerError, dispatched: false, ambiguous: false });
+  }
+  sequence += 1;
+  const operationId = args.operationId || `intent-${Date.now()}-${sequence}`;
+  evictTerminalWorkers();
+  evictStaleLedgers();
+  if (operations.has(operationId) || reservedIds.has(operationId)) {
+    return intentError('operation_exists', { operationId });
+  }
+  if (operations.size + reservedIds.size >= MAX_OPERATIONS || ledgers.size + reservedIds.size >= MAX_OPERATIONS) {
+    return intentError('registry_full', { operationId });
+  }
+  const store = args.store || createIntentEvidenceStore({ adapter: createMemoryEvidenceAdapter() });
+  if (store.list(operationId).length) return intentError('operation_exists', { operationId });
+  let recording = null;
+  if (args.recordingDir !== undefined) {
+    try {
+      recording = createEvidenceRecording({ directory: args.recordingDir, namespace: 'intent', operationId, store,
+        now: args.now || Date.now });
+    } catch (error) { return intentError(error.code || 'recording_failed', { operationId }); }
+  }
+  reservedIds.add(operationId);
+  let worker;
+  try { worker = args.install
+    ? await require('./install-intent').createInstallIntent({ args: args.install, operationId, store, recording })
+    : args.permissionDialog
+    ? await require('./permission-intent').createPermissionIntent({ args: args.permissionDialog, operationId, store, recording })
+    : createIntentWorker({
+    operationId,
+    goal: args.goal || null,
+    target,
+    provider: args.provider || 'native',
+    observationTarget,
+    store,
+    adapter: resolveAdapter(args),
+    mode: args.mode || 'supervised',
+    agent: resolveAgent(args),
+    budget: resolveBudget(args),
+    timeoutMs: args.timeoutMs,
+    now: args.now || Date.now,
+    capturePort: args.capturePort || null,
+    captureRequirements: args.require || null,
+    recording,
+  }); } finally { reservedIds.delete(operationId); }
+  operations.set(operationId, worker);
+  ledgers.set(operationId, { store, status: 'created' });
+  return closing ? worker.cancel() : worker.start();
+}
+
+function status(args) {
+  if (typeof args.operationId !== 'string' || args.operationId.length === 0) return intentError('operationId_required', { field: 'operationId' });
+  const worker = operations.get(args.operationId);
+  if (worker) return worker.status(args);
+  const store = args.store || ledgers.get(args.operationId)?.store;
+  if (!store) return intentError('unknown_operation', { operationId: args.operationId || null });
+  const records = store.list(args.operationId);
+  if (!records.length) return intentError('unknown_operation', { operationId: args.operationId || null });
+  for (const record of records) {
+    const checked = store.read(record.evidenceId);
+    if (!checked.ok) return intentError(checked.error, { operationId: args.operationId });
+  }
+  const checkpoint = records.findLast(record => record.kind === 'checkpoint');
+  const saved = checkpoint?.payloadSummary;
+  const history = store.history(args.operationId, args.afterSequence ?? 0, args.limit);
+  if (saved && isIntentTerminal(saved.status)) return {
+    ...saved, command: 'intent', operationId: args.operationId, ok: saved.status === 'completed',
+    live: false, recovered: true, restartPolicy: 'none', terminalEvidenceId: checkpoint.evidenceId, history,
+  };
+  const unmatched = records.filter(record => record.kind === 'dispatch-marker')
+    .filter(marker => !records.some(record => record.kind === 'action-receipt' && record.actionId === marker.actionId));
+  return { ok: false, command: 'intent', operationId: args.operationId, status: 'interrupted', error: 'runtime_restarted',
+    live: false, recovered: true, restartPolicy: 'none', revision: records.at(-1).revision,
+    ambiguous: unmatched.length > 0 || records.some(record => record.kind === 'action-receipt' && record.ambiguous),
+    unmatchedActionIds: unmatched.map(marker => marker.actionId), history };
+}
+
+function read(args, fn) {
+  const worker = operations.get(args.operationId);
+  if (!worker) return intentError('unknown_operation', { operationId: args.operationId || null });
+  return fn(worker);
+}
+
+function resolveAdapter(args) {
+  if (args.adapter && typeof args.adapter.observe === 'function') return args.adapter;
+  if (args.adapter != null && args.adapter !== 'production') throw new TypeError('invalid_adapter');
+  if (args.target?.platform === 'ios') return createIOSIntentDeviceAdapter({ provider: args.ports?.ios });
+  if (args.target?.platform === 'web') return createWebIntentDeviceAdapter({ provider: args.ports?.web });
+  return createProductionIntentDeviceAdapter({ ports: args.ports, adb: args.adb });
+}
+
+function resolveAgent(args) {
+  if (args.agent) return args.agent;
+  if (args.decide) return createAutonomousAgentAdapter({ decide: args.decide });
+  if (args.agentModule) {
+    const loaded = require(args.agentModule);
+    const decide = typeof loaded.decide === 'function' ? loaded.decide.bind(loaded) : loaded;
+    return createAutonomousAgentAdapter({ decide });
+  }
+  return null;
+}
+
+function resolveBudget(args) {
+  if (args.budget && typeof args.budget.check === 'function') return args.budget;
+  if (args.mode !== 'autonomous' && !args.budget) return null;
+  return createIntentBudget(args.budget || {
+    maxSteps: args.maxSteps,
+    maxDurationMs: args.maxDurationMs,
+    maxAgentCalls: args.maxAgentCalls,
+    allowlist: args.allowlist,
+    now: args.now,
+  });
+}
+
+function evictTerminalWorkers() {
+  for (const [id, worker] of operations) {
+    if (!worker.isFinished()) continue;
+    const snapshot = worker.status();
+    if (!isIntentTerminal(snapshot.status)) continue;
+    const entry = ledgers.get(id);
+    if (entry) entry.status = snapshot.status;
+    operations.delete(id);
+  }
+}
+
+function evictStaleLedgers() {
+  if (ledgers.size < MAX_OPERATIONS) return;
+  for (const id of ledgers.keys()) {
+    if (operations.has(id)) continue;
+    ledgers.delete(id);
+    if (ledgers.size < MAX_OPERATIONS) return;
+  }
+}
+
+function isIntentTerminal(status) {
+  return status === 'completed'
+    || status === 'failed'
+    || status === 'inconclusive'
+    || status === 'cancelled'
+    || status === 'timeout'
+    || status === 'ambiguous'
+    || status === 'blocked_evidence_store'
+    || status === 'intervention_required';
+}
+
+function resetIntentOperations() {
+  const settling = Promise.allSettled([...operations.values()].filter(worker => !worker.isFinished()).map(worker => worker.cancel()));
+  operations.clear();
+  ledgers.clear();
+  closing = false;
+  sequence = 0;
+  return settling;
+}
+
+async function cancelActiveIntents() {
+  closing = true;
+  const cancelKnown = () => Promise.allSettled([...operations.values()]
+    .filter(worker => !worker.isFinished()).map(worker => worker.cancel()));
+  await cancelKnown();
+  await Promise.allSettled([...pendingStarts]);
+  await cancelKnown();
+}
+
+module.exports = { handle, resetIntentOperations, cancelActiveIntents };

package/bin/intent/intent-errors.js

@@ -0,0 +1,28 @@
+'use strict';
+
+function emptyTimings() {
+  return {
+    workerOverheadMs: 0,
+    targetLeaseWaitMs: 0,
+    providerAcquireMs: 0,
+    evidenceCommitMs: 0,
+    summaryMs: 0,
+    decisionWaitMs: 0,
+    actionMs: 0,
+    receiptCommitMs: 0,
+    totalMs: 0,
+  };
+}
+
+function intentError(error, extra = {}) {
+  return {
+    ok: false,
+    command: 'intent',
+    latestEvidenceIds: extra.latestEvidenceIds || {},
+    timings: extra.timings || emptyTimings(),
+    ...extra,
+    error,
+  };
+}
+
+module.exports = { intentError, emptyTimings };

package/bin/intent/intent-evidence-store.js

@@ -0,0 +1,121 @@
+'use strict';
+
+const { createEvidenceStore } = require('../shared-kernel/evidence-store');
+const { createExecutionLedger } = require('../shared-kernel/execution-ledger');
+
+function createIntentEvidenceStore(options = {}) {
+  const store = createEvidenceStore({ ...options, namespace: 'intent' });
+  const ledger = options.ledger || createExecutionLedger();
+  const persist = store.persist;
+
+  async function persistAndRecord(kind, record) {
+    const result = await persist(kind, record);
+    if (result.ok && typeof record.operationId === 'string' && record.operationId.length > 0) {
+      ledger.record({
+        executionId: record.operationId,
+        revision: record.revision,
+        kind,
+        target: record.target,
+        timestampMs: timestampFor(kind, record),
+        actionId: record.actionId,
+        parentFactId: kind === 'decision' ? firstId(record.basedOnEvidenceIds) : record.parentFactId,
+        payloadSummary: payloadSummaryFor(kind, record),
+        evidenceRefs: [result.evidenceId],
+        timings: kind === 'action-receipt' ? timingsOf(record) : record.timings,
+      });
+    }
+    return result;
+  }
+
+  return {
+    ...store,
+    persist: persistAndRecord,
+    commit: persistAndRecord,
+    ledger,
+    history(operationId, afterSequence = 0, limit) {
+      const restored = createExecutionLedger();
+      for (const record of store.list(operationId)) {
+        const checked = store.read(record.evidenceId);
+        if (!checked.ok) throw Object.assign(new Error(checked.error), { code: checked.error });
+        restored.record({ executionId: operationId, revision: record.revision, kind: record.kind,
+          target: record.target, timestampMs: timestampFor(record.kind, record), actionId: record.actionId,
+          parentFactId: record.kind === 'decision' ? firstId(record.basedOnEvidenceIds) : record.parentFactId,
+          payloadSummary: payloadSummaryFor(record.kind, record), evidenceRefs: [record.evidenceId],
+          timings: record.kind === 'action-receipt' ? timingsOf(record) : record.timings });
+      }
+      return restored.query(operationId, afterSequence, limit);
+    },
+  };
+}
+
+function timestampFor(kind, record) {
+  if (kind === 'observation') return record.capturedAtMs;
+  if (kind === 'action-receipt') return record.completedAtMs;
+  return record.timestampMs;
+}
+
+function firstId(ids) {
+  return Array.isArray(ids) && ids.length > 0 ? ids[0] : undefined;
+}
+
+function timingsOf(record) {
+  if (record.startedAtMs == null && record.completedAtMs == null) return undefined;
+  return { startedAtMs: record.startedAtMs, completedAtMs: record.completedAtMs };
+}
+
+function payloadSummaryFor(kind, record) {
+  if (kind === 'observation') {
+    const summary = {
+      provider: record.provider,
+      observationTarget: record.observationTarget,
+      rawTreeId: record.rawTreeId,
+      foregroundTarget: record.foregroundTarget,
+      capturedAtMs: record.capturedAtMs,
+    };
+    if (record.captureRefs !== undefined) summary.captureRefs = record.captureRefs;
+    if (record.captureCoverage !== undefined) summary.captureCoverage = record.captureCoverage;
+    if (record.capturePages !== undefined) summary.capturePages = record.capturePages;
+    return summary;
+  }
+  if (kind === 'summary') {
+    return {
+      rawTreeId: record.rawTreeId,
+      pageSummary: record.summary,
+    };
+  }
+  if (kind === 'decision') {
+    return {
+      decisionId: record.decisionId,
+      agentDecision: record.agentDecision,
+      actionSpecHash: record.actionSpecHash,
+      basedOnEvidenceIds: record.basedOnEvidenceIds,
+      mode: record.mode,
+      action: record.action,
+      reason: record.reason,
+    };
+  }
+  if (kind === 'dispatch-marker') {
+    return {
+      decisionId: record.decisionId,
+      actionSpecHash: record.actionSpecHash,
+      action: record.action,
+      state: record.state,
+    };
+  }
+  if (kind === 'action-receipt') {
+    return {
+      mechanicalStatus: record.mechanicalStatus,
+      error: record.error,
+      ambiguous: record.ambiguous === true,
+      dispatched: record.dispatched,
+      action: record.action,
+      resolved: record.resolved,
+      matched: record.matched,
+      rawTreeId: record.rawTreeId,
+      basedOnEvidenceIds: record.basedOnEvidenceIds,
+    };
+  }
+  return record.payloadSummary;
+}
+
+module.exports = { createIntentEvidenceStore };

package/bin/intent/intent-lifetime.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const { CommandError } = require('../command-errors');
+const { runExecution } = require('../shared-kernel/execution-scope');
+
+// An Intent owns work across multiple requests, including time spent idle.
+// Draining waits for owned provider/persistence work; it never races that work
+// against a timer and pretends it has settled.
+function createIntentLifetime({ timeoutMs, onDeadline }) {
+  if (timeoutMs !== null && (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647)) {
+    throw new CommandError('invalid_argument', 'Intent timeoutMs must be a positive integer in milliseconds.', { field: 'timeoutMs' });
+  }
+  const controller = new AbortController();
+  const pending = new Set();
+  let started = false;
+  let timer;
+  let deadlineMs = null;
+  function start() {
+    if (started) return;
+    started = true;
+    if (timeoutMs !== null) {
+      deadlineMs = Date.now() + timeoutMs;
+      timer = setTimeout(onDeadline, timeoutMs);
+      timer.unref?.();
+    }
+  }
+  function run(action, mutation = false) {
+    if (controller.signal.aborted) return Promise.reject(new CommandError('operation_stopped', 'This Intent no longer accepts work.'));
+    const task = runExecution({ deadlineMs: deadlineMs ?? Infinity, signal: controller.signal, mutation }, action);
+    pending.add(task);
+    const remove = () => pending.delete(task);
+    task.then(remove, remove);
+    return task;
+  }
+  function stop(code) {
+    clearTimeout(timer);
+    controller.abort({ code });
+  }
+  return { start, run, stop, drain: () => Promise.allSettled([...pending]), signal: controller.signal,
+    get deadlineMs() { return deadlineMs; }, get pendingCount() { return pending.size; } };
+}
+
+// Agent replies are values, not device actions. Pass a cancellation signal and
+// stop accepting replies on pause/cancel. An ignored signal cannot dispatch a
+// late decision through the Intent after this promise has settled.
+function awaitAgentReply(agent, input, signal) {
+  return new Promise((resolve, reject) => {
+    const abort = () => finish(new CommandError(signal.reason?.code || 'cancelled', 'The Intent stopped waiting for this Agent reply.'));
+    const finish = (error, value) => {
+      signal.removeEventListener('abort', abort);
+      error ? reject(error) : resolve(value);
+    };
+    if (signal.aborted) { abort(); return; }
+    signal.addEventListener('abort', abort, { once: true });
+    Promise.resolve().then(() => {
+      if (signal.aborted) throw new CommandError(signal.reason?.code || 'cancelled', 'Agent request cancelled before dispatch.');
+      return agent.decide({ ...input, signal });
+    }).then(value => finish(null, value), error => finish(error));
+  });
+}
+
+module.exports = { createIntentLifetime, awaitAgentReply };

package/bin/intent/intent-observation-target.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const { object, text, validateValue } = require('../shared-kernel/argument-schema');
+const { executionTargetSchema, normalizeExecutionTarget } = require('../shared-kernel/execution-target');
+const { CommandError } = require('../command-errors');
+
+const observationTargetSchema = { anyOf: [object({ webViewId: text }, ['webViewId']), { type: 'null' }],
+  description: 'Android or iOS H5 WebView selection. Null requires one visible WebView; an explicit ID never selects a replacement.' };
+
+function intentTargetSchema() {
+  const schema = executionTargetSchema({ intent: true });
+  // Script defaults and immutable evidence targets retain their own contract.
+  // A live Intent selects WebViews as observation state, not its frozen target.
+  delete schema.anyOf.find(branch => branch.properties.platform.const === 'ios').properties.webViewId;
+  return schema;
+}
+
+function normalizeIntentTarget(value) {
+  validateValue(value, intentTargetSchema(), 'target');
+  return normalizeExecutionTarget(value, { intent: true });
+}
+
+function normalizeObservationTarget(target, provider, value) {
+  validateValue(value, observationTargetSchema, 'observationTarget');
+  if (value === null) return null;
+  if (!['android', 'ios'].includes(target.platform) || provider !== 'h5') {
+    throw new CommandError('unsupported_intent_observation_target', 'webViewId selects an Android or iOS H5 observation.',
+      { field: 'observationTarget.webViewId' });
+  }
+  return Object.freeze({ webViewId: value.webViewId });
+}
+
+module.exports = { observationTargetSchema, intentTargetSchema, normalizeIntentTarget, normalizeObservationTarget };

package/bin/intent/intent-observer.js

@@ -0,0 +1,194 @@
+'use strict';
+
+const { summarizeTree } = require('../shared-kernel/summary-transformer');
+const { intentError } = require('./intent-errors');
+const { checkExecution } = require('../shared-kernel/execution-scope');
+const { capturePageMetadata } = require('../shared-kernel/live-capture-query');
+
+async function observeAndCommit(context, provider = context.provider, observationTarget = context.observationTarget) {
+  const timings = context.timings || {};
+  const observeStarted = context.now();
+  const observation = await context.adapter.observe({
+    ...context.target,
+    provider,
+    observationTarget,
+    rawTreeId: `${context.operationId}:${context.revision}`,
+  });
+  checkExecution();
+  timings.providerAcquireMs = (timings.providerAcquireMs || 0) + (context.now() - observeStarted);
+  if (!observation || observation.ok === false) {
+    const failure = { provider, observationTarget, revision: context.revision, response: observation };
+    const persisted = await context.store.persist('checkpoint', { operationId: context.operationId,
+      revision: context.revision, target: context.target, stepId: 'observation-failed', timestampMs: context.now(),
+      payloadSummary: { observationFailure: failure } });
+    if (!persisted.ok) return intentError(persisted.error || 'evidence_not_persisted', { persisted: false });
+    checkExecution();
+    context.observationFailure = { ...failure, evidenceId: persisted.evidenceId };
+    context.latestEvidenceIds = { ...context.latestEvidenceIds, observationFailure: persisted.evidenceId };
+    return intentError(observation?.error || 'provider_failed', { stage: 'provider' });
+  }
+  const routed = context.target.foregroundPackages !== undefined;
+  if (routed && (!observation.route || !['native', 'uia', 'flutter', 'h5'].includes(observation.provider))) return intentError('foreground_observation_required');
+  const activeProvider = routed ? observation.provider : provider;
+  const capture = await observeCapture(context);
+  checkExecution();
+  const persistStarted = context.now();
+  const observationRecord = {
+    operationId: context.operationId,
+    revision: context.revision,
+    target: context.target,
+    observedTarget: routed ? { ...context.target, packageName: observation.route.packageName } : context.target,
+    provider: activeProvider,
+    observationTarget,
+    capturedAtMs: context.now(),
+    foregroundTarget: observation.foregroundTarget,
+    rawTreeId: observation.rawTreeId,
+    rawTree: observation.rawTree,
+    ...(routed ? { route: observation.route, requestedTarget: context.target } : {}),
+  };
+  if (capture) {
+    observationRecord.captureRefs = capture.refs;
+    observationRecord.captureCoverage = capture.coverage;
+    observationRecord.capturePages = capture.pages.map(capturePageMetadata);
+  }
+  const persisted = await context.store.persist('observation', observationRecord);
+  timings.evidenceCommitMs = (timings.evidenceCommitMs || 0) + (context.now() - persistStarted);
+  if (!persisted.ok) {
+    return intentError(persisted.error || 'evidence_not_persisted', { persisted: false });
+  }
+  checkExecution();
+  if (capture && context.recording) {
+    const saved = await context.recording.record({ kind: 'intent-capture', revision: context.revision,
+      target: context.target, parentFactId: persisted.evidenceId,
+      data: { rawTreeId: observation.rawTreeId, capture } });
+    if (!saved.ok) return intentError(saved.error, { persisted: false });
+    checkExecution();
+  }
+  const summaryStarted = context.now();
+  const summary = summarizeTree({
+    provider: activeProvider,
+    rawTree: observation.rawTree,
+    rawTreeId: observation.rawTreeId,
+    ...(routed ? { maxBytes: 64 * 1024 - Buffer.byteLength(JSON.stringify(observation.route), 'utf8') - 32 } : {}),
+  });
+  timings.summaryMs = (timings.summaryMs || 0) + (context.now() - summaryStarted);
+  if (!summary.ok) return intentError(summary.error || 'summary_failed');
+  if (routed) summary.foreground = observation.route;
+  const summaryPersist = await context.store.persist('summary', {
+    operationId: context.operationId,
+    revision: context.revision,
+    rawTreeId: observation.rawTreeId,
+    target: context.target,
+    timestampMs: context.now(),
+    observationTarget,
+    summary,
+  });
+  if (!summaryPersist.ok) return intentError(summaryPersist.error || 'summary_not_persisted');
+  checkExecution();
+  const exposed = context.store.canExposeRevision(context.operationId);
+  if (!exposed.ok) return intentError(exposed.error);
+  context.provider = provider;
+  context.observationTarget = observationTarget;
+  context.observationFailure = null;
+  delete context.latestEvidenceIds.observationFailure;
+  context.latestSummary = summary;
+  context.latestProvider = activeProvider;
+  context.latestRoute = observation.route;
+  context.latestEvidenceId = persisted.evidenceId;
+  context.latestCapture = capture;
+  context.latestRawTree = observation.rawTree;
+  context.latestRawTreeId = observation.rawTreeId;
+  context.latestEvidenceIds = {
+    ...context.latestEvidenceIds,
+    observation: persisted.evidenceId,
+    summary: summaryPersist.evidenceId,
+  };
+  return {
+    ok: true,
+    revision: exposed.revision,
+    evidenceId: persisted.evidenceId,
+    summary: context.latestSummary,
+  };
+}
+
+async function observeCapture(context) {
+  if (!context.capturePort || !context.captureRequirements) return null;
+  const { streams, ...requirements } = context.captureRequirements;
+  if (streams.length === 0) return null;
+  const pages = [];
+  context.captureWatermarks ||= new Map();
+  for (const stream of streams) {
+    const previous = context.captureWatermarks.get(stream);
+    const actionCursor = previous && previous.actionId === context.actionId ? previous.actionCursor : previous?.cursor;
+    const page = await context.capturePort.observe({
+      ...requirements,
+      stream,
+      ...(context.actionId && previous && requirements.view !== 'connected-history' && requirements.history !== true
+        ? { factCursor: requirements.factCursor ?? actionCursor, runtimeEpoch: requirements.runtimeEpoch ?? previous.epoch }
+        : {}),
+    }, {
+      target: context.target,
+      platform: context.target.platform,
+      actionId: context.actionId,
+      runtimeEpoch: context.runtimeEpoch,
+      runtimeEpochChanged: context.runtimeEpochChanged === true,
+      disconnected: context.disconnected === true,
+    });
+    // An issued watermark bounds the next action even if earlier retained data
+    // has a known gap. The current observation keeps that partial coverage.
+    if (page.committed === true && ['complete', 'partial'].includes(page.coverage.status)
+      && page.watermarkCursor && page.runtimeEpoch) {
+      context.captureWatermarks.set(stream, { cursor: page.watermarkCursor, epoch: page.runtimeEpoch,
+        actionId: context.actionId, actionCursor: context.actionId ? requirements.factCursor ?? actionCursor : null });
+    }
+    pages.push({ stream, ...page });
+  }
+  return mergeCapturePages(pages);
+}
+
+function mergeCapturePages(pages) {
+  const refs = [];
+  const items = [];
+  let gap = false;
+  let committed = true;
+  let status = null;
+  for (const page of pages) {
+    refs.push(...page.refs);
+    items.push(...page.items);
+    if (page.gap) gap = true;
+    if (page.committed !== true) committed = false;
+    const pageStatus = page.coverage && page.coverage.status;
+    if (
+      pageStatus !== 'complete'
+      && pageStatus !== 'partial'
+      && pageStatus !== 'unavailable'
+    ) {
+      status = 'unavailable';
+    } else if (pageStatus === 'unavailable' || status === 'unavailable') {
+      status = 'unavailable';
+    } else if (pageStatus === 'partial' || status === 'partial') {
+      status = 'partial';
+    } else {
+      status = 'complete';
+    }
+  }
+  if (status == null) {
+    return {
+      coverage: { status: 'unavailable', gap: true, committed: false },
+      gap: true,
+      committed: false,
+      refs: [],
+      items: [],
+    };
+  }
+  return {
+    coverage: { status, gap, committed },
+    gap,
+    committed,
+    refs,
+    items,
+    pages,
+  };
+}
+
+module.exports = { observeAndCommit };