pi-onlyne 2.3.0 → 2.4.0

package/src/socket.mjs

@@ -15,7 +15,8 @@
 // tree to fall back on: it has to find the client the way the plan says an
 // external runtime does (`docs/v2-PLAN.md` line 289), by reading the
 // registration files in the runtime directory — `<digest>.json`, one per live
-// endpoint, holding `kind`, `role`, `root`, `pid`, `version` and `runtime`.
+// endpoint, holding `kind`, `role`, `cluster`, `root`, `pid`, `version` and
+// `runtime`.
 //
 // So a hand-started pi reads those files and the order of its answers is:
 //
@@ -182,7 +183,7 @@ export function registrationPath(root, env, options = {}) {
  *
  * @param {Record<string, string | undefined>} env
  * @param {{ readFile?: (path: string) => string, readDir?: (path: string) => string[], realpath?: (path: string) => string, uid?: number | null }} [options]
- * @returns {{ path: string, root: string, kind: string | null, runtime: string | null }[]}
+ * @returns {{ path: string, root: string, kind: string | null, role: string | null, runtime: string | null, cluster: string | null }[]}
  */
 export function listClientRegistrations(env, options = {}) {
   const readDir = options.readDir ?? ((path) => readdirSync(path));
@@ -212,6 +213,7 @@ export function listClientRegistrations(env, options = {}) {
       kind: parsed.kind,
       role: typeof parsed.role === "string" && parsed.role !== "" ? parsed.role : null,
       runtime: typeof parsed.runtime === "string" && parsed.runtime !== "" ? parsed.runtime : null,
+      cluster: typeof parsed.cluster === "string" && parsed.cluster !== "" ? parsed.cluster : null,
     });
   }
   return found;
