Proposal: a Host shared by frameworks built on bedrock

[Zaba505]

Summary

Add a nested module, github.com/z5labs/bedrock/host, that holds the type a framework built on bedrock uses to hand an App the network and the filesystem. The module has three parts:

• host.Host[F], with Listen, Dial and a filesystem F that each framework declares;
• host.OSFS, the real machine's filesystem, a struct with a method for every file function of package os, and host.OS(), the real machine's Host;
• hosttest, an in-memory network and a filesystem confined to the test's temp directory, which runs inside a testing/synctest bubble.

bedrock defines the type and never passes one. bedrock.Process and App.Run don't change, and bedrock.Main doesn't build a Host. A framework passes the Host in, as humus does today through Setup.Host.

The code already exists. It is humus's Host from z5labs/humus#630 and humustest's in-memory Host from z5labs/humus#633, moved here. What changes is the filesystem, designed with a second framework in mind (a command-line framework built on bedrock). bedrock fixes what each filesystem method means and ships the implementations, and each framework chooses the methods its users see. A few names change too.

Background

bedrock's package doc leaves the host to the framework, in Beyond the boundary:

bedrock owns only what exec hands a process. The network, the filesystem, the clock and randomness belong to the App or to the framework built on bedrock, which passes them in explicitly.

humus filled that gap:

