@ccmsg/cli 0.9.1 → 0.11.0

package/src/instance/config.ts

@@ -1,7 +1,15 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute } from "node:path";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
 import { type DumpPreset, type Endpoint, TranscriptItemSelector } from "@ccmsg/protocol";
 import { DEFAULT_HARNESS, type Harness, HARNESSES, isHarness } from "../harness/index.ts";
+import { ID } from "./identity.ts";
 import { parseCidr } from "./client.ts";
 
 /** Where the instance accepts WebSocket connections, and from whom.
@@ -110,11 +118,24 @@ export interface InstanceConfig {
    * home says nothing about the program it belongs to, and an instance that
    * guessed would walk the wrong tree for the whole of its first session. */
   readonly harness: Harness;
-  /** Every mesh endpoint, this instance's own among them (§7.1). The same list
-   * goes to every instance and names none of them in particular: which entry is
-   * this one is settled at startup by the probe, so one file can be copied to
-   * every host unchanged (§8.2). */
-  readonly peers: readonly Endpoint[];
+  /** Every instance of the mesh, this one among them (§7.1).
+   *
+   * Data, and the same data on every host: a settings function is handed it
+   * and may read it — an instance that wants to know who else there is has it
+   * here — but a returned list that differs from the file's is refused. Which
+   * entry is this instance is the row carrying its own id, which is what
+   * settles `endpoint` below. */
+  readonly endpoints: readonly EndpointRow[];
+  /** Where peers and people reach this instance: its own row of the mesh
+   * (§7.1).
+   *
+   * Not something a settings file states — the row is, and two places to write
+   * one address is one place for it to be wrong. An instance behind a reverse
+   * proxy is dialled at the proxy's name and listens on loopback, and the two
+   * cannot be derived from each other, so what a peer dials is written down
+   * beside who it belongs to. Absent on an instance the mesh does not name,
+   * which is one that serves the unix socket alone. */
+  readonly endpoint?: Endpoint;
   /** Absent when this instance serves the unix socket only. */
   readonly entry?: EntryConfig;
   readonly upstream: UpstreamConfig;
@@ -147,176 +168,543 @@ export class ConfigError extends Error {
   }
 }
 
-/** An instance with no config file: the unix socket, no peers, no upstreams.
+/** An instance with no config file: the unix socket, no mesh, no upstreams.
  *
  * Absent is not broken. A config that is not there states nothing wrong, while
  * one that is there and unreadable states something wrong — only the second is
  * the fail-fast case. */
 export const DEFAULT_CONFIG: InstanceConfig = {
   harness: DEFAULT_HARNESS,
-  peers: [],
+  endpoints: [],
   upstream: {},
   direct_delivery: true,
   fork_origin: false,
   dump: { presets: [] },
 };
 
-/** Read the config, once, at startup (DV-Q8).
+/** The file every instance's settings start from, and the directory holding
+ * one file per instance. Both are read from the config home a person edits
+ * (§8.2). The names are held here alone, so what the files are called is one
+ * edit rather than a search. */
+export const CONFIG_FILE = "config_v2.ts";
+export const INSTANCES_DIR = "instances";
+
+/** The declarations a config file writes against, as they are called where
+ * they are copied to, and as this build keeps them. */
+export const TYPES_FILE = "ccmsg-config_v2.d.ts";
+const TYPES_SOURCE = "ccmsg-config.d.ts";
+
+/** What the settings used to be written in. Named so a config home that still
+ * holds one is told where its settings have moved to, rather than starting
+ * with every setting it carried silently absent. */
+const JSON_FILE = "config.json";
+
+/** The fields a config function may hand back. Checked rather than ignored,
+ * because a misspelled field is a setting that was written and does not take:
+ * the types say so while the file is being edited, and this says so when it is
+ * read. */
+const FIELDS = ["harness", "entry", "upstream", "direct_delivery", "fork_origin", "dump"] as const;
+
+/** What only one instance's own file may state: which config home it answers
+ * for, and the address it is reached at. Neither is a thing the shared file
+ * could say once for everybody. */
+const INSTANCE_FIELDS = ["dir", "name"] as const;
+
+/** The mesh, as data: who is in it and where each one is reached.
  *
- * There is no watch and no reload: the file is small, an instance is cheap to
- * restart because almost nothing it holds is persistent (§3.6), and restarting
- * is therefore the whole of "apply a config change" (§8.2). */
-export function loadConfig(file: string, dir: string): InstanceConfig {
-  return parseConfig(file, settingsFor(loadShared(file), dir));
-}
+ * A list rather than something derived, because it is the one thing an
+ * instance cannot work out for itself — which address of the several a host
+ * has is the one its peers dial, and which of the entries is this instance.
+ * Both are answered by the row carrying its own id, which is what settles
+ * `self` (§7.1) without asking the network anything.
+ *
+ * Every instance of the mesh is in it, this host's and the others', so one
+ * file can be copied to every host unchanged (§8.2). */
+export const ENDPOINTS_FILE = "endpoints.json";
 
