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

package/bin/shared-kernel/web-dom-target.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const { object, text, validateValue } = require('./argument-schema');
+const schema = 'aab.web-dom-target/v1';
+const string = { type: 'string' };
+const elementKeys = ['elementId', 'tag', 'id', 'name', 'type', 'role', 'ariaLabel', 'placeholder', 'href', 'text'];
+const elementSchema = object(Object.fromEntries(elementKeys.map(key => [key, key === 'elementId' ? text : string])), elementKeys);
+const pageSchema = object({ schemaVersion: { const: schema }, sessionId: text, runtimeEpoch: text,
+  targetId: text, navigationId: text, url: text }, ['schemaVersion', 'sessionId', 'runtimeEpoch', 'targetId', 'navigationId', 'url']);
+const selectorSchema = { ...object({ elementId: text, text, ariaLabel: text, css: text, tag: text, role: text }),
+  oneOf: ['elementId', 'text', 'ariaLabel', 'css'].map(key => ({ required: [key] })) };
+const intentSelectorSchema = { ...object({ elementId: text, text, ariaLabel: text, tag: text, role: text }),
+  oneOf: ['elementId', 'text', 'ariaLabel'].map(key => ({ required: [key] })) };
+const expectedTargetSchema = object({ pageRef: pageSchema, element: elementSchema }, ['pageRef', 'element']);
+const reject = error => ({ ok: false, error, dispatched: false, ambiguous: false });
+
+function validateSnapshot(dom, target) {
+  validateValue(dom.pageRef, pageSchema);
+  if (dom.targetSchema !== schema || dom.url !== dom.pageRef.url
+    || ['sessionId', 'runtimeEpoch', 'targetId'].some(key => dom.pageRef[key] !== target[key])
+    || !Array.isArray(dom.controls) || dom.controlCount !== dom.controls.length
+    || typeof dom.truncated !== 'boolean' || typeof dom.bodyTextTruncated !== 'boolean') throw new Error('invalid_web_dom_target');
+  const ids = new Set();
+  for (const node of dom.controls) {
+    validateValue(Object.fromEntries(elementKeys.map(key => [key, node[key]])), elementSchema);
+    if (ids.has(node.elementId) || ['visible', 'disabled', 'editable'].some(key => typeof node[key] !== 'boolean')
+      || ![true, false, 'mixed', null].includes(node.checked)) throw new Error('invalid_web_dom_control');
+    ids.add(node.elementId);
+  }
+}
+
+function selectWebNode(tree, selector) {
+  if (tree?.webTargetSchema !== schema || tree.dom?.targetSchema !== schema) return reject('web_dom_target_schema_required');
+  if (selector.css !== undefined) return reject('web_intent_css_selector_requires_observation');
+  if (tree.dom.truncated) return reject('web_dom_snapshot_truncated');
+  const matches = tree.dom.controls.filter(node => node.visible === true
+    && ['elementId', 'text', 'ariaLabel', 'tag', 'role'].every(key => selector[key] === undefined || selector[key] === node[key]));
+  if (matches.length !== 1) return { ...reject(matches.length ? 'web_element_ambiguous' : 'web_element_not_found'), matched: matches.length };
+  const node = matches[0];
+  if (node.disabled) return reject('web_element_disabled');
+  return { ok: true, node, targetRef: { pageRef: tree.pageRef, element: Object.fromEntries(elementKeys.map(key => [key, node[key]])) } };
+}
+
+module.exports = { schema, selectorSchema, intentSelectorSchema, expectedTargetSchema, pageSchema, elementKeys, selectWebNode, validateSnapshot };

package/bin/shared-kernel/xml-attributes.js

@@ -0,0 +1,25 @@
+'use strict';
+
+// Decode one XML layer. In particular, 
 is the literal text 
.
+function decodeXmlAttribute(value) {
+  const named = { quot: '"', apos: "'", lt: '<', gt: '>', amp: '&' };
+  return value.replace(/&(#x[0-9a-fA-F]+|#[0-9]+|quot|apos|lt|gt|amp);/g, (_, entity) => {
+    if (entity[0] !== '#') return named[entity];
+    const code = entity[1] === 'x' ? Number.parseInt(entity.slice(2), 16) : Number.parseInt(entity.slice(1), 10);
+    if (!(code === 9 || code === 10 || code === 13 || (code >= 0x20 && code <= 0xD7FF)
+      || (code >= 0xE000 && code <= 0xFFFD) || (code >= 0x10000 && code <= 0x10FFFF))) {
+      throw new Error('invalid_xml_character_reference');
+    }
+    return String.fromCodePoint(code);
+  });
+}
+
+function parseXmlAttributes(tag) {
+  const attributes = {};
+  for (const match of tag.matchAll(/([A-Za-z0-9_:-]+)="([^"]*)"/g)) {
+    attributes[match[1]] = decodeXmlAttribute(match[2]);
+  }
+  return attributes;
+}
+
+module.exports = { decodeXmlAttribute, parseXmlAttributes };

