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

package/bin/script/script-durable-restore.js

@@ -0,0 +1,195 @@
+'use strict';
+
+const { compileScriptSpec, scriptHash } = require('./script-spec');
+const { scriptError } = require('./script-errors');
+const { readScriptResult } = require('./script-result');
+const { verifyChecksum, checksumOf } = require('../shared-kernel/evidence-schema');
+
+const RESTORE_CONTEXT = Symbol('scriptRestoreContext');
+
+function unmatchedPreparedAction(store, operationId) {
+  const records = store.list(operationId);
+  return records.some((marker) => {
+    if (marker.kind !== 'dispatch-marker' || marker.state !== 'prepared') return false;
+    const receipt = records.find((item) => item.kind === 'action-receipt' && item.actionId === marker.actionId);
+    return !receipt || receipt.ambiguous === true;
+  });
+}
+
+function loadDurableCheckpoint(store, operationId) {
+  if (!store || typeof store.latest !== 'function' || typeof store.list !== 'function' || !operationId) {
+    return scriptError('unknown_operation', { operationId: operationId || null });
+  }
+  const records = store.list(operationId);
+  for (const record of records) {
+    if (!verifyChecksum(record).ok) return scriptError('checksum_mismatch', { operationId });
+  }
+  const checkpoint = records.filter((item) => item.kind === 'checkpoint').at(-1);
+  if (!checkpoint) return scriptError('unknown_operation', { operationId });
+  if (unmatchedPreparedAction(store, operationId)) {
+    return scriptError('ambiguous', { operationId, status: 'ambiguous', pauseReason: 'ambiguous' });
+  }
+  const actionSequence = records.reduce((maximum, item) => Math.max(maximum, item.actionSequence || 0), checkpoint.actionSequence || 0);
+  return { ok: true, checkpoint, records, actionSequence };
+}
+
+function planCodeRestore({ checkpoint, script } = {}) {
+  if (!checkpoint) return scriptError('unknown_operation');
+  if (checkpoint.script && Array.isArray(checkpoint.script.steps)) {
+    return scriptError('script_format_removed');
+  }
+  const candidate = script;
+  if (candidate?.target && checkpoint.target && checksumOf(candidate.target) !== checksumOf(checkpoint.target)) {
+    return scriptError('script_target_mismatch');
+  }
+  if (candidate?.permissions && checkpoint.permissions && checksumOf(candidate.permissions) !== checksumOf(checkpoint.permissions)) {
+    return scriptError('script_permissions_mismatch');
+  }
+  let input = candidate;
+  if (input === undefined) {
+    if (!checkpoint.source || !checkpoint.language) return scriptError('script_source_required', { hash: checkpoint.hash || null });
+    input = { schemaVersion: 'aab.code-script/v1' };
+    // The durable record owns the frozen program. Omit absent optional fields
+    // instead of injecting undefined or mixing it with a caller's program.
+    for (const field of ['name', 'language', 'source', 'target', 'permissions', 'policy', 'inputs', 'entrypoint']) {
+      if (Object.hasOwn(checkpoint, field)) input[field] = checkpoint[field];
+    }
+  }
+  const compiled = compileScriptSpec(input);
+  if (!compiled.ok) return compiled;
+  if (candidate === undefined && checkpoint.sourcePath) {
+    compiled.spec.sourcePath = checkpoint.sourcePath;
+    compiled.hash = scriptHash(compiled.spec);
+  }
+  if (checkpoint.hash && compiled.hash !== checkpoint.hash) {
+    return scriptError('script_hash_mismatch', {
+      hash: checkpoint.hash,
+      provided: compiled.hash,
+    });
+  }
+  return { ok: true, format: 'code', compiled, checkpoint };
+}
+
+function codeStartCheckpoint(compiled, operationId) {
+  const spec = compiled.spec;
+  const body = {
+    operationId,
+    revision: 1,
+    stepId: 'start',
+    status: 'running',
+    hash: compiled.hash,
+    language: spec.language,
+    sourcePath: spec.sourcePath,
+    name: spec.name,
+    target: spec.target,
+    permissions: spec.permissions,
+    policy: spec.policy,
+    inputs: spec.inputs,
+    entrypoint: spec.entrypoint,
+    actionSequence: 0,
+  };
+  if (spec.policy.restartPolicy === 'checkpoint') {
+    body.source = spec.source;
+  }
+  return body;
+}
+
+function codeRuntimeCheckpoint(record, checkpoint, revision) {
+  return {
+    ...codeStartCheckpoint({ spec: record.spec, hash: record.hash }, record.operationId),
+    revision,
+    stepId: checkpoint.name,
+    checkpoint,
+    actionSequence: record.actionSequence,
+    checkpointActionSequence: record.actionSequence,
+  };
+}
+
+function specFromCompiled(compiled) {
+  const spec = compiled.spec;
+  return {
+    schemaVersion: 'aab.code-script/v1',
+    name: spec.name,
+    language: spec.language,
+    source: spec.source,
+    target: spec.target,
+    permissions: spec.permissions,
+    policy: spec.policy,
+    inputs: spec.inputs,
+    entrypoint: spec.entrypoint,
+  };
+}
+
+function restartGate(checkpoint, records = []) {
+  if (checkpoint.policy?.restartPolicy !== 'checkpoint' || !checkpoint.checkpoint) {
+    return scriptError('not_resumable', { restartPolicy: checkpoint.policy?.restartPolicy || 'none' });
+  }
+  if (checkpoint.status === 'completed' || checkpoint.status === 'cancelled'
+      || (checkpoint.status === 'failed' && !['child_crashed', 'runtime_lost'].includes(checkpoint.error))) {
+    return scriptError('not_resumable', { status: checkpoint.status });
+  }
+  // A receipt can confirm an effect while the language state still precedes it.
+  // Re-entering that checkpoint would repeat the effect, so require reconciliation.
+  const boundary = checkpoint.checkpointActionSequence || 0;
+  if (records.some((item) => item.kind === 'action-receipt'
+      && item.actionSequence > boundary && item.dispatched !== false)) {
+    return scriptError('ambiguous', { status: 'ambiguous', pauseReason: 'checkpoint_precedes_action' });
+  }
+  return { ok: true };
+}
+
+async function restoreUnknownOperation(args = {}) {
+  const { store, operationId, script, supervisor } = args;
+  const loaded = loadDurableCheckpoint(store, operationId);
+  if (!loaded.ok) return loaded;
+  const checkpoint = loaded.checkpoint;
+  if (checkpoint.script && Array.isArray(checkpoint.script.steps)) return scriptError('script_format_removed');
+  const op = args.operation || 'status';
+  const gate = restartGate(checkpoint, loaded.records);
+  if (op === 'status' || op === 'wait') {
+    const terminal = ['completed', 'cancelled', 'failed'].includes(checkpoint.status);
+    const result = checkpoint.status === 'completed' && checkpoint.resultRef
+      ? readScriptResult({ store, operationId }) : null;
+    if (result?.ok === false) return { ...result, status: 'failed', restored: true, resumable: false };
+    return {
+      ok: true,
+      command: 'script',
+      operationId,
+      status: terminal ? checkpoint.status : 'failed',
+      error: terminal ? checkpoint.error || null : 'runtime_lost',
+      persisted: true,
+      restored: true,
+      resumeMode: gate.ok ? 'checkpoint' : 'none',
+      resumable: gate.ok,
+      hash: checkpoint.hash || null,
+      resultRef: checkpoint.resultRef ?? null,
+    };
+  }
+  if (op !== 'resume') return scriptError('not_resumable', { operationId });
+  if (!gate.ok) return { ...gate, operationId };
+  const planned = planCodeRestore({ checkpoint, script });
+  if (!planned.ok) return planned;
+  return supervisor.handle({
+    ...args,
+    operation: 'start',
+    script: specFromCompiled(planned.compiled),
+    [RESTORE_CONTEXT]: {
+      compiled: planned.compiled,
+      checkpoint: checkpoint.checkpoint,
+      revision: checkpoint.revision,
+      actionSequence: loaded.actionSequence,
+      checkpointActionSequence: checkpoint.checkpointActionSequence || 0,
+    },
+  });
+}
+
+module.exports = {
+  unmatchedPreparedAction,
+  loadDurableCheckpoint,
+  planCodeRestore,
+  codeStartCheckpoint,
+  codeRuntimeCheckpoint,
+  restoreUnknownOperation,
+  RESTORE_CONTEXT,
+  restartGate,
+};

