@c4roa0/agentpay-user 0.0.0-stage → 0.3.0

package/src/install-and-setup.mjs

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MPL-2.0
+// This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+// If a copy was not distributed with this file, see https://mozilla.org/MPL/2.0/.
+import { rememberUserDataDir } from "./local-data-directory.mjs";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { runInstall } from "./install-user.mjs";
+
+export async function installAndSetup({
+  userDir,
+  market,
+  dataDir,
+  install = runInstall,
+  start = startGuide,
+  remember = rememberUserDataDir,
+  write = console.log,
+}) {
+  const result = await install({ userDir, market, dataDir, write });
+  if (!result?.completed)
+    throw Error(
+      "Installation did not complete. Run the same Install command to resume.",
+    );
+  await remember({ userDir, dataDir });
+  return start({ userDir, dataDir });
+}
+function startGuide({ userDir, dataDir }) {
+  return new Promise((resolve, reject) => {
+    // Start only after the installed packages are verified. Keeping imports in the
+    // child avoids requiring ethers before the installer has installed it.
+    const child = spawn(
+      process.execPath,
+      [join(userDir, "scripts/user-setup.mjs"), "--guided", dataDir],
+      { stdio: "inherit" },
+    );
+    child.once("error", reject);
+    child.once("exit", (code) => resolve(code ?? 1));
+  });
+}

package/src/install-preflight.mjs

