@piagent/platform 1.6.1 → 1.8.0

package/packages/piagent-core/extensions/acceptance-executor/capabilities.mjs

@@ -0,0 +1,127 @@
+import { protocolShape as shape, validateValue, MAX_STRING_LENGTH } from "./values.mjs";
+import { validateReferencePairs, validateReferenceIdentity } from "./reference-identity.mjs";
+
+export const MAX_CALLBACKS = 8;
+export const MAX_CALLBACK_STEPS = 64;
+export const MAX_CALLBACK_CALLS = 64;
+export const MAX_CALLBACK_DELAY_JOBS = 32;
+export const MAX_CALLBACK_TRACE_CHARS = 32768;
+const ID = /^[a-zA-Z0-9][a-zA-Z0-9:._-]{0,79}$/;
+export const ERROR_CLASSES = ["TypeError", "RangeError", "SyntaxError", "ReferenceError", "EvalError", "URIError", "Error"];
+export const CASE_CAPABILITY_FIELDS = ["awaitResult", "observeIdentity", "observeError", "observeErrorMessage", "callbacks", "errors", "referencePairs"];
+export const OBSERVATION_CAPABILITY_FIELDS = ["callbackTrace", "returnIdentity", "errorObservation", "errorMessage", "referenceIdentity"];
+export const callbackIds = item => new Set((item.callbacks ?? []).map(callback => callback.id));
+
+export function validateCaseCapabilities(item, { nodeProfile = false, budget } = {}) {
+  validateReferencePairs(item, { backingStore: nodeProfile });
+  for (const key of ["awaitResult", "observeIdentity", "observeError", "observeErrorMessage"]) {
+    if (Object.hasOwn(item, key) && item[key] !== true) throw new TypeError("Invalid case capability");
+  }
+  const errors = new Set();
+  if (Object.hasOwn(item, "errors")) {
+    if (!Array.isArray(item.errors) || item.errors.length < 1 || item.errors.length > 32) throw new TypeError("Invalid error inputs");
+    for (const error of item.errors) {
+      shape(error, ["id", "errorClass", "message", "properties"], ["id", "errorClass", "message"]);
+      if (typeof error.id !== "string" || !ID.test(error.id) || errors.has(error.id) || !ERROR_CLASSES.includes(error.errorClass)
+        || typeof error.message !== "string" || error.message.length > MAX_STRING_LENGTH) throw new TypeError("Invalid error input");
+      errors.add(error.id);
+      if (Object.hasOwn(error, "properties")) {
+        validateValue(error.properties, true, new Set(), { typedBytes: nodeProfile, budget });
+        if (error.properties.type !== "record") throw new TypeError("Error properties must be a record");
+      }
+    }
+  }
+  const callbacks = new Set();
+  if (Object.hasOwn(item, "callbacks")) {
+    if (!Array.isArray(item.callbacks) || item.callbacks.length < 1 || item.callbacks.length > MAX_CALLBACKS) throw new TypeError("Invalid callbacks");
+    for (const callback of item.callbacks) {
+      shape(callback, ["id", "mode", "repeatLast", "steps", "settleAfterJobs"], ["id", "mode", "repeatLast", "steps"]);
+      if (typeof callback.id !== "string" || !ID.test(callback.id) || callbacks.has(callback.id) || !["sync", "promise"].includes(callback.mode)
+        || typeof callback.repeatLast !== "boolean" || !Array.isArray(callback.steps)
+        || callback.steps.length < 1 || callback.steps.length > MAX_CALLBACK_STEPS) throw new TypeError("Invalid callback input");
+      callbacks.add(callback.id);
+      if (Object.hasOwn(callback, "settleAfterJobs") && (callback.mode !== "promise" || !Number.isSafeInteger(callback.settleAfterJobs)
+        || callback.settleAfterJobs < 1 || callback.settleAfterJobs > MAX_CALLBACK_DELAY_JOBS)) throw new TypeError("Invalid callback settlement delay");
+      for (const step of callback.steps) {
+        if (step.outcome === "return") { shape(step, ["outcome", "value"]); validateValue(step.value, true, new Set(), { typedBytes: nodeProfile, budget }); }
+        else if (step.outcome === "throw") {
+          shape(step, ["outcome", "error"]);
+          if (!errors.has(step.error)) throw new TypeError("Unknown callback error");
+        } else throw new TypeError("Invalid callback outcome");
+      }
+    }
+  }
+  return callbacks;
+}
+
+export function validateCallbackTrace(trace, item, { nodeProfile = false, typedOutputBudget } = {}) {
+  if (!item.callbacks || !Array.isArray(trace) || trace.length > MAX_CALLBACK_CALLS * 2
+    || JSON.stringify(trace).length > MAX_CALLBACK_TRACE_CHARS) throw new TypeError("Invalid callback trace");
+  const ids = callbackIds(item);
+  const calls = new Map(), settled = new Set();
+  let total = 0;
+  for (const call of trace) {
+    if (call?.event === "call") {
+      shape(call, ["callback", "call", "event", "args"]);
+      if (!ids.has(call.callback) || call.call !== (calls.get(call.callback) ?? 0) || ++total > MAX_CALLBACK_CALLS
+        || !Array.isArray(call.args) || call.args.length > 16) throw new TypeError("Invalid callback call");
+      for (const value of call.args) validateValue(value, true, ids, { typedBytes: nodeProfile, typedOutputBudget });
+      calls.set(call.callback, call.call + 1);
+    } else {
+      shape(call, ["callback", "call", "event", "outcome"]);
+      const callback = item.callbacks.find(value => value.id === call.callback), key = JSON.stringify([call.callback, call.call]);
+      if (call.event !== "settle" || callback?.mode !== "promise" || !Number.isSafeInteger(call.call) || call.call < 0
+        || call.call >= (calls.get(call.callback) ?? 0) || settled.has(key)
+        || !["return", "throw"].includes(call.outcome)) throw new TypeError("Invalid callback settlement");
+      const step = callback.steps[Math.min(call.call, callback.steps.length - 1)];
+      if ((!callback.repeatLast && call.call >= callback.steps.length) || call.outcome !== step.outcome) throw new TypeError("Conflicting callback settlement");
+      settled.add(key);
+    }
+  }
+  for (const callback of item.callbacks.filter(value => value.mode === "promise")) {
+    for (let index = 0; index < (calls.get(callback.id) ?? 0); index += 1) {
+      if (!settled.has(JSON.stringify([callback.id, index]))) throw new TypeError("Missing callback settlement");
+    }
+  }
+}
+
+export function validateReturnIdentity(value, item) {
+  if (!item.observeIdentity || !Array.isArray(value) || value.length > item.args.length) throw new TypeError("Invalid return identity");
+  let previous = -1;
+  for (const index of value) {
+    if (!Number.isSafeInteger(index) || index <= previous || index >= item.args.length
+      || !["array", "record", "date", "uint8array", "buffer", "arraybuffer", "dataview", "result", "error-property"].includes(item.args[index].type)) throw new TypeError("Invalid identity argument");
+    previous = index;
+  }
+}
+
+export function validateErrorObservation(value, item, { nodeProfile = false, typedOutputBudget } = {}) {
+  shape(value, ["identity", "properties"]);
+  if (!item.observeError || value.identity !== null && !(item.errors ?? []).some(error => error.id === value.identity)) {
+    throw new TypeError("Invalid error identity");
+  }
+  validateValue(value.properties, true, callbackIds(item), { typedBytes: nodeProfile, typedOutputBudget });
+  if (value.properties.type !== "record") throw new TypeError("Invalid observed error properties");
+}
+
+export function validateErrorMessage(value, item) {
+  // null means the inert prototype chain was fully observed and had no message.
+  // Unavailable/executable/oversized messages use outcome:unsupported instead.
+  if (!item.observeErrorMessage || value !== null && (typeof value !== "string" || value.length > MAX_STRING_LENGTH)) {
+    throw new TypeError("Invalid observed error message");
+  }
+}
+
+export function validateObservedCapabilities(observation, item, { nodeProfile = false, typedOutputBudget } = {}) {
+  const settled = ["return", "throw", "constructed"].includes(observation.outcome);
+  for (const [field, required, validate] of [
+    ["callbackTrace", settled && Boolean(item.callbacks), validateCallbackTrace],
+    ["returnIdentity", observation.outcome === "return" && item.observeIdentity, validateReturnIdentity],
+    ["errorObservation", observation.outcome === "throw" && item.observeError, validateErrorObservation],
+    ["errorMessage", observation.outcome === "throw" && item.observeErrorMessage, validateErrorMessage],
+    ["referenceIdentity", settled && Boolean(item.referencePairs), validateReferenceIdentity]
+  ]) {
+    if (required) validate(observation[field], item, { nodeProfile, typedOutputBudget });
+    else if (Object.hasOwn(observation, field)) throw new TypeError("Unexpected capability observation");
+  }
+}