package/bin/target-execution.js

@@ -0,0 +1,275 @@
+'use strict';
+
+const { createHash } = require('node:crypto');
+const { targetIdentity } = require('./shared-kernel/execution-target');
+const { CommandError } = require('./command-errors');
+const { isAndroidMutation, isMutationCommand, executionTimeoutMs } = require('./command-registry');
+const { runExecution, checkExecution, currentExecution, executionFailure } = require('./shared-kernel/execution-scope');
+const { getProcessDeviceMutationLease } = require('./shared-kernel/device-mutation-lease');
+
+class TargetExecution {
+  constructor({ requestTtlMs = 5 * 60_000, maxRequests = 2_048, now = Date.now } = {}) {
+    if (!Number.isFinite(requestTtlMs) || requestTtlMs < 0) {
+      throw new TypeError('requestTtlMs must be a non-negative number');
+    }
+    if (!Number.isInteger(maxRequests) || maxRequests < 1) {
+      throw new TypeError('maxRequests must be a positive integer');
+    }
+    if (typeof now !== 'function') {
+      throw new TypeError('now must be a function');
+    }
+    this.targetTails = new Map();
+    this.requests = new Map();
+    this.requestTtlMs = requestTtlMs;
+    this.maxRequests = maxRequests;
+    this.now = now;
+  }
+
+  execute(command, args, runner) {
+    if (typeof command !== 'string' || command.length === 0) {
+      throw new TypeError('command is required');
+    }
+    if (!args || typeof args !== 'object' || Array.isArray(args)) {
+      throw new TypeError('args must be an object');
+    }
+    if (typeof runner !== 'function') {
+      throw new TypeError('runner must be a function');
+    }
+
+    const normalizedArgs = { ...args };
+    const target = targetFor(command, normalizedArgs);
+    const requestKey = idempotencyKey(target.key, normalizedArgs.requestId);
+    const requestHash = requestKey === null ? null : requestDigest(command, normalizedArgs);
+    this.pruneRequests();
+    if (requestKey !== null && this.requests.has(requestKey)) {
+      const existing = this.requests.get(requestKey);
+      if (existing.requestHash !== requestHash) throw new CommandError('idempotency_conflict',
+        'requestId was already used for a different command or arguments.', { field: 'requestId' });
+      return existing.promise;
+    }
+
+    const requestedAtMs = this.now();
+    const deviceMutation = isAndroidMutation(command, normalizedArgs);
+    const queueKey = deviceMutation ? `android-device:${normalizedArgs.serial}`
+      : command === 'web-execution' ? `${target.key}:control`
+      : command === 'web-dom' ? `${target.key}:observation` : target.key;
+    const execution = runExecution({ timeoutMs: executionTimeoutMs(command, normalizedArgs), mutation: isMutationCommand(command, normalizedArgs) }, () => this.enqueue(queueKey, async () => {
+      const startedAtMs = this.now();
+      try {
+        const legacyResult = deviceMutation
+          ? await getProcessDeviceMutationLease().run(normalizedArgs.serial, () => runner(command, normalizedArgs))
+          : await runner(command, normalizedArgs);
+        const completedAtMs = this.now();
+        const feedback = buildFeedback({
+          command,
+          requestId: normalizedArgs.requestId,
+          target,
+          status: resultStatus(legacyResult),
+          requestedAtMs,
+          startedAtMs,
+          completedAtMs,
+        });
+        return feedbackEnabled(normalizedArgs.feedback)
+          ? appendFeedback(legacyResult, feedback)
+          : legacyResult;
+      } catch (error) {
+        const completedAtMs = this.now();
+        if (feedbackEnabled(normalizedArgs.feedback)) {
+          error._feedback = buildFeedback({
+            command,
+            requestId: normalizedArgs.requestId,
+            target,
+            status: 'failed',
+            requestedAtMs,
+            startedAtMs,
+            completedAtMs,
+          });
+        }
+        throw error;
+      }
+    }));
+
+    if (requestKey !== null) {
+      const request = {
+        requestHash,
+        promise: execution,
+        settled: false,
+        expiresAtMs: Number.POSITIVE_INFINITY,
+      };
+      this.requests.set(requestKey, request);
+      const markSettled = () => {
+        request.settled = true;
+        request.expiresAtMs = this.now() + this.requestTtlMs;
+        this.pruneRequests();
+      };
+      execution.then(markSettled, markSettled);
+    }
+    return execution;
+  }
+
+  pruneRequests() {
+    const now = this.now();
+    for (const [key, request] of this.requests) {
+      if (request.settled && request.expiresAtMs < now) {
+        this.requests.delete(key);
+      }
+    }
+    if (this.requests.size <= this.maxRequests) return;
+    for (const [key, request] of this.requests) {
+      if (!request.settled) continue;
+      this.requests.delete(key);
+      if (this.requests.size <= this.maxRequests) return;
+    }
+  }
+
+  enqueue(targetKey, action) {
+    const previous = this.targetTails.get(targetKey) || Promise.resolve();
+    const scope = currentExecution();
+    let started = false;
+    let abort;
+    const execution = previous.catch(() => undefined).then(() => {
+      started = true;
+      scope?.signal.removeEventListener('abort', abort);
+      checkExecution();
+      return action();
+    });
+    this.targetTails.set(targetKey, execution);
+    const clearTail = () => {
+      if (this.targetTails.get(targetKey) === execution) {
+        this.targetTails.delete(targetKey);
+      }
+    };
+    execution.then(clearTail, clearTail);
+    // A queued cancellation may return immediately, but the queue barrier stays
+    // behind the preceding operation. Once dispatched, await actual settlement.
+    return new Promise((resolve, reject) => {
+      abort = () => { if (!started) reject(executionFailure(scope)); };
+      scope?.signal.addEventListener('abort', abort, { once: true });
+      execution.then(resolve, reject).finally(() => scope?.signal.removeEventListener('abort', abort));
+    });
+  }
+}
+
+function feedbackEnabled(value) {
+  return value !== false && String(value || 'auto').toLowerCase() !== 'off';
+}
+
+function requestDigest(command, args) {
+  function canonical(value) {
+    if (Array.isArray(value)) return value.map(canonical);
+    if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]));
+    return value;
+  }
+  const { requestId, ...content } = args;
+  return createHash('sha256').update(JSON.stringify(canonical({ command, arguments: content }))).digest('hex');
+}
+
+function targetFor(command, args) {
+  if (command === 'logcat' && String(args.deviceLogScope || '').toLowerCase() === 'device') {
+    const serial = targetPart(args.serial);
+    return {
+      kind: 'android-device',
+      key: targetKey('android-device', serial, ''),
+      serial,
+    };
+  }
+
+  if (command.startsWith('ios-')) {
+    const deviceId = targetPart(args.deviceId);
+    const bundleId = targetPart(args.bundleId);
+    return {
+      kind: 'ios', platform: 'ios',
+      key: targetIdentity({ platform: 'ios', deviceId, bundleId }),
+      deviceId,
+      bundleId,
+    };
+  }
+
+  if (command.startsWith('web-')) {
+    const sessionId = targetPart(args.sessionId);
+    const targetId = targetPart(args.targetId);
+    const runtimeEpoch = targetPart(args.runtimeEpoch);
+    return {
+      kind: 'web', platform: 'web',
+      key: targetIdentity({ platform: 'web', sessionId, runtimeEpoch, targetId }),
+      sessionId,
+      runtimeEpoch,
+      targetId,
+    };
+  }
+
+  const serial = targetPart(args.serial);
+  const packageName = targetPart(args.packageName);
+  return {
+    kind: 'android', platform: 'android',
+    key: targetIdentity({ platform: 'android', serial, packageName }),
+    serial,
+    packageName,
+  };
+}
+
+function targetPart(value) {
+  return value === undefined || value === null ? '' : String(value);
+}
+
+function targetKey(kind, first, second) {
+  return `${kind}:${JSON.stringify([first, second])}`;
+}
+
+function idempotencyKey(targetKeyValue, requestId) {
+  if (requestId === undefined || requestId === null) return null;
+  return JSON.stringify([targetKeyValue, String(requestId)]);
+}
+
+function resultStatus(result) {
+  if (result && typeof result === 'object' && result.ok === false) return 'failed';
+  if (result && typeof result === 'object' && result.verified === true) return 'verified';
+  if (result === undefined || result === null) return 'inconclusive';
+  if (result && typeof result === 'object' && result.inconclusive === true) return 'inconclusive';
+  return 'completed';
+}
+
+function buildFeedback({
+  command,
+  requestId,
+  target,
+  status,
+  requestedAtMs,
+  startedAtMs,
+  completedAtMs,
+}) {
+  return {
+    status,
+    target,
+    dispatch: {
+      command,
+      requestId: requestId === undefined ? null : requestId,
+      serializedByTarget: true,
+    },
+    timings: {
+      requestedAtMs,
+      startedAtMs,
+      completedAtMs,
+      queueWaitMs: startedAtMs - requestedAtMs,
+      durationMs: completedAtMs - startedAtMs,
+    },
+    evidence: [],
+  };
+}
+
+function appendFeedback(legacyResult, feedback) {
+  if (
+    legacyResult === null
+    || typeof legacyResult !== 'object'
+    || Buffer.isBuffer(legacyResult)
+    || Array.isArray(legacyResult)
+  ) {
+    return legacyResult;
+  }
+  return { ...legacyResult, _feedback: feedback };
+}
+
+module.exports = {
+  TargetExecution,
+  targetFor,
+};