@@ -0,0 +1,201 @@
+import { walletPackage } from "./wallet-package.mjs";
+// SPDX-License-Identifier: MPL-2.0
+// This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+// If a copy was not distributed with this file, see https://mozilla.org/MPL/2.0/.
+import { NODE_REQUIREMENT, supportedNodeVersion } from "./node-version.mjs";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { dirname, join, resolve, relative, isAbsolute } from "node:path";
+import { createRequire } from "node:module";
+
+const inside = (parent, child) => {
+  const path = relative(parent, child);
+  return (
+    !path ||
+    (!path.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) &&
+      path !== ".." &&
+      !isAbsolute(path))
+  );
+};
+export async function checkLocalInstallation({
+  userDir,
+  dataDir,
+  nodeVersion = process.versions.node,
+  uid = process.getuid(),
+}) {
+  userDir = resolve(userDir);
+  let walletDir = null;
+  const checks = [];
+  const add = (code, status, message, fix = null) =>
+    checks.push({ code, status, message, fix });
+  add(
+    "NODE_VERSION",
+    supportedNodeVersion(nodeVersion) ? "passed" : "failed",
+    `Node ${nodeVersion}; requires ${NODE_REQUIREMENT}`,
+    `Install ${NODE_REQUIREMENT}`,
+  );
+  async function repository(path, name, label) {
+    try {
+      const manifest = JSON.parse(
+        await readFile(join(path, "package.json"), "utf8"),
+      );
+      if (manifest.name !== name) throw new Error("wrong package");
+      add(`${label}_REPOSITORY`, "passed", `${label} repository found`);
+      return manifest;
+    } catch {
+      add(
+        `${label}_REPOSITORY`,
+        "failed",
+        `${label} repository missing or invalid`,
+        "Reinstall this User version and its pinned npm dependencies",
+      );
+      return null;
+    }
+  }
+  const user = await repository(userDir, "@c4roa0/agentpay-user", "USER");
+  try {
+    const wallet = walletPackage(userDir);
+    walletDir = wallet.directory;
+    for (const entry of [wallet.cli, join(walletDir, 'lib/client.js'), join(walletDir, 'lib/local.js')]) {
+      if (!(await lstat(entry)).isFile()) throw Error('Missing compiled Wallet entry');
+    }
+    add('WALLET_PACKAGE', 'passed', `Wallet ${wallet.manifest.version} matches the installed User`);
+  } catch (error) {
+    add('WALLET_PACKAGE', 'failed', 'Compatible Wallet package is missing or incomplete', 'Reinstall the reviewed User version, then run agentpay repair. Source checkout: npm ci.');
+  }
+  if (user) {
+    const require = createRequire(join(userDir, 'package.json'));
+    for (const dependency of Object.keys(user.dependencies || {})) {
+      try {
+        try { require.resolve(dependency); }
+        catch (error) {
+          if (error.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') throw error;
+          let found = false;
+          for (const base of require.resolve.paths(dependency) || []) {
+            try {
+              const dir = join(base, dependency);
+              const pkg = JSON.parse(await readFile(join(dir, 'package.json'), 'utf8'));
+              const entry = pkg.exports?.['.']?.import;
+              if (pkg.name !== dependency || typeof entry !== 'string' || !entry.startsWith('./') || entry.includes('..')) continue;
+              if (!(await lstat(join(dir, entry))).isFile()) continue;
+              found = true; break;
+            } catch {}
+          }
+          if (!found) throw error;
+        }
+        add(`USER_DEPENDENCY_${dependency}`, 'passed', `${dependency} resolves without loading code`);
+      } catch (error) {
+        add(`USER_DEPENDENCY_${dependency}`, 'failed', `${dependency} is not installed or resolvable (${error.code || 'INVALID_PACKAGE_ENTRY'})`, 'Reinstall this User version. Source checkout: npm ci.');
+      }
+    }
+  }
+  dataDir = resolve(dataDir);
+  let privatePath = dataDir;
+  try {
+    // Resolve existing ancestors, including symlinks, even for a new directory.
+    let existing = dataDir;
+    const missing = [];
+    while (true) {
+      try {
+        privatePath = resolve(await realpath(existing), ...missing.reverse());
+        break;
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+        if (existing === dirname(existing)) throw error;
+        missing.push(existing.slice(dirname(existing).length + 1));
+        existing = dirname(existing);
+      }
+    }
+    const roots = await Promise.all(
+      [userDir, walletDir].filter(Boolean).map((path) =>
+        realpath(path).catch(() => resolve(path)),
+      ),
+    );
+    if (roots.some((root) => inside(root, privatePath))) {
+      add(
+        "PRIVATE_PATH",
+        "failed",
+        "Private data must be outside user and wallet repositories",
+        "Choose an owner-held private directory outside both repositories",
+      );
+    } else {
+      const targets = [
+        dataDir,
+        join(dataDir, "wallet"),
+        join(dataDir, "runtime"),
+      ];
+      for (const target of targets) {
+        try {
+          const info = await lstat(target);
+          const valid =
+            info.isDirectory() &&
+            !info.isSymbolicLink() &&
+            info.uid === uid &&
+            !(info.mode & 0o077);
+          add(
+            `PRIVATE_DIRECTORY_${relative(dataDir, target) || "root"}`,
+            valid ? "passed" : "failed",
+            valid
+              ? "Private directory permissions checked"
+              : "Private directory must be owner-held, non-symlink and 0700-or-stricter",
+            "Inspect ownership/type; choose or secure your own private directory before installation",
+          );
+        } catch (error) {
+          add(
+            `PRIVATE_DIRECTORY_${relative(dataDir, target) || "root"}`,
+            error.code === "ENOENT" ? "pending" : "failed",
+            error.code === "ENOENT"
+              ? "Not created yet; setup install will create this directory"
+              : "Private directory could not be inspected",
+          );
+        }
+      }
+    }
+  } catch {
+    add(
+      "PRIVATE_PATH",
+      "failed",
+      "Private path could not be resolved",
+      "Check path access and symbolic links",
+    );
+  }
+  // Advisory inventory only; do not migrate or discard existing requests during setup.
+  if (!checks.some((check) => check.status === "failed")) {
+    try {
+      const { createInvocationStore } = await import("./invocation-store.mjs");
+      const entries = Object.values(
+        await createInvocationStore(
+          join(dataDir, "runtime/invocations.json"),
+        ).inventory(),
+      );
+      const legacy = entries.filter(
+        (entry) => entry.routingVersion !== "agentpay.runtime-call.v1",
+      ).length;
+      add(
+        "INVOCATION_HISTORY",
+        legacy ? "warning" : "passed",
+        legacy
+          ? `${legacy} older request(s) are preserved. Runtime can start; check agentpay status after unlocking Wallet.`
+          : "Local invocation history can be inspected without migration",
+      );
+    } catch {
+      add(
+        "INVOCATION_HISTORY",
+        "failed",
+        "Local invocation history needs review; existing data was preserved",
+        "Start Runtime for its status view; do not delete history or repeat purchases",
+      );
+    }
+  }
+  return {
+    ok: !checks.some((check) => check.status === "failed"),
+    checks,
+    userDir,
+    walletDir,
+    dataDir,
+    readyToPurchase: false,
+    scope: "read_only_installation_preflight",
+    networkChecked: false,
+    message:
+      "This checks local prerequisites only; Wallet package compatibility is checked; keys, Policy and running-process readiness are not verified",
+  };
+}

package/src/install-user.mjs

@@ -0,0 +1,279 @@
+import { installationDirectory, importSetupFiles } from "./installation-paths.mjs";
+// SPDX-License-Identifier: MPL-2.0
+// This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+// If a copy was not distributed with this file, see https://mozilla.org/MPL/2.0/.
+import { NODE_REQUIREMENT, supportedNodeVersion } from "./node-version.mjs";
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import {
+  appendFile,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  rename,
+  unlink,
+} from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { checkLocalInstallation } from "./install-preflight.mjs";
+
+export function marketSettingsUrl(value) {
+  const url = new URL(value);
+  if (
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    url.pathname !== "/" ||
+    !(
+      url.protocol === "https:" ||
+      (url.protocol === "http:" &&
+        ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname))
+    )
+  )
+    throw Error(
+      "Use the Market HTTPS origin, or a loopback HTTP origin for private rehearsal.",
+    );
+  return new URL("/market/web/onboarding/user-config", url).href;
+}
+export async function fingerprint(root, paths) {
+  const hash = createHash("sha256");
+  async function visit(name) {
+    const full = join(root, name),
+      info = await lstat(full);
+    if (info.isSymbolicLink())
+      throw Error(`Inspect the symbolic link before installing: ${full}`);
+    if (info.isDirectory()) {
+      for (const child of (await readdir(full)).sort())
+        await visit(join(name, child));
+    } else if (info.isFile()) {
+      hash.update(name);
+      hash.update("\0");
+      hash.update(await readFile(full));
+      hash.update("\0");
+    } else throw Error(`Unexpected installation input: ${full}`);
+  }
+  for (const path of paths) await visit(path);
+  return hash.digest("hex");
+}
+async function saveJson(path, value) {
+  const temp = `${path}.${randomUUID()}.tmp`;
+  const file = await open(temp, "wx", 0o600);
+  try {
+    await file.writeFile(JSON.stringify(value, null, 2) + "\n");
+    await file.sync();
+    await file.close();
+    await rename(temp, path);
+  } finally {
+    await file.close().catch(() => {});
+    await unlink(temp).catch(() => {});
+  }
+}
+export async function runInstall({
+  userDir,
+  market,
+  dataDir,
+  run = runCommand,
+  fetchImpl = fetch,
+  write = console.log,
+  nodeVersion = process.versions.node,
+  prepareOnly = false,
+  beforePrepare,
+  afterPrepare,
+}) {
+  userDir = resolve(userDir);
+
+  const endpoint = prepareOnly ? null : marketSettingsUrl(market);
+  if (typeof process.getuid !== "function")
+    throw Error(
+      "This installer needs POSIX file ownership support. Native Windows installation is not available; use a supported Linux environment.",
+    );
+  if (!supportedNodeVersion(nodeVersion))
+    throw Error(
+      `Install ${NODE_REQUIREMENT} first. Detected Node ${nodeVersion}.`,
+    );
+  const pkg = JSON.parse(await readFile(join(userDir, 'package.json'), 'utf8'));
+  if (pkg.name !== '@c4roa0/agentpay-user') throw Error('Unexpected User package.');
+  const privateDir = resolve(dataDir), stateDir = installationDirectory();
+  await mkdir(stateDir, {recursive:true, mode:0o700});
+  const stateInfo = await lstat(stateDir);
+  if (!stateInfo.isDirectory() || stateInfo.isSymbolicLink() || stateInfo.uid !== process.getuid() || stateInfo.mode & 0o077)
+    throw Error('Installation state directory must be owner-held and private.');
+  const lockPath = join(stateDir, "install.lock");
+  let lock;
+  try {
+    lock = await open(lockPath, "wx", 0o600);
+  } catch (e) {
+    if (e.code === "EEXIST")
+      throw Error(
+        `Another installation may be running. Check ${lockPath} before removing a stale lock.`,
+      );
+    throw e;
+  }
+  const logPath = join(stateDir, `install-${Date.now()}-${randomUUID()}.log`),
+    statePath = join(stateDir, "state.json");
+  let state = { version: 1 };
+  try {
+    try {
+      const info = await lstat(statePath);
+      if (
+        !info.isFile() ||
+        info.isSymbolicLink() ||
+        info.uid !== process.getuid() ||
+        info.mode & 0o077
+      )
+        throw Error("Unsafe install checkpoint");
+      state = JSON.parse(await readFile(statePath, "utf8"));
+      if (state.version !== 1) throw Error("Unknown install checkpoint");
+    } catch (e) {
+      if (e.code !== "ENOENT") throw e;
+    }
+    const initial = await checkLocalInstallation({
+      userDir,
+      dataDir: privateDir,
+      nodeVersion,
+    });
+    const pathErrors = initial.checks.filter(
+      (c) =>
+        c.status === "failed" &&
+        (c.code === "PRIVATE_PATH" || c.code.startsWith("PRIVATE_DIRECTORY_")),
+    );
+    if (pathErrors.length)
+      throw Error(`${pathErrors[0].message}. ${pathErrors[0].fix || ""}`);
+    // Update service handoff runs inside the same installer lock as dependency writes.
+    const preparationContext = {
+      logPath,
+      state,
+      initial,
+      saveState: () => saveJson(statePath, state),
+    };
+    if (
+      prepareOnly &&
+      beforePrepare &&
+      (await beforePrepare(preparationContext)) === false
+    )
+      return { completed: true, skipped: true, logPath };
+    // npm installations already contain their dependencies. A source checkout may
+    // install its frozen dependency tree, but never compiles or edits Wallet source.
+    const lockfile = join(userDir, 'package-lock.json');
+    let sourceInstall = false;
+    try { sourceInstall = (await lstat(lockfile)).isFile(); } catch (e) { if(e.code !== 'ENOENT') throw e; }
+    const inputs = sourceInstall ? await fingerprint(userDir, ['package.json', 'package-lock.json']) : null;
+    if (sourceInstall && (state.userDependencies !== inputs || !initial.ok)) {
+      write('1/2 Install the pinned User and Wallet dependencies. This may take a few minutes.');
+      await run('npm', ['ci'], {cwd:userDir, logPath});
+      state.userDependencies = inputs;
+    } else write('1/2 Check installed User and Wallet packages.');
+    const checked = await checkLocalInstallation({
+      userDir,
+      dataDir: privateDir,
+      nodeVersion,
+    });
+    if (!checked.ok) {
+      const failed = checked.checks.find((c) => c.status === "failed");
+      throw Error(`${failed.message}. ${failed.fix || ""}`);
+    }
+    await mkdir(privateDir, {recursive:true, mode:0o700});
+    await importSetupFiles(privateDir, userDir);
+    state.dataDir = privateDir;
+    await saveJson(statePath, state);
+    if (prepareOnly) {
+      if (afterPrepare) await afterPrepare(preparationContext);
+      return { completed: true, logPath };
+    }
+    write("2/2 Download public Market settings.");
+    let response;
+    try {
+      response = await fetchImpl(endpoint, {
+        redirect: "error",
+        signal: AbortSignal.timeout(15000),
+      });
+    } catch (error) {
+      const code =
+        error.cause?.code || error.code || error.name || "NETWORK_ERROR";
+      const safeCode = String(code)
+        .replace(/[^A-Za-z0-9_]/g, "")
+        .slice(0, 64);
+      await appendFile(
+        logPath,
+        `Market settings request failed: ${endpoint} (${safeCode})\n`,
+      );
+      throw Error(
+        `Cannot download Market settings from ${endpoint} (${safeCode}). Check the Market connection; for private rehearsal, keep the website SSH tunnel open and try 127.0.0.1 instead of localhost.`,
+      );
+    }
+    if (!response.ok)
+      throw Error(
+        `Market settings unavailable (HTTP ${response.status}). Retry the same Install command later.`,
+      );
+    const chunks = [];
+    let bytes = 0;
+    if (!response.body) throw Error("Empty Market settings response.");
+    for await (const chunk of response.body) {
+      bytes += chunk.length;
+      if (bytes > 16384) throw Error("Market settings response too large.");
+      chunks.push(Buffer.from(chunk));
+    }
+    const raw = Buffer.concat(chunks).toString("utf8");
+    const { validatePublicDeployment } = await import(
+      "./prepare-onboarding.mjs"
+    );
+    const config = validatePublicDeployment(JSON.parse(raw));
+    await saveJson(join(privateDir, "user-deployment.json"), config);
+    write(
+      "User, Wallet and Market settings are ready. Continuing to setup.",
+    );
+    return { completed: true, logPath };
+  } catch (error) {
+    await appendFile(logPath, `Installation stopped: ${error.message}\n`, {
+      mode: 0o600,
+    }).catch(() => {});
+    write(
+      `Installation stopped. ${error.message}\nAfter resolving the cause, rerun the same Install command. Log: ${logPath}`,
+    );
+    error.messageDisplayed = true;
+    error.logPath = logPath;
+    throw error;
+  } finally {
+    await lock.close();
+    await unlink(lockPath);
+  }
+}
+async function runCommand(command, args, { cwd, logPath }) {
+  const log = await open(logPath, "a", 0o600);
+  try {
+    await new Promise((resolve, reject) => {
+      const child = spawn(command, args, {
+        cwd,
+        env: {
+          ...process.env,
+          PATH:
+            dirname(process.execPath) +
+            (process.platform === "win32" ? ";" : ":") +
+            (process.env.PATH || ""),
+          COREPACK_ENABLE_DOWNLOAD_PROMPT: "0",
+        },
+        stdio: ["ignore", log.fd, log.fd],
+      });
+      child.once("error", (e) =>
+        reject(
+          Error(
+            `${command} could not start (${e.code}). Check that it is installed and on PATH.`,
+          ),
+        ),
+      );
+      child.once("exit", (code) =>
+        code === 0
+          ? resolve()
+          : reject(
+              Error(
+                `${command} ${args.join(" ")} failed (exit ${code}). See the install log.`,
+              ),
+            ),
+      );
+    });
+  } finally {
+    await log.close();
+  }
+}

