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

package/bin/fact-store.js

@@ -0,0 +1,226 @@
+'use strict';
+
+const { createSegmentedFactStoreAdapter } = require('./segmented-fact-store');
+
+/**
+ * Stable FactStore Module boundary.
+ *
+ * Runtime callers use record for an immediate commit or offer for a bounded
+ * asynchronous write, then read/status. Segment layout, recovery, quotas,
+ * cursors and diagnostic adapters remain implementation details.
+ */
+class FactStore {
+  constructor(adapter, { queueLimit = 256, schedule = setImmediate } = {}) {
+    assertAdapter(adapter);
+    if (!Number.isInteger(queueLimit) || queueLimit < 1) {
+      throw new TypeError('queueLimit must be a positive integer');
+    }
+    if (typeof schedule !== 'function') throw new TypeError('schedule must be a function');
+    this.adapter = adapter;
+    this.queueLimit = queueLimit;
+    this.schedule = schedule;
+    this.queue = [];
+    this.scheduled = false;
+    this.flushing = false;
+    this.flushPromise = null;
+    this.drainWaiters = [];
+    this.closed = false;
+    this.writerAvailable = true;
+    this.writerReason = null;
+    this.writerDropped = 0;
+    this.writerLastError = null;
+  }
+
+  record(facts, options = {}) {
+    if (this.closed) throw new Error('FactStore is closed');
+    const list = Array.isArray(facts) ? facts : [facts];
+    if (list.length === 0) return { ok: true, receipts: [], count: 0 };
+    const receipts = list.map((fact) => this.adapter.record(fact, options));
+    if (receipts.some(isPromise)) {
+      throw new TypeError('FactStore.record must complete synchronously; use offer for asynchronous writes');
+    }
+    return {
+      ok: receipts.every((receipt) => receipt?.ok !== false),
+      receipts,
+      count: receipts.length,
+      ...(Array.isArray(facts) ? {} : { receipt: receipts[0] }),
+    };
+  }
+
+  offer(facts, options = {}) {
+    if (this.closed) return rejectedOffer('closed');
+    if (!this.writerAvailable) return rejectedOffer(this.writerReason || 'unavailable');
+    if (this.queue.length >= this.queueLimit) {
+      this.writerDropped += 1;
+      return rejectedOffer('queue_full');
+    }
+    let resolveCompletion;
+    const completion = new Promise((resolve) => {
+      resolveCompletion = resolve;
+    });
+    this.queue.push({ facts, options, resolveCompletion });
+    this.kick();
+    return { accepted: true, completion };
+  }
+
+  read(query = {}) {
+    return this.adapter.read(query);
+  }
+
+  status() {
+    return {
+      ...this.adapter.status(),
+      writer: {
+        available: !this.closed && this.writerAvailable,
+        reason: this.closed ? 'closed' : this.writerReason,
+        queueLength: this.queue.length,
+        dropped: this.writerDropped,
+        lastError: this.writerLastError,
+        flushing: this.flushing,
+      },
+    };
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.queue.length > 0) {
+      this.writerDropped += this.queue.length;
+      this.settleQueuedFailures('closed');
+    }
+    this.adapter.close?.();
+  }
+
+  async drain() {
+    if (this.queue.length === 0 && !this.flushing && !this.scheduled) return;
+    this.kick();
+    await new Promise((resolve) => this.drainWaiters.push(resolve));
+  }
+
+  kick() {
+    if (this.scheduled || this.flushing || this.queue.length === 0 || !this.writerAvailable) return;
+    this.scheduled = true;
+    this.schedule(() => {
+      this.scheduled = false;
+      void this.flush();
+    });
+  }
+
+  flush() {
+    if (this.flushPromise) return this.flushPromise;
+    this.flushing = true;
+    this.flushPromise = (async () => {
+      while (this.queue.length > 0 && this.writerAvailable) {
+        const item = this.queue[0];
+        const result = await recordAsync(this.adapter, item.facts, item.options);
+        item.resolveCompletion(result);
+        this.queue.shift();
+        if (result.ok === false) {
+          this.writerLastError = result.error || 'persist_failed';
+          if (isTerminalWriterError(result.error)) {
+            this.writerAvailable = false;
+            this.writerReason = result.error;
+            this.writerDropped += this.queue.length;
+            this.settleQueuedFailures(result.error);
+          }
+        }
+      }
+    })().finally(() => {
+      this.flushing = false;
+      this.flushPromise = null;
+      this.resolveDrainWaiters();
+      this.kick();
+    });
+    return this.flushPromise;
+  }
+
+  settleQueuedFailures(error) {
+    while (this.queue.length > 0) {
+      const item = this.queue.shift();
+      item.resolveCompletion({ ok: false, stored: false, error });
+    }
+  }
+
+  resolveDrainWaiters() {
+    if (this.queue.length > 0 || this.flushing || this.scheduled) return;
+    for (const resolve of this.drainWaiters.splice(0)) resolve();
+  }
+
+}
+
+function createSegmentedFactStore(options = {}) {
+  return new FactStore(createSegmentedFactStoreAdapter(options), {
+    queueLimit: options.queueLimit,
+    schedule: options.schedule,
+  });
+}
+
+/**
+ * Production factory. Segmented mmap is the only authoritative fact-payload
+ * implementation. SQLite belongs exclusively to the rebuildable query
+ * projection inside SegmentedFactStore; it is never a second payload backend
+ * and native-load failures are never hidden by switching storage engines.
+ */
+function createFactStore(options = {}) {
+  if (Object.prototype.hasOwnProperty.call(options, 'backend')) {
+    throw new TypeError('FactStore backend selection is not supported; segmented mmap is authoritative');
+  }
+  return createSegmentedFactStore(options);
+}
+
+function assertAdapter(adapter) {
+  if (
+    !adapter
+    || typeof adapter.record !== 'function'
+    || typeof adapter.read !== 'function'
+    || typeof adapter.status !== 'function'
+  ) {
+    throw new TypeError('FactStore adapter must implement record/read/status');
+  }
+}
+
+async function recordAsync(adapter, facts, options) {
+  const list = Array.isArray(facts) ? facts : [facts];
+  if (list.length === 0) return { ok: true, receipts: [], count: 0 };
+  const receipts = [];
+  try {
+    for (const fact of list) {
+      receipts.push(await adapter.record(fact, options));
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      stored: false,
+      error: error.code || error.message || 'persist_failed',
+      detail: error.message || String(error),
+    };
+  }
+  return {
+    ok: receipts.every((receipt) => receipt?.ok !== false),
+    receipts,
+    count: receipts.length,
+    ...(Array.isArray(facts) ? {} : {
+      receipt: receipts[0],
+      stored: receipts[0]?.stored,
+      error: receipts[0]?.error,
+    }),
+  };
+}
+
+function isPromise(value) {
+  return value && typeof value.then === 'function';
+}
+
+function isTerminalWriterError(error) {
+  return error === 'ENOSPC' || error === 'fact_store_disabled';
+}
+
+function rejectedOffer(reason) {
+  return { accepted: false, reason };
+}
+
+module.exports = {
+  FactStore,
+  createFactStore,
+  createSegmentedFactStore,
+};