package/bin/web/command-schema.js

@@ -0,0 +1,60 @@
+'use strict';
+const { webCommandSchema } = require('../shared-kernel/provider-command-contracts');
+const { selectorSchema, expectedTargetSchema } = require('../shared-kernel/web-dom-target');
+const text = { type: 'string', minLength: 1, maxLength: 1024 };
+const integer = (minimum, maximum) => ({ type: 'integer', minimum, maximum });
+const object = (properties, required = []) => ({ type: 'object', additionalProperties: false, properties, required });
+const target = { sessionId: text, runtimeEpoch: text, targetId: { enum: ['main'], default: 'main' } };
+const control = { timeoutMs: { ...integer(1, 30000), default: 5000 }, requestId: text, feedback: { enum: ['auto', 'off', 'full'] } };
+const query = { history: { type: 'boolean', default: false }, sinceMs: integer(0, Number.MAX_SAFE_INTEGER),
+  cursor: { ...text, maxLength: 4096 }, throughCursor: { ...text, maxLength: 4096 }, limit: { ...integer(1, 16), default: 16 } };
+const cursorPair = { anyOf: [{ required: ['cursor', 'throughCursor'] }, { not: { anyOf: [{ required: ['cursor'] }, { required: ['throughCursor'] }] } }] };
+
+function webSchema(command) {
+  if (command === 'web-session-start') return object({ host: text, webPort: integer(0, 65535),
+    path: { ...text, pattern: '^/[A-Za-z0-9/_-]+$' }, token: text, ...control });
+  if (['web-provider-status', 'web-session-stop', 'web-connect-info', 'web-sessions'].includes(command)) return object(control);
+  if (command === 'web-status') return object({ sessionId: text, ...control }, ['sessionId']);
+  if (command === 'web-execution') return { ...object({ ...target, ...control,
+    operation: { enum: ['status', 'result', 'cancel', 'reconcile'] }, actionId: text }, ['operation', 'sessionId', 'runtimeEpoch']),
+    oneOf: [{ properties: { operation: { enum: ['status', 'reconcile'] }, actionId: false } },
+      { properties: { operation: { enum: ['result', 'cancel'] } }, required: ['actionId'] }] };
+  if (command === 'web-command') {
+    const schema = webCommandSchema({ ...target, ...control });
+    for (const branch of schema.anyOf) branch.required.push('runtimeEpoch');
+    schema.required.push('sessionId', 'runtimeEpoch');
+    return schema;
+  }
+  if (['web-logs', 'web-network', 'web-state', 'web-events'].includes(command)) return {
+    ...object({ ...target, ...query, ...control,
+      view: { enum: ['decision-window', 'connected-history'], default: 'decision-window' },
+      factCursor: { ...text, maxLength: 4096 }, afterActionId: text,
+    }, ['sessionId', 'runtimeEpoch']), allOf: [cursorPair,
+      { not: { properties: { history: { const: true }, view: { const: 'decision-window' } }, required: ['history', 'view'] } },
+      { if: { required: ['afterActionId'] }, then: { required: ['factCursor'] } },
+      { if: { anyOf: [
+        { properties: { history: { const: true } }, required: ['history'] },
+        { properties: { view: { const: 'connected-history' } }, required: ['view'] },
+      ] }, then: { properties: { factCursor: false, afterActionId: false } } },
+    ] };
+  if (command === 'web-dom') return { ...object({ ...target, ...query, ...control, selector: text, maxControls: integer(1, 1000) }, ['sessionId', 'runtimeEpoch']),
+    allOf: [cursorPair], oneOf: [
+      { properties: { history: { const: false }, cursor: false, throughCursor: false, sinceMs: false, limit: false } },
+      { properties: { history: { const: true }, selector: false, maxControls: false }, required: ['history'] },
+    ] };
+  if (command === 'web-scroll') return { ...object({ ...target, ...control, selector: selectorSchema, expectedTarget: expectedTargetSchema,
+    mode: { enum: ['into-view', 'by'] }, deltaX: { type: 'number' }, deltaY: { type: 'number' } }, ['sessionId', 'runtimeEpoch', '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'] } }] };
+  const fields = command === 'web-key' ? { selector: selectorSchema, expectedTarget: expectedTargetSchema, key: { enum: ['Enter', 'Escape'] } }
+    : command === 'web-input' ? { selector: selectorSchema, expectedTarget: expectedTargetSchema, value: { type: 'string', maxLength: 16384 } }
+    : command === 'web-click' ? { selector: selectorSchema, expectedTarget: expectedTargetSchema }
+    : { selector: selectorSchema, targetText: text };
+  const schema = object({ ...target, ...control, ...fields }, ['sessionId', 'runtimeEpoch',
+    ...(command === 'web-key' ? ['selector', 'key'] : command === 'web-input' ? ['selector', 'value'] : command === 'web-click' ? ['selector'] : [])]);
+  if (command === 'web-wait') schema.oneOf = [
+    { required: ['selector'], properties: { targetText: false } }, { required: ['targetText'], properties: { selector: false } }];
+  return schema;
+}
+module.exports = { webSchema };