package/src/installation-paths.mjs

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: MPL-2.0
+// Program upgrades never own or replace private state. XDG_STATE_HOME is standard
+// per-user state storage; explicit data-directory settings still select key/history data.
+import { homedir } from 'node:os';
+import { isAbsolute, join, dirname } from 'node:path';
+import { lstat, mkdir, copyFile, constants } from 'node:fs/promises';
+export function installationDirectory() {
+  const base = process.env.XDG_STATE_HOME || join(homedir(), '.local/state');
+  if (!isAbsolute(base)) throw Error('XDG_STATE_HOME must be an absolute path.');
+  return join(base, 'agentpay/user');
+}
+export function legacyInstallationDirectory(userDir) { return join(dirname(userDir), '.agentpay-install'); }
+export async function deploymentFilePath(dataDir, userDir, name) {
+  if (!['anvil-onboarding.json', 'user-deployment.json'].includes(name)) throw Error('Invalid setup filename.');
+  const current = join(dataDir, name);
+  try { await lstat(current); return current; } catch (e) { if (e.code !== 'ENOENT') throw e; }
+  // Read-only fallback for an existing source installation. Never search unrelated machines.
+  return join(dirname(userDir), name);
+}
+export async function importSetupFiles(dataDir, userDir) {
+  for (const name of ['anvil-onboarding.json', 'user-deployment.json']) {
+    const source = await deploymentFilePath(dataDir, userDir, name);
+    if (source === join(dataDir, name)) continue;
+    let info;
+    try { info = await lstat(source); } catch (e) { if (e.code === 'ENOENT') continue; throw e; }
+    if (!info.isFile() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) || info.size > 16384)
+      throw Error('Old setup configuration needs ownership/permission review before migration.');
+    await mkdir(dataDir, {recursive:true, mode:0o700});
+    await copyFile(source, join(dataDir,name), constants.COPYFILE_EXCL).catch(e => { if(e.code !== 'EEXIST') throw e; });
+  }
+}