• humus.Host holds Listen, Dial and an FS that hands out *os.File. The design was settled in the lifecycle review and its revision. It imports only context, io/fs, net and os.
• humustest.Host is a network of net.Pipe connections that starts no goroutines, and a real filesystem in t.TempDir() confined with os.Root (Proposal: humustest — whole-service testing on top of bedrocktest humus#633). Its host.go, network.go and fs.go import only the standard library, plus humus for the two types.

Neither file has anything to do with services. They are the second boundary, the one bedrock leaves open, and every framework on bedrock needs one.

A second framework is coming. A command-line framework on bedrock is planned as a project of its own. humus's conventions are a service's (logs on stdout, a grace period sized for Kubernetes, exit codes 0, 1 and 78), and a CLI needs different answers to the same questions. CLIs also touch files and the network more than services do, and their tests need the same hermetic host. Today the CLI framework could only do one of two things, and both are bad:

• Import humus. The root package is the only home of humus.Host, and importing it links in the OpenTelemetry SDK, every OTLP exporter and grpc-go: go list -deps lists 126 gRPC and OTLP packages. It would also tie the CLI framework's design and releases to humus's.
• Copy it. The type and OSHost are about 150 lines. The test host is about 760 more (host.go, network.go and fs.go), with about 1,400 lines of tests. Two copies would drift apart, and what drifts is the contract: what a relative name resolves against, which error a missing file returns, when a test's network refuses a dial. A team's shared code, such as a helper that loads its TLS bundle or a client constructor that dials, would then behave one way under humus and another under the CLI framework, and only one of the two test hosts would match the machine it stands in for.

bedrock already carries a piece of the same thing. example/httpserver takes Listen as a field, and its test builds a 60-line in-memory pipeListener.

The precedent is fit, circuit and retry (#578, #595, #606). Each is something frameworks share, kept in a nested module so the root module stays exactly the process model. In #595's words, bedrock ships the model and the framework ships the wiring. For the Host, bedrock ships the contract and its implementations, and each framework chooses how much of them its users see. bedrock standardizes; humus and the CLI framework are the opinionated layers that decide what to enforce.

Proposed API

package host // github.com/z5labs/bedrock/host

// FS constrains the filesystem of a Host. Its one method is unexported, so
// FS is implemented only in this module, by OSFS and by hosttest's FS, and
// a type elsewhere satisfies it by embedding one of them. A framework
// declares the filesystem its users see as an interface that embeds FS
// and lists the methods it needs.
type FS interface {
	fs()
}

// Host is the network and the filesystem that a framework hands an App
// beyond its process. F is the filesystem the framework exposes. Every
// field is required.
type Host[F FS] struct {
	// Listen announces on the local network address, like net.Listen.
	Listen func(network, address string) (net.Listener, error)

	// Dial connects to the address on the named network, like
	// (*net.Dialer).DialContext.
	Dial func(ctx context.Context, network, address string) (net.Conn, error)

	// FS is the Host's filesystem.
	FS F
}

// OSFS is the filesystem of the real machine. It has no fields, and its
// zero value is ready to use:
//
//	var fsys host.OSFS
//
// It has one method for every function of package os that names a file,
// except those that read or change process-wide state, and each method is
// the os function of the same name. CreateTemp and MkdirTemp with
// dir == "" use os.TempDir.
//
// Names are OS paths, and a relative name is relative to Getwd. Files are
// *os.File, so a file opened through OSFS can be handed to anything that
// takes an OS file or a path. OSFS gains a method when package os gains a
// function.
type OSFS struct{}

func (OSFS) Open(name string) (*os.File, error)
func (OSFS) OpenFile(name string, flag int, perm os.FileMode) (*os.File, error)
func (OSFS) Create(name string) (*os.File, error)
func (OSFS) CreateTemp(dir, pattern string) (*os.File, error)
func (OSFS) OpenRoot(name string) (*os.Root, error)
func (OSFS) OpenInRoot(dir, name string) (*os.File, error)
func (OSFS) ReadFile(name string) ([]byte, error)
func (OSFS) WriteFile(name string, data []byte, perm os.FileMode) error
func (OSFS) Truncate(name string, size int64) error
func (OSFS) CopyFS(dir string, fsys fs.FS) error
func (OSFS) Mkdir(name string, perm os.FileMode) error
func (OSFS) MkdirAll(name string, perm os.FileMode) error
func (OSFS) MkdirTemp(dir, pattern string) (string, error)
func (OSFS) ReadDir(name string) ([]os.DirEntry, error)
func (OSFS) Remove(name string) error
func (OSFS) RemoveAll(name string) error
func (OSFS) Rename(oldname, newname string) error
func (OSFS) Link(oldname, newname string) error
func (OSFS) Symlink(oldname, newname string) error
func (OSFS) Readlink(name string) (string, error)
func (OSFS) Stat(name string) (os.FileInfo, error)
func (OSFS) Lstat(name string) (os.FileInfo, error)
func (OSFS) Chmod(name string, mode os.FileMode) error
func (OSFS) Chown(name string, uid, gid int) error
func (OSFS) Lchown(name string, uid, gid int) error
func (OSFS) Chtimes(name string, atime, mtime time.Time) error

// Getwd returns the absolute path that relative names are relative to.
func (OSFS) Getwd() (string, error)

// DirFS returns an fs.FS view of dir, for fs.WalkDir, fs.Glob,
// template.ParseFS and the other std helpers.
func (OSFS) DirFS(dir string) fs.FS

// OS returns the Host of the real machine: net.Listen, a net.Dialer's
// DialContext, and an OSFS. A framework copies its fields into a Host of
// its own filesystem.
func OS() Host[OSFS]

package hosttest // github.com/z5labs/bedrock/host/hosttest

// Host is a test's network and filesystem: a network of net.Pipe
// connections, and a filesystem in a directory from tb.TempDir(), confined
// with os.Root. It starts no goroutines, so build it inside the
// testing/synctest bubble that uses it. A Host is safe for concurrent use.
// A test builds the App's host.Host from its Listen, Dial and FS.
type Host struct{ /* unexported fields */ }

// Option configures a Host built by New.
type Option func(*Host)

// New returns a Host configured by opts. It reports misuse through tb.
func New(tb testing.TB, opts ...Option) *Host

// WithFiles writes files into the Host's directory, keyed by their path
// relative to it with forward slashes, such as "etc/config.yaml".
func WithFiles(files map[string][]byte) Option

// Listen and Dial are the Host's network. Dial refuses with ECONNREFUSED
// when nothing listens, and never waits for a listener.
func (h *Host) Listen(network, address string) (net.Listener, error)
func (h *Host) Dial(ctx context.Context, network, address string) (net.Conn, error)

// Listening returns a channel that is closed once a Dial to address would
// reach a listener, like bedrocktest's Process.Notified.
func (h *Host) Listening(address string) <-chan struct{}

// FS returns the Host's filesystem.
func (h *Host) FS() *FS

// Path returns the absolute path of name, relative to the Host's
// directory, to put in an argument or a setting.
func (h *Host) Path(name string) string

// FS is a filesystem confined to a Host's directory with os.Root. It has
// every method of host.OSFS, with the same results, except that a name
// that leaves the directory fails. Its Getwd is the Host's directory.
type FS struct{ /* unexported fields */ }

A framework declares the filesystem its users see, and an alias hides the type parameter from them. Here is a CLI framework that gives a command five methods:

package cli // a command-line framework built on bedrock

// FS is the filesystem a command sees.
type FS interface {
	host.FS

	Open(name string) (*os.File, error)
	OpenFile(name string, flag int, perm os.FileMode) (*os.File, error)
	MkdirAll(name string, perm os.FileMode) error
	Chmod(name string, mode os.FileMode) error
	Getwd() (string, error)
}

// Host is what the framework hands a command.
type Host = host.Host[FS]

// OSHost returns the Host of the real machine.
func OSHost() Host {
	h := host.OS()
	return Host{Listen: h.Listen, Dial: h.Dial, FS: h.FS}
}

The framework's test helper builds a Host the same way, from hosttest's Listen, Dial and FS. Both assignments to FS are checked when they compile.

An App built on bedrock alone does the same. It declares only the methods it calls and takes the Host as a field, the way example/httpserver takes Listen. Here is a small CLI that downloads a URL into a file, and calls one method:

// FS is the filesystem App writes to.
type FS interface {
	host.FS
	OpenFile(name string, flag int, perm os.FileMode) (*os.File, error)
}

// App downloads the URL in its first argument into the file named by its
// second.
type App struct {
	Host host.Host[FS]
}

func (a App) Run(ctx context.Context, p bedrock.Process) bedrock.ExitStatus {
	if len(p.Args) != 3 {
		_, _ = fmt.Fprintln(p.Stderr, "usage: fetch URL FILE")
		return bedrock.Exit(2)
	}
	if err := a.fetch(ctx, p.Args[1], p.Args[2]); err != nil {
		_, _ = fmt.Fprintln(p.Stderr, "fetch:", err)
		return bedrock.ExitWithCause(1, err)
	}
	return bedrock.Exit(0)
}

func (a App) fetch(ctx context.Context, url, name string) error {
	tr := &http.Transport{DialContext: a.Host.Dial}
	defer tr.CloseIdleConnections()
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
	if err != nil {
		return err
	}
	f, err := a.Host.FS.OpenFile(name, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0o644)
	if err != nil {
		return err
	}
	resp, err := (&http.Client{Transport: tr}).Do(req)
	if err != nil {
		return errors.Join(err, f.Close())
	}
	_, err = io.Copy(f, resp.Body)
	return errors.Join(err, resp.Body.Close(), f.Close())
}

func main() {
	h := host.OS()
	bedrock.Main(App{Host: host.Host[FS]{Listen: h.Listen, Dial: h.Dial, FS: h.FS}})
}

Its test runs the whole App, the server it calls and the file it writes, with no real socket and no file outside the test's directory:

func TestApp_writes_the_body_to_the_file(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		h := hosttest.New(t)
		ln, err := h.Listen("tcp", ":8080")
		require.NoError(t, err)
		srv := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
			_, _ = io.WriteString(w, "hello")
		})}
		served := make(chan error, 1)
		go func() { served <- srv.Serve(ln) }()

		app := App{Host: host.Host[FS]{Listen: h.Listen, Dial: h.Dial, FS: h.FS()}}
		_, status := bedrocktest.Start(t, app,
			bedrocktest.WithArgs("http://localhost:8080/", "out.txt"),
		)
		st := <-status
		require.Zero(t, st.Code(), st.Cause())

		b, err := os.ReadFile(h.Path("out.txt"))
		require.NoError(t, err)
		require.Equal(t, "hello", string(b))

		require.NoError(t, srv.Close())
		require.ErrorIs(t, <-served, http.ErrServerClosed)
	})
}