package/bin/script/script-entry-code.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const { handleCodeOrRemoved } = require('./script-entry-route');
+const { createScriptHostPort } = require('./script-host-port');
+const { createScriptSupervisor } = require('./script-supervisor');
+const { getProcessDeviceMutationLease } = require('../shared-kernel/device-mutation-lease');
+
+function createProductionHost(opts = {}) {
+  if (typeof opts.actions !== 'function') {
+    throw new TypeError('host_actions_required');
+  }
+  return createScriptHostPort({
+    ...opts,
+    mutationLease: opts.mutationLease || getProcessDeviceMutationLease(),
+  });
+}
+
+const codeSupervisor = createScriptSupervisor({ createHost: createProductionHost });
+
+function handle(args = {}) {
+  return handleCodeOrRemoved(args, args.supervisor || codeSupervisor);
+}
+
+function resetScriptOperations() {}
+
+module.exports = { handle, resetScriptOperations, createProductionHost, cancelActiveScripts: () => codeSupervisor.cancelAll() };

package/bin/script/script-entry-route.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const { restoreUnknownOperation } = require('./script-durable-restore');
+const { scriptError } = require('./script-errors');
+const { isRemovedScriptFormat, removedScriptFormatError } = require('./script-format-removed');
+const { isCodeScript } = require('./script-spec');
+const { readScriptResult } = require('./script-result');
+
+function scriptInput(args) {
+  return args.script;
+}
+
+async function handleCodeOrRemoved(args = {}, supervisor) {
+  const script = scriptInput(args);
+  if (args.operation === 'result' && args.store) return readScriptResult(args);
+  if ((args.operation || 'start') === 'start') {
+    if (isRemovedScriptFormat(script)) return removedScriptFormatError();
+    if (!isCodeScript(script)) return scriptError('invalid_script', { field: 'schemaVersion' });
+    return supervisor.handle(args);
+  }
+  if (args.operation === 'runtime-status' || (args.operationId && supervisor.knownOperation(args.operationId))) {
+    return supervisor.handle(args);
+  }
+  if (args.operationId && args.store) {
+    const restored = await restoreUnknownOperation({
+      ...args,
+      store: args.store,
+      operationId: args.operationId,
+      script,
+      supervisor,
+      operation: args.operation || 'status',
+    });
+    return restored;
+  }
+  return scriptError('unknown_operation', { operationId: args.operationId || null });
+}
+
+module.exports = { handleCodeOrRemoved };