package/packages/piagent-core/extensions/acceptance-executor/guest.mjs

@@ -0,0 +1,285 @@
+import { numberValue, validateValue } from "./values.mjs";
+import { INTRINSICS } from "./intrinsics.mjs";
+import { approvedModuleLoader } from "./module-graph.mjs";
+import { createExecutionBudget } from "./budget.mjs";
+import { callbackIds } from "./capabilities.mjs";
+import { createJobDrainer } from "./jobs.mjs";
+import { createNodeProfile } from "./node-profile.mjs";
+import { invocationTrace } from "./invocation.mjs";
+
+/** A request-owned realm. Only explicitly contiguous sequence cases share it. */
+export function createGuestSession(QuickJS, request, overallDeadline, typedOutputBudget = { rawBytes: 0 }) {
+  const runtime = QuickJS.newRuntime();
+  runtime.setMemoryLimit(32 * 1024 * 1024);
+  runtime.setMaxStackSize(512 * 1024);
+  const budget = createExecutionBudget(overallDeadline);
+  let interruption = null, importDenied = false;
+  const interrupted = () => Boolean(interruption ??= budget.poll());
+  runtime.setInterruptHandler(interrupted);
+  const loader = approvedModuleLoader(request, () => { importDenied = true; });
+  runtime.setModuleLoader(loader.load, loader.normalize);
+  const context = runtime.newContext(), persistent = [], temporary = [];
+  const keep = (handle) => { temporary.push(handle); return handle; };
+  const retain = (handle) => { persistent.push(handle); return handle; };
+  const take = (result) => {
+    if (result.error) { keep(result.error); throw new Error("Guest operation failed"); }
+    return keep(result.value);
+  };
+  const disposeTemporary = () => { while (temporary.length) temporary.pop().dispose(); };
+  let namespace, methods, initializationFailure, currentCallbacks = new Set(), profile;
+  const receivers = new Map();
+  function initializeIntrinsics() {
+    const result = context.evalCode(INTRINSICS);
+    if (result.error) { keep(result.error); throw new Error("Intrinsic initialization failed"); }
+    const intrinsics = retain(result.value);
+    methods = Object.fromEntries(["installStructuredClone", "cloneFault", "makeDate", "dateTime", "typeOf", "errorClass", "clockReads", "beginCall", "observeValue", "defineData",
+      "beginCapabilities", "makeError", "makeCallback", "callback", "callbackFault", "callbackTrace", "errorObservation", "errorMessage", "awaitValue", "sameReference", "referenceIdentity", "invokeTarget"]
+      .map((name) => [name, retain(context.getProp(intrinsics, name))]));
+    if (request.schemaVersion === 2) {
+      take(context.callFunction(methods.installStructuredClone, context.undefined));
+      profile = createNodeProfile({ runtime, context, retain, interrupted });
+    }
+  }
+  function input(value) {
+    switch (value.type) {
+      case "undefined": return context.undefined;
+      case "null": return context.null;
+      case "boolean": return value.value ? context.true : context.false;
+      case "string": return keep(context.newString(value.value));
+      case "number": return keep(context.newNumber(Number(value.value)));
+      case "date": return take(context.callFunction(methods.makeDate, context.undefined, keep(context.newNumber(Number(value.value)))));
+      case "callback": return take(context.callFunction(methods.callback, context.undefined, keep(context.newString(value.value))));
+      case "uint8array": case "buffer": case "arraybuffer": case "dataview": {
+        if (!profile) throw new TypeError("Typed input requires Node profile");
+        return take(context.callFunction(profile.methods.makeTyped, context.undefined, keep(context.newString(value.type)),
+          keep(context.newString(value.value.backingBase64)), keep(context.newNumber(value.value.byteOffset)), keep(context.newNumber(value.value.byteLength))));
+      }
+      case "array": case "record": {
+        const result = keep(value.type === "array" ? context.newArray() : context.newObject());
+        value.value.forEach((entry, index) => take(context.callFunction(methods.defineData, context.undefined, result,
+          keep(context.newString(value.type === "array" ? String(index) : entry.key)), input(value.type === "array" ? entry : entry.value))));
+        return result;
+      }
+      default: throw new TypeError("Unsupported resolved input");
+    }
+  }
+  function observe(handle, allowDate = false, allowCallbacks = false) {
+    const encoded = take(context.callFunction(methods.observeValue, context.undefined, handle, allowDate ? context.true : context.false,
+      allowCallbacks ? context.true : context.false, profile ? profile.methods.observeTypedValue : context.undefined));
+    const result = JSON.parse(context.getString(encoded));
+    if (result.reason) return result;
+    validateValue(result.value, allowDate, allowCallbacks ? currentCallbacks : new Set(), { typedBytes: Boolean(profile), typedOutputBudget });
+    return result;
+  }
+  function configureCapabilities(item) {
+    currentCallbacks = callbackIds(item);
+    take(context.callFunction(methods.beginCapabilities, context.undefined));
+    for (const error of item.errors ?? []) take(context.callFunction(methods.makeError, context.undefined,
+      keep(context.newString(error.id)), keep(context.newString(error.errorClass)), keep(context.newString(error.message)),
+      input(error.properties ?? { type: "record", value: [] })));
+    for (const callback of item.callbacks ?? []) {
+      const steps = { type: "array", value: callback.steps.map(step => ({ type: "record", value: [
+        { key: "outcome", value: { type: "string", value: step.outcome } }, step.outcome === "return"
+          ? { key: "value", value: step.value } : { key: "error", value: { type: "string", value: step.error } }
+      ] })) };
+      take(context.callFunction(methods.makeCallback, context.undefined, keep(context.newString(callback.id)), keep(context.newString(callback.mode)),
+        callback.repeatLast ? context.true : context.false, input(steps), keep(context.newNumber(callback.settleAfterJobs ?? 1))));
+    }
+  }
+  function callbackFault() {
+    const value = take(context.callFunction(methods.callbackFault, context.undefined));
+    return context.typeof(value) === "string" ? context.getString(value) : null;
+  }
+  function* executeSteps(item) {
+    interruption = null;
+    const traced = observation => request.schemaVersion === 2 ? { ...observation,
+      invocationTrace: invocationTrace({ ...item, exportName: item.exportName ?? request.exportName }, observation.outcome),
+      services: profile?.caseCounters() ?? { calls: 0, rawBytes: 0, textBytes: 0,
+        decodersCreated: 0, timersScheduled: 0, denials: 0 } } : observation;
+    const incomplete = (reason, outcome = "error") => traced({ id: item.id, outcome, reason,
+      ...(outcome === "error" && ["guest-cpu-budget", "guest-wall-deadline"].includes(reason) && budget.diagnostics()
+        ? { resources: budget.diagnostics() } : {}) });
+    try {
+      if (initializationFailure) return incomplete(initializationFailure.reason, initializationFailure.outcome);
+      // Trusted observer/profile bootstrap can include pinned runtime identity
+      // hashing. It remains under the request wall and container watchdog, but
+      // must not consume the candidate's fixed per-case thread-CPU allowance.
+      if (!methods) initializeIntrinsics();
+      if (interrupted()) return incomplete(interruption);
+      budget.beginCase(); interruption = null; profile?.beginCase();
+      if (interrupted()) return incomplete(interruption);
+      take(context.callFunction(methods.beginCall, context.undefined, Object.hasOwn(item, "clock") ? context.true : context.false,
+        keep(context.newNumber(item.clock ?? 0))));
+      configureCapabilities(item);
+      const jobs = createJobDrainer({ runtime, context, interrupted, keep });
+      const drain = () => item.awaitResult ? jobs.drain()
+        : runtime.hasPendingJob() ? { reason: "async-job-unsupported", outcome: "unsupported" } : null;
+      const jobFailure = failure => incomplete(interrupted() ? interruption : failure.reason, interrupted() ? "error" : failure.outcome);
+      const args = item.args.map(input);
+      if (!namespace) {
+        const moduleResult = context.evalCode(request.source, request.moduleGraph?.entry ?? "candidate.mjs", { type: "module" });
+        if (moduleResult.error) {
+          keep(moduleResult.error);
+          const timedOut = interrupted();
+          const cloneFault = take(context.callFunction(methods.cloneFault, context.undefined));
+          const cloneReason = context.typeof(cloneFault) === "string" ? context.getString(cloneFault) : null;
+          initializationFailure = { outcome: (importDenied || cloneReason) && !timedOut ? "unsupported" : "error",
+            reason: timedOut ? interruption : importDenied ? "module-import-unsupported" : cloneReason ?? "module-initialization-failed" };
+          return incomplete(initializationFailure.reason, initializationFailure.outcome);
+        }
+        const module = retain(moduleResult.value);
+        const failed = drain();
+        if (failed) { initializationFailure = failed; return jobFailure(failed); }
+        const promise = jobs.state(module, retain);
+        if (!item.awaitResult && promise.value !== module) {
+          initializationFailure = { outcome: "unsupported", reason: "async-module-unsupported" };
+          return incomplete(initializationFailure.reason, initializationFailure.outcome);
+        }
+        if (promise.reason) { initializationFailure = promise; return jobFailure(promise); }
+        if (promise.error) {
+          initializationFailure = { outcome: "error", reason: "module-initialization-failed" };
+          return incomplete(initializationFailure.reason);
+        }
+        namespace = promise.value;
+      }
+      const beforeCall = drain();
+      if (beforeCall) return jobFailure(beforeCall);
+      const invocation = item.invocation ?? { kind: "call" };
+      const target = invocation.kind === "method" ? context.undefined : keep(context.getProp(namespace, item.exportName ?? request.exportName));
+      if (invocation.kind !== "method"
+        && context.getString(take(context.callFunction(methods.typeOf, context.undefined, target))) !== "function") {
+        return incomplete("callable-export-missing", "unsupported");
+      }
+      const receiver = invocation.kind === "method" ? receivers.get(invocation.receiverId) : context.undefined;
+      if (invocation.kind === "method" && !receiver) return incomplete("receiver-unavailable", "unsupported");
+      let called;
+      if (profile) {
+        const argArray = keep(context.newArray());
+        args.forEach((arg, index) => take(context.callFunction(methods.defineData, context.undefined, argArray,
+          keep(context.newString(String(index))), arg)));
+        called = context.callFunction(methods.invokeTarget, context.undefined, target, receiver,
+          keep(context.newString(invocation.kind)), keep(context.newString(invocation.method ?? "")), argArray);
+      } else called = context.callFunction(target, context.undefined, args);
+      let returned, threw = Boolean(called.error), constructed = invocation.kind === "construct" && !threw;
+      if (constructed) { returned = retain(called.value); receivers.set(invocation.receiverId, returned); }
+      else returned = keep(called.error ?? called.value);
+      if (item.awaitResult && !threw) {
+        const awaited = context.callFunction(methods.awaitValue, context.undefined, returned);
+        returned = keep(awaited.error ?? awaited.value); threw = Boolean(awaited.error);
+      }
+      if (interrupted()) return incomplete(interruption);
+      if (importDenied) return incomplete("module-import-unsupported", "unsupported");
+      let afterCall = drain();
+      if (afterCall) return jobFailure(afterCall);
+      if (importDenied) return incomplete("module-import-unsupported", "unsupported");
+      if (item.awaitResult && !threw) {
+        let settled = jobs.state(returned);
+        while (settled.reason && profile?.pendingTimers()) {
+          if (!(yield profile.fireNext())) break;
+          afterCall = jobs.drain(); if (afterCall) return jobFailure(afterCall);
+          settled = jobs.state(returned);
+        }
+        if (settled.reason) return jobFailure(settled);
+        returned = settled.error ?? settled.value; threw = Boolean(settled.error); constructed = false;
+      }
+      const profileFault = profile?.fault();
+      if (profileFault) return incomplete(profileFault.reason, profileFault.outcome);
+      const cloneFault = take(context.callFunction(methods.cloneFault, context.undefined));
+      if (context.typeof(cloneFault) === "string") return incomplete(context.getString(cloneFault), "unsupported");
+      const callbackError = callbackFault();
+      if (callbackError) return incomplete(callbackError);
+      let observation;
+      if (threw) {
+        let message;
+        if (item.observeErrorMessage) {
+          const result = JSON.parse(context.getString(take(context.callFunction(methods.errorMessage, context.undefined, returned))));
+          if (result.reason) return incomplete(result.reason, "unsupported");
+          message = result.value;
+        }
+        const errorClass = context.getString(take(context.callFunction(methods.errorClass, context.undefined, returned)));
+        if (errorClass === "InternalError") return incomplete("guest-resource-error");
+        observation = { id: item.id, outcome: "throw", errorClass };
+        if (item.observeErrorMessage) observation.errorMessage = message;
+        if (item.observeError) {
+          const result = JSON.parse(context.getString(take(context.callFunction(methods.errorObservation, context.undefined, returned))));
+          if (result.reason) return incomplete(result.reason, "unsupported");
+          observation.errorObservation = result;
+        }
+      } else if (constructed) observation = { id: item.id, outcome: "constructed" };
+      else {
+        const result = observe(returned);
+        if (result.reason) return incomplete(result.reason, "unsupported");
+        observation = { id: item.id, outcome: "return", value: result.value };
+        if (item.observeIdentity) {
+          observation.returnIdentity = [];
+          for (let index = 0; index < args.length; index += 1) {
+            if (context.getNumber(take(context.callFunction(methods.sameReference, context.undefined, returned, args[index])))) observation.returnIdentity.push(index);
+          }
+        }
+      }
+      if (item.callbacks) observation.callbackTrace = JSON.parse(context.getString(take(context.callFunction(methods.callbackTrace, context.undefined))));
+      if (item.referencePairs) {
+        observation.referenceIdentity = [];
+        const root = selector => selector.root === "argument" ? args[selector.index]
+          : selector.root === (threw ? "error" : "return") ? returned : context.undefined;
+        const path = selector => input({ type: "array", value: selector.path.map(value => ({ type: "string", value })) });
+        for (const pair of item.referencePairs) {
+          const result = JSON.parse(context.getString(take(context.callFunction(methods.referenceIdentity, context.undefined,
+            root(pair.left), path(pair.left), pair.left.projection ? keep(context.newString(pair.left.projection)) : context.undefined,
+            root(pair.right), path(pair.right), pair.right.projection ? keep(context.newString(pair.right.projection)) : context.undefined))));
+          if (result.reason) return incomplete(result.reason, "unsupported");
+          observation.referenceIdentity.push({ id: pair.id, same: result.same });
+        }
+      }
+      const dateArgsAfter = [];
+      for (let index = 0; index < item.args.length; index += 1) if (item.args[index].type === "date") {
+        const value = take(context.callFunction(methods.dateTime, context.undefined, args[index]));
+        dateArgsAfter.push({ index, value: numberValue(context.getNumber(value)) });
+      }
+      if (item.observeArgs) {
+        observation.argsAfter = [];
+        for (const arg of args) {
+          const result = observe(arg, true, true);
+          if (result.reason) return incomplete(result.reason, "unsupported");
+          observation.argsAfter.push(result.value);
+        }
+      }
+      const clockReads = context.getNumber(take(context.callFunction(methods.clockReads, context.undefined)));
+      if (interrupted()) return incomplete(interruption);
+      if (profile?.fault()) return incomplete(profile.fault().reason, profile.fault().outcome);
+      if (profile?.pendingTimers()) return incomplete("pending-timer", "unsupported");
+      if (runtime.hasPendingJob()) return incomplete("async-job-unsupported", "unsupported");
+      const finalFault = callbackFault();
+      if (finalFault) return incomplete(finalFault);
+      return traced({ ...observation, dateArgsAfter, clockReads });
+    } catch { return incomplete(interrupted() ? interruption : "guest-observation-failed"); }
+    finally { disposeTemporary(); }
+  }
+  function execute(item) {
+    const steps = executeSteps(item), first = steps.next();
+    if (request.schemaVersion === 1) {
+      if (!first.done) { steps.return(); throw new Error("Legacy execution cannot yield"); }
+      return first.value;
+    }
+    return (async () => {
+      let current = first;
+      while (!current.done) {
+        try { current = steps.next(await current.value); }
+        catch (error) { current = steps.throw(error); }
+      }
+      return current.value;
+    })();
+  }
+  return { execute, dispose() {
+    const services = profile?.totals(), timerTrace = profile?.timerTrace();
+    profile?.dispose(); receivers.clear();
+    const summary = profile ? { services, timerTrace, quiescence: profile.quiescence(receivers.size) } : null;
+    disposeTemporary(); while (persistent.length) persistent.pop().dispose(); context.dispose(); runtime.dispose();
+    return summary;
+  } };
+}
+
+export async function executeCase(QuickJS, request, item, overallDeadline) {
+  const session = createGuestSession(QuickJS, request, overallDeadline);
+  try { return await session.execute(item); } finally { session.dispose(); }
+}