Every block above compiles against a prototype of this API. Written in humus's types, the example and its test also pass with -race today against humus.Host and humustest.Host.

Design decisions

• A nested module, not the root module. It follows fit, circuit and retry, so the root module stays exactly the process model. Its library code imports only the standard library. Neither module requires the other, not even for tests, as with fit, circuit and retry, so a framework that wants only the Host gets nothing else. The alternative was bedrock.Host next to bedrock.Process, and it was rejected:

  • it suggests that bedrock passes a Host in;
  • it gives the root package a second OS edge next to os.go, which is today the only file that touches the real process.

• bedrock defines the Host and never passes one. Process stays what exec hands a process, and App.Run and Main don't change. Each framework decides how an App receives its Host: humus through Setup.Host, a CLI framework through its own types, and an App on bedrock alone through a field.

• bedrock fixes the contract, and each framework chooses the surface. Host is generic over the filesystem it carries. bedrock defines what every filesystem method means and ships the two implementations, OSFS and hosttest's FS. A framework declares the interface its users see and hides the type parameter behind an alias, type Host = host.Host[FS]. humus and a CLI framework are opinionated, and each exposes as much of the filesystem as its users need. bedrock isn't, so it doesn't choose for them.

  • Every assignment is checked when it compiles. OSFS and hosttest's FS assign to any framework interface they satisfy. A framework that asks for a method OSFS lacks gets a compile error at the assignment: host.OSFS does not implement FS (missing method Chdir).
  • What frameworks share is the contract, not a type. host.Host[humus.FS] and host.Host[cli.FS] are different types. Shared code that needs only the network is generic, such as func NewClient[F host.FS](h host.Host[F]) *http.Client. Shared code that needs the filesystem takes the smallest interface it calls, such as interface{ Open(string) (*os.File, error) }, which every framework's FS satisfies.
  • The alternative was one FS interface in a non-generic Host, and it was rejected. A framework that wanted a different surface would have to declare a Host of its own, or reach its own methods through a type assertion, which is checked only at run time.