package/bin/script/script-entry.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./script-entry-code');

package/bin/script/script-errors.js

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

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

@@ -0,0 +1,22 @@
+'use strict';
+
+const { createEvidenceStore } = require('../shared-kernel/evidence-store');
+const { randomUUID } = require('node:crypto');
+
+function createScriptEvidenceStore(options = {}) {
+  const store = createEvidenceStore({ maxBytes: 65 * 1024 * 1024, ...options, namespace: 'script' });
+  // Store instances restart their local counter. IDs must not overwrite an earlier run.
+  const identified = (kind, record) => ({
+    ...record,
+    evidenceId: record.evidenceId || `script:${kind}:${record.operationId}:${randomUUID()}`,
+  });
+  const persist = (kind, record) => store.persist(kind, identified(kind, record));
+  return {
+    ...store,
+    persist,
+    commit: persist,
+    offer: (kind, record) => store.offer(kind, identified(kind, record)),
+  };
+}
+
+module.exports = { createScriptEvidenceStore };

package/bin/script/script-format-removed.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const { scriptError } = require('./script-errors');
+
+function isRemovedScriptFormat(input) {
+  if (typeof input === 'string') {
+    const trimmed = input.trim();
+    if (!trimmed) return false;
+    if (trimmed.startsWith('{')) {
+      try {
+        return isRemovedScriptFormat(JSON.parse(trimmed));
+      } catch {
+        return false;
+      }
+    }
+    return /(^|\n)[ \t]*steps\s*:/.test(trimmed);
+  }
+  if (!input || typeof input !== 'object') return false;
+  return Array.isArray(input.steps);
+}
+
+function removedScriptFormatError() {
+  return scriptError('script_format_removed', { field: 'steps' });
+}
+
+module.exports = { isRemovedScriptFormat, removedScriptFormatError };