@le-space/node 0.1.0

package/index.js

@@ -0,0 +1,2061 @@
+// src/env.ts
+function requiredEnv(name, env = process.env) {
+  const value = env[name];
+  if (value == null || value === "") {
+    throw new Error(`Missing required environment variable ${name}`);
+  }
+  return value;
+}
+function optionalEnv(name, fallback = "", env = process.env) {
+  return env[name] ?? fallback;
+}
+function integerEnv(name, fallback, env = process.env) {
+  const raw = optionalEnv(name, String(fallback), env);
+  const value = Number.parseInt(raw, 10);
+  if (!Number.isFinite(value)) {
+    throw new Error(`${name} must be an integer.`);
+  }
+  return value;
+}
+function booleanEnv(name, fallback, env = process.env) {
+  const raw = optionalEnv(name, fallback ? "true" : "false", env).trim().toLowerCase();
+  if (raw === "true" || raw === "1" || raw === "yes") return true;
+  if (raw === "false" || raw === "0" || raw === "no") return false;
+  throw new Error(`${name} must be a boolean-like value.`);
+}
+function jsonEnv(name, fallback, env = process.env) {
+  const raw = optionalEnv(name, fallback, env);
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${name} must be valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+// src/github-outputs.ts
+import { appendFile } from "fs/promises";
+async function appendGithubOutput(name, value, env = process.env) {
+  const outputFile = env.GITHUB_OUTPUT;
+  if (!outputFile) return;
+  await appendFile(outputFile, `${name}=${String(value ?? "")}
+`);
+}
+async function appendGithubSummary(lines, env = process.env) {
+  const summaryFile = env.GITHUB_STEP_SUMMARY;
+  if (!summaryFile) return;
+  await appendFile(summaryFile, `${lines.join("\n")}
+`);
+}
+function actionLog(level, message, options = {}) {
+  const normalizedLevel = ["notice", "warning", "error"].includes(level) ? level : "notice";
+  const escaped = String(message).replace(/\r?\n/g, "%0A");
+  const stderr = options.stderr ?? process.stderr;
+  const githubActions = options.githubActions ?? process.env.GITHUB_ACTIONS === "true";
+  if (githubActions) {
+    stderr.write(`::${normalizedLevel}::${escaped}
+`);
+  }
+  stderr.write(`${message}
+`);
+}
+
+// src/signer.ts
+function ensureWalletAddress(wallet) {
+  if (typeof wallet.address === "string" && wallet.address.trim()) return wallet.address;
+  if (typeof wallet.getAddress === "function") return wallet.getAddress();
+  throw new Error("The provided wallet implementation does not expose an address.");
+}
+async function loadWalletCtor(options = {}) {
+  return options.walletCtor ?? await import("ethers").then((module) => module.Wallet).catch(() => {
+    throw new Error("ethers is required to create the default Node private-key signer.");
+  });
+}
+async function createPrivateKeySigner(privateKey, options = {}) {
+  const Wallet = await loadWalletCtor(options);
+  return async (_sender, payload) => {
+    const wallet = new Wallet(privateKey);
+    return wallet.signMessage(payload);
+  };
+}
+async function createPrivateKeyIdentity(privateKey, options = {}) {
+  const Wallet = await loadWalletCtor(options);
+  const wallet = new Wallet(privateKey);
+  const address = await ensureWalletAddress(wallet);
+  return {
+    address,
+    signer: async (_sender, payload) => wallet.signMessage(payload)
+  };
+}
+
+// src/deploy-outputs.ts
+async function emitDeployOutputs(deployResult, env = process.env) {
+  const runtime = deployResult?.runtime ?? null;
+  const selectedCrn = runtime?.selectedCrn ?? deployResult?.selectedCrn ?? null;
+  const runtimeJson = JSON.stringify(runtime ?? {});
+  const mappedPortsJson = JSON.stringify(runtime?.mappedPorts ?? {});
+  const portForwardingJson = JSON.stringify(deployResult?.portForwarding ?? {});
+  const configurationJson = JSON.stringify(deployResult?.configuration ?? {});
+  const verificationJson = JSON.stringify(deployResult?.verification ?? {});
+  const probeMultiaddrsJson = JSON.stringify(deployResult?.configuration?.metadata?.probe_multiaddrs ?? []);
+  const browserBootstrapMultiaddrsJson = JSON.stringify(
+    deployResult?.configuration?.metadata?.browser_bootstrap_multiaddrs ?? []
+  );
+  const relayPeerId = deployResult?.configuration?.metadata?.peer_id ?? "";
+  const deploymentStatus = deployResult?.status ?? "";
+  await appendGithubOutput("deployer_address", deployResult?.sender ?? "", env);
+  await appendGithubOutput("instance_item_hash", deployResult?.itemHash ?? "", env);
+  await appendGithubOutput("instance_status", deploymentStatus, env);
+  await appendGithubOutput("instance_http_status", deployResult?.httpStatus ?? "", env);
+  await appendGithubOutput("port_forward_aggregate_item_hash", deployResult?.portForwarding?.aggregateItemHash ?? "", env);
+  await appendGithubOutput("port_forward_status", deployResult?.portForwarding?.aggregateStatus ?? "", env);
+  await appendGithubOutput("crn_hash", selectedCrn?.hash ?? "", env);
+  await appendGithubOutput("crn_name", selectedCrn?.name ?? "", env);
+  await appendGithubOutput("crn_url", runtime?.allocation?.crnUrl ?? "", env);
+  await appendGithubOutput("host_ipv4", runtime?.hostIpv4 ?? "", env);
+  await appendGithubOutput("ipv6", runtime?.ipv6 ?? "", env);
+  await appendGithubOutput("web_proxy_url", runtime?.proxyUrl ?? "", env);
+  await appendGithubOutput("ssh_command", runtime?.sshCommand ?? "", env);
+  await appendGithubOutput("setup_endpoint_ok", runtime?.setupHealth?.ok ?? "", env);
+  await appendGithubOutput("mapped_ports_json", mappedPortsJson, env);
+  await appendGithubOutput("configuration_json", configurationJson, env);
+  await appendGithubOutput("relay_peer_id", relayPeerId, env);
+  await appendGithubOutput("probe_multiaddrs_json", probeMultiaddrsJson, env);
+  await appendGithubOutput("browser_bootstrap_multiaddrs_json", browserBootstrapMultiaddrsJson, env);
+  await appendGithubOutput("verification_json", verificationJson, env);
+  await appendGithubOutput("verification_ok", deployResult?.verification?.ok ?? "", env);
+  await appendGithubOutput("port_forwarding_json", portForwardingJson, env);
+  await appendGithubOutput("runtime_json", runtimeJson, env);
+  await appendGithubSummary([
+    "## Aleph VM deployment",
+    "",
+    `- Instance item hash: \`${deployResult?.itemHash ?? "unknown"}\``,
+    `- Deployment status: \`${deploymentStatus || "unknown"}\``,
+    `- Port-forward aggregate status: \`${deployResult?.portForwarding?.aggregateStatus ?? "unknown"}\``,
+    `- CRN: \`${selectedCrn?.name ?? selectedCrn?.hash ?? "unknown"}\``,
+    `- CRN URL: \`${runtime?.allocation?.crnUrl ?? "unknown"}\``,
+    `- Host IPv4: \`${runtime?.hostIpv4 ?? "unknown"}\``,
+    `- IPv6: \`${runtime?.ipv6 ?? "unknown"}\``,
+    `- Web proxy URL: \`${runtime?.proxyUrl ?? "unknown"}\``,
+    `- Relay peer ID: \`${relayPeerId || "unknown"}\``,
+    `- SSH command: \`${runtime?.sshCommand ?? "unknown"}\``,
+    `- Setup endpoint reachable before configure: \`${runtime?.setupHealth?.ok ?? "unknown"}\``,
+    `- Runtime diagnostics: \`${runtime?.diagnostics?.state ?? "unknown"}${runtime?.diagnostics?.timedOut ? " (timed out)" : ""}\``,
+    `- Runtime reason: \`${runtime?.diagnostics?.reason ?? "none"}\``,
+    `- Verification ok: \`${deployResult?.verification?.ok ?? "unknown"}\``,
+    "",
+    "### Port mappings",
+    "",
+    "```json",
+    mappedPortsJson,
+    "```",
+    "",
+    "### Reachability checks",
+    "",
+    "```json",
+    verificationJson,
+    "```"
+  ], env);
+  return { runtimeJson, verificationJson };
+}
+async function emitGeocodedCrnOutputs(geocodedCrns, env = process.env) {
+  const payload = JSON.stringify(geocodedCrns);
+  await appendGithubOutput("geocoded_crns_json", payload, env);
+  await appendGithubOutput("geocoded_crn_count", geocodedCrns.length, env);
+  await appendGithubSummary([
+    "## Aleph geocoded CRNs",
+    "",
+    `- Geocoded CRNs: \`${geocodedCrns.length}\``
+  ], env);
+}
+
+// src/deploy-plan.ts
+function parseDeployPlan(env = process.env) {
+  const requiredPorts = jsonEnv(
+    "ALEPH_VM_REQUIRED_PORTS_JSON",
+    "[]",
+    env
+  );
+  return {
+    profile: optionalEnv("ALEPH_VM_PROFILE", "uc-go-peer", env),
+    privateKey: requiredEnv("ALEPH_VM_PRIVATE_KEY", env),
+    apiHost: optionalEnv("ALEPH_VM_API_HOST", "https://api2.aleph.im", env),
+    crnListUrl: optionalEnv("ALEPH_VM_CRN_LIST_URL", "https://crns-list.aleph.sh/crns.json", env),
+    name: requiredEnv("ALEPH_VM_NAME", env),
+    sshPublicKey: requiredEnv("ALEPH_VM_SSH_PUBLIC_KEY", env),
+    rootfsItemHash: requiredEnv("ALEPH_VM_ROOTFS_ITEM_HASH", env),
+    rootfsVersion: optionalEnv("ALEPH_VM_ROOTFS_VERSION", "", env),
+    rootfsSizeMiB: integerEnv("ALEPH_VM_ROOTFS_SIZE_MIB", 20480, env),
+    crnHash: optionalEnv("ALEPH_VM_CRN_HASH", "", env),
+    preferredCountryCode: optionalEnv("ALEPH_VM_PREFERRED_COUNTRY_CODE", "DE", env),
+    geoCrnLimit: integerEnv("ALEPH_VM_GEO_CRN_LIMIT", 30, env),
+    maxCrnAttempts: integerEnv("ALEPH_VM_MAX_CRN_ATTEMPTS", 5, env),
+    vcpus: integerEnv("ALEPH_VM_VCPUS", 1, env),
+    memoryMiB: integerEnv("ALEPH_VM_MEMORY_MIB", 1024, env),
+    seconds: integerEnv("ALEPH_VM_SECONDS", 30, env),
+    channel: optionalEnv("ALEPH_VM_CHANNEL", "TEST", env),
+    waitAttempts: integerEnv("ALEPH_VM_WAIT_ATTEMPTS", 60, env),
+    waitDelayMs: integerEnv("ALEPH_VM_WAIT_DELAY_MS", 5e3, env),
+    runtimeAttempts: integerEnv("ALEPH_VM_RUNTIME_ATTEMPTS", 40, env),
+    runtimeDelayMs: integerEnv("ALEPH_VM_RUNTIME_DELAY_MS", 5e3, env),
+    setupAttempts: integerEnv("ALEPH_VM_SETUP_ATTEMPTS", 15, env),
+    setupDelayMs: integerEnv("ALEPH_VM_SETUP_DELAY_MS", 4e3, env),
+    verifyAttempts: integerEnv("ALEPH_VM_VERIFY_ATTEMPTS", 25, env),
+    verifyDelayMs: integerEnv("ALEPH_VM_VERIFY_DELAY_MS", 5e3, env),
+    tcpTimeoutMs: integerEnv("ALEPH_VM_TCP_TIMEOUT_MS", 5e3, env),
+    httpTimeoutMs: integerEnv("ALEPH_VM_HTTP_TIMEOUT_MS", 1e4, env),
+    metadataAttempts: integerEnv("ALEPH_VM_METADATA_ATTEMPTS", 80, env),
+    metadataDelayMs: integerEnv("ALEPH_VM_METADATA_DELAY_MS", 3e3, env),
+    metadataTimeoutMs: integerEnv("ALEPH_VM_METADATA_TIMEOUT_MS", 24e4, env),
+    configureTimeoutMs: integerEnv("ALEPH_VM_CONFIGURE_TIMEOUT_MS", 18e4, env),
+    enableCaddyProxy: booleanEnv("ALEPH_VM_ENABLE_CADDY_PROXY", false, env),
+    autoConfigure: booleanEnv("ALEPH_VM_AUTO_CONFIGURE", true, env),
+    verifyReachability: booleanEnv("ALEPH_VM_VERIFY_REACHABILITY", true, env),
+    requiredPorts,
+    publishPortForwards: booleanEnv("ALEPH_VM_PUBLISH_PORT_FORWARDS", true, env)
+  };
+}
+
+// src/deploy-executor.ts
+import { createHash } from "crypto";
+import net from "net";
+import { setTimeout as sleep } from "timers/promises";
+
+// ../core/src/constants.ts
+var DEFAULT_ALEPH_CHANNEL = "TEST";
+
+// ../core/src/manifests.ts
+var DEFAULT_ALEPH_API_HOST = "https://api2.aleph.im";
+
+// ../core/src/crns.ts
+var DEFAULT_CRN_LIST_URL = "https://crns-list.aleph.sh/crns.json";
+var DEFAULT_COUNTRY_LOOKUP_BASE_URL = "https://api.country.is";
+var DEFAULT_DNS_RESOLVE_URL = "https://dns.google/resolve";
+function asString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function normalizeCountryCode(value) {
+  const normalized = asString(value)?.toUpperCase() ?? null;
+  return normalized && /^[A-Z]{2}$/.test(normalized) ? normalized : null;
+}
+function lookupHost(address) {
+  try {
+    return new URL(address ?? "").hostname.trim().toLowerCase();
+  } catch {
+    return String(address ?? "").trim().toLowerCase().replace(/^https?:\/\//, "").replace(/:\d+$/, "");
+  }
+}
+function isIpAddress(host) {
+  return /^\d{1,3}(?:\.\d{1,3}){3}$/.test(host) || host.includes(":");
+}
+function countryNameFromCode(value) {
+  if (!value) return null;
+  try {
+    const displayNames = new Intl.DisplayNames(["en"], { type: "region" });
+    return displayNames.of(value) ?? value;
+  } catch {
+    return value;
+  }
+}
+function compatibleCrns(crns, excludedHashes = []) {
+  const excluded = new Set(excludedHashes.filter(Boolean));
+  return [...crns].filter((crn) => {
+    if (!crn?.hash || excluded.has(crn.hash)) return false;
+    if (crn.qemu_support === false) return false;
+    if (crn.system_usage?.active === false) return false;
+    return true;
+  });
+}
+function scoreSortedCrns(crns) {
+  return [...crns].sort((left, right) => {
+    const rightScore = typeof right.score === "number" ? right.score : Number(right.score ?? Number.NEGATIVE_INFINITY);
+    const leftScore = typeof left.score === "number" ? left.score : Number(left.score ?? Number.NEGATIVE_INFINITY);
+    if (rightScore !== leftScore) return rightScore - leftScore;
+    const leftName = (left.name || left.address || left.hash).toLowerCase();
+    const rightName = (right.name || right.address || right.hash).toLowerCase();
+    return leftName.localeCompare(rightName);
+  });
+}
+async function resolveHostIp(host, options) {
+  if (!host) return null;
+  if (isIpAddress(host)) return host;
+  for (const type of ["A", "AAAA"]) {
+    const url = new URL(options.dnsResolveUrl ?? DEFAULT_DNS_RESOLVE_URL);
+    url.searchParams.set("name", host);
+    url.searchParams.set("type", type);
+    url.searchParams.set("edns_client_subnet", "0.0.0.0/0");
+    const response = await options.fetch(url.toString(), {
+      cache: "no-cache"
+    });
+    if (!response.ok) continue;
+    const payload = await response.json();
+    const record = Array.isArray(payload?.Answer) ? payload.Answer.find((entry) => typeof entry?.data === "string" && entry.data.trim()) : null;
+    if (typeof record?.data === "string" && record.data.trim()) {
+      return record.data.trim();
+    }
+  }
+  return null;
+}
+async function lookupIpLocation(ip, options) {
+  const url = new URL(`${options.countryLookupBaseUrl ?? DEFAULT_COUNTRY_LOOKUP_BASE_URL}/${encodeURIComponent(ip)}`);
+  url.searchParams.set("fields", "city,subdivision");
+  const response = await options.fetch(url.toString(), {
+    cache: "no-cache"
+  });
+  if (!response.ok) {
+    return {
+      resolved_ip: ip,
+      city: null,
+      region: null,
+      country: null,
+      country_code: null,
+      geo_source: null
+    };
+  }
+  const payload = await response.json();
+  const countryCode = normalizeCountryCode(payload?.country);
+  return {
+    resolved_ip: asString(payload?.ip) ?? ip,
+    city: asString(payload?.city),
+    region: asString(payload?.subdivision),
+    country: countryNameFromCode(countryCode),
+    country_code: countryCode,
+    geo_source: "country.is"
+  };
+}
+async function fetchCrns(options) {
+  const requestUrl = new URL(options.url ?? DEFAULT_CRN_LIST_URL);
+  requestUrl.searchParams.set("filter_inactive", "true");
+  const response = await options.fetch(requestUrl.toString(), {
+    cache: "no-cache"
+  });
+  if (!response.ok) {
+    throw new Error(`CRN list request failed: ${response.status}`);
+  }
+  const payload = await response.json();
+  return Array.isArray(payload?.crns) ? payload.crns : [];
+}
+async function enrichCrnsWithGeo(crns, options) {
+  return Promise.all(
+    crns.map(async (crn) => {
+      if (crn.city || crn.region || crn.country || crn.country_code) {
+        return crn;
+      }
+      try {
+        const host = lookupHost(crn.address);
+        const ip = await resolveHostIp(host, {
+          fetch: options.fetch,
+          dnsResolveUrl: options.dnsResolveUrl
+        });
+        if (!ip) return crn;
+        return {
+          ...crn,
+          ...await lookupIpLocation(ip, {
+            fetch: options.fetch,
+            countryLookupBaseUrl: options.countryLookupBaseUrl
+          })
+        };
+      } catch {
+        return crn;
+      }
+    })
+  );
+}
+async function listGeocodedCrns(options) {
+  const sortedCrns = scoreSortedCrns(compatibleCrns(await fetchCrns({
+    url: options.url,
+    fetch: options.fetch
+  })));
+  const geocodedCrns = await enrichCrnsWithGeo(
+    sortedCrns.slice(0, Math.max(1, Number(options.limit) || 30)),
+    options
+  );
+  return geocodedCrns.filter((crn) => Boolean(crn.city || crn.region || crn.country || crn.country_code)).sort((left, right) => {
+    const leftLabel = `${left.country ?? ""}/${left.region ?? ""}/${left.city ?? ""}/${left.name ?? left.hash}`.toLowerCase();
+    const rightLabel = `${right.country ?? ""}/${right.region ?? ""}/${right.city ?? ""}/${right.name ?? right.hash}`.toLowerCase();
+    return leftLabel.localeCompare(rightLabel);
+  });
+}
+async function rankCandidateCrns(crns, options) {
+  const preferredCountryCode = normalizeCountryCode(options.preferredCountryCode);
+  const geoLimit = Math.max(1, Number(options.geoLimit) || 30);
+  const sortedCrns = scoreSortedCrns(compatibleCrns(crns, options.excludedHashes));
+  if (!preferredCountryCode || sortedCrns.length === 0) {
+    return sortedCrns;
+  }
+  const enrichedTopCrns = await enrichCrnsWithGeo(sortedCrns.slice(0, geoLimit), options);
+  const mergedByHash = new Map(enrichedTopCrns.map((crn) => [crn.hash, crn]));
+  const mergedCrns = sortedCrns.map((crn) => mergedByHash.get(crn.hash) ?? crn);
+  const originalIndex = new Map(mergedCrns.map((crn, index) => [crn.hash, index]));
+  return [...mergedCrns].sort((left, right) => {
+    const leftPreferred = normalizeCountryCode(left.country_code) === preferredCountryCode ? 1 : 0;
+    const rightPreferred = normalizeCountryCode(right.country_code) === preferredCountryCode ? 1 : 0;
+    if (leftPreferred !== rightPreferred) {
+      return rightPreferred - leftPreferred;
+    }
+    return (originalIndex.get(left.hash) ?? Number.MAX_SAFE_INTEGER) - (originalIndex.get(right.hash) ?? Number.MAX_SAFE_INTEGER);
+  });
+}
+
+// ../core/src/port-forwarding.ts
+var DEFAULT_INSTANCE_PORT_FORWARDS = [
+  { port: 22, tcp: true, udp: false, purpose: "SSH" }
+];
+function normalizeRequestedPort(entry) {
+  return {
+    port: entry.port,
+    tcp: entry.tcp === true,
+    udp: entry.udp === true,
+    purpose: entry.purpose?.trim() || void 0
+  };
+}
+function normalizePortFlags(value) {
+  if (!value || typeof value !== "object") return null;
+  const candidate = value;
+  return {
+    tcp: candidate.tcp === true,
+    udp: candidate.udp === true
+  };
+}
+function normalizeExistingPortForwardEntry(entry) {
+  if (!entry?.ports || typeof entry.ports !== "object") return {};
+  return Object.fromEntries(
+    Object.entries(entry.ports).map(([port, flags]) => [port, normalizePortFlags(flags)]).filter((item) => item[1] != null)
+  );
+}
+function requestedPortFlags(portForwards) {
+  return Object.fromEntries(
+    portForwards.map((entry) => [
+      String(entry.port),
+      {
+        tcp: entry.tcp === true,
+        udp: entry.udp === true
+      }
+    ])
+  );
+}
+function mergePortFlagMaps(existing, requested) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const [port, flags] of Object.entries(existing)) {
+    merged.set(port, {
+      tcp: flags.tcp === true,
+      udp: flags.udp === true
+    });
+  }
+  for (const [port, flags] of Object.entries(requested)) {
+    const current = merged.get(port);
+    merged.set(port, {
+      tcp: current?.tcp === true || flags.tcp === true,
+      udp: current?.udp === true || flags.udp === true
+    });
+  }
+  return Object.fromEntries([...merged.entries()].sort((left, right) => Number(left[0]) - Number(right[0])));
+}
+function mergeRequiredPortForwards(...groups) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const group of groups) {
+    for (const entry of group ?? []) {
+      const normalized = normalizeRequestedPort(entry);
+      const current = merged.get(normalized.port);
+      merged.set(normalized.port, {
+        port: normalized.port,
+        tcp: current?.tcp === true || normalized.tcp === true,
+        udp: current?.udp === true || normalized.udp === true,
+        purpose: current?.purpose ?? normalized.purpose
+      });
+    }
+  }
+  return [...merged.values()].sort((left, right) => left.port - right.port);
+}
+function requiredInstancePortForwards(manifest) {
+  return mergeRequiredPortForwards(DEFAULT_INSTANCE_PORT_FORWARDS, manifest?.requiredPortForwards);
+}
+async function fetchPortForwardAggregate(address, options) {
+  const requestUrl = new URL(`/api/v0/aggregates/${address}.json`, options.apiHost ?? DEFAULT_ALEPH_API_HOST);
+  requestUrl.searchParams.set("keys", "port-forwarding");
+  const response = await options.fetch(requestUrl.toString(), { cache: "no-cache" });
+  if (response.status === 404) return {};
+  if (!response.ok) {
+    throw new Error(`Port-forward aggregate request failed: ${response.status}`);
+  }
+  const payload = await response.json();
+  const aggregate = payload.data?.["port-forwarding"];
+  if (!aggregate || typeof aggregate !== "object" || Array.isArray(aggregate)) return {};
+  return aggregate;
+}
+
+// ../core/src/aleph-normalizers.ts
+function asString2(value) {
+  return typeof value === "string" && value.trim() ? value : null;
+}
+function asNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function normalizeMessageStatus(status) {
+  if (typeof status !== "string") return "unknown";
+  const normalized = status.toLowerCase();
+  if (normalized === "processed" || normalized === "pending" || normalized === "rejected") {
+    return normalized;
+  }
+  return "unknown";
+}
+function normalizeProxyUrl(value) {
+  const stringValue = asString2(value);
+  if (!stringValue) return null;
+  if (/^https?:\/\//i.test(stringValue)) return stringValue;
+  return `https://${stringValue}`;
+}
+function messageTypeFromEnvelope(payload) {
+  if (!payload) return null;
+  const type = payload.type ?? payload.message?.type ?? (Array.isArray(payload.messages) ? payload.messages[0]?.type : void 0);
+  return typeof type === "string" ? type.toUpperCase() : null;
+}
+function extractReferenceHashes(details) {
+  if (!details || typeof details !== "object" || !("errors" in details)) return [];
+  const errors = details.errors;
+  if (!Array.isArray(errors)) return [];
+  return errors.filter((value) => typeof value === "string");
+}
+function describeRejectedDeployment(payload, references, rootfsRef) {
+  const errorCode = typeof payload.error_code === "number" ? payload.error_code : null;
+  const pendingReferences = references.filter((reference) => reference.status === "pending");
+  const missingReferences = references.filter((reference) => reference.status === "missing");
+  const rootfsReference = references.find((reference) => reference.itemHash === rootfsRef);
+  if (rootfsReference?.status === "pending") {
+    return `Aleph rejected this deployment because the referenced rootfs STORE message ${rootfsReference.itemHash} is still pending and cannot yet be used by an instance. Wait for that STORE message to process, then deploy again.`;
+  }
+  if (pendingReferences.length > 0) {
+    return `Aleph rejected this deployment because referenced message(s) are still pending: ${pendingReferences.map((reference) => reference.itemHash).join(", ")}.`;
+  }
+  if (missingReferences.length > 0) {
+    return `Aleph rejected this deployment because referenced message(s) were not found on Aleph: ${missingReferences.map((reference) => reference.itemHash).join(", ")}.`;
+  }
+  const referencedHashes = extractReferenceHashes(payload.details);
+  if (referencedHashes.length > 0) {
+    return `Aleph rejected this deployment${errorCode ? ` (error ${errorCode})` : ""}. Referenced message(s): ${referencedHashes.join(", ")}.`;
+  }
+  return `Aleph rejected this deployment${errorCode ? ` (error ${errorCode})` : ""}.`;
+}
+function extractProxyUrl(item, networking) {
+  const networkingCandidates = [
+    networking?.proxy_url,
+    networking?.proxyUrl,
+    networking?.web_access_url,
+    networking?.webAccessUrl,
+    networking?.proxy_hostname,
+    networking?.proxyHostname,
+    networking?.domain,
+    networking?.hostname
+  ];
+  for (const candidate of networkingCandidates) {
+    const normalized = normalizeProxyUrl(candidate);
+    if (normalized) return normalized;
+  }
+  const webAccessCandidates = [item.web_access, item.webAccess];
+  for (const entry of webAccessCandidates) {
+    const normalized = normalizeProxyUrl(entry?.url) ?? normalizeProxyUrl(entry?.proxy_url) ?? normalizeProxyUrl(entry?.hostname) ?? normalizeProxyUrl(entry?.domain);
+    if (normalized) return normalized;
+  }
+  return null;
+}
+function normalizeExecution(item, crnUrl) {
+  const networking = item.networking ?? null;
+  const mappedPorts = networking && "mapped_ports" in networking && networking.mapped_ports && typeof networking.mapped_ports === "object" ? Object.fromEntries(
+    Object.entries(networking.mapped_ports).map(([port, mapping]) => [
+      port,
+      {
+        host: asNumber(mapping?.host) ?? void 0,
+        tcp: typeof mapping?.tcp === "boolean" ? mapping.tcp : void 0,
+        udp: typeof mapping?.udp === "boolean" ? mapping.udp : void 0
+      }
+    ])
+  ) : void 0;
+  if (networking && ("host_ipv4" in networking || "ipv6_ip" in networking || "ipv4_network" in networking)) {
+    const v2Item = item;
+    return {
+      crnUrl,
+      version: "v2",
+      running: typeof v2Item.running === "boolean" ? v2Item.running : void 0,
+      networking: {
+        ipv4_network: asString2(networking.ipv4_network),
+        host_ipv4: asString2(networking.host_ipv4),
+        ipv6_network: asString2(networking.ipv6_network),
+        ipv6_ip: asString2(networking.ipv6_ip),
+        ipv4_ip: asString2(networking.ipv4_ip),
+        proxy_url: extractProxyUrl(v2Item, networking),
+        mapped_ports: mappedPorts
+      },
+      status: v2Item.status ? {
+        defined_at: asString2(v2Item.status.defined_at),
+        preparing_at: asString2(v2Item.status.preparing_at),
+        prepared_at: asString2(v2Item.status.prepared_at),
+        starting_at: asString2(v2Item.status.starting_at),
+        started_at: asString2(v2Item.status.started_at),
+        stopping_at: asString2(v2Item.status.stopping_at),
+        stopped_at: asString2(v2Item.status.stopped_at)
+      } : null
+    };
+  }
+  return {
+    crnUrl,
+    version: "v1",
+    networking: {
+      ipv4: networking && "ipv4" in networking ? asString2(networking.ipv4) : null,
+      ipv6: networking && "ipv6" in networking ? asString2(networking.ipv6) : null
+    },
+    status: null
+  };
+}
+
+// ../core/src/deployment-inspection.ts
+async function fetchMessageEnvelope(itemHash, options) {
+  const response = await options.fetch(`${options.apiHost ?? DEFAULT_ALEPH_API_HOST}/api/v0/messages/${itemHash}`, {
+    cache: "no-cache"
+  });
+  if (response.status === 404) return null;
+  if (!response.ok) throw new Error(`Message lookup failed: ${response.status}`);
+  return await response.json();
+}
+async function fetchReference(itemHash, options) {
+  const payload = await fetchMessageEnvelope(itemHash, options);
+  if (!payload) {
+    return {
+      itemHash,
+      status: "missing",
+      type: null
+    };
+  }
+  return {
+    itemHash,
+    status: normalizeMessageStatus(payload.status),
+    type: messageTypeFromEnvelope(payload)
+  };
+}
+async function inspectDeploymentResult(itemHash, options) {
+  const payload = await fetchMessageEnvelope(itemHash, options);
+  if (!payload) {
+    return {
+      status: "unknown",
+      errorCode: null,
+      details: null,
+      rejectionReason: `Deployment message ${itemHash} was not found on Aleph.`,
+      references: []
+    };
+  }
+  const relatedHashes = new Set(options.rootfsRef ? [options.rootfsRef] : []);
+  for (const referenceHash of extractReferenceHashes(payload.details)) {
+    relatedHashes.add(referenceHash);
+  }
+  const references = await Promise.all(
+    Array.from(relatedHashes).map((hash) => fetchReference(hash, options))
+  );
+  const status = normalizeMessageStatus(payload.status);
+  const errorCode = typeof payload.error_code === "number" ? payload.error_code : null;
+  const details = payload.details && typeof payload.details === "object" ? payload.details : null;
+  return {
+    status,
+    errorCode,
+    details,
+    rejectionReason: status === "rejected" ? describeRejectedDeployment(payload, references, options.rootfsRef) : null,
+    references
+  };
+}
+async function waitForDeploymentResult(itemHash, options) {
+  const attempts = Math.max(1, Number(options.attempts ?? 15));
+  const delayMs = Math.max(0, Number(options.delayMs ?? 2e3));
+  const sleep2 = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  let lastResult = await inspectDeploymentResult(itemHash, options);
+  for (let attempt = 1; attempt < attempts; attempt += 1) {
+    if (lastResult.status === "processed" || lastResult.status === "rejected") {
+      return lastResult;
+    }
+    await sleep2(delayMs);
+    lastResult = await inspectDeploymentResult(itemHash, options);
+  }
+  return lastResult;
+}
+
+// ../core/src/broadcast.ts
+function signaturePayload(message) {
+  return [message.chain, message.sender, message.type, message.item_hash].join("\n");
+}
+async function signAlephMessage(unsignedMessage, signer) {
+  const signature = await signer(unsignedMessage.sender, signaturePayload(unsignedMessage));
+  return {
+    ...unsignedMessage,
+    signature: signature.startsWith("0x") ? signature : `0x${signature}`
+  };
+}
+function normalizeBroadcastStatus(httpStatus, responseStatus) {
+  if (httpStatus === 202) return "pending";
+  return normalizeMessageStatus(responseStatus);
+}
+function isInvalidMessageFormatResponse(response, payload) {
+  if (response.status !== 422) return false;
+  const details = payload?.details;
+  if (typeof details === "string" && details.includes("InvalidMessageFormat")) return true;
+  if (details && typeof details === "object") {
+    const detailMessage = details.message;
+    if (typeof detailMessage === "string" && detailMessage.includes("InvalidMessageFormat")) return true;
+  }
+  return false;
+}
+function isRetryableBroadcastFailure(response, payload) {
+  if (response.status >= 500) return true;
+  const publicationStatus = payload?.publication_status?.status;
+  if (typeof publicationStatus === "string" && publicationStatus.toLowerCase() === "error") {
+    return true;
+  }
+  return false;
+}
+async function postBroadcastPayload(body, options) {
+  const rawResponse = await options.fetch(`${options.apiHost ?? DEFAULT_ALEPH_API_HOST}/api/v0/messages`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  const response = await rawResponse.json().catch(() => ({}));
+  return {
+    response,
+    httpStatus: rawResponse.status
+  };
+}
+async function broadcastAlephMessage(message, options) {
+  const attempts = [
+    { sync: options.sync ?? false, message },
+    { ...message, sync: options.sync ?? false },
+    { ...message }
+  ];
+  for (let index = 0; index < attempts.length; index += 1) {
+    const result = await postBroadcastPayload(attempts[index], {
+      apiHost: options.apiHost,
+      fetch: options.fetch
+    });
+    if (result.httpStatus === 202 || normalizeBroadcastStatus(result.httpStatus, result.response?.message_status) !== "unknown" || result.httpStatus >= 200 && result.httpStatus < 300) {
+      return result;
+    }
+    const canRetry = index < attempts.length - 1 && (isInvalidMessageFormatResponse({ status: result.httpStatus }, result.response) || isRetryableBroadcastFailure({ status: result.httpStatus }, result.response));
+    if (!canRetry) {
+      throw new Error(`Broadcast failed: ${result.httpStatus} ${JSON.stringify(result.response ?? {})}`);
+    }
+  }
+  throw new Error("Broadcast failed: no compatible request format was accepted");
+}
+
+// ../core/src/forget.ts
+function asOptionalReason(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+async function createUnsignedForgetMessage(args) {
+  const content = {
+    address: args.sender,
+    time: args.now ?? Date.now() / 1e3,
+    hashes: [...new Set((args.hashes ?? []).filter(Boolean))],
+    aggregates: [...new Set((args.aggregates ?? []).filter(Boolean))],
+    reason: asOptionalReason(args.reason)
+  };
+  if (content.hashes.length === 0 && content.aggregates.length === 0) {
+    throw new Error("FORGET message requires at least one hash or aggregate key.");
+  }
+  const itemContent = JSON.stringify(content);
+  const itemHash = await args.hasher(itemContent);
+  return {
+    sender: args.sender,
+    chain: "ETH",
+    type: "FORGET",
+    item_hash: itemHash,
+    item_type: "inline",
+    item_content: itemContent,
+    time: args.now ?? Date.now() / 1e3,
+    channel: args.channel ?? DEFAULT_ALEPH_CHANNEL
+  };
+}
+async function forgetAlephMessages(args) {
+  const unsignedMessage = await createUnsignedForgetMessage({
+    sender: args.sender,
+    hashes: args.hashes,
+    aggregates: args.aggregates,
+    reason: args.reason,
+    hasher: args.hasher,
+    channel: args.channel,
+    now: args.now
+  });
+  const message = await signAlephMessage(unsignedMessage, args.signer);
+  const { response, httpStatus } = await broadcastAlephMessage(message, {
+    apiHost: args.apiHost,
+    sync: args.sync,
+    fetch: args.fetch
+  });
+  return {
+    sender: args.sender,
+    itemHash: message.item_hash,
+    response,
+    httpStatus,
+    status: normalizeBroadcastStatus(httpStatus, response?.message_status)
+  };
+}
+async function cleanupFailedDeployment(args) {
+  try {
+    return await forgetAlephMessages({
+      sender: args.sender,
+      hashes: [args.instanceItemHash],
+      reason: args.reason ?? "Discard failed deployment attempt",
+      signer: args.signer,
+      hasher: args.hasher,
+      fetch: args.fetch,
+      channel: args.channel,
+      apiHost: args.apiHost
+    });
+  } catch (error) {
+    return {
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+// ../core/src/retention.ts
+var SUCCESSFUL_DEPLOYMENTS_AGGREGATE_KEY = "uc-go-peer-successful-deployments";
+function asString3(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function normalizeRetentionRecord(record) {
+  if (!record || typeof record !== "object" || Array.isArray(record)) return null;
+  const candidate = record;
+  const instanceItemHash = asString3(candidate.instance_item_hash);
+  if (!instanceItemHash) return null;
+  return {
+    instance_item_hash: instanceItemHash,
+    rootfs_item_hash: asString3(candidate.rootfs_item_hash) ?? "",
+    site_item_hash: asString3(candidate.site_item_hash) ?? "",
+    rootfs_cid: asString3(candidate.rootfs_cid) ?? "",
+    site_url: asString3(candidate.site_url) ?? "",
+    relay_peer_id: asString3(candidate.relay_peer_id) ?? "",
+    rootfs_version: asString3(candidate.rootfs_version) ?? "",
+    deployed_at: asString3(candidate.deployed_at) ?? (/* @__PURE__ */ new Date()).toISOString(),
+    vm_name: asString3(candidate.vm_name) ?? ""
+  };
+}
+function normalizeRetentionLedger(value) {
+  if (Array.isArray(value)) {
+    return value.map(normalizeRetentionRecord).filter((entry) => entry != null);
+  }
+  if (value && typeof value === "object" && Array.isArray(value.deployments)) {
+    return value.deployments.map(normalizeRetentionRecord).filter((entry) => entry != null);
+  }
+  return [];
+}
+function retentionRecordId(record) {
+  return [record.instance_item_hash, record.rootfs_item_hash, record.site_item_hash].join(":");
+}
+function hashesFromRetentionRecord(record) {
+  return [record.instance_item_hash, record.rootfs_item_hash, record.site_item_hash].filter(Boolean);
+}
+async function fetchAggregateKey(args) {
+  const requestUrl = new URL(`/api/v0/aggregates/${args.address}.json`, args.apiHost ?? "https://api2.aleph.im");
+  requestUrl.searchParams.set("keys", args.key);
+  const response = await args.fetch(requestUrl.toString(), { cache: "no-cache" });
+  if (response.status === 404) return {};
+  if (!response.ok) {
+    throw new Error(`Aggregate request failed for key ${args.key}: ${response.status}`);
+  }
+  const payload = await response.json();
+  return payload?.data?.[args.key] ?? {};
+}
+async function createUnsignedAggregateMessage(args) {
+  const itemContent = JSON.stringify(args.content);
+  const itemHash = await args.hasher(itemContent);
+  return {
+    sender: args.sender,
+    chain: "ETH",
+    type: "AGGREGATE",
+    item_hash: itemHash,
+    item_type: "inline",
+    item_content: itemContent,
+    time: args.now ?? Date.now() / 1e3,
+    channel: args.channel ?? DEFAULT_ALEPH_CHANNEL
+  };
+}
+async function publishAggregateKey(args) {
+  const aggregateContent = {
+    address: args.sender,
+    key: args.key,
+    content: args.content,
+    time: args.now ?? Date.now() / 1e3
+  };
+  const unsignedMessage = await createUnsignedAggregateMessage({
+    sender: args.sender,
+    content: aggregateContent,
+    hasher: args.hasher,
+    channel: args.channel,
+    now: args.now
+  });
+  const message = await signAlephMessage(unsignedMessage, args.signer);
+  const { response, httpStatus } = await broadcastAlephMessage(message, {
+    apiHost: args.apiHost,
+    sync: true,
+    fetch: args.fetch
+  });
+  return {
+    itemHash: message.item_hash,
+    status: normalizeBroadcastStatus(httpStatus, response?.message_status),
+    response,
+    httpStatus
+  };
+}
+async function retainSuccessfulDeployments(args) {
+  const keepCount = Math.max(0, Number.parseInt(String(args.keepCount ?? 0), 10) || 0);
+  const aggregateKey = asString3(args.aggregateKey) ?? SUCCESSFUL_DEPLOYMENTS_AGGREGATE_KEY;
+  const currentRecord = normalizeRetentionRecord(args.currentRecord);
+  if (!currentRecord) {
+    throw new Error("retainSuccessfulDeployments requires a current deployment record with instance_item_hash.");
+  }
+  const existingValue = await fetchAggregateKey({
+    address: args.sender,
+    key: aggregateKey,
+    fetch: args.fetch,
+    apiHost: args.apiHost
+  });
+  const existingRecords = normalizeRetentionLedger(existingValue);
+  const mergedRecords = [currentRecord, ...existingRecords];
+  const uniqueRecords = [];
+  const seenIds = /* @__PURE__ */ new Set();
+  for (const record of mergedRecords) {
+    const id = retentionRecordId(record);
+    if (seenIds.has(id)) continue;
+    seenIds.add(id);
+    uniqueRecords.push(record);
+  }
+  const retainedRecords = keepCount > 0 ? uniqueRecords.slice(0, keepCount) : [];
+  const prunedRecords = keepCount > 0 ? uniqueRecords.slice(keepCount) : uniqueRecords;
+  const retainedHashes = new Set(retainedRecords.flatMap(hashesFromRetentionRecord));
+  const extraForgetHashes = [...new Set((args.extraForgetHashes ?? []).filter(Boolean))];
+  const forgetHashes = [.../* @__PURE__ */ new Set([...prunedRecords.flatMap(hashesFromRetentionRecord), ...extraForgetHashes])].filter(
+    (hash) => !retainedHashes.has(hash)
+  );
+  const aggregateContent = {
+    keep: keepCount,
+    updated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    deployments: retainedRecords
+  };
+  const aggregatePublication = await publishAggregateKey({
+    sender: args.sender,
+    key: aggregateKey,
+    content: aggregateContent,
+    signer: args.signer,
+    hasher: args.hasher,
+    fetch: args.fetch,
+    channel: args.channel,
+    apiHost: args.apiHost,
+    now: args.now
+  });
+  let forgetResult = null;
+  if (forgetHashes.length > 0) {
+    forgetResult = await forgetAlephMessages({
+      sender: args.sender,
+      hashes: forgetHashes,
+      reason: args.reason ?? `Prune successful deployments beyond retention limit ${keepCount}`,
+      signer: args.signer,
+      hasher: args.hasher,
+      fetch: args.fetch,
+      channel: args.channel,
+      apiHost: args.apiHost,
+      now: args.now
+    });
+  }
+  return {
+    sender: args.sender,
+    aggregateKey,
+    keepCount,
+    aggregatePublication,
+    retainedRecords,
+    prunedRecords,
+    forgetHashes,
+    forgetResult
+  };
+}
+
+// ../core/src/aggregate-publication.ts
+function createPortForwardAggregateContent(args) {
+  const existingPorts = normalizeExistingPortForwardEntry(args.existingAggregate?.[args.instanceItemHash]);
+  const mergedPorts = mergePortFlagMaps(existingPorts, requestedPortFlags(args.requestedPorts));
+  return {
+    address: args.sender,
+    key: "port-forwarding",
+    content: {
+      [args.instanceItemHash]: {
+        ports: mergedPorts
+      }
+    },
+    time: args.now ?? Date.now() / 1e3
+  };
+}
+async function createUnsignedAggregateMessage2(args) {
+  const itemContent = JSON.stringify(args.content);
+  const itemHash = await args.hasher(itemContent);
+  return {
+    sender: args.sender,
+    chain: "ETH",
+    type: "AGGREGATE",
+    item_hash: itemHash,
+    item_type: "inline",
+    item_content: itemContent,
+    time: args.now ?? Date.now() / 1e3,
+    channel: args.channel ?? DEFAULT_ALEPH_CHANNEL
+  };
+}
+async function ensureInstancePortForwards(args) {
+  const requestedPorts = requiredInstancePortForwards(args.manifest);
+  const aggregate = await fetchPortForwardAggregate(args.sender, {
+    apiHost: args.apiHost,
+    fetch: args.fetch
+  });
+  const content = createPortForwardAggregateContent({
+    sender: args.sender,
+    instanceItemHash: args.instanceItemHash,
+    requestedPorts,
+    existingAggregate: aggregate
+  });
+  const unsignedMessage = await createUnsignedAggregateMessage2({
+    sender: args.sender,
+    content,
+    hasher: args.hasher,
+    channel: args.channel
+  });
+  const message = await signAlephMessage(unsignedMessage, args.signer);
+  const { response, httpStatus } = await broadcastAlephMessage(message, {
+    apiHost: args.apiHost,
+    sync: args.sync,
+    fetch: args.fetch
+  });
+  const aggregateStatus = normalizeBroadcastStatus(httpStatus, response.message_status);
+  if (aggregateStatus === "rejected") {
+    throw new Error(`Port-forward aggregate was rejected by Aleph: ${JSON.stringify(response.details ?? response)}`);
+  }
+  return {
+    aggregateItemHash: message.item_hash,
+    aggregateStatus,
+    requestedPorts
+  };
+}
+
+// ../core/src/instance-deployment.ts
+var SSH_PUBLIC_KEY_PATTERN = /^(ssh-rsa|ssh-ed25519|ecdsa-sha2-nistp256|ecdsa-sha2-nistp384|ecdsa-sha2-nistp521|sk-ssh-ed25519@openssh\.com|sk-ecdsa-sha2-nistp256@openssh\.com)\s+[A-Za-z0-9+/]+={0,3}(?:\s+.+)?$/;
+function normalizeSshPublicKey(value) {
+  return value.split(/\r?\n/g).map((line) => line.trim()).filter(Boolean).join(" ").replace(/\s+/g, " ").trim();
+}
+function isValidSshPublicKey(value) {
+  return SSH_PUBLIC_KEY_PATTERN.test(normalizeSshPublicKey(value));
+}
+function createReleaseMetadata(name, rootfsVersion, deployer = "shared-aleph-tooling") {
+  return {
+    name,
+    rootfs_version: rootfsVersion,
+    deployer
+  };
+}
+function createInstanceContent(args) {
+  const sshKey = normalizeSshPublicKey(args.sshPublicKey);
+  if (!sshKey) {
+    throw new Error("An SSH public key is required.");
+  }
+  if (!isValidSshPublicKey(sshKey)) {
+    throw new Error("SSH public key must be a single valid .pub line.");
+  }
+  if (!args.rootfsItemHash || !/^[a-fA-F0-9]{64}$/.test(args.rootfsItemHash)) {
+    throw new Error("rootfsItemHash must be a 64-character Aleph item hash.");
+  }
+  return {
+    address: args.address,
+    time: args.now ?? Date.now() / 1e3,
+    allow_amend: false,
+    metadata: createReleaseMetadata(args.name.trim(), args.rootfsVersion ?? "custom-rootfs", args.deployer),
+    authorized_keys: [sshKey],
+    environment: {
+      internet: true,
+      aleph_api: true,
+      hypervisor: "qemu",
+      reproducible: false,
+      shared_cache: false
+    },
+    resources: {
+      vcpus: Number(args.vcpus),
+      memory: Number(args.memoryMiB),
+      seconds: Number(args.seconds ?? 30)
+    },
+    payment: {
+      type: "credit"
+    },
+    requirements: args.crnHash ? {
+      node: {
+        node_hash: args.crnHash
+      }
+    } : void 0,
+    volumes: [],
+    rootfs: {
+      parent: {
+        ref: args.rootfsItemHash,
+        use_latest: true
+      },
+      persistence: "host",
+      size_mib: Number(args.rootfsSizeMiB)
+    }
+  };
+}
+async function createUnsignedInstanceMessage(args) {
+  const itemContent = JSON.stringify(args.content);
+  const itemHash = await args.hasher(itemContent);
+  return {
+    sender: args.sender,
+    chain: "ETH",
+    type: "INSTANCE",
+    item_hash: itemHash,
+    item_type: "inline",
+    item_content: itemContent,
+    time: args.now ?? Date.now() / 1e3,
+    channel: args.channel ?? DEFAULT_ALEPH_CHANNEL
+  };
+}
+async function deployInstance(args) {
+  const unsignedMessage = await createUnsignedInstanceMessage({
+    sender: args.sender,
+    content: args.content,
+    hasher: args.hasher,
+    channel: args.channel,
+    now: args.now
+  });
+  const signature = await args.signer(unsignedMessage.sender, [unsignedMessage.chain, unsignedMessage.sender, unsignedMessage.type, unsignedMessage.item_hash].join("\n"));
+  const message = {
+    ...unsignedMessage,
+    signature: signature.startsWith("0x") ? signature : `0x${signature}`
+  };
+  const { response, httpStatus } = await broadcastAlephMessage(message, {
+    apiHost: args.apiHost,
+    sync: args.sync,
+    fetch: args.fetch
+  });
+  const status = httpStatus === 202 ? "pending" : typeof response.message_status === "string" ? response.message_status : "unknown";
+  return {
+    itemHash: message.item_hash,
+    httpStatus,
+    status,
+    message,
+    response,
+    rejectionReason: status === "rejected" ? String(response.details ?? "Aleph rejected this deployment.") : null
+  };
+}
+
+// ../core/src/runtime.ts
+var DEFAULT_SCHEDULER_ALLOCATION_URL = "https://scheduler.api.aleph.cloud/api/v0/allocation";
+var DEFAULT_TWO_N_SIX_HASH_URL = "https://api.2n6.me/api/hash";
+function asString4(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function asNumber2(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function findCrnByHash(crns, crnHash) {
+  return crns.find((crn) => crn.hash === crnHash) ?? null;
+}
+async function fetchSchedulerAllocation(itemHash, options) {
+  const response = await options.fetch(
+    `${options.schedulerAllocationUrl ?? DEFAULT_SCHEDULER_ALLOCATION_URL}/${itemHash}`,
+    { cache: "no-cache" }
+  );
+  if (response.status === 404) return null;
+  if (!response.ok) {
+    throw new Error(`Scheduler allocation request failed: ${response.status}`);
+  }
+  const payload = await response.json();
+  const node = payload?.node;
+  return {
+    source: "scheduler",
+    crnHash: asString4(node?.node_id),
+    crnUrl: asString4(node?.url),
+    node: node ? {
+      node_id: asString4(node.node_id) ?? void 0,
+      url: asString4(node.url) ?? void 0,
+      ipv6: asString4(node.ipv6),
+      supports_ipv6: typeof node.supports_ipv6 === "boolean" ? node.supports_ipv6 : void 0
+    } : null,
+    vmIpv6: asString4(payload?.vm_ipv6),
+    period: payload?.period ? {
+      start_timestamp: asString4(payload.period.start_timestamp) ?? void 0,
+      duration_seconds: asNumber2(payload.period.duration_seconds) ?? void 0
+    } : null
+  };
+}
+async function fetch2n6WebAccessUrl(itemHash, options) {
+  const response = await options.fetch(
+    `${options.twoN6HashUrl ?? DEFAULT_TWO_N_SIX_HASH_URL}/${itemHash}`,
+    { cache: "no-cache" }
+  );
+  if (!response.ok) return null;
+  const payload = await response.json();
+  return {
+    url: normalizeProxyUrl(payload?.url ?? payload?.subdomain),
+    active: typeof payload?.active === "boolean" ? payload.active : null,
+    subdomain: asString4(payload?.subdomain)
+  };
+}
+async function fetchCrnExecutionMap(crnUrl, options) {
+  const normalizedCrnUrl = String(crnUrl).replace(/\/+$/, "");
+  for (const [version, suffix] of [
+    ["v2", "/v2/about/executions/list"],
+    ["v1", "/about/executions/list"]
+  ]) {
+    const requestUrl = `${normalizedCrnUrl}${suffix}`;
+    const response = await options.fetch(requestUrl, {
+      cache: "no-cache"
+    });
+    if (response.ok) {
+      const payload = await response.json();
+      return {
+        version,
+        payload: payload && typeof payload === "object" ? payload : null,
+        requestUrl
+      };
+    }
+    if (response.status !== 404) {
+      return {
+        version,
+        payload: null,
+        requestUrl
+      };
+    }
+  }
+  return {
+    version: "v2",
+    payload: null,
+    requestUrl: `${normalizedCrnUrl}/v2/about/executions/list`
+  };
+}
+function describeRuntimeAvailability(runtime) {
+  const execution = runtime.execution ?? null;
+  const mappedPorts = runtime.mappedPorts ?? {};
+  const hostIpv4 = runtime.hostIpv4 ?? null;
+  const proxyUrl = runtime.proxyUrl ?? null;
+  const schedulerSource = runtime.allocation?.source ?? null;
+  const webAccessActive = runtime.webAccess?.active ?? null;
+  const mappedPortCount = Object.keys(mappedPorts).length;
+  if (hostIpv4 && mappedPortCount > 0) {
+    return {
+      state: "ready",
+      reason: null,
+      schedulerSource,
+      executionSeen: Boolean(execution),
+      webAccessActive,
+      mappedPortCount,
+      proxyUrl
+    };
+  }
+  if (!execution && proxyUrl && webAccessActive === false) {
+    return {
+      state: "proxy-reserved-inactive",
+      reason: "Aleph reserved a proxy URL for the VM, but it is still inactive and the selected CRN has not exposed execution networking yet.",
+      schedulerSource,
+      executionSeen: false,
+      webAccessActive,
+      mappedPortCount,
+      proxyUrl
+    };
+  }
+  if (!execution && schedulerSource === "manual") {
+    return {
+      state: "crn-execution-missing",
+      reason: "The deployment is pinned to a specific CRN, but that CRN is not exposing this VM in its execution list yet.",
+      schedulerSource,
+      executionSeen: false,
+      webAccessActive,
+      mappedPortCount,
+      proxyUrl
+    };
+  }
+  if (execution && !hostIpv4) {
+    return {
+      state: "execution-missing-host-ipv4",
+      reason: "The CRN exposed an execution record, but it does not include a public host IPv4 yet.",
+      schedulerSource,
+      executionSeen: true,
+      webAccessActive,
+      mappedPortCount,
+      proxyUrl
+    };
+  }
+  if (execution && mappedPortCount === 0) {
+    return {
+      state: "execution-missing-port-mappings",
+      reason: "The CRN exposed an execution record, but mapped ports are still empty.",
+      schedulerSource,
+      executionSeen: true,
+      webAccessActive,
+      mappedPortCount,
+      proxyUrl
+    };
+  }
+  return {
+    state: "runtime-pending",
+    reason: "Aleph has not exposed enough runtime networking details yet.",
+    schedulerSource,
+    executionSeen: Boolean(execution),
+    webAccessActive,
+    mappedPortCount,
+    proxyUrl
+  };
+}
+async function fetchVmRuntime(args) {
+  const crns = args.crns ?? await fetchCrns({
+    url: args.crnListUrl ?? DEFAULT_CRN_LIST_URL,
+    fetch: args.fetch
+  });
+  const schedulerAllocation = await fetchSchedulerAllocation(args.itemHash, {
+    fetch: args.fetch,
+    schedulerAllocationUrl: args.schedulerAllocationUrl
+  }).catch(() => null);
+  const selectedCrn = args.crnHash ? findCrnByHash(crns, args.crnHash) : null;
+  const allocation = schedulerAllocation ?? (selectedCrn ? {
+    source: "manual",
+    crnHash: selectedCrn.hash,
+    crnUrl: selectedCrn.address,
+    node: { url: selectedCrn.address },
+    vmIpv6: null,
+    period: null
+  } : null);
+  const webAccess = await fetch2n6WebAccessUrl(args.itemHash, {
+    fetch: args.fetch,
+    twoN6HashUrl: args.twoN6HashUrl
+  }).catch(() => null);
+  const webAccessUrl = webAccess?.url ?? null;
+  let execution = null;
+  let executionLookupBlocked = false;
+  if (allocation?.crnUrl) {
+    const executionLookup = await fetchCrnExecutionMap(allocation.crnUrl, {
+      fetch: args.fetch
+    });
+    const executionPayload = executionLookup.payload?.[args.itemHash];
+    if (executionPayload && typeof executionPayload === "object") {
+      execution = normalizeExecution(executionPayload, allocation.crnUrl);
+      if (!execution.networking.proxy_url && webAccessUrl) {
+        execution.networking.proxy_url = webAccessUrl;
+      }
+    } else if (executionLookup.payload == null) {
+      executionLookupBlocked = true;
+    }
+  }
+  const hostIpv4 = execution?.networking?.host_ipv4 ?? execution?.networking?.ipv4 ?? null;
+  const ipv6 = execution?.networking?.ipv6_ip ?? execution?.networking?.ipv6 ?? allocation?.vmIpv6 ?? null;
+  const mappedPorts = execution?.networking?.mapped_ports ?? {};
+  const sshPort = mappedPorts?.["22"]?.host ?? null;
+  const proxyUrl = execution?.networking?.proxy_url ?? webAccessUrl ?? null;
+  const diagnostics = describeRuntimeAvailability({
+    allocation,
+    execution,
+    webAccess,
+    hostIpv4,
+    ipv6,
+    proxyUrl,
+    mappedPorts
+  });
+  return {
+    allocation,
+    execution,
+    webAccess,
+    webAccessUrl,
+    hostIpv4,
+    ipv6,
+    proxyUrl,
+    mappedPorts,
+    diagnostics,
+    sshCommand: hostIpv4 && sshPort ? `ssh root@${hostIpv4} -p ${sshPort}` : ipv6 ? `ssh root@${ipv6}` : null,
+    selectedCrn,
+    executionLookupBlocked
+  };
+}
+async function waitForVmRuntime(args) {
+  const attempts = Math.max(1, Number(args.attempts ?? 20));
+  const delayMs = Math.max(0, Number(args.delayMs ?? 4e3));
+  const sleep2 = args.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  let lastRuntime = await fetchVmRuntime(args);
+  for (let attempt = 0; attempt < attempts - 1; attempt += 1) {
+    if (lastRuntime.hostIpv4 && Object.keys(lastRuntime.mappedPorts ?? {}).length > 0) {
+      return lastRuntime;
+    }
+    await sleep2(delayMs);
+    lastRuntime = await fetchVmRuntime(args);
+  }
+  if (lastRuntime.diagnostics) {
+    lastRuntime.diagnostics.timedOut = true;
+  }
+  return lastRuntime;
+}
+
+// ../core/src/guest.ts
+function proxyHostnameFromUrl(value) {
+  try {
+    return value ? new URL(value).hostname : null;
+  } catch {
+    return null;
+  }
+}
+async function defaultHttpProbe(fetch, url, timeoutMs = 1e4) {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    const response = await fetch(url, {
+      method: "GET",
+      redirect: "follow",
+      signal: controller.signal
+    });
+    clearTimeout(timeout);
+    return {
+      ok: response.ok,
+      status: response.status,
+      url: response.url
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+async function notifyCrnAllocation(args) {
+  const normalizedCrnUrl = typeof args.crnUrl === "string" ? args.crnUrl.trim().replace(/\/+$/, "") : "";
+  if (!normalizedCrnUrl) {
+    return {
+      status: "skipped",
+      reason: "No CRN URL available for allocation notification."
+    };
+  }
+  try {
+    const response = await args.fetch(`${normalizedCrnUrl}/control/allocation/notify`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({ instance: args.itemHash })
+    });
+    const payload = await response.json().catch(() => null);
+    if (!response.ok) {
+      return {
+        status: "unconfirmed",
+        reason: `CRN allocation notify returned ${response.status}.`,
+        payload
+      };
+    }
+    return {
+      status: "confirmed",
+      payload
+    };
+  } catch (error) {
+    return {
+      status: "unconfirmed",
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+async function waitForSetupEndpoint(args) {
+  const attempts = Math.max(1, Number(args.attempts ?? 15));
+  const delayMs = Math.max(0, Number(args.delayMs ?? 4e3));
+  const sleep2 = args.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const url = `http://${args.hostIpv4}:${args.setupPort}/health`;
+  let result = await defaultHttpProbe(args.fetch, url, Number(args.httpTimeoutMs ?? 1e4));
+  for (let attempt = 1; attempt < attempts; attempt += 1) {
+    if (result.ok) return result;
+    await sleep2(delayMs);
+    result = await defaultHttpProbe(args.fetch, url, Number(args.httpTimeoutMs ?? 1e4));
+  }
+  return result;
+}
+async function configureUcGoPeer(args) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), Number(args.timeoutMs ?? 18e4));
+  const payload = {
+    public_ipv4: args.hostIpv4,
+    public_ipv6: args.publicIpv6 ?? void 0,
+    proxy_url: args.proxyUrl ?? void 0,
+    tcp_port: args.tcpPort ?? void 0,
+    ws_port: args.wsPort ?? void 0,
+    udp_port: args.udpPort ?? void 0,
+    quic_port: args.quicPort ?? void 0,
+    webrtc_port: args.webrtcPort ?? void 0
+  };
+  try {
+    const response = await args.fetch(`http://${args.hostIpv4}:${args.setupPort}/configure`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal
+    });
+    const responsePayload = await response.json().catch(() => null);
+    if (!response.ok) {
+      throw new Error(
+        `Relay setup request failed: ${response.status} ${typeof responsePayload === "string" ? responsePayload : JSON.stringify(responsePayload ?? {})}`
+      );
+    }
+    return responsePayload;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function fetchUcGoPeerMetadata(args) {
+  const attempts = Math.max(1, Number(args.attempts ?? 60));
+  const delayMs = Math.max(0, Number(args.delayMs ?? 3e3));
+  const sleep2 = args.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  let lastPayload = null;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), Number(args.timeoutMs ?? 18e4));
+    try {
+      const response = await args.fetch(`http://${args.hostIpv4}:${args.setupPort}/metadata`, {
+        signal: controller.signal
+      });
+      const payload = await response.json().catch(() => null);
+      lastPayload = payload;
+      if (response.ok && payload && typeof payload === "object" && payload.status === "ready") {
+        return payload;
+      }
+      if (response.status >= 500) {
+        throw new Error(
+          `Relay metadata request failed: ${response.status} ${typeof payload === "string" ? payload : JSON.stringify(payload ?? {})}`
+        );
+      }
+    } finally {
+      clearTimeout(timeout);
+    }
+    if (attempt < attempts - 1) {
+      await sleep2(delayMs);
+    }
+  }
+  throw new Error(
+    `Relay metadata did not become ready after ${attempts} attempts: ${typeof lastPayload === "string" ? lastPayload : JSON.stringify(lastPayload ?? {})}`
+  );
+}
+async function verifyUcGoPeerReachability(args) {
+  const checks = {};
+  const mappedPorts = args.mappedPorts ?? {};
+  const hostIpv4 = args.hostIpv4;
+  const skippedInternalPorts = new Set((args.skipInternalPorts ?? ["80"]).map((value) => String(value)));
+  const httpProbe = args.httpProbe ?? ((url, timeoutMs) => defaultHttpProbe(args.fetch, url, timeoutMs));
+  if (hostIpv4) {
+    for (const [internalPort, mapping] of Object.entries(mappedPorts)) {
+      if (skippedInternalPorts.has(String(internalPort))) continue;
+      if (mapping?.tcp === true && mapping?.host) {
+        checks[`tcp:${internalPort}`] = {
+          host: hostIpv4,
+          port: mapping.host,
+          ...await args.tcpProbe(hostIpv4, mapping.host, Number(args.tcpTimeoutMs ?? 5e3))
+        };
+      } else if (mapping?.udp === true && mapping?.host) {
+        checks[`udp:${internalPort}`] = {
+          host: hostIpv4,
+          port: mapping.host,
+          ok: null,
+          note: "UDP mapping published; CI does not perform an application-level UDP handshake probe."
+        };
+      }
+    }
+  }
+  if (args.proxyUrl && args.verifyProxyHttp !== false) {
+    checks["https:proxy"] = await httpProbe(args.proxyUrl, Number(args.httpTimeoutMs ?? 1e4));
+  }
+  const proxyHostname = proxyHostnameFromUrl(args.proxyUrl);
+  if (proxyHostname) {
+    checks["tcp:proxy-443"] = await args.tcpProbe(proxyHostname, 443, Number(args.tcpTimeoutMs ?? 5e3));
+  }
+  const failedChecks = Object.entries(checks).filter(([, value]) => value?.ok === false);
+  return {
+    ok: failedChecks.length === 0,
+    checks
+  };
+}
+
+// src/deploy-executor.ts
+function defaultHasher(payload) {
+  return createHash("sha256").update(payload).digest("hex");
+}
+async function defaultTcpProbe(host, port, timeoutMs = 5e3) {
+  return await new Promise((resolve) => {
+    const socket = net.createConnection({ host, port: Number(port) });
+    const finalize = (result) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(result);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => finalize({ ok: true }));
+    socket.once("timeout", () => finalize({ ok: false, error: `timeout after ${timeoutMs}ms` }));
+    socket.once("error", (error) => finalize({ ok: false, error: error.message }));
+  });
+}
+function diagnosticsFromInspection(result, plan) {
+  if (result.status === "processed") {
+    return {
+      state: "aleph-processed",
+      timedOut: false,
+      reason: "Deployment message processed by Aleph."
+    };
+  }
+  if (result.status === "rejected") {
+    return {
+      state: "aleph-rejected",
+      timedOut: false,
+      reason: result.rejectionReason ?? "Aleph rejected the deployment."
+    };
+  }
+  return {
+    state: "aleph-processing-timeout",
+    timedOut: true,
+    reason: `Deployment remained ${result.status} after ${plan.waitAttempts} poll attempt(s).`
+  };
+}
+function mergeVerificationState(args) {
+  const runtimeState = args.runtime?.diagnostics?.state ?? null;
+  return {
+    ok: args.inspection.status === "processed",
+    state: runtimeState ?? args.inspection.status,
+    rejectionReason: args.inspection.rejectionReason,
+    references: args.inspection.references
+  };
+}
+async function candidateCrnsForPlan(plan, fetchImpl) {
+  const crns = await fetchCrns({
+    url: plan.crnListUrl,
+    fetch: fetchImpl
+  });
+  if (plan.crnHash) {
+    const explicit = crns.find((crn) => crn.hash === plan.crnHash);
+    return explicit ? [explicit] : [];
+  }
+  return (await rankCandidateCrns(crns, {
+    fetch: fetchImpl,
+    preferredCountryCode: plan.preferredCountryCode,
+    geoLimit: plan.geoCrnLimit
+  })).slice(0, Math.max(1, plan.maxCrnAttempts));
+}
+function buildManifest(plan, manifest) {
+  return manifest ?? {
+    version: "1.0",
+    profile: plan.profile,
+    rootfsItemHash: plan.rootfsItemHash,
+    rootfsSizeMiB: plan.rootfsSizeMiB,
+    rootfsInstallStrategy: "thin",
+    requiredPortForwards: plan.requiredPorts,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    notes: "Synthetic manifest assembled by the shared deploy executor."
+  };
+}
+async function executeDeployPlan(plan, dependencies = {}) {
+  const fetchImpl = dependencies.fetch ?? globalThis.fetch?.bind(globalThis);
+  if (typeof fetchImpl !== "function") {
+    throw new Error("A fetch implementation is required to execute the shared deploy plan.");
+  }
+  const hasher = dependencies.hasher ?? defaultHasher;
+  const tcpProbe = dependencies.tcpProbe ?? defaultTcpProbe;
+  const sleepImpl = dependencies.sleep ?? ((ms) => sleep(ms).then(() => void 0));
+  const identity = dependencies.sender && dependencies.signer ? { address: dependencies.sender, signer: dependencies.signer } : await createPrivateKeyIdentity(plan.privateKey);
+  const candidateCrns = await candidateCrnsForPlan(plan, fetchImpl);
+  if (candidateCrns.length === 0) {
+    throw new Error("No compatible CRN was available for deployment.");
+  }
+  let lastError = null;
+  for (const candidateCrn of candidateCrns) {
+    const content = createInstanceContent({
+      address: identity.address,
+      name: plan.name,
+      sshPublicKey: plan.sshPublicKey,
+      rootfsItemHash: plan.rootfsItemHash,
+      rootfsSizeMiB: plan.rootfsSizeMiB,
+      vcpus: plan.vcpus,
+      memoryMiB: plan.memoryMiB,
+      seconds: plan.seconds,
+      rootfsVersion: plan.rootfsVersion || "custom-rootfs",
+      crnHash: candidateCrn.hash,
+      deployer: "shared-aleph-tooling"
+    });
+    const deployment = await deployInstance({
+      sender: identity.address,
+      content,
+      hasher,
+      signer: identity.signer,
+      fetch: fetchImpl,
+      apiHost: plan.apiHost,
+      channel: plan.channel,
+      sync: true
+    });
+    const inspection = await waitForDeploymentResult(deployment.itemHash, {
+      rootfsRef: plan.rootfsItemHash,
+      apiHost: plan.apiHost,
+      fetch: fetchImpl,
+      attempts: plan.waitAttempts,
+      delayMs: plan.waitDelayMs,
+      sleep: sleepImpl
+    });
+    if (inspection.status === "rejected") {
+      lastError = new Error(
+        `Deployment on ${candidateCrn.name ?? candidateCrn.hash} was rejected: ${inspection.rejectionReason ?? "no additional rejection reason from Aleph"}.`
+      );
+      continue;
+    }
+    if (inspection.status !== "processed") {
+      await cleanupFailedDeployment({
+        sender: identity.address,
+        instanceItemHash: deployment.itemHash,
+        reason: `Deployment message stayed ${inspection.status}`,
+        signer: identity.signer,
+        hasher,
+        fetch: fetchImpl,
+        channel: plan.channel,
+        apiHost: plan.apiHost
+      });
+      lastError = new Error(
+        `Deployment message ${deployment.itemHash} on ${candidateCrn.name ?? candidateCrn.hash} stayed ${inspection.status} without becoming processed.`
+      );
+      continue;
+    }
+    let portForwarding = null;
+    if (plan.publishPortForwards && plan.requiredPorts.length > 0) {
+      const aggregate = await ensureInstancePortForwards({
+        sender: identity.address,
+        instanceItemHash: deployment.itemHash,
+        manifest: buildManifest(plan, dependencies.manifest),
+        signer: identity.signer,
+        hasher,
+        fetch: fetchImpl,
+        channel: plan.channel,
+        apiHost: plan.apiHost,
+        sync: true
+      });
+      portForwarding = {
+        aggregateItemHash: aggregate.aggregateItemHash,
+        aggregateStatus: aggregate.aggregateStatus
+      };
+    }
+    const runtime = await waitForVmRuntime({
+      itemHash: deployment.itemHash,
+      fetch: fetchImpl,
+      crnHash: candidateCrn.hash,
+      crns: candidateCrns,
+      crnListUrl: plan.crnListUrl,
+      attempts: plan.runtimeAttempts,
+      delayMs: plan.runtimeDelayMs,
+      sleep: sleepImpl
+    }).catch(() => null);
+    const runtimeMetadata = runtime ? {
+      allocation: runtime.allocation,
+      hostIpv4: runtime.hostIpv4,
+      ipv6: runtime.ipv6,
+      proxyUrl: runtime.proxyUrl,
+      sshCommand: runtime.sshCommand,
+      setupHealth: null,
+      mappedPorts: runtime.mappedPorts,
+      diagnostics: runtime.diagnostics,
+      selectedCrn: runtime.selectedCrn ?? { hash: candidateCrn.hash, name: candidateCrn.name ?? "" }
+    } : {
+      allocation: null,
+      hostIpv4: null,
+      ipv6: null,
+      proxyUrl: null,
+      sshCommand: null,
+      setupHealth: null,
+      mappedPorts: {},
+      diagnostics: diagnosticsFromInspection(inspection, plan),
+      selectedCrn: { hash: candidateCrn.hash, name: candidateCrn.name ?? "" }
+    };
+    if (!runtime?.hostIpv4 || Object.keys(runtime?.mappedPorts ?? {}).length === 0) {
+      await cleanupFailedDeployment({
+        sender: identity.address,
+        instanceItemHash: deployment.itemHash,
+        reason: `Processed deployment never exposed runtime networking${runtime?.diagnostics?.state ? ` (${runtime.diagnostics.state})` : ""}`,
+        signer: identity.signer,
+        hasher,
+        fetch: fetchImpl,
+        channel: plan.channel,
+        apiHost: plan.apiHost
+      });
+      lastError = new Error(
+        `Deployment ${deployment.itemHash} on ${candidateCrn.name ?? candidateCrn.hash} was processed but did not expose runtime networking in time.${runtime?.diagnostics?.reason ? ` ${runtime.diagnostics.reason}` : ""}`
+      );
+      continue;
+    }
+    let configuration = null;
+    let verification = null;
+    if (runtime.selectedCrn?.address) {
+      await notifyCrnAllocation({
+        crnUrl: runtime.selectedCrn.address,
+        itemHash: deployment.itemHash,
+        fetch: fetchImpl
+      }).catch(() => null);
+    }
+    if (runtime.hostIpv4 && plan.autoConfigure !== false && plan.profile === "uc-go-peer") {
+      const mappedPorts = runtime.mappedPorts ?? {};
+      const setupPort = mappedPorts["80"]?.host ?? null;
+      const tcpPort = mappedPorts["9095"]?.host ?? null;
+      const wsPort = mappedPorts["9097"]?.host ?? tcpPort;
+      const udpPort = mappedPorts["9095"]?.udp === true ? mappedPorts["9095"]?.host ?? null : null;
+      const proxyUrl = plan.enableCaddyProxy ? runtime.proxyUrl ?? null : null;
+      if (setupPort && runtime.hostIpv4) {
+        const setupHealth = await waitForSetupEndpoint({
+          hostIpv4: runtime.hostIpv4,
+          setupPort,
+          fetch: fetchImpl,
+          attempts: plan.setupAttempts,
+          delayMs: plan.setupDelayMs,
+          httpTimeoutMs: plan.httpTimeoutMs,
+          sleep: sleepImpl
+        });
+        runtimeMetadata.setupHealth = setupHealth;
+        if (!setupHealth.ok) {
+          await cleanupFailedDeployment({
+            sender: identity.address,
+            instanceItemHash: deployment.itemHash,
+            reason: "Temporary setup endpoint never became reachable",
+            signer: identity.signer,
+            hasher,
+            fetch: fetchImpl,
+            channel: plan.channel,
+            apiHost: plan.apiHost
+          });
+          lastError = new Error(`Temporary setup endpoint did not become reachable at http://${runtime.hostIpv4}:${setupPort}/health.`);
+          continue;
+        }
+        const configureResult = await configureUcGoPeer({
+          hostIpv4: runtime.hostIpv4,
+          publicIpv6: runtime.ipv6,
+          setupPort,
+          tcpPort,
+          wsPort,
+          udpPort,
+          quicPort: udpPort,
+          webrtcPort: udpPort,
+          proxyUrl,
+          fetch: fetchImpl,
+          timeoutMs: plan.configureTimeoutMs
+        });
+        const metadataResult = await fetchUcGoPeerMetadata({
+          hostIpv4: runtime.hostIpv4,
+          setupPort,
+          fetch: fetchImpl,
+          attempts: plan.metadataAttempts,
+          delayMs: plan.metadataDelayMs,
+          timeoutMs: plan.metadataTimeoutMs,
+          sleep: sleepImpl
+        });
+        configuration = {
+          ...configureResult && typeof configureResult === "object" ? configureResult : {},
+          metadata: metadataResult && typeof metadataResult === "object" ? metadataResult.metadata ?? null : null
+        };
+        if (plan.verifyReachability !== false) {
+          let latestVerification = null;
+          for (let attempt = 0; attempt < plan.verifyAttempts; attempt += 1) {
+            latestVerification = await verifyUcGoPeerReachability({
+              hostIpv4: runtime.hostIpv4,
+              mappedPorts,
+              proxyUrl,
+              verifyProxyHttp: !plan.enableCaddyProxy,
+              skipInternalPorts: plan.enableCaddyProxy ? ["80"] : ["80", "443"],
+              tcpTimeoutMs: plan.tcpTimeoutMs,
+              httpTimeoutMs: plan.httpTimeoutMs,
+              fetch: fetchImpl,
+              tcpProbe
+            });
+            if (latestVerification?.ok) {
+              break;
+            }
+            if (attempt < plan.verifyAttempts - 1) {
+              await sleepImpl(plan.verifyDelayMs);
+            }
+          }
+          verification = latestVerification;
+        }
+      }
+    }
+    verification = verification ?? mergeVerificationState({
+      inspection,
+      runtime: runtimeMetadata
+    });
+    return {
+      sender: identity.address,
+      itemHash: deployment.itemHash,
+      httpStatus: deployment.httpStatus,
+      status: inspection.status,
+      selectedCrn: { hash: candidateCrn.hash, name: candidateCrn.name ?? "" },
+      portForwarding,
+      runtime: runtimeMetadata,
+      configuration,
+      verification
+    };
+  }
+  throw lastError ?? new Error("No compatible CRN deployment attempt succeeded.");
+}
+
+// src/action-runner.ts
+import { pathToFileURL } from "url";
+function parseOptionalJson(raw) {
+  if (!raw || !raw.trim()) return null;
+  return JSON.parse(raw);
+}
+function buildScaffoldDeployResult(env = process.env) {
+  const profile = optionalEnv("ALEPH_VM_PROFILE", "uc-go-peer", env);
+  const itemHash = optionalEnv("ALEPH_VM_INSTANCE_ITEM_HASH", "", env);
+  const status = optionalEnv("ALEPH_VM_INSTANCE_STATUS", itemHash ? "processed" : "unknown", env);
+  return {
+    sender: optionalEnv("ALEPH_VM_DEPLOYER_ADDRESS", "", env),
+    itemHash,
+    status,
+    portForwarding: {
+      aggregateItemHash: optionalEnv("ALEPH_VM_PORT_FORWARD_AGGREGATE_ITEM_HASH", "", env),
+      aggregateStatus: optionalEnv("ALEPH_VM_PORT_FORWARD_STATUS", "", env)
+    },
+    runtime: {
+      allocation: {
+        source: "manual",
+        crnUrl: optionalEnv("ALEPH_VM_CRN_URL", "", env)
+      },
+      hostIpv4: optionalEnv("ALEPH_VM_HOST_IPV4", "", env),
+      ipv6: optionalEnv("ALEPH_VM_IPV6", "", env),
+      proxyUrl: optionalEnv("ALEPH_VM_WEB_PROXY_URL", "", env),
+      sshCommand: optionalEnv("ALEPH_VM_SSH_COMMAND", "", env),
+      setupHealth: {
+        ok: optionalEnv("ALEPH_VM_SETUP_ENDPOINT_OK", "", env) === "true"
+      },
+      mappedPorts: parseOptionalJson(env.ALEPH_VM_MAPPED_PORTS_JSON) ?? {},
+      diagnostics: {
+        state: "scaffold",
+        timedOut: false,
+        reason: `Shared action runner scaffold for profile ${profile}`
+      },
+      selectedCrn: {
+        hash: optionalEnv("ALEPH_VM_CRN_HASH", "", env),
+        name: optionalEnv("ALEPH_VM_CRN_NAME", "", env)
+      }
+    },
+    configuration: {
+      metadata: {
+        peer_id: optionalEnv("ALEPH_VM_RELAY_PEER_ID", "", env),
+        probe_multiaddrs: parseOptionalJson(env.ALEPH_VM_PROBE_MULTIADDRS_JSON) ?? [],
+        browser_bootstrap_multiaddrs: parseOptionalJson(env.ALEPH_VM_BROWSER_BOOTSTRAP_MULTIADDRS_JSON) ?? []
+      }
+    },
+    verification: parseOptionalJson(env.ALEPH_VM_VERIFICATION_JSON) ?? {
+      ok: false,
+      state: "scaffold"
+    }
+  };
+}
+async function runActionMode(env = process.env, hooks = {}) {
+  const mode = optionalEnv("ALEPH_VM_MODE", "deploy", env);
+  const stdout = hooks.stdout ?? ((text) => process.stdout.write(text));
+  if (mode === "list-crns") {
+    if (!parseOptionalJson(env.ALEPH_VM_GEOCRN_PAYLOAD_JSON) && typeof globalThis.fetch !== "function") {
+      throw new Error("A fetch implementation is required for list-crns mode when no CRN payload is pre-supplied.");
+    }
+    const payload = parseOptionalJson(env.ALEPH_VM_GEOCRN_PAYLOAD_JSON) ?? await (hooks.listGeocodedCrns ?? listGeocodedCrns)({
+      url: optionalEnv("ALEPH_VM_CRN_LIST_URL", void 0, env) || void 0,
+      limit: Number(optionalEnv("ALEPH_VM_GEO_CRN_LIMIT", "30", env)),
+      fetch: globalThis.fetch.bind(globalThis)
+    });
+    await emitGeocodedCrnOutputs(payload, env);
+    stdout(`${JSON.stringify(payload)}
+`);
+    return;
+  }
+  if (mode === "retain-successful-deployments") {
+    if (typeof globalThis.fetch !== "function") {
+      throw new Error("A fetch implementation is required for retain-successful-deployments mode.");
+    }
+    const identity = await (hooks.createPrivateKeyIdentity ?? createPrivateKeyIdentity)(
+      requiredEnv("ALEPH_VM_PRIVATE_KEY", env)
+    );
+    const payload = await (hooks.retainSuccessfulDeployments ?? retainSuccessfulDeployments)({
+      sender: identity.address,
+      currentRecord: jsonEnv("ALEPH_VM_RETENTION_CURRENT_RECORD_JSON", "{}", env),
+      keepCount: integerEnv("ALEPH_VM_RETENTION_KEEP_COUNT", 2, env),
+      extraForgetHashes: jsonEnv("ALEPH_VM_RETENTION_EXTRA_FORGET_HASHES_JSON", "[]", env),
+      signer: identity.signer,
+      hasher: async (content) => {
+        const { createHash: createHash2 } = await import("crypto");
+        return createHash2("sha256").update(content).digest("hex");
+      },
+      fetch: globalThis.fetch.bind(globalThis),
+      channel: optionalEnv("ALEPH_VM_CHANNEL", "TEST", env),
+      apiHost: optionalEnv("ALEPH_VM_API_HOST", "https://api2.aleph.im", env)
+    });
+    await appendGithubOutput("retention_result_json", JSON.stringify(payload), env);
+    await appendGithubOutput("retention_forget_hashes_json", JSON.stringify(payload.forgetHashes ?? []), env);
+    await appendGithubOutput("retention_pruned_count", payload.prunedRecords?.length ?? 0, env);
+    await appendGithubOutput("retention_retained_count", payload.retainedRecords?.length ?? 0, env);
+    await appendGithubSummary([
+      "## Successful deployment retention",
+      "",
+      `- Keep count: \`${payload.keepCount}\``,
+      `- Retained deployments: \`${payload.retainedRecords?.length ?? 0}\``,
+      `- Pruned deployments: \`${payload.prunedRecords?.length ?? 0}\``,
+      `- Forgotten hashes: \`${(payload.forgetHashes ?? []).length}\``
+    ], env);
+    stdout(`${JSON.stringify(payload)}
+`);
+    return;
+  }
+  if (mode !== "deploy") {
+    throw new Error(`Unsupported ALEPH_VM_MODE "${mode}" in shared action runner.`);
+  }
+  const providedDeployResult = parseOptionalJson(env.ALEPH_VM_DEPLOY_RESULT_JSON);
+  let deployResult = providedDeployResult;
+  if (!deployResult) {
+    try {
+      deployResult = await (hooks.deployExecutor ?? executeDeployPlan)(parseDeployPlan(env));
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("Missing required environment variable")) {
+        deployResult = buildScaffoldDeployResult(env);
+      } else {
+        throw error;
+      }
+    }
+  }
+  if (!deployResult) {
+    throw new Error("Shared action runner did not produce a deploy result.");
+  }
+  await emitDeployOutputs(deployResult, env);
+  await appendGithubOutput("action_runner_mode", mode, env);
+  await appendGithubOutput("action_runner_profile", optionalEnv("ALEPH_VM_PROFILE", "uc-go-peer", env), env);
+  await appendGithubSummary([
+    "",
+    "### Shared Action Runner",
+    "",
+    `- Mode: \`${mode}\``,
+    `- Profile: \`${optionalEnv("ALEPH_VM_PROFILE", "uc-go-peer", env)}\``
+  ], env);
+  actionLog("notice", `Shared action runner executed in ${mode} mode for profile ${optionalEnv("ALEPH_VM_PROFILE", "uc-go-peer", env)}.`);
+  stdout(`${JSON.stringify(deployResult)}
+`);
+}
+async function main() {
+  await runActionMode(process.env);
+}
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    actionLog("error", message);
+    process.exitCode = 1;
+  });
+}
+export {
+  actionLog,
+  appendGithubOutput,
+  appendGithubSummary,
+  booleanEnv,
+  buildScaffoldDeployResult,
+  createPrivateKeyIdentity,
+  createPrivateKeySigner,
+  emitDeployOutputs,
+  emitGeocodedCrnOutputs,
+  executeDeployPlan,
+  integerEnv,
+  jsonEnv,
+  main,
+  optionalEnv,
+  parseDeployPlan,
+  requiredEnv,
+  runActionMode
+};