• Accept interfaces, return structs. OSFS and hosttest's FS are structs. OSFS has no fields, so var fsys host.OSFS is the real filesystem and it needs no constructor. bedrock exports no interface of filesystem methods. Each consumer, a framework or an App, declares the methods it calls, as fetch declares OpenFile.

  • No Host type is filled by both OS and hosttest. OS() returns Host[OSFS], which a framework or an App copies into a Host of its own filesystem, and hosttest's Host has no Host method. main and the test each build the App's Host from parts, as in the example above.
  • The alternative was an exported OSFS interface with every method, and it was rejected. OS and hosttest would hand out an interface, and a framework that embedded the interface whole would gain every method bedrock adds, whether or not it chose to. A framework that wants every method lists them.

• FS is sealed. Its one method is unexported, so FS is implemented only in this module. A type elsewhere satisfies it by embedding a value from this module, which is how a test wraps a filesystem to change one method. This is the pattern of testing.TB, whose private method exists "to prevent users implementing the interface and so future additions to it will not violate Go 1 compatibility". The seal gives two things:

  • Every filesystem is a conformance-tested one. A Host hands out OSFS or hosttest's FS, possibly wrapped, and the conformance table holds the two to the same results. So the compiler backs the decision below that there is no fake filesystem to keep in line with the real one. A filesystem written from scratch is still possible, by embedding host.FS itself, but it's a deliberate step, and whoever takes it keeps up with every method by hand.
  • Framework interfaces grow without breaking anyone. Every value that satisfies one is OSFS or hosttest's FS, possibly wrapped, and both have every method. So when a framework adds a method to its interface, its users' wrappers gain it by promotion. Adding a method to OSFS itself breaks no one, because it's a struct. So OSFS follows package os from one Go release to the next, and its method set doesn't have to be settled up front.

  The alternative was an any constraint, under which any type would do, including a hand-written fake that drifts from the real filesystem.