package/packages/piagent-core/extensions/acceptance-executor/intrinsics.mjs

@@ -0,0 +1,133 @@
+import { MAX_COLLECTION_LENGTH, MAX_STRING_LENGTH, MAX_VALUE_DEPTH, MAX_VALUE_NODES, MAX_VALUE_TEXT } from "./values.mjs";
+import { CALLBACK_INTRINSICS } from "./callback-intrinsics.mjs";
+import { REFERENCE_INTRINSICS } from "./reference-identity.mjs";
+import { INVOCATION_INTRINSICS } from "./invocation.mjs";
+import { STRUCTURED_CLONE_INTRINSICS } from "./structured-clone.mjs";
+
+// This closure is evaluated before the candidate. Only the worker retains its
+// handle; it installs no host callback, oracle, serializer or receipt writer.
+export const INTRINSICS = `(() => {
+  const D = Date, apply = Reflect.apply, isPrototypeOf = Object.prototype.isPrototypeOf;
+  const getTime = D.prototype.getTime, originalNow = D.now, define = Object.defineProperty, create = Object.create;
+  const ownKeys = Reflect.ownKeys, descriptor = Object.getOwnPropertyDescriptor, own = Object.hasOwn;
+  const prototype = Object.getPrototypeOf, objectPrototype = Object.prototype, isArray = Array.isArray;
+  const bytePrototype = prototype(Uint8Array.prototype), byteBuffer = descriptor(bytePrototype, 'buffer').get;
+  const dataViewBuffer = descriptor(DataView.prototype, 'buffer').get;
+  const arrayBufferLength = descriptor(ArrayBuffer.prototype, 'byteLength').get;
+  const stringify = JSON.stringify, finite = Number.isFinite, same = Object.is, numberString = Number.prototype.toString;
+  const WS = WeakSet, add = WS.prototype.add, has = WS.prototype.has, remove = WS.prototype.delete;
+  const dataDescriptor = (value, enumerable) => {
+    const result = create(null); result.value = value; result.writable = true;
+    result.enumerable = enumerable; result.configurable = true; return result;
+  };
+  const proxies = new WS(), P = Proxy, revoke = P.revocable, construct = Reflect.construct;
+  // Proxies may execute normally, but cannot masquerade as inert output data.
+  const track = p => { apply(add, proxies, [p]); return p; };
+  // A candidate may change Object.prototype; handler trap lookup must never
+  // inherit those properties and expose the underlying untracked factory.
+  const revocableHandler = create(null), constructorHandler = create(null);
+  revocableHandler.apply = (target, receiver, args) => {
+    const result = apply(target, receiver, args); track(result.proxy); return result;
+  };
+  constructorHandler.construct = (target, args, newTarget) => track(construct(target, args, newTarget));
+  define(P, 'revocable', dataDescriptor(new P(revoke, revocableHandler), false));
+  globalThis.Proxy = new P(P, constructorHandler);
+  const internalError = InternalError.prototype;
+  const prototypes = [TypeError.prototype, RangeError.prototype, SyntaxError.prototype,
+    ReferenceError.prototype, EvalError.prototype, URIError.prototype, Error.prototype];
+  const names = ['TypeError', 'RangeError', 'SyntaxError', 'ReferenceError', 'EvalError', 'URIError', 'Error'];
+  let reads = 0, clockEnabled = false, clockValue = 0;
+  // A module may capture Date.now once. Keep that callable live across the
+  // complete history, including transitions back to the real clock.
+  const observedNow = () => {
+    if (!clockEnabled) return apply(originalNow, D, []);
+    reads += 1; return clockValue;
+  };
+  const numeric = value => same(value, -0) ? '"-0"' : finite(value) ? apply(numberString, value, [])
+    : value !== value ? '"NaN"' : value < 0 ? '"-Infinity"' : '"Infinity"';
+  function observeValue(root, allowDate, allowCallbacks, typedObserver) {
+    let nodes = 0, text = 0;
+    const active = new WS();
+    function quote(value) {
+      text += value.length;
+      if (value.length > ${MAX_STRING_LENGTH} || text > ${MAX_VALUE_TEXT}) throw 'value-observation-limit';
+      return stringify(value);
+    }
+    function visit(value, depth) {
+      if (++nodes > ${MAX_VALUE_NODES} || depth > ${MAX_VALUE_DEPTH}) throw 'value-observation-limit';
+      if (value === null) return '{"type":"null"}';
+      const type = typeof value;
+      if (type === 'undefined') return '{"type":"undefined"}';
+      if (type === 'boolean') return '{"type":"boolean","value":' + (value ? 'true' : 'false') + '}';
+      if (type === 'number') return '{"type":"number","value":' + numeric(value) + '}';
+      if (type === 'string') return '{"type":"string","value":' + quote(value) + '}';
+      const callback = allowCallbacks ? callbackId(value) : undefined;
+      if (callback !== undefined) return '{"type":"callback","value":' + quote(callback) + '}';
+      if (type !== 'object' || apply(has, proxies, [value])) throw 'return-type-unsupported';
+      if (typedObserver !== undefined) {
+        const typedValue = apply(typedObserver, undefined, [value]);
+        if (typeof typedValue !== 'string') throw 'return-type-unsupported';
+        if (typedValue) return typedValue;
+      }
+      let timestamp, date = false;
+      try { timestamp = apply(getTime, value, []); date = true; } catch {}
+      if (date) {
+        if (!allowDate) throw 'return-type-unsupported';
+        return '{"type":"date","value":' + numeric(timestamp) + '}';
+      }
+      if (apply(has, active, [value])) throw 'structured-value-unsupported';
+      const array = isArray(value), proto = prototype(value);
+      if (!array && proto !== objectPrototype && proto !== null) throw 'return-type-unsupported';
+      const keys = ownKeys(value);
+      let count = keys.length;
+      if (array) {
+        const length = descriptor(value, 'length').value;
+        if (length > ${MAX_COLLECTION_LENGTH} || keys.length !== length + 1) throw 'structured-value-unsupported';
+        count = length;
+      } else if (count > ${MAX_COLLECTION_LENGTH}) throw 'value-observation-limit';
+      apply(add, active, [value]);
+      let output = '{"type":"' + (array ? 'array' : 'record') + '","value":[';
+      for (let index = 0; index < count; index += 1) {
+        const key = array ? apply(numberString, index, []) : keys[index];
+        if (typeof key !== 'string') throw 'structured-value-unsupported';
+        const property = descriptor(value, key);
+        if (!property || !own(property, 'value') || !property.enumerable) throw 'structured-value-unsupported';
+        if (index) output += ',';
+        output += array ? visit(property.value, depth + 1)
+          : '{"key":' + quote(key) + ',"value":' + visit(property.value, depth + 1) + '}';
+      }
+      apply(remove, active, [value]);
+      return output + ']}';
+    }
+    try { return '{"value":' + visit(root, 0) + '}'; }
+    catch (reason) {
+      const code = reason === 'value-observation-limit' || reason === 'typed-backing-limit' ? reason
+        : reason === 'structured-value-unsupported' ? reason : 'return-type-unsupported';
+      return '{"reason":' + stringify(code) + '}';
+    }
+  }
+  ${STRUCTURED_CLONE_INTRINSICS}
+  ${CALLBACK_INTRINSICS}
+  ${REFERENCE_INTRINSICS}
+  ${INVOCATION_INTRINSICS}
+  return {
+    installStructuredClone, cloneFault: () => cloneFailure,
+    makeDate: value => new D(value), dateTime: value => apply(getTime, value, []),
+    defineData: (object, key, value) => { define(object, key, dataDescriptor(value, true)); },
+    typeOf: value => typeof value, observeValue, referenceIdentity, invokeTarget, clockReads: () => reads,
+    beginCapabilities, makeError, makeCallback, callback: id => callbacks[id],
+    callbackFault: () => callbackFault, callbackTrace: () => '[' + trace + ']', errorObservation, errorMessage,
+    awaitValue: value => apply(promiseResolve, NativePromise, [value]),
+    sameReference: (left, right) => left !== null && typeof left === 'object' && same(left, right),
+    beginCall: (mock, value) => {
+      reads = 0; clockEnabled = mock; clockValue = value;
+      define(D, 'now', dataDescriptor(observedNow, false));
+    },
+    errorClass: value => {
+      if (value === null || (typeof value !== 'object' && typeof value !== 'function')) return 'non-error';
+      if (apply(isPrototypeOf, internalError, [value])) return 'InternalError';
+      for (let i = 0; i < prototypes.length; i += 1) if (apply(isPrototypeOf, prototypes[i], [value])) return names[i];
+      return 'non-error';
+    }
+  };
+})()`;