package/bin/feedback-probe.js

@@ -0,0 +1,285 @@
+'use strict';
+
+async function runWithFeedbackProbe({
+  command,
+  args = {},
+  runner,
+  sleep = delay,
+  maxWaitMs = 400,
+  intervalMs = 100,
+} = {}) {
+  if (typeof runner !== 'function') throw new TypeError('runner is required');
+  if (!isFullFeedback(args.feedback) || !isMutationCommand(command)) {
+    return { result: await runner(command, args), observation: null, evidence: [] };
+  }
+  if (command === 'launch-app' || command === 'launch-activity') {
+    return captureLaunchFeedback(command, args, runner);
+  }
+
+  const eventCommand = eventCommandFor(command);
+  const before = await safeRun(runner, eventCommand, { ...args, limit: 1 });
+  let sinceId = latestId(before?.items);
+  const result = await runner(command, args);
+  const evidence = [];
+  const uiEvents = [];
+  const semanticEvents = [];
+  const renderEvents = [];
+  const interactionEvents = [];
+  const attempts = Math.max(1, Math.ceil(maxWaitMs / Math.max(1, intervalMs)));
+  let pollCount = 0;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    await sleep(intervalMs);
+    pollCount += 1;
+    const captured = await safeRun(runner, eventCommand, {
+      ...args,
+      sinceId,
+      limit: 100,
+    });
+    if (!captured) continue;
+    evidence.push({ command: eventCommand, result: captured });
+    const items = Array.isArray(captured.items) ? captured.items : [];
+    sinceId = Math.max(sinceId, latestId(items));
+    for (const item of items.filter(isUiEvent)) {
+      const kind = uiEventKind(item);
+      if (kind === 'stable') continue;
+      uiEvents.push(item);
+      if (kind === 'semantic') semanticEvents.push(item);
+      if (kind === 'render' || item?.data?.renderChanged === true) renderEvents.push(item);
+      if (kind === 'interaction' || uiEventHasInteraction(item)) interactionEvents.push(item);
+    }
+    if (semanticEvents.length > 0) break;
+  }
+
+  if (semanticEvents.length > 0) {
+    return {
+      result,
+      evidence,
+      observation: {
+        mode: 'full',
+        changed: true,
+        semanticChanged: true,
+        renderChanged: renderEvents.length > 0,
+        interactionObserved: interactionEvents.length > 0,
+        inconclusive: false,
+        waitedMs: Math.min(maxWaitMs, pollCount * intervalMs),
+        events: uiEvents.slice(0, 20).map(summarizeUiEvent),
+      },
+    };
+  }
+
+  const fallback = {};
+  const treeCommand = treeCommandFor(command);
+  const tree = await safeRun(runner, treeCommand, args);
+  if (tree) {
+    evidence.push({ command: treeCommand, result: tree });
+    fallback.tree = summarizeTree(tree);
+  }
+  if (args.feedbackScreenshot !== false && !String(command).startsWith('web-')) {
+    const screenshotCommand = screenshotCommandFor(command);
+    const screenshot = await safeRun(runner, screenshotCommand, args);
+    if (screenshot) {
+      evidence.push({ command: screenshotCommand, result: screenshot });
+      fallback.screenshot = summarizeScreenshot(screenshot);
+    }
+  }
+  return {
+    result,
+    evidence,
+    observation: {
+      mode: 'full',
+      changed: renderEvents.length > 0,
+      semanticChanged: false,
+      renderChanged: renderEvents.length > 0,
+      interactionObserved: interactionEvents.length > 0,
+      inconclusive: true,
+      waitedMs: Math.min(maxWaitMs, pollCount * intervalMs),
+      events: uiEvents.slice(0, 20).map(summarizeUiEvent),
+      fallback,
+    },
+  };
+}
+
+async function captureLaunchFeedback(command, args, runner) {
+  // Launch must work without a running App SDK. Observe the system only after
+  // the original launch has settled, without claiming a before/after UI change.
+  const result = await runner(command, args);
+  if (result?.ok !== true) return { result, observation: null, evidence: [] };
+  const evidence = [];
+  const current = { foreground: result.foreground ?? null };
+  const targetArgs = pick(args, ['serial', 'adb', 'adbPath', 'packageName']);
+  const reads = [['uia-tree', { ...targetArgs, compact: true }, 'tree', summarizeTree]];
+  if (args.feedbackScreenshot !== false) reads.push(['screenshot', targetArgs, 'screenshot', summarizeScreenshot]);
+  for (const [readCommand, readArgs, key, summarize] of reads) {
+    let captured;
+    try { captured = await runner(readCommand, readArgs); }
+    catch (error) { captured = { ok: false, error: error.code || 'feedback_capture_failed', message: String(error.message || error) }; }
+    evidence.push({ command: readCommand, result: captured });
+    current[key] = summarize(captured);
+  }
+  return { result, evidence, observation: {
+    mode: 'full', basis: 'post-launch-system-snapshot', changed: false,
+    semanticChanged: false, renderChanged: false, interactionObserved: false,
+    inconclusive: true, events: [], current,
+  } };
+}
+
+function isFullFeedback(value) {
+  return String(value || '').toLowerCase() === 'full';
+}
+
+function isMutationCommand(command) {
+  const normalized = String(command || '').toLowerCase();
+  const readOnly = new Set([
+    'status', 'tree', 'uia-tree', 'screenshot', 'logs', 'network', 'state', 'events',
+    'logcat', 'keyboard-state', 'wait-text', 'flutter-tree', 'flutter-nodes', 'h5-dom',
+    'flutter-h5-dom', 'webview-pages', 'webview-network', 'webview-console',
+    'ios-status', 'ios-tree', 'ios-logs', 'ios-network', 'ios-state', 'ios-events',
+    'ios-h5-dom', 'ios-flutter-tree', 'ios-flutter-nodes', 'ios-screenshot',
+    'ios-uia-tree', 'ios-wda-status', 'ios-devices', 'ios-doctor',
+    'web-provider-status', 'web-connect-info', 'web-sessions', 'web-status', 'web-dom',
+    'web-logs', 'web-network', 'web-state', 'web-events', 'web-wait',
+  ]);
+  return !readOnly.has(normalized);
+}
+
+function eventCommandFor(command) {
+  const normalized = String(command || '');
+  if (normalized.startsWith('ios-')) return 'ios-events';
+  if (normalized.startsWith('web-')) return 'web-events';
+  return 'events';
+}
+
+function treeCommandFor(command) {
+  const normalized = String(command || '');
+  if (normalized.startsWith('ios-')) return 'ios-tree';
+  if (normalized.startsWith('web-')) return 'web-dom';
+  return 'tree';
+}
+
+function screenshotCommandFor(command) {
+  return String(command || '').startsWith('ios-') ? 'ios-screenshot' : 'screenshot';
+}
+
+async function safeRun(runner, command, args) {
+  try {
+    return await runner(command, args);
+  } catch (_) {
+    return null;
+  }
+}
+
+function latestId(items) {
+  if (!Array.isArray(items)) return 0;
+  return items.reduce((latest, item) => {
+    const id = Number(item?.id);
+    return Number.isFinite(id) ? Math.max(latest, id) : latest;
+  }, 0);
+}
+
+function isUiEvent(item) {
+  const category = String(item?.category || '').toLowerCase();
+  const name = String(item?.name || '').toLowerCase();
+  return category === 'ui' || category.startsWith('ui.') || name.startsWith('ui.');
+}
+
+function uiEventKind(item) {
+  const name = String(item?.name || '').toLowerCase();
+  const data = item?.data && typeof item.data === 'object' ? item.data : {};
+  if (name === 'ui.stable' || name.endsWith('.stable')) return 'stable';
+  if (data.semanticChanged === true) return 'semantic';
+  if (data.semanticChanged === false && data.renderChanged === true) return 'render';
+  if (data.renderOnly === true) return 'render';
+  if (name.includes('animation') || name.includes('frame') || name.includes('render')) return 'render';
+  if (
+    name === 'ui.changed'
+    && String(data.platform || '').toLowerCase() === 'flutter'
+    && (Number(data.frameCount) > 0 || Number(data.batchFrames) > 0)
+  ) {
+    return 'render';
+  }
+  if (
+    name === 'ui.changed'
+    && data.activeAnimations === true
+    && Number(data.changedComponentCount || 0) === 0
+  ) {
+    return 'render';
+  }
+  if (name === 'batch' || name === 'ui.batch') return uiBatchKind(data.events);
+  if (name.includes('interaction') || name.endsWith('.click') || name.endsWith('.tap')) {
+    return 'interaction';
+  }
+  return 'semantic';
+}
+
+function uiBatchKind(events) {
+  if (!Array.isArray(events) || events.length === 0) return 'semantic';
+  let interactionOnly = true;
+  for (const event of events) {
+    const type = String(event?.type || '').toLowerCase();
+    if (!type.startsWith('interaction.')) interactionOnly = false;
+  }
+  return interactionOnly ? 'interaction' : 'semantic';
+}
+
+function uiEventHasInteraction(item) {
+  const name = String(item?.name || '').toLowerCase();
+  if (name.includes('interaction') || name.endsWith('.click') || name.endsWith('.tap')) return true;
+  const events = item?.data?.events;
+  return Array.isArray(events) && events.some((event) => (
+    String(event?.type || '').toLowerCase().startsWith('interaction.')
+  ));
+}
+
+function summarizeUiEvent(item) {
+  return {
+    id: item?.id,
+    name: item?.name,
+    category: item?.category,
+    timestampMs: item?.timestampMs,
+    data: boundedObject(item?.data),
+  };
+}
+
+function summarizeTree(tree) {
+  return pick(tree, [
+    'ok', 'error', 'activity', 'nodeCount', 'windowCount', 'targetId', 'sessionId',
+    'updatedAtMs',
+  ]);
+}
+
+function summarizeScreenshot(screenshot) {
+  return pick(screenshot, [
+    'ok', 'error', 'path', 'outFile', 'format', 'width', 'height', 'deviceId',
+    'updatedAtMs',
+  ]);
+}
+
+function pick(value, keys) {
+  if (!value || typeof value !== 'object') return { value: String(value) };
+  const result = {};
+  for (const key of keys) {
+    if (value[key] !== undefined) result[key] = value[key];
+  }
+  return result;
+}
+
+function boundedObject(value) {
+  if (!value || typeof value !== 'object') return value ?? null;
+  const result = {};
+  for (const [key, child] of Object.entries(value).slice(0, 20)) {
+    if (typeof child === 'string') result[key] = child.slice(0, 300);
+    else if (child === null || typeof child !== 'object') result[key] = child;
+  }
+  return result;
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+module.exports = {
+  eventCommandFor,
+  isMutationCommand,
+  runWithFeedbackProbe,
+  uiEventKind,
+};