• OSFS is every file function of package os. It has one method for each function in os that names a file, except those that read or change process-wide state: Chdir, TempDir, UserHomeDir, UserConfigDir and UserCacheDir. Getwd is the one exception, because relative names need it (below).

  • New since humus: Create, OpenRoot, OpenInRoot, ReadFile, WriteFile, Truncate, CopyFS, Link, Symlink, Readlink, Lstat, Chmod, Chown, Lchown, Chtimes and Getwd.
  • In hosttest, most methods are one os.Root call. os.Root lacks CreateTemp, MkdirTemp, ReadDir, Truncate, CopyFS, OpenInRoot, DirFS and Getwd, so hosttest builds those from the others.
  • Why all of it: a CLI framework uses the filesystem more heavily than services do. A CLI marks a generated script executable, keeps times and links when it copies a tree, and confines an archive's extraction with os.Root so that a ../ entry can't escape. With every method in OSFS, each framework picks what it needs, and bedrock never picks for it.

• A framework declares its FS in one of two ways, each checked when it compiles:

  • List methods, with an interface that embeds host.FS, like the CLI framework above. It may list every method of OSFS. Its surface grows only when the framework adds a method.
  • Extend OSFS with a method it lacks. OSFS alone no longer satisfies the interface, so the framework wraps it, as struct{ host.OSFS } plus the method.

  A framework's FS can't embed the io/fs interfaces. Each of them embeds fs.FS, whose Open returns fs.File, so an interface that lists Open and embeds fs.ReadDirFS fails with duplicate method Open. DirFS is the way into io/fs.

• bedrock never converts a value to F. Inside a generic function, a value can become F only through a type assertion, which is checked at run time. So OS returns Host[OSFS], hosttest's FS method returns *FS, and a framework or an App builds its own Host from their fields, Host{Listen: h.Listen, Dial: h.Dial, FS: h.FS}, a line the compiler checks. There is no func OS[F FS]() Host[F].

• The rest is as humus settled it in Proposal: the humus App lifecycle humus#630.

  • A struct of functions, not an interface, so a test replaces one field, such as a Dial that fails, and keeps the rest.
  • The filesystem hands out *os.File, not an in-memory fake. Libraries that need a real file or a path keep working in tests, such as SQLite drivers, archive libraries and programs started with os/exec, and there is no fake filesystem to keep in line with the real one. It's a one-way decision: an *os.File is always an OS handle, so moving to an in-memory filesystem later would change every signature.
  • OSFS uses plain os calls. It can't be os.OpenRoot("/"), because os.Root refuses to follow absolute symbolic links even when it is rooted at /.

• Getwd, because relative names need a working directory. With OSFS, relative names resolve against the process's working directory, and with hosttest against the test's directory. filepath.Abs reads the real working directory through os.Getwd, so in a test it produces a path outside the test's directory, which hosttest refuses. Code that needs an absolute path joins the filesystem's Getwd instead. There is no Chdir, because the working directory is process-wide state. Strictly, the working directory is something exec hands a process, but it means nothing without a filesystem, so it belongs with the filesystem rather than in Process.