-/** One config home the shared file knows about.
+/** Which of them this host starts. An id here and not in the endpoints is a
+ * mistake; an id in the endpoints and not here is another host's instance,
+ * which this one dials and does not start. */
+export const SUPERVISOR_FILE = "supervisor.json";
+
+/** Where the settings that were read and checked are kept, and the one file
+ * the supervisor and every instance actually read.
  *
- * `dir` is the config home itself, which is what an instance is (A2); the rest
- * is whatever that instance sets differently from `defaults`, held raw because
- * it is merged before it is read. */
-export interface InstanceEntry {
+ * Apart from the files a person edits because the two answer different
+ * questions: what is being written, and what is running. A config that does
+ * not check out never reaches here, which is what lets a broken edit be
+ * reported without taking the host down (§8.3). */
+export const STATE_CONFIG_DIR = "config";
+export const SATISFIED_FILE = "satisfied.json";
+export const REJECTED_DIR = "config.rejected";
+
+/** One entry of the mesh. */
+export interface EndpointRow {
+  readonly id: string;
+  readonly endpoint: Endpoint;
+}
+
+/** What one instance is, once its file has been read. */
+export interface InstanceSetting {
+  readonly id: string;
+  readonly name: string;
   readonly dir: string;
-  readonly settings: Record<string, unknown>;
+  readonly config: InstanceConfig;
 }
 
-/** The one file a person edits: what every instance gets, and which config
- * homes run one.
+/** Everything that was read, checked, and is therefore what runs.
  *
- * One file rather than one per config home because both of the things it
- * carries are facts about the set — the peer list is the same for every
- * instance (§7.1), and "which config homes run an instance" is a question no
- * single instance can answer about itself. */
-export interface SharedConfig {
-  readonly defaults: Record<string, unknown>;
-  readonly instances: readonly InstanceEntry[];
+ * One value rather than a directory to walk: the supervisor and the instances
+ * read this and nothing else, so what they run with is what was checked, and
+ * no TypeScript is evaluated a second time where a different answer could come
+ * back. */
+export interface Satisfied {
+  readonly endpoints: readonly EndpointRow[];
+  readonly supervisor: { readonly instances: readonly string[] };
+  readonly instances: readonly InstanceSetting[];
 }
 
-export const EMPTY_SHARED: SharedConfig = { defaults: {}, instances: [] };
+/** A label a person may give an instance. Narrow because it is typed at a
+ * command and printed in a listing; nothing is found by it, since files are
+ * named by id. */
+export const CONFIG_NAME = /^[a-z0-9][a-z0-9._-]*$/;
 
-/** Read the shared file. Absent is not broken, for `DEFAULT_CONFIG`'s reason,
- * so it reads as the empty one; present and wrong ends the read (DV-Q9). */
-export function loadShared(file: string): SharedConfig {
-  let text: string;
-  try {
-    text = readFileSync(file, "utf8");
-  } catch {
-    return EMPTY_SHARED;
+/** Something wrong with one file, said where it is: which file, and what about
+ * it. Collected rather than thrown one at a time, so an operator who broke two
+ * things is told about both. */
+export interface ConfigProblem {
+  readonly file: string;
+  readonly msg: string;
+}
+
+/** The files this reads, at the paths they are read and copied by. */
+export function configFiles(configDir: string, instances: readonly string[]): string[] {
+  return [
+    join(configDir, CONFIG_FILE),
+    join(configDir, ENDPOINTS_FILE),
+    join(configDir, SUPERVISOR_FILE),
+    ...instances.map((id) => join(configDir, INSTANCES_DIR, instanceFileName(id))),
+  ];
+}
+
+export function instanceFileName(id: string): string {
+  return `instance-${id}.ts`;
+}
+
+/** Read everything a person edits, call what has to be called, and check the
+ * whole of it (DV-Q8, §8.3).
+ *
+ * One pass rather than a check per file, because what makes a config right is
+ * mostly between files: an id the supervisor starts has to be an entry of the
+ * mesh and have settings of its own, two instances must not hold one address
+ * or one config home, and the data is the mesh — a settings function that
+ * returned a different one has stated something it does not get to state. Each
+ * file is checked as far as it can be on its own so that a person is told
+ * where the mistake is, and nothing is applied until all of it holds.
+ *
+ * The settings functions are called here and never again: what they returned
+ * is what runs. They are expected to have no side effects, since this runs
+ * them to answer questions — `config show`, `config diff --satisfied` — as well as
+ * to apply them. */
+export async function evaluate(
+  configDir: string,
+): Promise<{ satisfied?: Satisfied; problems: readonly ConfigProblem[] }> {
+  const problems: ConfigProblem[] = [];
+  const at = (file: string, msg: string): undefined => {
+    problems.push({ file, msg });
+    return undefined;
+  };
+
+  const endpointsFile = join(configDir, ENDPOINTS_FILE);
+  const supervisorFile = join(configDir, SUPERVISOR_FILE);
+  const configFile = join(configDir, CONFIG_FILE);
+
+  const endpoints = readEndpoints(endpointsFile, at);
+  const supervised = readSupervisor(supervisorFile, at);
+
+  // An empty config home is not a broken one: nothing is being run, which is
+  // what a host that has had no `daemon add` looks like.
+  if (endpoints === undefined || supervised === undefined) {
+    if (problems.length > 0) return { problems };
+    return {
+      satisfied: { endpoints: [], supervisor: { instances: [] }, instances: [] },
+      problems,
+    };
   }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(text);
-  } catch (cause) {
-    throw new ConfigError(file, `not valid JSON (${String(cause)})`);
+
+  const defaults = await defaultsOf(configFile, endpoints, at);
+  const instances: InstanceSetting[] = [];
+  for (const id of supervised) {
+    if (!endpoints.some((row) => row.id === id)) {
+      at(supervisorFile, `${id} is not an entry of ${ENDPOINTS_FILE}`);
+      continue;
+    }
+    const file = join(configDir, INSTANCES_DIR, instanceFileName(id));
+    if (!existsSync(file)) {
+      at(supervisorFile, `${id} has no settings of its own at ${file}`);
+      continue;
+    }
+    if (defaults === undefined) continue;
+    const read = await instanceOf(file, id, defaults, endpoints, at);
+    if (read !== undefined) instances.push(read);
+  }
+
+  // What no single file can be wrong about on its own.
+  const dirs = new Map<string, string>();
+  const ports = new Map<number, string>();
+  for (const one of instances) {
+    const file = join(configDir, INSTANCES_DIR, instanceFileName(one.id));
+    const home = dirs.get(one.dir);
+    if (home !== undefined) at(file, `dir ${one.dir} is already what ${home} answers for`);
+    else dirs.set(one.dir, one.name);
+    const port = one.config.entry?.port;
+    if (port === undefined || port === 0) continue;
+    const held = ports.get(port);
+    if (held !== undefined) at(file, `port ${String(port)} is already ${held}'s`);
+    else ports.set(port, one.name);
   }
-  const top = objectOf(file, "the top level", parsed);
-  for (const name of Object.keys(top)) {
-    if (name !== "defaults" && name !== "instances") {
-      throw new ConfigError(file, `unknown top-level key ${name}; expected defaults or instances`);
+
+  if (problems.length > 0) return { problems };
+  return {
+    satisfied: { endpoints, supervisor: { instances: supervised }, instances },
+    problems,
+  };
+}
+
+/** The mesh as the data states it. */
+function readEndpoints(
+  file: string,
+  at: (file: string, msg: string) => undefined,
+): readonly EndpointRow[] | undefined {
+  const parsed = readJson(file, at);
+  if (parsed === undefined) return undefined;
+  if (!Array.isArray(parsed)) return at(file, "must be an array of {id, endpoint}");
+  const rows: EndpointRow[] = [];
+  for (const [index, raw] of parsed.entries()) {
+    const where = `[${String(index)}]`;
+    if (typeof raw !== "object" || raw === null) {
+      at(file, `${where} must be an object with id and endpoint`);
+      continue;
+    }
+    const fields = raw as Record<string, unknown>;
+    const id = fields["id"];
+    const endpoint = fields["endpoint"];
+    if (typeof id !== "string" || !ID.test(id)) {
+      at(file, `${where}.id must be an instance id`);
+      continue;
     }
+    if (typeof endpoint !== "string" || !ENDPOINT.test(endpoint)) {
+      at(file, `${where}.endpoint must be an http:// or https:// base URL ending in /`);
+      continue;
+    }
+    if (rows.some((row) => row.id === id)) at(file, `${where}.id repeats ${id}`);
+    else if (rows.some((row) => row.endpoint === endpoint)) {
+      // Two entries at one address would each be this instance to whoever
+      // dialled it, and neither could be told from the other (§7.1).
+      at(file, `${where}.endpoint repeats ${endpoint}`);
+    } else rows.push({ id, endpoint: endpoint as Endpoint });
   }
-  const raw = top["instances"];
-  if (raw !== undefined && !Array.isArray(raw)) {
-    throw new ConfigError(file, "instances must be an array of config homes");
+  return rows;
+}
+
+function readSupervisor(
+  file: string,
+  at: (file: string, msg: string) => undefined,
+): readonly string[] | undefined {
+  const parsed = readJson(file, at);
+  if (parsed === undefined) return undefined;
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return at(file, "must be an object with instances");
   }
-  const seen = new Set<string>();
-  const instances = ((raw ?? []) as unknown[]).map((entry, index) => {
-    const fields = objectOf(file, `instances[${index}]`, entry);
-    const { dir, ...settings } = fields;
-    if (typeof dir !== "string" || !isAbsolute(dir)) {
-      throw new ConfigError(file, `instances[${index}].dir must be an absolute config home`);
+  const listed = (parsed as Record<string, unknown>)["instances"] ?? [];
+  if (!Array.isArray(listed) || listed.some((id) => typeof id !== "string" || !ID.test(id))) {
+    return at(file, "instances must be an array of instance ids");
+  }
+  const ids = listed as string[];
+  const twice = ids.filter((id, index) => ids.indexOf(id) !== index);
+  if (twice.length > 0) return at(file, `instances repeats ${[...new Set(twice)].join(", ")}`);
+  return ids;
+}
+
+/** What every instance starts from. */
+async function defaultsOf(
+  file: string,
+  endpoints: readonly EndpointRow[],
+  at: (file: string, msg: string) => undefined,
+): Promise<InstanceConfig | undefined> {
+  if (!existsSync(file)) {
+    const legacy = join(dirname(file), JSON_FILE);
+    if (existsSync(legacy)) {
+      return at(
+        legacy,
+        `settings are TypeScript now: write ${file}, ${join(dirname(file), ENDPOINTS_FILE)} and ${join(dirname(file), SUPERVISOR_FILE)}`,
+      );
     }
-    if (seen.has(dir)) throw new ConfigError(file, `instances[${index}].dir repeats ${dir}`);
-    seen.add(dir);
-    return { dir, settings };
+    return { ...DEFAULT_CONFIG, endpoints };
+  }
+  const returned = await called(file, {
+    builtin: frozen({ ...DEFAULT_CONFIG, endpoints }),
+    config: copied({ ...DEFAULT_CONFIG, endpoints }),
+  });
+  if (returned.problem !== undefined) return at(file, returned.problem);
+  return settingsOf(file, returned.value, endpoints, false, at)?.config;
+}
+
+/** One instance's own file, read over what the shared one returned. */
+async function instanceOf(
+  file: string,
+  id: string,
+  defaults: InstanceConfig,
+  endpoints: readonly EndpointRow[],
+  at: (file: string, msg: string) => undefined,
+): Promise<InstanceSetting | undefined> {
+  const returned = await called(file, {
+    builtin: frozen({ ...DEFAULT_CONFIG, endpoints }),
+    default: frozen(defaults),
+    config: { ...copied(defaults), dir: "", name: id },
   });
+  if (returned.problem !== undefined) return at(file, returned.problem);
+  const read = settingsOf(file, returned.value, endpoints, true, at);
+  if (read === undefined) return undefined;
+  // Where this instance is reached: its own row of the mesh. An instance the
+  // data does not name could not be dialled by anybody and could not settle
+  // what a handshake calls it (§7.1), so it is a config error rather than an
+  // instance with no address.
+  const mine = endpoints.find((row) => row.id === id);
+  if (mine === undefined) {
+    return at(file, `${id} is not an entry of ${ENDPOINTS_FILE}, so it has no endpoint`);
+  }
   return {
-    defaults: top["defaults"] === undefined ? {} : objectOf(file, "defaults", top["defaults"]),
-    instances,
+    id,
+    name: read.name === "" ? id : read.name,
+    dir: read.dir,
+    config: { ...read.config, endpoint: mine.endpoint },
   };
 }
 
-/** Write the shared file back, at the shape a person reads it in. */
-export function saveShared(file: string, shared: SharedConfig): void {
-  const instances = shared.instances.map((entry) => ({ dir: entry.dir, ...entry.settings }));
-  mkdirSync(dirname(file), { recursive: true });
-  writeFileSync(file, `${JSON.stringify({ defaults: shared.defaults, instances }, null, 2)}\n`);
+/** The settings that were applied, as the state directory holds them. */
+export function applied(stateRoot: string): Satisfied | undefined {
+  let text: string;
+  try {
+    text = readFileSync(join(stateRoot, STATE_CONFIG_DIR, SATISFIED_FILE), "utf8");
+  } catch {
+    return undefined;
+  }
+  try {
+    return JSON.parse(text) as Satisfied;
+  } catch {
+    return undefined;
+  }
 }
 
-/** How one field of the shared file combines an instance's entry with the
- * defaults.
+/** Write down what checked out: the value the supervisor and the instances
+ * read, and a copy of each file it was read from.
  *
- * `merge` takes the two field by field, so an instance states only what it
- * differs in; `replace` takes the instance's value whole. */
-export type MergeRule = "merge" | "replace";
+ * The copies are what `config diff` compares against and what `config revert`
+ * puts back, so they are taken at the same relative paths. Only the files
+ * named above are copied: what a settings file imports is its own business and
+ * is not backed up here, and a config home that loses one of those still
+ * starts, because what starts an instance is the value and not the file. */
+export function apply(configDir: string, stateRoot: string, satisfied: Satisfied): void {
+  const into = join(stateRoot, STATE_CONFIG_DIR);
+  mkdirSync(join(into, INSTANCES_DIR), { recursive: true });
+  for (const file of configFiles(configDir, satisfied.supervisor.instances)) {
+    if (!existsSync(file)) continue;
+    copyFileSync(file, join(into, relative(configDir, file)));
+  }
+  writeFileSync(join(into, SATISFIED_FILE), `${JSON.stringify(satisfied, null, 2)}\n`);
+}
 
-/** The rule for every field path that holds an object or an array, which are
- * the only ones where "combine" could mean more than one thing.
+/** Read, check, and apply, which is the one thing startup and reload both do.
  *
- * Declared beside the parsers rather than derived from the values, because
- * whether a list is a sequence or a set is a fact about what the field means
- * and every list looks the same without it. A path not named here replaces:
- * that is what a scalar can do, and it is what an array does until some field
- * is a set and says so. */
-export const MERGE_RULES: Readonly<Record<string, MergeRule>> = {
-  // The same finished list goes to every instance (§7.1), so an instance that
-  // writes its own means to run with that one and no other.
-  peers: "replace",
-  entry: "merge",
-  "entry.source_ips": "replace",
-  "entry.trusted_proxies": "replace",
-  upstream: "merge",
-  "upstream.launcher": "merge",
-  "upstream.launcher.root_dirs": "replace",
-  "upstream.launcher.templates": "replace",
-  "upstream.launcher.clean_env": "replace",
-  "upstream.launcher.keep_env": "replace",
-  dump: "merge",
-  // A preset list is a whole vocabulary: an instance that names its own means
-  // to dump by those and not by the defaults' as well, since a name it did not
-  // write could shadow or be referenced by one it did.
-  "dump.presets": "replace",
-};
+ * A config that does not check out leaves the applied one standing and is
+ * reported: an instance already serving a session is not something a typo in a
+ * file should take away, and an operator finds out from the log and from
+ * `daemon status` rather than from everything being gone. The first run is the
+ * exception — there is nothing to fall back to, so there is nothing to run. */
+export async function settle(
+  configDir: string,
+  stateRoot: string,
+): Promise<{ satisfied: Satisfied; problems: readonly ConfigProblem[]; applied: boolean }> {
+  const read = await evaluate(configDir);
+  if (read.satisfied !== undefined) {
+    apply(configDir, stateRoot, read.satisfied);
+    return { satisfied: read.satisfied, problems: [], applied: true };
+  }
+  const standing = applied(stateRoot);
+  if (standing === undefined) {
+    throw new ConfigError(
+      read.problems[0]?.file ?? join(configDir, CONFIG_FILE),
+      read.problems.map((one) => `${one.file}: ${one.msg}`).join("; "),
+    );
+  }
+  return { satisfied: standing, problems: read.problems, applied: false };
+}
 
-function ruleFor(path: string): MergeRule {
-  return MERGE_RULES[path] ?? "replace";
+/** What one config home's instance runs with, out of what is applied. */
+export function configOf(satisfied: Satisfied, dir: string): InstanceSetting | undefined {
+  return satisfied.instances.find((one) => one.dir === dir);
+}
+
+function readJson(file: string, at: (file: string, msg: string) => undefined): unknown {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return undefined;
+  }
+  try {
+    return JSON.parse(text);
+  } catch (cause) {
+    return at(file, `not valid JSON (${String(cause)})`);
+  }
 }
 
-function plainObject(raw: unknown): raw is Record<string, unknown> {
-  return typeof raw === "object" && raw !== null && !Array.isArray(raw);
+/** Put the declarations a config file writes against beside the files that
+ * write against them.
+ *
+ * Copied into the config home rather than reached where this build keeps them:
+ * a relative `import type` resolves with no tsconfig and no node_modules
+ * anywhere near it, and it goes on resolving when this checkout moves. */
+export function writeConfigTypes(configDir: string): string {
+  const at = join(configDir, TYPES_FILE);
+  mkdirSync(configDir, { recursive: true });
+  copyFileSync(new URL(`./${TYPES_SOURCE}`, import.meta.url).pathname, at);
+  return at;
 }
 
-function merged(
-  base: Record<string, unknown>,
-  over: Record<string, unknown>,
-  at: string,
-): Record<string, unknown> {
-  const out: Record<string, unknown> = { ...base };
-  for (const [name, value] of Object.entries(over)) {
-    const path = at === "" ? name : `${at}.${name}`;
-    const under = out[name];
-    out[name] =
-      ruleFor(path) === "merge" && plainObject(under) && plainObject(value)
-        ? merged(under, value, path)
-        : value;
+/** Import one config file and call what it exports.
+ *
+ * The modified time rides on the specifier because an import is cached by it:
+ * a file read again in the same process after being edited — a supervisor
+ * asked to add an instance, a test writing two configs — would otherwise be
+ * the first read over again. */
+async function called(
+  file: string,
+  ctx: Record<string, unknown>,
+): Promise<{ value?: unknown; problem?: string }> {
+  let module: { default?: unknown };
+  try {
+    module = (await import(`${file}?mtime=${String(statSync(file).mtimeMs)}`)) as {
+      default?: unknown;
+    };
+  } catch (cause) {
+    return { problem: `cannot be loaded (${String(cause)})` };
+  }
+  const define = module.default;
+  if (typeof define !== "function") {
+    return { problem: "must default export a function taking { config } and returning it" };
+  }
+  try {
+    // Awaited whatever it answers with: what a settings file has to do to
+    // answer — read a secret, ask something — is its own business.
+    return { value: await (define as (given: unknown) => unknown)(ctx) };
+  } catch (cause) {
+    return { problem: `threw while being read (${String(cause)})` };
   }
-  return out;
 }
 
-/** What one config home's instance is configured with: its own entry over the
- * shared defaults, by the rule each field path declares. A config home the file
- * does not list still resolves — `daemon run` on an unregistered directory is
- * the defaults plus the built-ins. */
-export function settingsFor(shared: SharedConfig, dir: string): Record<string, unknown> {
-  const entry = shared.instances.find((one) => one.dir === dir);
-  return merged(shared.defaults, entry?.settings ?? {}, "");
+/** What one config function handed back, checked at the shape an instance uses
+ * it. */
+function settingsOf(
+  file: string,
+  returned: unknown,
+  endpoints: readonly EndpointRow[],
+  wantsDir: boolean,
+  at: (file: string, msg: string) => undefined,
+): { dir: string; name: string; config: InstanceConfig } | undefined {
+  if (typeof returned !== "object" || returned === null || Array.isArray(returned)) {
+    return at(file, "must return the config it was handed");
+  }
+  const fields = returned as Record<string, unknown>;
+  for (const name of Object.keys(fields)) {
+    if ((INSTANCE_FIELDS as readonly string[]).includes(name)) {
+      if (wantsDir) continue;
+      return at(file, `${name} belongs to an ${INSTANCES_DIR}/ file, which this is not`);
+    }
+    if (name === "endpoints") continue;
+    if (!(FIELDS as readonly string[]).includes(name)) {
+      return at(file, `unknown field ${name}; expected ${FIELDS.join(", ")}`);
+    }
+  }
+  // The mesh is data: a function is handed it so it can read it, and a
+  // function that handed back a different one has stated something that is
+  // not its to state — which would be a host running a mesh nobody wrote down.
+  if (!sameMesh(fields["endpoints"], endpoints)) {
+    return at(
+      file,
+      `endpoints are ${ENDPOINTS_FILE}'s to state, and this returned a different list`,
+    );
+  }
+  const dir = fields["dir"];
+  if (wantsDir && (typeof dir !== "string" || !isAbsolute(dir))) {
+    return at(file, "dir must be the absolute config home this instance answers for");
+  }
+  const name = fields["name"];
+  if (name !== undefined && (typeof name !== "string" || !CONFIG_NAME.test(name))) {
+    return at(file, "name must be a label in lower case, digits, dots, dashes");
+  }
+  let config: InstanceConfig;
+  try {
+    config = parseConfig(file, fields);
+  } catch (cause) {
+    return at(
+      file,
+      cause instanceof ConfigError ? cause.message.slice(file.length + 2) : String(cause),
+    );
+  }
+  return {
+    dir: wantsDir ? (dir as string) : "",
+    name: typeof name === "string" ? name : "",
+    config: { ...config, endpoints },
+  };
+}
+
+/** Whether what came back is the mesh that went in, row by row.
+ *
+ * Field by field rather than by serialising the two: what is being asked is
+ * whether a settings function changed anything, and two lists that differ in
+ * the order of their keys are the same mesh. */
+function sameMesh(returned: unknown, rows: readonly EndpointRow[]): boolean {
+  if (!Array.isArray(returned)) return rows.length === 0;
+  if (returned.length !== rows.length) return false;
+  return rows.every((row, at) => {
+    const one = returned[at] as { id?: unknown; endpoint?: unknown } | undefined;
+    return one?.id === row.id && one.endpoint === row.endpoint;
+  });
+}
+
+/** A copy nothing can write to, for the values a config function builds on
+ * rather than edits: what `builtin` and `default` are is settled before the
+ * file runs, so a file that tried to edit one is told so where it did it. */
+function frozen(value: InstanceConfig): Record<string, unknown> {
+  return deepFreeze(copied(value));
+}
+
+function deepFreeze<T>(value: T): T {
+  if (typeof value !== "object" || value === null) return value;
+  for (const held of Object.values(value)) deepFreeze(held);
+  return Object.freeze(value);
+}
+
+/** The mutable copy a config function edits and returns.
+ *
+ * The mesh is in it, because a settings function may want to read who else
+ * there is; handing back a different one is what is refused. */
+function copied(value: InstanceConfig): Record<string, unknown> {
+  return structuredClone(value) as unknown as Record<string, unknown>;
 }
 
 /** One instance's settings, read at the shape the instance uses them. */
 export function parseConfig(file: string, fields: Record<string, unknown>): InstanceConfig {
   return {
     harness: harnessOf(file, fields["harness"]),
-    peers: peersOf(file, fields["peers"]),
+    // Put back by the caller from the data, which is where the mesh is
+    // stated; what a settings function returned has already been held to it.
+    endpoints: [],
+    ...(fields["endpoint"] === undefined
+      ? {}
+      : { endpoint: endpointOf(file, "endpoint", fields["endpoint"]) }),
     ...(fields["entry"] === undefined ? {} : { entry: entryOf(file, fields["entry"]) }),
     upstream: upstreamOf(file, fields["upstream"]),
     direct_delivery: flagOf(
@@ -469,12 +857,6 @@ function terminalGatewayOf(file: string, raw: string): string {
   return raw;
 }
 
-function peersOf(file: string, raw: unknown): readonly Endpoint[] {
-  if (raw === undefined) return [];
-  if (!Array.isArray(raw)) throw new ConfigError(file, "peers must be an array of endpoint URLs");
-  return raw.map((peer, index) => endpointOf(file, `peers[${index}]`, peer));
-}
-
 function entryOf(file: string, raw: unknown): EntryConfig {
   const fields = objectOf(file, "entry", raw);
   const port = fields["port"];