package/bin/web/session-store.js

@@ -0,0 +1,157 @@
+'use strict';
+
+const { createHash, randomUUID } = require('node:crypto');
+const { isDeepStrictEqual } = require('node:util');
+const { getHostFactStore } = require('../shared-kernel/host-fact-store');
+const { sanitizePersistentValue } = require('../fact-codec');
+const { CommandError } = require('../command-errors');
+
+const partitions = { logs: 'app-log', network: 'network', state: 'state-event', events: 'state-event', dom: 'ui', completion: 'action', 'capture-barrier': 'action' };
+const maxRecordBytes = 128 * 1024;
+const maxPageRecords = 16;
+const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const key = (target, stream) => `web:${JSON.stringify([target.sessionId, target.targetId, stream])}`;
+
+// Web facts are Host-owned. Every ingress is committed through the existing
+// FactStore; sessions keep connection metadata, never another payload cache.
+class WebSessionStore {
+  constructor(getStore = getHostFactStore) { this.getStore = getStore; }
+
+  record(target, stream, item, { captureId, actionId = null } = {}) {
+    if (!partitions[stream]) throw new CommandError('invalid_web_stream', 'Unknown Web capture stream.');
+    const payload = { schemaVersion: 'aab.web-fact/v1', stream, ...target, captureId, item };
+    if (Buffer.byteLength(JSON.stringify(payload)) > maxRecordBytes)
+      throw new CommandError('web_record_too_large', 'Web facts must not exceed 128 KiB.');
+    const result = this.getStore().record({ partition: partitions[stream], targetKey: key(target, stream),
+      runtimeEpoch: target.runtimeEpoch, actionId, dedupeKey: `${key(target, stream)}:${target.runtimeEpoch}:${captureId}:${digest(payload)}`,
+      payload }, { durability: 'sync' });
+    const receipt = result.receipt;
+    if (result.ok !== true || receipt?.stored !== true)
+      throw new CommandError('web_persistence_unavailable', 'The Web fact was not committed; no memory result is substituted.');
+    return { stored: true, source: 'host-fact-store', globalSeq: receipt.globalSeq,
+      targetKey: key(target, stream), runtimeEpoch: target.runtimeEpoch, captureId,
+      representation: 'fact-store-redacted', originalSha256: digest(payload), storedSha256: digest(sanitizePersistentValue(payload)) };
+  }
+
+  read(target, stream, args = {}) {
+    const limit = args.limit ?? maxPageRecords;
+    if (!partitions[stream] || !Number.isInteger(limit) || limit < 1 || limit > maxPageRecords)
+      throw new CommandError('invalid_web_query', 'Web capture queries require a known stream and limit from 1 to 16.');
+    const query = { targetKey: key(target, stream), runtimeEpoch: target.runtimeEpoch,
+      partitions: [partitions[stream]], limit,
+      ...(args.sinceMs === undefined ? {} : { fromObservedAtMs: args.sinceMs }) };
+    const store = this.getStore();
+    const upper = args.throughCursor === undefined
+      ? store.read({ ...query, fromObservedAtMs: Number.MAX_SAFE_INTEGER, limit: 1 }) : null;
+    if (upper && upper.ok !== true) return upper;
+    const throughCursor = args.throughCursor ?? upper.cursor;
+    const page = store.read({ ...query, cursor: args.cursor, throughCursor });
+    if (!page.ok) return page;
+    const items = page.items.map(fact => {
+      const value = fact.payload;
+      if (value?.schemaVersion !== 'aab.web-fact/v1' || value.stream !== stream
+          || !isDeepStrictEqual({ sessionId: value.sessionId, runtimeEpoch: value.runtimeEpoch, targetId: value.targetId }, target))
+        throw new CommandError('invalid_web_fact', 'Stored Web fact does not match the requested document.');
+      return { ...value.item, id: fact.globalSeq, captureId: value.captureId, actionId: fact.actionId,
+        sessionId: target.sessionId, runtimeEpoch: target.runtimeEpoch, targetId: target.targetId,
+        receivedAtMs: fact.timestamps.observedAtMs,
+        ref: { source: 'host-fact-store', stream, globalSeq: fact.globalSeq, targetKey: fact.targetKey, runtimeEpoch: fact.runtimeEpoch } };
+    });
+    // State is a stream of recorded updates. Values describes this returned
+    // page only; it is not a fabricated snapshot of every current App key.
+    return { ok: true, type: stream, ...target, source: 'host-fact-store', persistence: true,
+      history: args.history === true, items, count: items.length, ...(stream === 'state' ? { values: stateValues(items) } : {}),
+      cursor: page.cursor, throughCursor, hasMore: page.hasMore, gap: page.gap, cursorExpired: page.cursorExpired };
+  }
+
+  saveCaptureBarrier(target, stream, status) {
+    const upper = this.getStore().read({ targetKey: key(target, stream), runtimeEpoch: target.runtimeEpoch,
+      partitions: [partitions[stream]], fromObservedAtMs: Number.MAX_SAFE_INTEGER, limit: 1 });
+    if (upper.ok !== true) throw new CommandError(upper.error, 'The capture watermark could not be read.');
+    const id = randomUUID();
+    const value = { stream, cursor: upper.cursor, ...status };
+    const receipt = this.record(target, 'capture-barrier', value, { captureId: id, actionId: id });
+    return { ...value, token: `wc1:${id}`, globalSeq: receipt.globalSeq };
+  }
+
+  captureBarrier(target, stream, token) {
+    if (typeof token !== 'string' || !/^wc1:[a-f0-9-]{36}$/.test(token))
+      throw new CommandError('invalid_web_capture_cursor', 'Use a watermark issued for this document and stream.');
+    const page = this.getStore().read({ partitions: ['action'], targetKey: key(target, 'capture-barrier'),
+      runtimeEpoch: target.runtimeEpoch, actionId: token.slice(4), limit: 2 });
+    if (page.ok !== true || page.items.length !== 1)
+      throw new CommandError('web_capture_cursor_unavailable', 'The original persisted capture watermark is unavailable.');
+    const fact = page.items[0], value = fact.payload;
+    if (value?.schemaVersion !== 'aab.web-fact/v1' || value.stream !== 'capture-barrier'
+      || value.item.stream !== stream || value.sessionId !== target.sessionId
+      || value.runtimeEpoch !== target.runtimeEpoch || value.targetId !== target.targetId)
+      throw new CommandError('web_capture_cursor_mismatch', 'The capture watermark belongs to another document or stream.');
+    return { ...value.item, token, globalSeq: fact.globalSeq };
+  }
+
+  readWindow(target, stream, args, through) {
+    const before = args.factCursor === undefined ? null : this.captureBarrier(target, stream, args.factCursor);
+    if (args.afterActionId !== undefined && before === null)
+      throw new CommandError('decision_watermark_required', 'Observe a capture watermark before the action.');
+    if (before && before.globalSeq > through.globalSeq)
+      throw new CommandError('invalid_web_capture_window', 'The upper watermark precedes the lower watermark.');
+    const page = this.read(target, stream, { ...args,
+      cursor: args.cursor ?? before?.cursor, throughCursor: through.cursor });
+    if (page.ok !== true) return page;
+    const reasons = [];
+    if (before && before.connectionId !== through.connectionId) reasons.push('web_capture_connection_changed');
+    const sdkProduced = through.sdk.sequence - (before?.sdk.sequence ?? 0);
+    const hostAccepted = through.host.accepted - (before?.host.accepted ?? 0);
+    if (sdkProduced !== hostAccepted || through.host.lastSequence !== through.sdk.sequence)
+      reasons.push('web_capture_sequence_gap');
+    if (through.sdk.losses !== (before?.sdk.losses ?? 0)
+      || through.host.rejected !== (before?.host.rejected ?? 0)) reasons.push('web_capture_loss');
+    const gap = reasons.length > 0 || page.gap;
+    if (through.sdk.pending > 0) reasons.push('web_capture_pending');
+    const items = args.afterActionId === undefined ? page.items : page.items.filter(item => item.actionId === args.afterActionId);
+    return { ...page, items, count: items.length, ...(stream === 'state' ? { values: stateValues(items) } : {}),
+      refs: items.map(item => item.ref), stream,
+      targetKey: key(target, stream), runtimeEpoch: target.runtimeEpoch,
+      coverage: { status: reasons.length ? 'partial' : 'complete', gap, committed: true,
+        scope: 'sdk-captures-through-barrier', reasons }, gap, committed: true,
+      window: { filterApplied: true, afterActionId: args.afterActionId ?? null,
+        factCursor: args.factCursor ?? null, sinceId: null, sinceMs: args.sinceMs ?? null,
+        targetKey: key(target, stream), runtimeEpoch: target.runtimeEpoch },
+      watermarkCursor: through.token, throughWatermark: through.globalSeq,
+      nextCursor: page.hasMore ? page.cursor : null, throughCursor: through.token,
+      barrier: { schemaVersion: 'aab.web-capture-window/v1',
+        lower: before === null ? null : { sdk: before.sdk, host: before.host, connectionId: before.connectionId },
+        upper: { sdk: through.sdk, host: through.host, connectionId: through.connectionId } },
+    };
+  }
+
+  saveCompletion(target, result) {
+    return this.record(target, 'completion', { result, originalSha256: digest(result) },
+      { captureId: result.actionId, actionId: result.actionId });
+  }
+
+  completion(target, actionId) {
+    const page = this.getStore().read({ partitions: ['action'], targetKey: key(target, 'completion'),
+      runtimeEpoch: target.runtimeEpoch, actionId, limit: 2 });
+    if (!page.ok) return page;
+    if (page.items.length !== 1) return { ok: false, error: 'web_original_completion_unavailable', settled: false };
+    const fact = page.items[0], payload = fact.payload;
+    if (payload?.schemaVersion !== 'aab.web-fact/v1' || payload.stream !== 'completion'
+        || !isDeepStrictEqual({ sessionId: payload.sessionId, runtimeEpoch: payload.runtimeEpoch, targetId: payload.targetId }, target)
+        || payload.item?.result?.actionId !== actionId)
+      return { ok: false, error: 'invalid_web_completion', settled: false };
+    return { ok: true, actionId, runtimeEpoch: target.runtimeEpoch, executionResult: payload.item.result,
+      receipt: { stored: true, globalSeq: fact.globalSeq, source: 'host-fact-store', originalSha256: payload.item.originalSha256 } };
+  }
+}
+
+function stateValues(items) {
+  const values = {};
+  for (const item of items) {
+    if (!Object.hasOwn(values, item.namespace)) Object.defineProperty(values, item.namespace, { value: {}, enumerable: true });
+    Object.defineProperty(values[item.namespace], item.key, { value: item.value, enumerable: true, configurable: true });
+  }
+  return values;
+}
+
+module.exports = { WebSessionStore, maxRecordBytes, maxPageRecords, digest };