• hosttest is humustest's Host, moved. Its rules follow a real network, as Proposal: humustest — whole-service testing on top of bedrocktest humus#633 settled them:

  • a name and port are held once;
  • a listener on every name (an empty host, 0.0.0.0 or ::) conflicts with any other listener on its port;
  • names are compared as written and never resolved;
  • port 0 picks from IANA's dynamic range;
  • every error is a *net.OpError.

  Dial refuses rather than waits. A test that dials before the App listens has dialled too early, and waiting would hide that. The test waits with synctest.Wait or Listening instead.

  hosttest's FS gets the unexported method by embedding host.FS through an unexported alias, so the field stays out of its docs. It must not embed OSFS for the method instead. Every method it forgot to write would then be the real filesystem's, and would compile and escape the test's directory. The same holds for any filesystem that confines another. No exported interface lists every method, so the conformance table checks that hosttest's FS has them all (see Testing).

  hosttest's Symlink refuses an absolute target with a *os.LinkError whose Err is errors.ErrUnsupported. os.Root won't follow an absolute link even when it points inside the root, so a link that works under OSFS would fail under hosttest at its first use, far from the call that made it. Refusing it fails at the cause. os.CopyFS copies a symbolic link with Symlink, so hosttest's CopyFS refuses an fsys holding an absolute link the same way. These two are the FS conformance table's one exception.

• No lint rule for the host boundary. forbidigo doesn't ban net.Listen, net.Dial or os's file API outside OS and OSFS. Because the filesystem hands out *os.File, user code works with os types directly, and a ban would get in its way. humus decided the same in Proposal: the humus App lifecycle humus#630 (open question 9), and bedrock's list covers only the process boundary. A framework that wants the host boundary enforced for its users adds the rule itself.

• No HTTP client helper. A client over the Host's network is one line, &http.Transport{DialContext: h.Dial}, and its settings, such as keep-alives and TLS, are the framework's choice. humustest's HTTPClient stays in humustest.

• New ambient leaks are documented. The host package doc lists what reads the real machine behind the Host's back:

  • os.Getwd and filepath.Abs;
  • http.DefaultTransport and net.DefaultResolver, which dial the real network;
  • a program started with os/exec, which sees the real network and the whole filesystem.

  bedrock's own Ambient leaks list gains os.TempDir, os.UserHomeDir, os.UserConfigDir and os.UserCacheDir, which read the real environment. A framework computes them from p.Environment instead.

Testing

• Coverage. Statement coverage of host and hosttest is 100.0%, as for every module, and the coverage gate covers the new module.
• synctest. hosttest's tests run inside testing/synctest bubbles, and none of them opens a real socket.
• TLS. host's tests run a TLS handshake over OS()'s network on loopback, and hosttest's tests run one over hosttest's network inside a synctest bubble. Their certificates come from unexported test helpers that use only the standard library. bedrock exports no certificate helpers.
• Conformance. humustest's conformance table moves with the network. It runs on hosttest, and, behind the conformance build tag, on host.OS() over real loopback sockets, which needs 127.0.0.2 on the loopback interface, as Linux has. A second table does the same for OSFS. Each method runs on OSFS in a t.TempDir() and on hosttest's FS, and must give the same result, including a *fs.PathError that names the path the caller passed. The table calls the methods through an unexported interface that lists all of OSFS's, so it doesn't compile if hosttest's FS lacks one. The coverage gate fails a method added to OSFS until the table calls it. As with bedrocktest's fake signals, the fake can't drift from what it stands in for.
• Examples. hosttest's package doc has a tested example of the same download, written as a function over a host.Host[FS], because the host module doesn't require the bedrock module. The CLI framework's FS and its alias are a whole-file example in host's.

Migration from today

• bedrock. The change is additive, and nothing in the root module changes but docs:
  • A fifth module. It needs CI build, vet, test and lint steps, the coverage gate, a depguard rule, and the CLAUDE.md commands and package layout. tag-modules.sh already finds every nested go.mod, so releases need nothing.
  • "Beyond the boundary" gains one sentence. For the network and the filesystem, the nested host module gives every framework the same contract and the same two implementations, and bedrock itself never passes a Host.
  • "Ambient leaks" gains the four os functions above.
  • example/httpserver keeps its Listen field. It shows the process model with nothing else, and the root module doesn't depend on nested modules.
