@hypit/hypit 0.1.3 → 0.1.5

package/packages/cli/src/output.ts

@@ -43,6 +43,8 @@ export type DoctorOutput = {
   readonly ok: boolean;
   readonly project: string;
   readonly profile?: string;
+  readonly profileSource?: "argument" | "project" | "none";
+  readonly selectionFile?: string;
   readonly diagnosticCount: number;
   readonly diagnostics: readonly CliDiagnostic[];
   readonly omittedDiagnostics?: number;
@@ -58,7 +60,7 @@ export type AuthorCheckOutput = {
   readonly assets: number;
   readonly modules: number;
   readonly outputCount: number;
-  readonly outputs: readonly {
+  readonly outputs?: readonly {
     readonly name: string;
     readonly type: string;
   }[];
@@ -80,6 +82,7 @@ export type RunCheckOutput = {
   readonly targets: readonly string[];
   readonly candidates: number;
   readonly satisfactions: number;
+  readonly historicalOutputCount?: number;
   readonly steps?: number;
   readonly unresolvedHistoricalOutputs?: readonly {
     readonly candidate: string;
@@ -92,7 +95,7 @@ export type RunCheckOutput = {
 export type PlanPreflight = {
   readonly ok: boolean;
   readonly capabilityCount: number;
-  readonly capabilities: readonly string[];
+  readonly capabilities?: readonly string[];
   readonly omittedCapabilities?: number;
   readonly diagnosticCount: number;
   readonly diagnostics: readonly CliDiagnostic[];
@@ -117,7 +120,7 @@ export type PlanOutput = {
   readonly run: string;
   readonly targetCount: number;
   readonly targets: readonly string[];
-  readonly steps: number;
+  readonly steps?: number;
   readonly requestCount: number;
   readonly requestIssueCount: number;
   /** Present when a Runtime Profile was selected. */
@@ -126,19 +129,45 @@ export type PlanOutput = {
   readonly unresolvedRequestCount?: number;
   readonly unsupportedRequestCount?: number;
   readonly choiceCount: number;
-  readonly choices: readonly { readonly output: string; readonly candidate: string }[];
+  readonly choices?: readonly { readonly output: string; readonly candidate: string }[];
   readonly omittedChoices?: number;
   readonly unreached?: readonly { readonly output: string; readonly operation: string }[];
   readonly omittedUnreached?: number;
   /** Present only when a Runtime Profile was selected; the Endpoint and price page behind each capability. */
   readonly providers?: readonly PlanProvider[];
-  readonly omittedProviders?: number;
   /** Every external request the Build will make, in step order, with its parameters when known. */
   readonly needs?: readonly PlanNeed[];
-  readonly omittedNeeds?: number;
   readonly preflight?: PlanPreflight;
 };
 
+/** Output scope is independent of encoding. Limits apply to expanded detail, not demanded work. */
+export function createPlanOutput(plan: PlanOutput, options: { readonly verbose: boolean; readonly limit: number }): PlanOutput {
+  const { steps, choices = [], unreached = [], preflight, ...summary } = plan;
+  const limit = options.limit;
+  return {
+    ...summary,
+    ...(options.verbose ? {
+      steps,
+      choices: choices.slice(0, limit),
+      ...(choices.length <= limit ? {} : { omittedChoices: choices.length - limit }),
+      unreached: unreached.slice(0, limit),
+      ...(unreached.length <= limit ? {} : { omittedUnreached: unreached.length - limit }),
+    } : {}),
+    ...(preflight === undefined ? {} : { preflight: {
+      ok: preflight.ok,
+      capabilityCount: preflight.capabilityCount,
+      diagnosticCount: preflight.diagnosticCount,
+      diagnostics: preflight.diagnostics,
+      ...(options.verbose ? {
+        capabilities: preflight.capabilities?.slice(0, limit) ?? [],
+        ...((preflight.capabilities?.length ?? 0) <= limit ? {} : {
+          omittedCapabilities: preflight.capabilities!.length - limit,
+        }),
+      } : {}),
+    } }),
+  };
+}
+
 export type PricingEntry = PlanProvider & {
   readonly pricingDocuments?: readonly PricingDocument[];
   readonly pricingError?: string;
@@ -272,9 +301,16 @@ function renderDoctor(view: Extract<CliPresentation, { kind: "doctor" }>, io: Cl
   const lines = [colors.accent(colors.strong("Hypit Doctor")), ""];
   lines.push(...facts([
     ["Project", shortPath(view.machine.project)],
-    ...(view.machine.profile === undefined ? [] : [["Profile", shortPath(view.machine.profile)] as const]),
+    ["Runtime Profile", view.machine.profile === undefined ? "not selected" : shortPath(view.machine.profile)],
+    ...(view.machine.profileSource === "argument"
+      ? [["Runtime selection", "command argument (this invocation only)"] as const]
+      : view.machine.selectionFile === undefined ? [] : [["Runtime selection", shortPath(view.machine.selectionFile)] as const]),
+    ["Scope", view.machine.profile === undefined ? "project Results only" : "selected Runtime and project Results"],
   ], colors));
   lines.push("");
+  if (view.machine.profile === undefined) {
+    lines.push("Select an existing Profile with hypit runtime use <profile>, or pass --runtime <profile> to check it.", "");
+  }
   if (view.machine.diagnostics.length === 0) {
     lines.push(heading("success", "No problems found", io, colors));
   } else {
@@ -301,7 +337,7 @@ function renderAuthorCheck(
   verbose: boolean,
 ): string {
   const lines = [heading("success", "Source is valid", io, colors), ""];
-  const readable = view.machine.outputs;
+  const readable = view.machine.outputs ?? [];
   lines.push(...facts([
     ["Source", shortPath(view.machine.source)],
     ["Outputs", String(view.machine.outputCount)],
@@ -341,8 +377,7 @@ function renderRunCheck(
   verbose: boolean,
 ): string {
   const lines = [heading("success", "Run source is valid", io, colors), ""];
-  const reuse = (view.machine.unresolvedHistoricalOutputs?.length ?? 0)
-    + (view.machine.omittedHistoricalOutputs ?? 0);
+  const reuse = view.machine.historicalOutputCount ?? 0;
   const targetSummary = view.machine.targets.length === 0
     ? String(view.machine.targetCount)
     : view.machine.targets.join(", ")
@@ -424,7 +459,7 @@ function needSummaryText(needs: readonly PlanNeed[]): string {
   const pendingCount = first.pending.length;
   if (pendingCount > 0) parts.push(`${pendingCount === 1 ? "input" : `${pendingCount} inputs`} produced during Build`);
   if (first.issue !== undefined) parts.push(`could not inspect: ${first.issue}`);
-  return parts.length === 0 ? "no parameters" : parts.join(" · ");
+  return parts.length === 0 ? "request summary unavailable" : parts.join(" · ");
 }
 
 /** One line per distinct request shape, counted; the step names when only one request has that shape. */
@@ -480,6 +515,7 @@ function renderPlan(
     ["Run", shortPath(view.machine.run)],
     ["Targets", targetSummary],
     ["Requests", String(view.machine.requestCount)],
+    ...(view.machine.choiceCount === 0 ? [] : [["Run choices", String(view.machine.choiceCount)] as const]),
     ...(view.machine.requestIssueCount === 0 ? [] : [["Request issues", String(view.machine.requestIssueCount)] as const]),
     ...((view.machine.providerRequestCount ?? 0) === 0 ? [] : [["Provider requests", String(view.machine.providerRequestCount)] as const]),
     ...((view.machine.localRequestCount ?? 0) === 0 ? [] : [["Local requests", String(view.machine.localRequestCount)] as const]),
@@ -488,7 +524,7 @@ function renderPlan(
     ...(view.machine.preflight === undefined ? [] : [[
       "Preflight", view.machine.preflight.ok ? "ready" : "needs attention",
     ] as const]),
-    ...(verbose ? [["Steps", String(view.machine.steps)] as const] : []),
+    ...(!verbose || view.machine.steps === undefined ? [] : [["Steps", String(view.machine.steps)] as const]),
   ], colors));
   if (view.machine.providers !== undefined) {
     if (view.machine.providers.length > 0) lines.push("", colors.strong("Providers and price pages"));
@@ -522,9 +558,6 @@ function renderPlan(
       const requests = new Set(group.map((provider) => provider.request));
       lines.push(...groupedNeedLines((view.machine.needs ?? []).filter((need) => requests.has(need.request)), colors, verbose));
     }
-    if ((view.machine.omittedProviders ?? 0) > 0) {
-      lines.push(`  ${colors.dim(`${view.machine.omittedProviders} more requests · use --limit <count>`)}`);
-    }
   } else if (view.machine.requestCount > 0) {
     const byCapability = new Map<string, PlanNeed[]>();
     for (const need of view.machine.needs ?? []) {
@@ -550,9 +583,9 @@ function renderPlan(
   }
   if (view.machine.preflight !== undefined
     && (view.machine.preflight.diagnostics.length > 0
-      || (verbose && view.machine.preflight.capabilities.length > 0))) {
+      || (verbose && (view.machine.preflight.capabilities?.length ?? 0) > 0))) {
     lines.push("", colors.strong("Runtime preflight"));
-    if (verbose) for (const capability of view.machine.preflight.capabilities) lines.push(`  ${colors.accent(capability)}`);
+    if (verbose) for (const capability of view.machine.preflight.capabilities ?? []) lines.push(`  ${colors.accent(capability)}`);
     if (verbose && (view.machine.preflight.omittedCapabilities ?? 0) > 0) {
       lines.push(`  ${colors.dim(`${view.machine.preflight.omittedCapabilities} more capabilities · use --limit <count>`)}`);
     }
@@ -569,9 +602,9 @@ function renderPlan(
       lines.push(`  ${colors.dim(`${capabilityCount} demanded Endpoint ${capabilityCount === 1 ? "capability" : "capabilities"} checked.`)}`);
     }
   }
-  if (view.machine.choices.length > 0) {
+  if (verbose && (view.machine.choices?.length ?? 0) > 0) {
     lines.push("", colors.strong("Run choices"));
-    for (const selection of view.machine.choices) {
+    for (const selection of view.machine.choices ?? []) {
       const status = colors.success(glyph(io, "✓", "+"));
       lines.push(`  ${status} ${colors.accent(selection.output)} ← ${selection.candidate}`);
     }
@@ -765,22 +798,27 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
       colors.dim("Validate one self-described Author Source or Run Source without executing it."),
       "",
       "  hypit check <source> [--workspace <workspace>] [--asset-root <directory>]",
+      "  --verbose lists exported names/types and historical references.",
     ],
     doctor: [
       colors.accent(colors.strong("hypit doctor")),
       colors.dim("Diagnose project Results and, when selected or supplied, one Runtime Profile."),
       "",
-      "  hypit doctor [<runtime-profile>] [--workspace <project>]",
+      "  hypit doctor [--runtime <profile>] [--workspace <project>] [--endpoint <instance>]",
+      "  A positional Profile is also accepted in place of --runtime.",
+      "  Repeat --endpoint <instance> to limit the operation to chosen services; omission covers the Profile.",
       "  Without a Runtime Profile, checks only the project's selected Result Store.",
     ],
     plan: [
       colors.accent(colors.strong("hypit plan")),
-      colors.dim("Freeze the demanded subgraph and expose explicit Run choices and every external Need."),
+      colors.dim("Show targets, demanded requests and their readiness without executing them."),
       "",
       "  hypit plan <run-source> [--runtime <profile>] [--workspace <workspace>] [--asset-root <directory>]",
       "",
       "With --runtime, plan also preflights only the demanded deployment slice and names the Provider",
       "and price page behind each external request.",
+      "--verbose expands Run choices and unreached declarations. --limit bounds that detail,",
+      "while all demanded requests and diagnostics remain visible in both text and JSON.",
       "Planning never starts external work.",
     ],
     pricing: [
@@ -813,12 +851,14 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
       "  hypit runtime init [<profile>] [--workspace <project>] create and select a starter Profile",
       "  hypit runtime use <profile> [--workspace <project>]  select the project Profile",
       "  hypit runtime unset [--workspace <project>]          remove only that selection",
-      "  hypit runtime up [<profile>]      prepare local packages and programs, then start the Worker",
+      "  hypit runtime up [<profile>] [--endpoint <instance>]  prepare helpers, then start the Worker",
       "  hypit runtime status [<profile>]  inspect the local Worker, active Builds and programs",
       "  hypit runtime logs [<profile>] [--lines <count>]",
       "  hypit runtime down [<profile>]    stop the Worker; external programs keep running",
       "",
       "The project is resolved first. Selection is read only from that project's .hypit/runtime.",
+      "All runtime actions accept --workspace <project>; operational actions also accept --runtime <profile>.",
+      "For up, repeat --endpoint <instance> to prepare only chosen services; omission prepares the Profile.",
       "No Profile filename discovery or parent-project inheritance is performed.",
       "Remote Endpoints such as HypiHub are not started by this command; use doctor to test them.",
     ],
@@ -830,28 +870,34 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
       "  hypit packages install <package@exact-version>",
       "",
       "The package is reused by every project and later session on this machine.",
-      "npm owns the ordinary package.json; Hypit creates no package lock or receipt.",
+      "Each exact version has its own installation; npm owns package.json and package-lock.json.",
+      "Preparation reports its install.log for live output and later diagnosis.",
     ],
     programs: [
       colors.accent(colors.strong("hypit programs")),
       colors.dim("Prepare and operate external programs declared by Endpoints in one Runtime Profile."),
       "",
-      "  hypit programs up [<profile>] [--max-wait-ms <ms>]",
-      "  hypit programs status [<profile>]",
-      "  hypit programs down [<profile>]",
+      "  hypit programs up [--runtime <profile>] [--workspace <project>] [--max-wait-ms <ms>]",
+      "  hypit programs status [--runtime <profile>] [--workspace <project>]",
+      "  hypit programs down [--runtime <profile>] [--workspace <project>]",
+      "  A positional Profile is also accepted in place of --runtime.",
+      "  Repeat --endpoint <instance> to limit the operation to chosen services; omission covers the Profile.",
     ],
     activity: [
       colors.accent(colors.strong("hypit activity")),
       colors.dim("Inspect active Builds and Provider pool capacity."),
       "",
-      "  hypit activity [--runtime <profile>] [--watch]",
-      "  hypit activity [--runtime <profile>] --watch --jsonl",
+      "  hypit activity [--workspace <project>] [--runtime <profile>] [--watch]",
+      "  hypit activity [--workspace <project>] [--runtime <profile>] --watch --jsonl",
     ],
     paths: [
       colors.accent(colors.strong("hypit paths")),
       colors.dim("Show project, Runtime and host state locations without creating them."),
       "",
-      "  hypit paths [--runtime <profile>]",
+      "  hypit paths [--workspace <project>] [--runtime <profile>]",
+      "  Shows whether Runtime selection comes from a command argument or the project's .hypit/runtime.",
+      "  Without --workspace, the nearest package.json above cwd defines the project (otherwise cwd).",
+      "  Relative command-line paths start at cwd, including when --workspace is supplied.",
     ],
     builds: [
       colors.accent(colors.strong("hypit builds")),
@@ -859,11 +905,19 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
       "",
       "  hypit builds [--workspace <project>] [--limit <count>] [--before <build-id>]",
     ],
+    logs: [
+      colors.accent(colors.strong("hypit logs")),
+      colors.dim("Read Build execution evidence; finished logs need only the project Result Repository."),
+      "",
+      "  hypit logs <build-id> [--workspace <project>] [--runtime <profile>] [--lines <count>]",
+      "  --lines <count>           show the last N records (default 50)",
+      "  runtime logs             reads the Worker process log instead",
+    ],
     status: [
       colors.accent(colors.strong("hypit status")),
       colors.dim("Show one Build now, or keep watching it without owning execution."),
       "",
-      "  hypit status <build-id> [--runtime <profile>] [--watch]",
+      "  hypit status <build-id> [--workspace <project>] [--runtime <profile>] [--watch]",
       "  --watch                   observe until a Result outcome or operator attention",
       "  --max-wait-ms <ms>        stop watching after a bounded wait",
     ],
@@ -872,6 +926,8 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
       colors.dim("Inspect one project-owned Build Result and its public Outputs."),
       "",
       "  hypit inspect <build-id> [--output <name>] [--limit <count>] [--workspace <project>]",
+      "  Defaults to targets and highlighted Outputs. --verbose expands other available Outputs.",
+      "  --output selects one exact name; --limit bounds expanded lists.",
     ],
     get: [
       colors.accent(colors.strong("hypit get")),
@@ -892,14 +948,14 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
       colors.accent(colors.strong("hypit cancel")),
       colors.dim("Stop one Build and request cancellation of submitted work when supported."),
       "",
-      "  hypit cancel <build-id> [--runtime <profile>] [--reason <text>]",
+      "  hypit cancel <build-id> [--workspace <project>] [--runtime <profile>] [--reason <text>]",
     ],
     result: [
       colors.accent(colors.strong("hypit result")),
       colors.dim("Edit one Result, finish an interrupted Result write, or discard an incomplete submission."),
       "",
-      "  hypit result finish <build-id> [--runtime <profile>]",
-      "  hypit result discard <build-id> [--runtime <profile>]",
+      "  hypit result finish <build-id> [--workspace <project>] [--runtime <profile>]",
+      "  hypit result discard <build-id> [--workspace <project>] [--runtime <profile>]",
       "  hypit result edit <build-id> [--workspace <project>] [--title <text>] [--note <text>]",
       "                           [--highlight <output> ...]",
       "  --clear-title            remove the Result's human title",
@@ -913,6 +969,7 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
       "  hypit auth status <endpoint-instance> [--runtime <profile>] [--slot <name>]",
       "  hypit auth login <endpoint-instance> [--runtime <profile>] [--slot <name>] [--from <secret-file>]",
       "  hypit auth logout <endpoint-instance> [--runtime <profile>] [--slot <name>]",
+      "  All auth actions accept --workspace <project> to use that project's selection.",
     ],
   };
   const selected = topics[topic];
@@ -942,6 +999,7 @@ export function writeCliHelp(io: CliIo, topic?: string): void {
     colors.strong("Results"),
     row("builds", "list Results newest first"),
     row("history <output>", "find one named Output across Builds"),
+    row("logs <build-id> [--lines <count>]", "read saved Build execution phases and diagnostics"),
     row("status <build-id> [--watch]", "show current work and Result facts"),
     row("inspect <build-id>", "inspect one Result"),
     row("get <build-id> --output <name> --to <path>", "export one Build Output"),
@@ -953,7 +1011,7 @@ export function writeCliHelp(io: CliIo, topic?: string): void {
     row("runtime up|status|logs|down", "prepare and manage the local Build Runtime"),
     row("programs up|status|down", "manage declared external programs only"),
     row("packages install|status", "manage pinned upstream packages in the machine home"),
-    row("activity [--watch]", "inspect active Builds and shared capacity"),
+    row("activity [--watch]", "show active Builds and their current phases"),
     row("cancel <build-id>", "withdraw one active Build"),
     row("paths", "show physical state locations"),
     row("auth status|login|logout", "manage Endpoint credentials"),

package/packages/cli/src/result-export.ts

@@ -1,3 +1,4 @@
+import { fileReferenceIdentity } from "@hypit/build-result";
 import { randomUUID } from "node:crypto";
 import { lstat, mkdir, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
@@ -53,7 +54,7 @@ async function openResultFile(
   file: BuildResultFileRef,
 ): Promise<AsyncIterable<Uint8Array>> {
   const input = await repository.openFile(build, file);
-  if (input === undefined) throw new Error(`Build ${build} file ${file.path} is unavailable`);
+  if (input === undefined) throw new Error(`File ${fileReferenceIdentity(build, file)} is unavailable`);
   return input;
 }
 
@@ -83,20 +84,28 @@ async function exportComposite(
   const temporary = join(dirname(target), `.${basename(target)}.part-${randomUUID()}`);
   try {
     await mkdir(temporary);
-    const copied = new Set<string>();
+    const copied = new Map<string, BuildResultFileRef>();
+    const paths = new Set<string>();
+    const bindings = [];
     for (const binding of resolvedOutput.value.document.resources) {
-      const file = binding.file;
-      if (copied.has(file.path)) continue;
-      copied.add(file.path);
-      assert(file.path !== "value.json", "Composite Result file value.json conflicts with its exported value document");
-      await writeStream(
-        containedPath(temporary, file.path),
-        await openResultFile(repository, resolvedOutput.build, file),
-      );
+      const file = await repository.describeFile(resolvedOutput.build, binding.file);
+      const identity = fileReferenceIdentity(resolvedOutput.build, file);
+      let local = copied.get(identity);
+      if (local === undefined) {
+        let path = file.kind === "build-file" ? file.path : `files/file-${copied.size + 1}`;
+        const name = basename(path);
+        let index = copied.size + 1;
+        while (paths.has(path) || path === "value.json") path = `files/import-${index++}/${name}`;
+        paths.add(path);
+        local = { kind: "build-file", path, size: file.size, mediaType: file.mediaType };
+        copied.set(identity, local);
+        await writeStream(containedPath(temporary, path), await openResultFile(repository, resolvedOutput.build, file));
+      }
+      bindings.push({ at: binding.at, file: local });
     }
     await writeFile(
       join(temporary, "value.json"),
-      `${JSON.stringify(resolvedOutput.value.document, null, 2)}\n`,
+      `${JSON.stringify({ ...resolvedOutput.value.document, resources: bindings }, null, 2)}\n`,
       { flag: "wx" },
     );
     await rename(temporary, target);
@@ -122,7 +131,7 @@ export async function exportBuildResultOutput(
   const target = resolve(destination);
   if (resolvedOutput.value.kind === "value") {
     await exportComposite(repository, { ...resolvedOutput, value: resolvedOutput.value }, target);
-  } else if (resolvedOutput.value.kind === "build-file") {
+  } else if ((resolvedOutput.value.kind === "build-file" || resolvedOutput.value.kind === "external-file")) {
     const resource = resolvedOutput.value;
     await exportFile(target, async (temporary) => {
       await writeStream(
@@ -142,7 +151,7 @@ export async function exportBuildResultOutput(
     type: publishedOutput.type,
     kind: resolvedOutput.value.kind === "inline"
       ? "scalar"
-      : resolvedOutput.value.kind === "build-file" ? "resource" : "composite",
+      : (resolvedOutput.value.kind === "build-file" || resolvedOutput.value.kind === "external-file") ? "resource" : "composite",
     path: target,
   };
 }

package/packages/cli/src/run-file.ts

@@ -1,3 +1,4 @@
+import { fileReferenceIdentity, ownedFileReference } from "@hypit/build-result";
 import { randomUUID } from "node:crypto";
 import type {
   BuildResultRepository,
@@ -24,15 +25,17 @@ import type { RunFrontend } from "@hypit/run";
 export type LoadedRunFile = NodeCompiledRun & {
   readonly path: string;
   readonly compiler: NodeRunCompiler;
+  readonly resultResourceReferences: Readonly<Record<string, BuildResultFileRef>>;
 };
 
 type BuildResultResolutionSession = {
   readonly files: Map<string, ArtifactAttachment>;
+  readonly references: Map<string, BuildResultFileRef>;
   readonly outputs: Map<string, Promise<RepositoryBuildResultOutput | undefined>>;
 };
 
 function createBuildResultResolutionSession(): BuildResultResolutionSession {
-  return { files: new Map(), outputs: new Map() };
+  return { files: new Map(), outputs: new Map(), references: new Map() };
 }
 
 export async function checkRunFile(options: {
@@ -88,9 +91,10 @@ export async function resolveBuildResultValue(
   const manifest = await repository.read(build);
   if (manifest?.outcome === undefined) return undefined;
   const resultAttachment = async (owner: string, file: BuildResultFileRef): Promise<ArtifactAttachment> => {
-    const address = `${owner}\u0000${file.path}`;
+    const address = fileReferenceIdentity(owner, file);
     const existing = session.files.get(address);
     if (existing !== undefined) return existing;
+    file = await repository.describeFile(owner, file);
     const artifact: BlobRef = {
       kind: "blob",
       resource: `res_${randomUUID()}`,
@@ -101,11 +105,12 @@ export async function resolveBuildResultValue(
       artifact,
       async open() {
         const stream = await repository.openFile(owner, file);
-        if (stream === undefined) throw new Error(`Build ${owner} file ${file.path} is unavailable`);
+        if (stream === undefined) throw new Error(`File ${address} is unavailable`);
         return stream;
       },
     };
     session.files.set(address, attachment);
+    session.references.set(artifact.resource, ownedFileReference(owner, file));
     return attachment;
   };
   const attachments = new Map<string, ArtifactAttachment>();
@@ -120,7 +125,7 @@ export async function resolveBuildResultValue(
   const owner = resolved.build === build ? manifest : await repository.read(resolved.build);
   if (owner?.outcome === undefined) return undefined;
   let value: StoredValue;
-  if (resolved.value.kind === "build-file") {
+  if (resolved.value.kind === "build-file" || resolved.value.kind === "external-file") {
     const attachment = await resultAttachment(resolved.build, resolved.value);
     attachments.set(attachment.artifact.resource, attachment);
     value = attachment.artifact;
@@ -147,8 +152,7 @@ function createRunCompiler(options: {
   readonly frontends: readonly RunFrontend[];
   readonly packageContributions: readonly NodePackageContribution[];
   readonly results?: BuildResultRepository;
-}): NodeRunCompiler {
-  const resultSession = createBuildResultResolutionSession();
+}, resultSession = createBuildResultResolutionSession()): NodeRunCompiler {
   const fragments = new RunFragmentRegistry();
   for (const item of options.packageContributions) {
     installRunFragmentHostFacets(item.hostFacets ?? [], fragments);
@@ -180,7 +184,14 @@ export async function loadRunFile(options: {
   readonly packageContributions: readonly NodePackageContribution[];
   readonly results?: BuildResultRepository;
 }): Promise<LoadedRunFile> {
-  const compiler = createRunCompiler(options);
+  const resultSession = createBuildResultResolutionSession();
+  const compiler = createRunCompiler(options, resultSession);
   const compiled = await compiler.compileSource(options.workspace.entry, options.workspace);
-  return { path: options.workspace.entry.id, compiler, ...compiled };
+  const references = new Map<string, BuildResultFileRef>(compiled.attachments.flatMap((attachment) =>
+    attachment.location === undefined ? [] : [[attachment.artifact.resource, {
+      kind: "external-file" as const, uri: attachment.location,
+      size: attachment.artifact.size, mediaType: attachment.artifact.mediaType,
+    }]]));
+  for (const [resource, file] of resultSession.references) references.set(resource, file);
+  return { path: options.workspace.entry.id, compiler, ...compiled, resultResourceReferences: Object.fromEntries(references) };
 }