package/src/invocation-result.mjs

@@ -0,0 +1,148 @@
+// Private result persistence. Received output and verified replayable output are distinct
+// states; storing bytes alone does not establish delivery or final settlement.
+// SPDX-License-Identifier: MPL-2.0
+// This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+// If a copy was not distributed with this file, see https://mozilla.org/MPL/2.0/.
+import { constants } from "node:fs";
+import { open, mkdir, lstat, link, unlink } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+function resultFiles(statePath, pending = false) {
+  const directory = statePath + (pending ? ".pending-results" : ".results");
+  const version = pending
+    ? "agentpay.pending-result.v1"
+    : "agentpay.invocation-result.v1";
+  const name = (id) => {
+    if (!/^0x[0-9a-f]{64}$/.test(id || ""))
+      throw Error("INVOCATION_RESULT_ID_INVALID");
+    return join(directory, id + ".json");
+  };
+  return {
+    async read(invocation) {
+      try {
+        const dir = await lstat(directory);
+        if (
+          !dir.isDirectory() ||
+          dir.isSymbolicLink() ||
+          dir.uid !== process.getuid() ||
+          dir.mode & 0o077
+        )
+          throw Error("INVOCATION_RESULT_UNSAFE");
+      } catch (error) {
+        if (error.code === "ENOENT") return null;
+        throw error;
+      }
+
+      let file;
+      try {
+        file = await open(
+          name(invocation.invocationId),
+          constants.O_RDONLY | constants.O_NOFOLLOW,
+        );
+      } catch (error) {
+        if (error.code === "ENOENT") return null;
+        throw error;
+      }
+      let value;
+      try {
+        const st = await file.stat();
+        if (
+          !st.isFile() ||
+          st.uid !== process.getuid() ||
+          st.mode & 0o077 ||
+          st.size > 2 * 1048576
+        )
+          throw Error("INVOCATION_RESULT_UNSAFE");
+        value = JSON.parse(await file.readFile("utf8"));
+      } finally {
+        await file.close();
+      }
+      if (
+        value?.version !== version ||
+        value.invocationId !== invocation.invocationId ||
+        value.requestHash !== invocation.requestHash ||
+        value.serviceBinding !== invocation.serviceBinding ||
+        !value.result ||
+        typeof value.result !== "object" ||
+        Array.isArray(value.result)
+      )
+        throw Error("INVOCATION_RESULT_CONFLICT");
+      return value.result;
+    },
+    async save(invocation, result) {
+      const content =
+        JSON.stringify({
+          version,
+          invocationId: invocation.invocationId,
+          requestHash: invocation.requestHash,
+          serviceBinding: invocation.serviceBinding,
+          result,
+        }) + "\n";
+      if (Buffer.byteLength(content) > 2 * 1048576)
+        throw Error("INVOCATION_RESULT_TOO_LARGE");
+      await mkdir(directory, { mode: 0o700 }).catch((error) => {
+        if (error.code !== "EEXIST") throw error;
+      });
+      const st = await lstat(directory);
+      if (
+        !st.isDirectory() ||
+        st.isSymbolicLink() ||
+        st.uid !== process.getuid() ||
+        st.mode & 0o077
+      )
+        throw Error("INVOCATION_RESULT_UNSAFE");
+      const parent = await open(dirname(directory), "r");
+      try {
+        await parent.sync();
+      } finally {
+        await parent.close();
+      }
+      const target = name(invocation.invocationId),
+        temporary = join(directory, ".result-" + randomUUID());
+      const file = await open(temporary, "wx", 0o600);
+      try {
+        try {
+          await file.writeFile(content);
+          await file.sync();
+        } finally {
+          await file.close();
+        }
+        await link(temporary, target).catch(async (error) => {
+          if (error.code !== "EEXIST") throw error;
+          const existing = await this.read(invocation);
+          const immutable = (v) => {
+            if (pending) return v;
+            const { finalization, deadlines, ...content } = v;
+            return content;
+          };
+          if (
+            JSON.stringify(immutable(existing)) !==
+            JSON.stringify(immutable(result))
+          )
+            throw Error("INVOCATION_RESULT_CONFLICT");
+        });
+        const dir = await open(directory, "r");
+        try {
+          await dir.sync();
+        } finally {
+          await dir.close();
+        }
+      } finally {
+        await unlink(temporary).catch((error) => {
+          if (error.code !== "ENOENT") throw error;
+        });
+      }
+    },
+  };
+}
+
+export function invocationResults(statePath) {
+  const verified = resultFiles(statePath),
+    pending = resultFiles(statePath, true);
+  return {
+    read: verified.read.bind(verified),
+    save: verified.save.bind(verified),
+    readPending: pending.read.bind(pending),
+    savePending: pending.save.bind(pending),
+  };
+}