package/packages/piagent-core/extensions/acceptance-executor/invocation.mjs

@@ -0,0 +1,39 @@
+import { protocolShape as shape } from "./values.mjs";
+
+const RECEIVER = /^[a-zA-Z0-9][a-zA-Z0-9:._-]{0,79}$/;
+const METHOD = /^(?:set|get)$/;
+
+/** Validate the finite v2 invocation language. Receiver history is checked by protocol.mjs. */
+export function validateInvocation(value) {
+  if (value?.kind === "call") shape(value, ["kind"]);
+  else if (value?.kind === "construct") {
+    shape(value, ["kind", "receiverId"]);
+    if (typeof value.receiverId !== "string" || !RECEIVER.test(value.receiverId)) throw new TypeError("Invalid constructor receiver");
+  } else if (value?.kind === "method") {
+    shape(value, ["kind", "receiverId", "method"]);
+    if (typeof value.receiverId !== "string" || !RECEIVER.test(value.receiverId)
+      || typeof value.method !== "string" || !METHOD.test(value.method)) throw new TypeError("Invalid receiver method");
+  } else throw new TypeError("Invalid invocation");
+  return value;
+}
+
+export function invocationTrace(item, outcome) {
+  const invocation = item.invocation ?? { kind: "call" };
+  return {
+    kind: invocation.kind,
+    ...(invocation.kind === "call" ? { exportName: item.exportName } : {}),
+    ...(invocation.receiverId ? { receiverId: invocation.receiverId } : {}),
+    ...(invocation.method ? { method: invocation.method } : {}),
+    outcome
+  };
+}
+
+// Evaluated in the private observer closure before candidate code. Captured
+// Reflect operations cannot be replaced by candidate prototype/global writes.
+export const INVOCATION_INTRINSICS = `
+  const invokeTarget = (target, receiver, kind, method, args) => {
+    if (kind === 'construct') return construct(target, args);
+    if (kind === 'method') return apply(receiver[method], receiver, args);
+    return apply(target, undefined, args);
+  };
+`;