• humus. humus adopts this through a proposal of its own and a revision of its charter, Proposal: humus on the bedrock process model humus#629. Nothing in this proposal changes humus. That proposal decides whether:
  • humus.FS lists every method of OSFS or a subset, with type Host = host.Host[FS]; humus hasn't released since v0.15.0, so the old types go without a deprecation period;
  • humustest.Host is built on hosttest or replaced by it;
  • humustest keeps its CA, Telemetry, Start and TestService.
• The CLI framework is a project of its own, built on bedrock and host. It isn't proposed here.

Settled questions

1. The OSFS method set. The rule stands: every os function that names a file, minus the five that read or change process-wide state, plus Getwd. OpenInRoot, CopyFS and Truncate stay in.
2. Names. A name doesn't repeat its package, so the names are host.OS() and hosttest.New(t), not host.OSHost() or hosttest.NewHost(t).
3. TLS test certificates. Public helpers stay in humustest, including its CA. host's own tests cover TLS over both networks (see Testing). A bedrock package of TLS, CA and certificate helpers may deserve a proposal of its own.
4. No NewOSFS. OSFS has no fields, so var fsys host.OSFS is the real filesystem, and OS() stays.
5. Absolute symbolic links in hosttest. Symlink refuses them (see Design decisions).

Out of scope

• Passing a Host through Process, App.Run or Main.
• An in-memory filesystem, and injecting I/O errors such as a full disk. Code that needs those tests puts an io.Writer seam in its own code.
• The clock and randomness, which come from testing/synctest and testing/cryptotest.
• ListenPacket, Unix sockets and name resolution. hosttest's network is TCP, with names compared as written.
• User directories, such as the home and config directories, which a framework computes from p.Environment.
• Chdir, because the working directory is process-wide state.
• A lint rule for the host boundary; see Design decisions.
• TLS, CA and certificate helpers, which stay in humustest and may get a bedrock proposal of their own.

[Zaba505]

The design is settled, and the body above now records every decision. It's filed as five stories, each blocked by the one before:

1. story(host): nested module with Host, FS and OSFS #615 story(host): nested module with Host, FS and OSFS
2. story(host): hosttest's network, ported from humustest #616 story(host): hosttest's network, ported from humustest
3. story(host): hosttest's confined filesystem, ported from humustest #617 story(host): hosttest's confined filesystem, ported from humustest
4. story(host): the rest of OSFS in hosttest, with absolute symbolic links refused #618 story(host): the rest of OSFS in hosttest, with absolute symbolic links refused
5. story(host): package docs, examples, README and bedrock's boundary docs #619 story(host): package docs, examples, README and bedrock's boundary docs

Settled decisions

1. OSFS's method set: every os function that names a file, minus Chdir, TempDir and the three User*Dir functions, plus Getwd. OpenInRoot, CopyFS and Truncate stay in.
2. Names don't repeat the package: host.OS() and hosttest.New(t).
3. Public TLS, CA and certificate helpers stay in humustest. host's own tests cover TLS over both networks, with unexported test certificates. A bedrock package of such helpers may get a proposal of its own.
4. No NewOSFS: OSFS has no fields, so var fsys host.OSFS is the real filesystem. OS() stays.
5. Absolute symbolic links in hosttest:
   • hosttest's Symlink refuses an absolute target with errors.ErrUnsupported, because os.Root won't follow one even inside the root;
   • its CopyFS refuses an fsys holding one the same way;
   • these are the FS conformance table's one exception.
6. No dependency on the bedrock module: the host module doesn't require it, not even for tests. So hosttest's tested example is a function over a host.Host[FS], not a bedrock App.

humus adopts this through a proposal of its own and z5labs/humus#629, as the Migration section says.