@ccmsg/cli 0.9.0 → 0.10.1

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 { isAbsolute, join } 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,30 @@ 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). */
+  /** Every mesh endpoint, this instance's own among them (§7.1).
+   *
+   * Derived rather than written: the instances on this host are the ones whose
+   * files say which port they listen on, and the rest are the endpoints
+   * `peers.json` names. A person who had to write the local half as well would
+   * be writing down a second time what `daemon add` already settled, and could
+   * get it wrong — which is a mesh an instance is silently not in. Which entry
+   * of the list is this instance is settled at startup by the probe (§7.1). */
   readonly peers: readonly Endpoint[];
+  /** Where peers and people reach this instance, when that is not the address
+   * it binds.
+   *
+   * 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. It is
+   * what the mesh puts in its list for this instance — so it is what the probe
+   * settles `self` to, what a handshake carries as `iss` and `aud`, and what
+   * a person is handed to open a page at (§7.1). Absent leaves the address
+   * this instance binds, which is what a host with no proxy in front of it
+   * has.
+   *
+   * Stated per instance, in the file that already states which port: what a
+   * proxy is set up to forward where is one fact, and writing it twice is a
+   * second place for it to be wrong. */
+  readonly endpoint?: Endpoint;
   /** Absent when this instance serves the unix socket only. */
   readonly entry?: EntryConfig;
   readonly upstream: UpstreamConfig;