@@ -227,10 +229,28 @@ export function listClientRegistrations(env, options = {}) {
  * the moment `onlyne-client` binds the socket. When a client registration for
  * `role` appears in `<runtime_dir>`, it prefers that registration's socket.
  *
+ * A role name is per cluster, not per machine: two clusters on one machine both
+ * run `lazuli`, and the runtime directory carries one registration per client.
+ * The declared cluster answers first: when `options.cluster` names one, the
+ * registration of that role in that cluster is the answer, whatever tree this
+ * session runs in. That is the sandwiched agent — started from one cluster's
+ * root, its role workspace living in another — which the tree below would
+ * otherwise answer with the wrong client, and whose frames that client drops
+ * as another workspace's. Where one cluster holds several clients of the role,
+ * that is a fault of the cluster and refused by name.
+ *
+ * Without a usable declared cluster, the tree this session runs in decides
+ * between the role's clients, in either direction — `workspaceRoot` above the
+ * registered root (a resident started in the cluster root, its role workspace
+ * below) or below it. Where that leaves several, the resolution is refused
+ * rather than answered with the deterministic path: with a client of that role
+ * already running elsewhere, nothing binds that path, and every frame written
+ * to it is a silently dropped message (field report 2026-10-21, issue 1).
+ *
  * @param {Record<string, string | undefined>} env
  * @param {string} workspaceRoot
  * @param {string} role
- * @param {{ readFile?: (path: string) => string, readDir?: (path: string) => string[], realpath?: (path: string) => string, uid?: number | null, runtime?: string }} [options]
+ * @param {{ readFile?: (path: string) => string, readDir?: (path: string) => string[], realpath?: (path: string) => string, uid?: number | null, runtime?: string, cluster?: string | null }} [options]
  * @returns {string}
  */
 export function resolveResidentSocketPath(env, workspaceRoot, role, options = {}) {
@@ -240,17 +260,48 @@ export function resolveResidentSocketPath(env, workspaceRoot, role, options = {}
   const dir = runtimeDir(env, options);
   const here = canonicalRoot(workspaceRoot, options);
   const candidates = listClientRegistrations(env, options);
+  const socketOf = (entry) => join(dir, `${workspaceDigest(entry.root, options)}${SOCKET_SUFFIX}`);
+
+  // The cluster the session declares outranks the tree it happens to run in:
+  // a body in one cluster's workspace and a workspace in another's is exactly
+  // what tree containment gets wrong. An unknown cluster is not an error — it
+  // is a session whose file predates clustering, or names one whose client is
+  // not up yet — so it falls through to the tree rules below.
+  const cluster = typeof options.cluster === "string" && options.cluster.trim() !== "" ? options.cluster.trim() : null;
+  if (cluster) {
+    const byCluster = candidates.filter((entry) => entry.cluster === cluster && (!role || entry.role === role));
+    if (byCluster.length === 1) return socketOf(byCluster[0]);
+    if (byCluster.length > 1) {
+      throw new SocketResolutionError(
+        `onlyne: ${byCluster.length} clients are registered as role ${role ?? "?"} in cluster ${cluster} — ` +
+          `${describe(byCluster)} — so which one serves this session is ambiguous. ` +
+          "Start this workspace's client, or name the socket with ONLYNE_SOCKET",
+        byCluster,
+      );
+    }
+  }
 
   const coveringRole = candidates.filter((entry) => covers(entry.root, here) && (!role || !entry.role || entry.role === role));
   if (coveringRole.length > 0) {
     const nearest = coveringRole.reduce((best, entry) => (entry.root.length > best.root.length ? entry : best));
-    return join(dir, `${workspaceDigest(nearest.root, options)}${SOCKET_SUFFIX}`);
+    return socketOf(nearest);
   }
 
   if (role) {
     const byRole = candidates.filter((entry) => entry.role === role);
     if (byRole.length === 1) {
-      return join(dir, `${workspaceDigest(byRole[0].root, options)}${SOCKET_SUFFIX}`);
+      return socketOf(byRole[0]);
+    }
+    if (byRole.length > 1) {
+      const inTree = byRole.filter((entry) => covers(here, entry.root) || covers(entry.root, here));
+      if (inTree.length === 1) return socketOf(inTree[0]);
+      throw new SocketResolutionError(
+        `onlyne: ${byRole.length} clients are registered as role ${role} — ${describe(byRole)} — ` +
+          `and ${inTree.length === 0 ? "none of them is" : `${inTree.length} of them are`} ` +
+          `in this workspace's tree (${here}), so which one serves this session is ambiguous. ` +
+          "Start this workspace's client, or name the socket with ONLYNE_SOCKET",
+        inTree.length > 0 ? inTree : byRole,
+      );
     }
   }
 
@@ -322,9 +373,13 @@ function covers(root, here) {
   return root === here || here.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
 }
 
-/** `<path> (root <root>, runtime <runtime>)` per entry, for an error message. */
+/** `<path> (root <root>, runtime <runtime>, cluster <cluster>)` per entry, for an error message. */
 function describe(entries) {
   return entries
-    .map((entry) => `${entry.path} (root ${entry.root}, runtime ${entry.runtime ?? "-"})`)
+    .map(
+      (entry) =>
+        `${entry.path} (root ${entry.root}, runtime ${entry.runtime ?? "-"}` +
+        `${entry.cluster ? `, cluster ${entry.cluster}` : ""})`,
+    )
     .join(", ");
 }

package/src/socket.test.mjs

@@ -51,9 +51,11 @@ function registrationName(root) {
 }
 
 /** The registration of one client whose sessions run under `runtime`. */
-function client(root, runtimeName = "pi") {
-  // The writer's spelling is the canonical one (`RegistrationFile::new`).
-  return { kind: "client", role: "planner", root: canonicalRoot(root), pid: 4242, version: "0.2.0", runtime: runtimeName };
+function client(root, runtimeName = "pi", role = "planner", cluster = null) {
+  // The writer's spelling is the canonical one (`RegistrationFile::new`), and
+  // `cluster` is written only when the client's server names one.
+  const body = { kind: "client", role, root: canonicalRoot(root), pid: 4242, version: "0.2.0", runtime: runtimeName };
+  return cluster === null ? body : { ...body, cluster };
 }
 
 /** The env a client-spawned session carries, with the runtime directory pinned. */
@@ -262,3 +264,128 @@ test("resolveResidentSocketPath falls back to deterministic socket before client
     socketPath(roleWs, envFor(liveDir)),
   );
 });
+
+test("a role name two clusters share resolves to the client in this tree", () => {
+  const chamber = scratch("pi-onlyne-chamber-");
+  const workshop = scratch("pi-onlyne-workshop-");
+  const chamberRole = join(chamber, "lazuli");
+  const workshopRole = join(workshop, "lazuli");
+  mkdirSync(chamberRole, { recursive: true });
+  mkdirSync(workshopRole, { recursive: true });
+  const dir = runtime([
+    { name: registrationName(workshopRole), body: client(workshopRole, "pi", "lazuli") },
+    { name: registrationName(chamberRole), body: client(chamberRole, "pi", "lazuli") },
+  ]);
+
+  // The field report's shape: a resident started in the cluster root, its own
+  // role workspace below it, and another cluster's client of the same role
+  // elsewhere on the machine. The tree decides; two role matches no longer
+  // mean no answer.
+  assert.equal(resolveResidentSocketPath(envFor(dir), chamber, "lazuli"), socketPath(chamberRole, envFor(dir)));
+  // From inside the role workspace the same client answers: there the
+  // registered root contains this one.
+  assert.equal(resolveResidentSocketPath(envFor(dir), chamberRole, "lazuli"), socketPath(chamberRole, envFor(dir)));
+});
+
+test("a role no client in this tree serves is refused, never dialed on the deterministic path", () => {
+  const first = scratch("pi-onlyne-cluster-");
+  const second = scratch("pi-onlyne-cluster-");
+  const unrelated = scratch("pi-onlyne-ws-");
+  const firstRole = join(first, "lazuli");
+  const secondRole = join(second, "lazuli");
+  mkdirSync(firstRole, { recursive: true });
+  mkdirSync(secondRole, { recursive: true });
+  const elsewhere = runtime([
+    { name: registrationName(firstRole), body: client(firstRole, "pi", "lazuli") },
+    { name: registrationName(secondRole), body: client(secondRole, "pi", "lazuli") },
+  ]);
+
+  // Neither candidate is in this tree's chain in either direction, so which
+  // lazuli serves this session has no answer — and the deterministic path
+  // belongs to no client, which is the socket the report wrote into.
+  const error = refusal(() => resolveResidentSocketPath(envFor(elsewhere), unrelated, "lazuli"));
+  assert.match(error.message, /2 clients are registered as role lazuli/);
+  assert.match(error.message, /ambiguous/);
+  assert.equal(error.candidates.length, 2);
+  assert.ok(
+    !error.message.includes(socketPath(unrelated, envFor(elsewhere))),
+    "the refusal names the candidates, not the socket nothing binds",
+  );
+
+  // Several same-named clients inside one tree are the same question: no
+  // nearest root names a single client, so it is refused as well.
+  const parent = scratch("pi-onlyne-parent-");
+  const leftRole = join(parent, "left", "lazuli");
+  const rightRole = join(parent, "right", "lazuli");
+  mkdirSync(leftRole, { recursive: true });
+  mkdirSync(rightRole, { recursive: true });
+  const nested = runtime([
+    { name: registrationName(leftRole), body: client(leftRole, "pi", "lazuli") },
+    { name: registrationName(rightRole), body: client(rightRole, "pi", "lazuli") },
+  ]);
+  const nestedError = refusal(() => resolveResidentSocketPath(envFor(nested), parent, "lazuli"));
+  assert.match(nestedError.message, /2 of them are in this workspace's tree/);
+  assert.equal(nestedError.candidates.length, 2);
+});
+
+test("the declared cluster answers before the tree a sandwiched agent runs in", () => {
+  // The sandwiched agent: its body runs inside `chamber`'s tree, and the role
+  // workspace it serves lives in `workshop`. Tree containment answers with
+  // chamber's client, whose frames the workshop's client never sees, so the
+  // declaration has to outrank the tree.
+  const chamber = scratch("pi-onlyne-chamber-");
+  const workshop = scratch("pi-onlyne-workshop-");
+  const chamberRole = join(chamber, "lazuli");
+  const workshopRole = join(workshop, "lazuli");
+  mkdirSync(chamberRole, { recursive: true });
+  mkdirSync(workshopRole, { recursive: true });
+  const dir = runtime([
+    { name: registrationName(chamberRole), body: client(chamberRole, "pi", "lazuli", "chamber") },
+    { name: registrationName(workshopRole), body: client(workshopRole, "pi", "lazuli", "workshop") },
+  ]);
+
+  assert.equal(
+    resolveResidentSocketPath(envFor(dir), chamber, "lazuli", { cluster: "workshop" }),
+    socketPath(workshopRole, envFor(dir)),
+  );
+  // Declaring the cluster the tree already sits in changes nothing.
+  assert.equal(
+    resolveResidentSocketPath(envFor(dir), chamber, "lazuli", { cluster: "chamber" }),
+    socketPath(chamberRole, envFor(dir)),
+  );
+
+  // A cluster no client of this role registered, a blank declaration, and no
+  // declaration at all: each falls back to tree containment.
+  for (const options of [{ cluster: "nowhere" }, { cluster: "   " }, {}]) {
+    assert.equal(
+      resolveResidentSocketPath(envFor(dir), chamber, "lazuli", options),
+      socketPath(chamberRole, envFor(dir)),
+    );
+  }
+});
+
+test("two clients of the role in the declared cluster are refused by name", () => {
+  const cluster = scratch("pi-onlyne-cluster-");
+  const leftRole = join(cluster, "left", "lazuli");
+  const rightRole = join(cluster, "right", "lazuli");
+  const elsewhereRole = join(cluster, "elsewhere", "lazuli");
+  for (const role of [leftRole, rightRole, elsewhereRole]) mkdirSync(role, { recursive: true });
+  const dir = runtime([
+    { name: registrationName(leftRole), body: client(leftRole, "pi", "lazuli", "house") },
+    { name: registrationName(rightRole), body: client(rightRole, "pi", "lazuli", "house") },
+    { name: registrationName(elsewhereRole), body: client(elsewhereRole, "pi", "lazuli", "other") },
+  ]);
+
+  // The tree holds one of the two, which is not an answer: the declaration
+  // named a cluster serving this role twice, so the cluster is the fault.
+  const error = refusal(() =>
+    resolveResidentSocketPath(envFor(dir), cluster, "lazuli", { cluster: "house" }),
+  );
+  assert.match(error.message, /2 clients are registered as role lazuli in cluster house/);
+  assert.match(error.message, /ambiguous/);
+  assert.equal(error.candidates.length, 2);
+  assert.ok(
+    error.candidates.every((entry) => entry.cluster === "house"),
+    "the refusal names the cluster's own clients, not the other cluster's",
+  );
+});