package/packages/piagent-core/extensions/acceptance-executor/jobs.mjs

@@ -0,0 +1,29 @@
+export const MAX_ASYNC_JOBS = 1024;
+
+/** Bounded guest jobs only. No host await, IO callback, timer or Promise hook. */
+export function createJobDrainer({ runtime, context, interrupted, keep }) {
+  let jobs = 0;
+  return {
+    drain() {
+      while (runtime.hasPendingJob()) {
+        if (interrupted()) return { reason: "async-job-interrupted", outcome: "error" };
+        if (jobs >= MAX_ASYNC_JOBS) return { reason: "async-job-limit", outcome: "error" };
+        const result = runtime.executePendingJobs(1);
+        if (result.error) { keep(result.error); return { reason: "async-job-failed", outcome: "error" }; }
+        if (result.value !== 1) return { reason: "async-job-stalled", outcome: "error" };
+        jobs += 1;
+      }
+      // An interrupt can reject the final Promise while executePendingJobs
+      // itself reports one successfully processed job. Preserve the budget
+      // stop before its InternalError is mistaken for an ordinary rejection.
+      return interrupted() ? { reason: "async-job-interrupted", outcome: "error" } : null;
+    },
+    state(handle, retain = keep) {
+      const state = context.getPromiseState(handle);
+      if (state.notAPromise) return { value: handle };
+      if (state.type === "fulfilled") return { value: retain(state.value) };
+      if (state.type === "rejected") return { error: retain(state.error) };
+      return { reason: "async-promise-unsettled", outcome: "unsupported" };
+    }
+  };
+}