@@ -161,47 +188,302 @@ export const DEFAULT_CONFIG: InstanceConfig = {
   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", "endpoint"] as const;
+
+/** Which clusters this host knows of, and where each one's own file is.
+ *
+ * Data rather than a function, and a list rather than a directory listing: what
+ * is a cluster and what is an instance is stated, so a file nobody listed is
+ * not read and a file somebody listed and then deleted is an error rather than
+ * a cluster that quietly shrank. `ccmsg mesh` and `daemon add` write these,
+ * which is why they are the shape a program reads whole.
  *
- * 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 cluster's file is this host's account of that cluster. A cluster spans
+ * hosts and no copy of it is the canonical one: each host writes down the peers
+ * it dials and the instances it runs. */
+export const CLUSTERS_FILE = "clusters.json";
+export const CLUSTERS_DIR = "clusters";
+
+export function clusterFileName(id: string): string {
+  return `cluster-${id}.json`;
+}
+
+export function instanceFileName(id: string): string {
+  return `instance-${id}.ts`;
 }
 
-/** One config home the shared file knows about.
+/** What one file under `instances/` says: which config home it is for, and
+ * what that instance runs with.
  *
- * `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 {
+ * The id is what the file is called and what everything the instance issued is
+ * keyed by; the name is a label a person picks and may change, and defaults to
+ * the id. Keeping them apart is what lets a rename be a rename — the file, the
+ * state directory and every record already written stay where they are. */
+export interface InstanceSetting {
+  readonly id: string;
+  readonly name: string;
   readonly dir: string;
-  readonly settings: Record<string, unknown>;
+  readonly config: InstanceConfig;
+  /** The clusters this instance belongs to, in the order the host lists them.
+   * More than one is allowed: an instance is a config home, and which
+   * management units it is part of is a separate question (A2). */
+  readonly clusters: readonly ClusterInfo[];
 }
 
-/** The one file a person edits: what every instance gets, and which config
- * homes run one.
+/** One cluster, as this host writes it down.
  *
- * 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[];
+ * A cluster is the unit a person manages: some instances, one mesh, one scope
+ * for the authentication records that are replicated across it. Which
+ * instances are in it is stated here rather than discovered, so an instance
+ * file that nobody listed runs nothing and an id listed with no file is an
+ * error. */
+export interface ClusterSetting {
+  readonly id: string;
+  readonly name: string;
+  /** The mesh endpoints of this cluster that this host does not serve itself.
+   * The ones it does serve are the instances listed below, at the address each
+   * of their files gives them. */
+  readonly peers: readonly Endpoint[];
+  readonly instances: readonly string[];
 }
 
-export const EMPTY_SHARED: SharedConfig = { defaults: {}, instances: [] };
+/** What an instance is told about one cluster it belongs to: which cluster,
+ * and every mesh endpoint of it — this instance's own among them, because that
+ * is what the startup probe settles which entry it is against (§7.1). */
+export interface ClusterInfo {
+  readonly id: string;
+  readonly name: string;
+  readonly peers: readonly Endpoint[];
+}
+
+/** A label a person may give an instance or a cluster.
+ *
+ * Narrow because it is typed at a command and printed in a listing, not
+ * because anything is found by it: files are named by id, so a name may change
+ * without moving anything. */
+export const CONFIG_NAME = /^[a-z0-9][a-z0-9._-]*$/;
+
+/** Everything the config home says, read once (DV-Q8).
+ *
+ * There is no watch and no reload: the files are 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).
+ *
+ * The functions are handed frozen copies of what they build on and a mutable
+ * copy of their own starting point, so what an instance runs with is what its
+ * file returned: there is no merge rule to know, because the file does the
+ * combining itself and can see exactly what it is combining with. */
+export async function loadAll(configDir: string): Promise<{
+  readonly defaults: InstanceConfig;
+  readonly clusters: readonly ClusterSetting[];
+  readonly instances: readonly InstanceSetting[];
+}> {
+  const file = join(configDir, CONFIG_FILE);
+  if (!existsSync(file)) {
+    const legacy = join(configDir, JSON_FILE);
+    if (existsSync(legacy)) {
+      throw new ConfigError(
+        legacy,
+        `settings are TypeScript now: write ${file}, ${join(configDir, CLUSTERS_FILE)} and ${join(configDir, INSTANCES_DIR, instanceFileName("<id>"))}`,
+      );
+    }
+    return { defaults: DEFAULT_CONFIG, clusters: [], instances: [] };
+  }
+  const returned = await called(file, {
+    builtin: frozen(DEFAULT_CONFIG),
+    config: copied(DEFAULT_CONFIG),
+  });
+  const defaults = settingsOf(file, returned, false).config;
+  const clusters = loadClusters(configDir);
+
+  // Every instance any cluster lists, read once however many clusters list it:
+  // an instance is one config home and one process, and belonging to two
+  // clusters is not being two of anything.
+  const own = new Map<string, { name: string; dir: string; config: InstanceConfig }>();
+  const homes = new Map<string, string>();
+  for (const cluster of clusters) {
+    for (const id of cluster.instances) {
+      if (own.has(id)) continue;
+      const at = join(configDir, INSTANCES_DIR, instanceFileName(id));
+      if (!existsSync(at)) {
+        throw new ConfigError(
+          join(configDir, CLUSTERS_DIR, clusterFileName(cluster.id)),
+          `names instance ${id}, whose file ${at} is not there`,
+        );
+      }
+      const answer = await called(at, {
+        builtin: frozen(DEFAULT_CONFIG),
+        default: frozen(defaults),
+        config: { ...copied(defaults), dir: "", name: id },
+      });
+      const settings = settingsOf(at, answer, true);
+      // Two instances answering for one config home would take each other's
+      // lock and state (A2), so which of the two files is wrong is asked here
+      // rather than discovered as a start that never settles.
+      const already = homes.get(settings.dir);
+      if (already !== undefined) {
+        throw new ConfigError(at, `dir ${settings.dir} is already what ${already} answers for`);
+      }
+      homes.set(settings.dir, instanceFileName(id));
+      own.set(id, {
+        name: settings.name === "" ? id : settings.name,
+        dir: settings.dir,
+        config: settings.config,
+      });
+    }
+  }
+
+  // What each cluster's mesh is: its own remote peers, and the instances of
+  // this host that are in it, each at the address its file gives it (§7.1).
+  const meshes = new Map<string, ClusterInfo>();
+  for (const cluster of clusters) {
+    const mesh: Endpoint[] = [];
+    for (const id of cluster.instances) {
+      const reached = endpointOfInstance(own.get(id)?.config);
+      if (reached !== undefined && !mesh.includes(reached)) mesh.push(reached);
+    }
+    for (const peer of cluster.peers) if (!mesh.includes(peer)) mesh.push(peer);
+    meshes.set(cluster.id, { id: cluster.id, name: cluster.name, peers: mesh });
+  }
+
+  const instances = [...own].map(([id, held]) => {
+    const mine = clusters
+      .filter((cluster) => cluster.instances.includes(id))
+      .flatMap((cluster) => {
+        const info = meshes.get(cluster.id);
+        return info === undefined ? [] : [info];
+      });
+    // The mesh this instance dials is every cluster it is in. Holding the
+    // clusters apart as well is what the isolation between them will be built
+    // on; what it does today is say which are which.
+    const peers: Endpoint[] = [];
+    for (const cluster of mine) {
+      for (const peer of cluster.peers) if (!peers.includes(peer)) peers.push(peer);
+    }
+    return {
+      id,
+      name: held.name,
+      dir: held.dir,
+      config: { ...held.config, peers },
+      clusters: mine,
+    };
+  });
+  return { defaults, clusters, instances };
+}
+
+/** Where a peer reaches one instance: what its file says it is reached at, and
+ * failing that the address it binds. Neither is an instance that serves the
+ * unix socket alone, which is in nobody's mesh. */
+function endpointOfInstance(config: InstanceConfig | undefined): Endpoint | undefined {
+  if (config === undefined) return undefined;
+  if (config.endpoint !== undefined) return config.endpoint;
+  return config.entry === undefined ? undefined : localEndpoint(config.entry);
+}
+
+/** The clusters this host knows of, in the order it lists them. */
+export function loadClusters(configDir: string): readonly ClusterSetting[] {
+  const file = join(configDir, CLUSTERS_FILE);
+  const top = readJson(file);
+  if (top === undefined) return [];
+  const listed = (top as { clusters?: unknown })["clusters"];
+  if (!Array.isArray(listed) || listed.some((id) => !ID.test(String(id)))) {
+    throw new ConfigError(file, "clusters must be an array of cluster ids");
+  }
+  const ids = listed as string[];
+  const repeated = ids.filter((id, index) => ids.indexOf(id) !== index);
+  if (repeated.length > 0) {
+    throw new ConfigError(file, `repeats ${[...new Set(repeated)].join(", ")}`);
+  }
+  return ids.map((id) => loadCluster(configDir, id));
+}
+
+/** One cluster's own file. Listed and missing is an error: a cluster whose
+ * instances could not be read is a mesh silently short of them. */
+export function loadCluster(configDir: string, id: string): ClusterSetting {
+  const file = join(configDir, CLUSTERS_DIR, clusterFileName(id));
+  const fields = readJson(file);
+  if (fields === undefined) {
+    throw new ConfigError(
+      join(configDir, CLUSTERS_FILE),
+      `names cluster ${id}, whose file ${file} is not there`,
+    );
+  }
+  const name = fields["name"];
+  if (name !== undefined && (typeof name !== "string" || !CONFIG_NAME.test(name))) {
+    throw new ConfigError(file, "name must be a label in lower case, digits, dots, dashes");
+  }
+  const peers = fields["peers"];
+  if (peers !== undefined && !Array.isArray(peers)) {
+    throw new ConfigError(file, "peers must be an array of endpoint URLs");
+  }
+  const read = ((peers ?? []) as unknown[]).map((peer, index) =>
+    endpointOf(file, `peers[${String(index)}]`, peer),
+  );
+  const twice = read.filter((peer, index) => read.indexOf(peer) !== index);
+  if (twice.length > 0)
+    throw new ConfigError(file, `peers repeats ${[...new Set(twice)].join(", ")}`);
+  const instances = fields["instances"];
+  if (
+    instances !== undefined &&
+    (!Array.isArray(instances) || instances.some((one) => !ID.test(String(one))))
+  ) {
+    throw new ConfigError(file, "instances must be an array of instance ids");
+  }
+  return {
+    id,
+    name: typeof name === "string" ? name : id,
+    peers: read,
+    instances: (instances ?? []) as string[],
+  };
+}
+
+/** Write one cluster's file back, at the shape a person reads it in. */
+export function saveCluster(configDir: string, cluster: ClusterSetting): void {
+  mkdirSync(join(configDir, CLUSTERS_DIR), { recursive: true });
+  writeFileSync(
+    join(configDir, CLUSTERS_DIR, clusterFileName(cluster.id)),
+    `${JSON.stringify({ name: cluster.name, peers: cluster.peers, instances: cluster.instances }, null, 2)}\n`,
+  );
+}
 
-/** 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 {
+/** Write down which clusters there are. */
+export function saveClusters(configDir: string, ids: readonly string[]): void {
+  mkdirSync(configDir, { recursive: true });
+  writeFileSync(join(configDir, CLUSTERS_FILE), `${JSON.stringify({ clusters: ids }, null, 2)}\n`);
+}
+
+function readJson(file: string): Record<string, unknown> | undefined {
   let text: string;
   try {
     text = readFileSync(file, "utf8");
   } catch {
-    return EMPTY_SHARED;
+    return undefined;
   }
   let parsed: unknown;
   try {
@@ -209,114 +491,156 @@ export function loadShared(file: string): SharedConfig {
   } catch (cause) {
     throw new ConfigError(file, `not valid JSON (${String(cause)})`);
   }
-  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`);
-    }
-  }
-  const raw = top["instances"];
-  if (raw !== undefined && !Array.isArray(raw)) {
-    throw new ConfigError(file, "instances must be an array of config homes");
-  }
-  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`);
-    }
-    if (seen.has(dir)) throw new ConfigError(file, `instances[${index}].dir repeats ${dir}`);
-    seen.add(dir);
-    return { dir, settings };
-  });
-  return {
-    defaults: top["defaults"] === undefined ? {} : objectOf(file, "defaults", top["defaults"]),
-    instances,
-  };
+  return objectOf(file, "the top level", parsed);
+}
+
+/** The address another instance on this host is dialled at, when its file
+ * states no public one.
+ *
+ * A bind of every address is not an address, so a host that listens on all of
+ * them is reached at the loopback one — the peer doing the dialling is on this
+ * machine, and that is the address it has. */
+function localEndpoint(entry: EntryConfig): Endpoint {
+  const host = entry.host === "0.0.0.0" || entry.host === "::" ? "127.0.0.1" : entry.host;
+  const at = host.includes(":") ? `[${host}]` : host;
+  return `http://${at}:${String(entry.port)}/` as 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 instances this host runs, in the order its clusters list them. */
+export async function loadInstances(configDir: string): Promise<readonly InstanceSetting[]> {
+  return (await loadAll(configDir)).instances;
 }
 
-/** How one field of the shared file combines an instance's entry with the
- * defaults.
+/** What one config home's instance runs with. A config home no cluster lists
+ * still resolves — `daemon run` on an unregistered directory is what
+ * `config.ts` returns, plus the built-ins. */
+export async function loadConfig(configDir: string, dir: string): Promise<InstanceConfig> {
+  const all = await loadAll(configDir);
+  return all.instances.find((one) => one.dir === dir)?.config ?? all.defaults;
+}
+
+/** Put the declarations a config file writes against beside the files that
+ * write against them.
  *
- * `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";
+ * 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;
+}
 
-/** 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.
+/** Import one config file and call what it exports.
  *
- * 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",
-};
+ * 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<unknown> {
+  let module: { default?: unknown };
+  try {
+    module = (await import(`${file}?mtime=${String(statSync(file).mtimeMs)}`)) as {
+      default?: unknown;
+    };
+  } catch (cause) {
+    throw new ConfigError(file, `cannot be loaded (${String(cause)})`);
+  }
+  const define = module.default;
+  if (typeof define !== "function") {
+    throw new ConfigError(
+      file,
+      "must default export a function taking { config } and returning it",
+    );
+  }
+  try {
+    return await (define as (given: unknown) => unknown)(ctx);
+  } catch (cause) {
+    if (cause instanceof ConfigError) throw cause;
+    throw new ConfigError(file, `threw while being read (${String(cause)})`);
+  }
+}
 
-function ruleFor(path: string): MergeRule {
-  return MERGE_RULES[path] ?? "replace";
+/** What one config function handed back, checked at the shape an instance uses
+ * it. */
+function settingsOf(
+  file: string,
+  returned: unknown,
+  wantsDir: boolean,
+): { dir: string; name: string; config: InstanceConfig } {
+  const fields = objectOf(file, "what the config function returned", returned);
+  for (const name of Object.keys(fields)) {
+    if ((INSTANCE_FIELDS as readonly string[]).includes(name)) {
+      if (wantsDir) continue;
+      throw new ConfigError(
+        file,
+        `${name} belongs to an ${INSTANCES_DIR}/ file, which this is not`,
+      );
+    }
+    if (name === "peers") {
+      // Said as its own refusal rather than as an unknown field, because a
+      // person writing one is not misspelling anything: they are stating a
+      // mesh, and the answer is where a mesh is stated now.
+      throw new ConfigError(
+        file,
+        `peers are not written here: a mesh belongs to a cluster, so the instances of one are the ids its ${CLUSTERS_DIR}/ file lists and the rest are that file's peers (ccmsg mesh add)`,
+      );
+    }
+    if (!(FIELDS as readonly string[]).includes(name)) {
+      throw new ConfigError(file, `unknown field ${name}; expected ${FIELDS.join(", ")}`);
+    }
+  }
+  const dir = fields["dir"];
+  if (wantsDir && (typeof dir !== "string" || !isAbsolute(dir))) {
+    throw new ConfigError(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))) {
+    throw new ConfigError(file, "name must be a label in lower case, digits, dots, dashes");
+  }
+  return {
+    dir: wantsDir ? (dir as string) : "",
+    name: typeof name === "string" ? name : "",
+    config: parseConfig(file, fields),
+  };
 }
 
-function plainObject(raw: unknown): raw is Record<string, unknown> {
-  return typeof raw === "object" && raw !== null && !Array.isArray(raw);
+/** 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 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;
-  }
-  return out;
+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);
 }
 
-/** 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 ?? {}, "");
+/** The mutable copy a config function edits and returns.
+ *
+ * Without `peers`, which is the one field of a config that no file writes: it
+ * is derived from the instances of this host and `peers.json`, so handing it
+ * over would be offering a value that is ignored — and a file that returned it
+ * unchanged would be returning a field this refuses.  */
+function copied(value: InstanceConfig): Record<string, unknown> {
+  const { peers: _derived, ...written } = structuredClone(value);
+  return written 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"]),
+    // Filled in by whoever read the config home, which is the only place the
+    // mesh is known: one file states one instance, and a mesh is every one of
+    // them plus what `peers.json` names.
+    peers: [],
+    ...(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 +793,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"];