elanous 0.2.0 → 0.2.4

package/src/control-plane/member-tokens.ts

@@ -0,0 +1,88 @@
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { chmodSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+
+interface MemberTokenEntry { sha256: string; issuedAt: string }
+type MemberTokenStore = Record<string, MemberTokenEntry>;
+
+function pathFor(root: string): string {
+  return join(root, 'control', 'member-tokens.json');
+}
+
+function validMachine(machine: string): boolean {
+  return /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(machine) && !['__proto__', 'constructor', 'prototype'].includes(machine);
+}
+
+function checkMachine(machine: string): void {
+  if (!validMachine(machine)) throw new Error('invalid control machine');
+}
+
+function readStore(root: string): MemberTokenStore {
+  const path = pathFor(root);
+  let contents: string;
+  try { contents = readFileSync(path, 'utf8'); }
+  catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return {};
+    throw err;
+  }
+  const parsed: unknown = JSON.parse(contents);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) ||
+      !Object.entries(parsed).every(([machine, entry]) =>
+        validMachine(machine) && entry !== null && typeof entry === 'object' && !Array.isArray(entry) &&
+        Object.keys(entry).length === 2 &&
+        typeof (entry as MemberTokenEntry).sha256 === 'string' && /^[a-f0-9]{64}$/.test((entry as MemberTokenEntry).sha256) &&
+        typeof (entry as MemberTokenEntry).issuedAt === 'string' && !Number.isNaN(Date.parse((entry as MemberTokenEntry).issuedAt)))) {
+    throw new Error('invalid control member tokens file');
+  }
+  const entries = parsed as MemberTokenStore;
+  if (new Set(Object.values(entries).map(entry => entry.sha256)).size !== Object.keys(entries).length) {
+    throw new Error('duplicate control member tokens');
+  }
+  if ((statSync(path).mode & 0o077) !== 0) chmodSync(path, 0o600);
+  return entries;
+}
+
+function writeStore(root: string, entries: MemberTokenStore): void {
+  const path = pathFor(root);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temp, JSON.stringify(entries), { flag: 'wx', mode: 0o600 });
+    renameSync(temp, path);
+  } catch (err) {
+    try { unlinkSync(temp); } catch { /* no temporary file */ }
+    throw err;
+  }
+}
+
+export function issueMemberToken(machine: string, root: string = effectiveInstanceRoot()): string {
+  checkMachine(machine);
+  const entries = readStore(root);
+  const token = randomBytes(32).toString('hex');
+  entries[machine] = { sha256: createHash('sha256').update(token).digest('hex'), issuedAt: new Date().toISOString() };
+  writeStore(root, entries);
+  return token;
+}
+
+export function revokeMemberToken(machine: string, root: string = effectiveInstanceRoot()): void {
+  checkMachine(machine);
+  const entries = readStore(root);
+  if (Object.hasOwn(entries, machine)) {
+    delete entries[machine];
+    writeStore(root, entries);
+  }
+}
+
+export function listMemberTokens(root: string = effectiveInstanceRoot()): Array<{ machine: string; issuedAt: string }> {
+  return Object.entries(readStore(root)).map(([machine, { issuedAt }]) => ({ machine, issuedAt }));
+}
+
+export function machineForToken(token: string, root: string = effectiveInstanceRoot()): string | undefined {
+  const digest = createHash('sha256').update(token).digest();
+  let match: string | undefined;
+  for (const [machine, { sha256 }] of Object.entries(readStore(root))) {
+    if (timingSafeEqual(digest, Buffer.from(sha256, 'hex'))) match = machine;
+  }
+  return match;
+}

package/src/control-plane/member.ts

@@ -0,0 +1,159 @@
+import { readFileSync } from 'node:fs';
+import { cpus, freemem, loadavg, totalmem } from 'node:os';
+import { join } from 'node:path';
+import { debug } from '../debug/log.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { readPrimaryJoin } from './primary.js';
+import { resolveMachineName } from '../roles/machine-name.js';
+import { readMachineProfile } from '../roles/machine-profile.js';
+
+const DEFAULT_INTERVAL_MS = 30_000;
+const MAX_RETRY_MS = 300_000;
+// Ordinary ticks start within the 10-minute TTL; first failure retries within 30 seconds.
+const MAX_INTERVAL_MS = MAX_RETRY_MS;
+const REQUEST_TIMEOUT_MS = 5_000;
+
+export function measureLoad(now: () => number = Date.now): {
+  loadAvg: number[]; cpuCount: number; freeMem: number; totalMem: number; observedAt: number;
+} {
+  return {
+    loadAvg: loadavg(), cpuCount: cpus().length,
+    freeMem: freemem(), totalMem: totalmem(), observedAt: now(),
+  };
+}
+
+/** Read only the member credential. A missing or malformed file never creates credentials. */
+export function readMemberToken(root: string = effectiveInstanceRoot()): string | undefined {
+  const joined = readPrimaryJoin(root)?.tokens.member;
+  if (joined) return joined;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(join(root, 'control', 'tokens.json'), 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return undefined;
+    const token = (parsed as Record<string, unknown>).member;
+    return typeof token === 'string' && /^[a-f0-9]{64}$/.test(token) ? token : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export interface MemberResource {
+  id: string;
+  name: string;
+  attrs?: Record<string, unknown>;
+}
+
+export interface MemberHeartbeatOptions {
+  coordinatorUrl: string;
+  token: string;
+  machine: MemberResource;
+  instance: MemberResource & { endpoint: string };
+  intervalMs?: number;
+  fetch?: (input: URL | RequestInfo, init?: RequestInit) => Promise<Response>;
+  now?: () => number;
+}
+
+/** 넥서스 멤버의 기계 신원 — OS hostname 이 아니라 임대·관제가 쓰는 기계 식별자(`resolveMachineName`)를 쓴다.
+ *  🅢 09-27: mbp 넥서스가 `machine:MacBookProM5` 로 올라가 프로필 id `mbp` 와 어긋날 뻔했다(가벼운 멤버는 이미 id 를 쓴다).
+ *  프로필이 있으면 맡은 일·자리 순위를 속성에 싣는다(가벼운 멤버와 같은 칸). */
+export function nexusMemberMachine(root: string = effectiveInstanceRoot(), host?: string): MemberResource {
+  const { machine } = resolveMachineName({ root, ...(host ? { host } : {}) });
+  const profile = readMachineProfile(root);
+  return {
+    id: `machine:${machine}`, name: machine,
+    ...(profile && profile.id === machine ? { attrs: { duties: profile.duties, seats: profile.seats } } : {}),
+  };
+}
+
+/** Best-effort registration; no network work is awaited by the caller. */
+export function startMemberHeartbeat(opts: MemberHeartbeatOptions): () => void {
+  const interval = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+  if (!Number.isFinite(interval) || interval <= 0 || interval > MAX_INTERVAL_MS) throw new Error('invalid member heartbeat interval');
+  const base = new URL(opts.coordinatorUrl);
+  if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password) throw new Error('invalid coordinator URL');
+  if (!opts.token || !opts.machine.id || !opts.instance.id || !opts.instance.endpoint) throw new Error('missing member configuration');
+  const send = opts.fetch ?? globalThis.fetch;
+  const now = opts.now ?? Date.now;
+  const controller = new AbortController();
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let registered = false;
+  let heartbeatsSinceInstanceRefresh = 0;
+  let failures = 0;
+  let lastFailure: string | undefined;
+  const machineId = opts.machine.id;
+  // 자원의 `machine` 칸 = 기계 «이름»(가벼운 멤버·임대와 같은 값). 기계 범위 토큰은 이 칸을 토큰의 기계와 대조한다(server.ts requireMachine).
+  const machineName = opts.machine.name;
+
+  const post = async (path: string, body: unknown): Promise<void> => {
+    const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+    const signal = AbortSignal.any([controller.signal, timeout]);
+    let response: Response;
+    try {
+      response = await send(new URL(path, base), {
+        method: 'POST',
+        headers: { authorization: `Bearer ${opts.token}`, 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+        signal,
+      });
+    } catch {
+      throw new Error('network-or-timeout');
+    }
+    if (!response.ok) {
+      if (response.status === 404 && path.endsWith('/heartbeat')) registered = false;
+      throw new Error(`http-${response.status}`);
+    }
+  };
+  const register = async (): Promise<void> => {
+    await post('/v1/resources/register', {
+      ...opts.machine, kind: 'machine', machine: machineName, owner: '',
+      attrs: { ...opts.machine.attrs, load: measureLoad(now) }, observedAt: now(), ttlMs: MAX_RETRY_MS * 2,
+    });
+    await post('/v1/resources/register', {
+      ...opts.instance, kind: 'instance', machine: machineName, owner: '',
+      attrs: opts.instance.attrs ?? {}, observedAt: now(), ttlMs: MAX_RETRY_MS * 2,
+    });
+    registered = true;
+    heartbeatsSinceInstanceRefresh = 0;
+  };
+  const schedule = (ms: number): void => {
+    if (stopped) return;
+    timer = setTimeout(() => { void tick(); }, ms);
+    timer.unref?.();
+  };
+  const tick = async (): Promise<void> => {
+    if (stopped) return;
+    try {
+      if (!registered) await register();
+      else {
+        await post(`/v1/resources/${encodeURIComponent(machineId)}/heartbeat`, { attrs: { load: measureLoad(now) } });
+        heartbeatsSinceInstanceRefresh++;
+        if (heartbeatsSinceInstanceRefresh * interval >= MAX_RETRY_MS) {
+          await post(`/v1/resources/${encodeURIComponent(opts.instance.id)}/heartbeat`, {});
+          heartbeatsSinceInstanceRefresh = 0;
+        }
+      }
+      if (stopped) return;
+      failures = 0;
+      schedule(interval);
+    } catch (error) {
+      if (stopped) return;
+      const reason = error instanceof Error ? error.message : 'unknown';
+      if (reason !== lastFailure) {
+        try { debug.log('control.member', 'heartbeat-failed', { reason }); } catch { /* logging is best-effort */ }
+      }
+      lastFailure = reason;
+      failures++;
+      // A lost record needs immediate re-registration. Other failures retry ahead of
+      // the ordinary tick so a single timeout at the longest interval cannot exceed TTL.
+      schedule(!registered && reason === 'http-404'
+        ? 0
+        : Math.min(MAX_RETRY_MS, Math.min(interval, DEFAULT_INTERVAL_MS) * 2 ** (failures - 1)));
+    }
+  };
+  queueMicrotask(() => { void tick(); });
+  return () => {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+    controller.abort();
+  };
+}

package/src/control-plane/port-lease-heartbeat.ts

@@ -0,0 +1,101 @@
+import { readMemberToken } from './member.js';
+import { PORT_BANDS } from './ports.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+
+const RENEW_MS = 30_000;
+const RETRY_MS = 5_000;
+export const PORT_LEASE_TTL_MS = 600_000;
+// Stop before the coordinator can reassign the port, including request timeout and shutdown time.
+const EXPIRY_MARGIN_MS = 10_000;
+
+/** The detached NEXUS owns renewal and cleanup; the short-lived launcher never holds a timer. */
+export async function startPortLeaseHeartbeat(port: number, leaseId: string, options: {
+  fetchFn?: (url: string, init: RequestInit) => Promise<Response>;
+  token?: string;
+  intervalMs?: number;
+  retryMs?: number;
+  now?: () => number;
+  onError?: (error: Error) => void;
+  onLeaseLost: (error: Error) => void;
+}): Promise<() => Promise<void>> {
+  if (!Number.isInteger(port) || port < PORT_BANDS.test.start || port > PORT_BANDS.test.end) throw new Error('invalid coordinator lease port');
+  if (!leaseId?.trim()) throw new Error('missing coordinator lease id');
+  if ((options.intervalMs !== undefined && (!Number.isFinite(options.intervalMs) || options.intervalMs <= 0 || options.intervalMs >= PORT_LEASE_TTL_MS - EXPIRY_MARGIN_MS)) ||
+      (options.retryMs !== undefined && (!Number.isFinite(options.retryMs) || options.retryMs <= 0))) throw new Error('invalid coordinator renewal interval');
+  const token = options.token ?? readMemberToken(effectiveInstanceRoot());
+  if (!token) throw new Error('missing coordinator member token');
+  const send = options.fetchFn ?? fetch;
+  const now = options.now ?? Date.now;
+  const base = `http://127.0.0.1:${PORT_BANDS.reserved[0]}/v1/leases/port/${port}`;
+  const headers = { Authorization: `Bearer ${token}`, 'x-port-lease-id': leaseId };
+  let stopped = false;
+  let initialCheckDone = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
+  let pending: Promise<void> = Promise.resolve();
+  const startedAt = now();
+  let lastSuccess = startedAt;
+  const lost = (error: Error): void => {
+    if (stopped) return;
+    stopped = true;
+    if (timer) clearTimeout(timer);
+    if (deadlineTimer) clearTimeout(deadlineTimer);
+    if (initialCheckDone) options.onLeaseLost(error);
+  };
+  const armDeadline = (): void => {
+    if (deadlineTimer) clearTimeout(deadlineTimer);
+    const remaining = lastSuccess + PORT_LEASE_TTL_MS - EXPIRY_MARGIN_MS - now();
+    if (remaining <= 0) { lost(new Error('coordinator port lease renewal deadline exceeded')); return; }
+    deadlineTimer = setTimeout(() => lost(new Error('coordinator port lease renewal deadline exceeded')), remaining);
+  };
+  const renew = async (): Promise<void> => {
+    try {
+      const response = await send(`${base}/heartbeat`, {
+        method: 'POST', headers, signal: AbortSignal.timeout(1000),
+      });
+      if (!response.ok) throw new Error(`coordinator lease renewal HTTP ${response.status}`);
+      if (!stopped) {
+        const receivedAt = now();
+        if (receivedAt >= lastSuccess + PORT_LEASE_TTL_MS - EXPIRY_MARGIN_MS) {
+          lost(new Error('coordinator port lease renewal deadline exceeded'));
+          return;
+        }
+        lastSuccess = receivedAt;
+        armDeadline();
+        if (!stopped) timer = setTimeout(tick, options.intervalMs ?? RENEW_MS);
+      }
+    } catch (error) {
+      if (stopped) return;
+      const failure = error instanceof Error ? error : new Error(String(error));
+      try { options.onError?.(failure); } catch { /* logging must not interrupt renewal */ }
+      if (now() >= lastSuccess + PORT_LEASE_TTL_MS - EXPIRY_MARGIN_MS || [400, 403, 404, 409].some(status => failure.message === `coordinator lease renewal HTTP ${status}`)) lost(failure);
+      else timer = setTimeout(tick, Math.min(options.retryMs ?? RETRY_MS, lastSuccess + PORT_LEASE_TTL_MS - EXPIRY_MARGIN_MS - now()));
+    }
+    timer?.unref?.();
+  };
+  const tick = (): void => { if (!stopped) pending = renew(); };
+  const initial = await send(`${base}/heartbeat`, {
+    method: 'POST', headers, signal: AbortSignal.timeout(1000),
+  });
+  if (!initial.ok) throw new Error(`coordinator lease renewal HTTP ${initial.status}`);
+  const confirmedAt = now();
+  if (confirmedAt >= startedAt + PORT_LEASE_TTL_MS - EXPIRY_MARGIN_MS) throw new Error('coordinator port lease renewal deadline exceeded');
+  lastSuccess = confirmedAt;
+  armDeadline();
+  if (stopped) throw new Error('coordinator port lease renewal deadline exceeded');
+  initialCheckDone = true;
+  if (!stopped) timer = setTimeout(tick, options.intervalMs ?? RENEW_MS);
+  timer?.unref?.();
+  return async () => {
+    if (!stopped) {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+      if (deadlineTimer) clearTimeout(deadlineTimer);
+    }
+    await pending;
+    const response = await send(base, {
+      method: 'DELETE', headers, signal: AbortSignal.timeout(1000),
+    });
+    if (!response.ok && response.status !== 404 && response.status !== 403) throw new Error(`coordinator lease release HTTP ${response.status}`);
+  };
+}

package/src/control-plane/ports.ts

@@ -0,0 +1,40 @@
+import { ResourceLedger, ResourceLedgerError, type ResourceRecord } from './ledger.js';
+import { DEFAULT_NEXUS_HTTP_PORT } from '../nexus/default-port.js';
+
+/** Inclusive port bands; only the test band is allocated by the coordinator. */
+export const PORT_BANDS = {
+  reserved: [31413, DEFAULT_NEXUS_HTTP_PORT, 31420],
+  test: { start: 31450, end: 31499 },
+  offline: { start: 31500, end: 31509 },
+} as const;
+
+/** 한 번의 임대가 가질 수 있는 최장 수명(24시간). 이보다 긴 요청은 이 값으로 잘린다 — 죽은 주인이 대역을 영영 붙잡지 못하게. */
+export const MAX_PORT_LEASE_TTL_MS = 24 * 60 * 60 * 1000;
+
+export interface PortLeaseRequest {
+  machine: string;
+  purpose: string;
+  ttlMs: number;
+  /** Authenticated token fingerprint; direct callers default to their machine identity. */
+  owner?: string;
+  /** Ports rejected by a local bind probe during this allocation attempt. */
+  excluded?: readonly number[];
+}
+
+export function portLeaseId(port: number): string {
+  return `port-lease:${port}`;
+}
+
+/** Allocate the lowest unleased test port, replacing an expired lease if needed. */
+export function leasePort(request: PortLeaseRequest, ledger: ResourceLedger, now = Date.now()): ResourceRecord {
+  const { machine, purpose, ttlMs } = request;
+  if (!machine?.trim() || !purpose?.trim() || !Number.isFinite(ttlMs) || ttlMs <= 0 || !Number.isFinite(now) ||
+      (request.owner !== undefined && !request.owner.trim())) {
+    throw new ResourceLedgerError(400, 'invalid-port-lease');
+  }
+  if (request.excluded?.some(port => !Number.isInteger(port) || port < PORT_BANDS.test.start || port > PORT_BANDS.test.end)) {
+    throw new ResourceLedgerError(400, 'invalid-port-lease');
+  }
+  const owner = request.owner ?? machine;
+  return ledger.leaseTestPort({ machine, purpose, ttlMs: Math.min(ttlMs, MAX_PORT_LEASE_TTL_MS), owner }, PORT_BANDS.test, now, request.excluded);
+}

package/src/control-plane/primary.ts

@@ -0,0 +1,169 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { CONTROL_HOSTNAME, DEFAULT_CONTROL_PORT, type ControlScope } from './server.js';
+import { debug } from '../debug/log.js';
+
+export interface PrimaryJoin {
+  url: string;
+  tokens: Partial<Record<ControlScope, string>>;
+  machine?: string;
+}
+
+export interface PrimaryConfig {
+  url?: string;
+  tokens?: Partial<Record<ControlScope, string>>;
+  primaryCandidates?: Array<{ machine: string; url: string; tokens?: Partial<Record<ControlScope, string>> }>;
+}
+
+export interface PrimaryAddress {
+  url: string;
+  token: string | undefined;
+  source: 'config' | 'join' | 'local' | 'lease';
+  machine?: string;
+}
+
+const TOKEN_PATTERN = /^[a-f0-9]{64}$/;
+
+function address(value: string): string {
+  const url = new URL(value);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password ||
+      url.search || url.hash || url.pathname !== '/') throw new Error('invalid primary URL');
+  return url.origin;
+}
+
+function scopedTokens(value: unknown): Partial<Record<ControlScope, string>> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('invalid primary tokens');
+  const row = value as Record<string, unknown>;
+  if (Object.keys(row).some(key => !['admin', 'member', 'query'].includes(key))) throw new Error('invalid primary tokens');
+  for (const token of Object.values(row)) {
+    if (typeof token !== 'string' || !TOKEN_PATTERN.test(token)) throw new Error('invalid primary tokens');
+  }
+  return row as Partial<Record<ControlScope, string>>;
+}
+
+/** Publish only explicitly supplied credentials; never generate or widen scopes. */
+export function writePrimaryJoin(joinFile: PrimaryJoin, root: string = effectiveInstanceRoot()): void {
+  const value = { url: address(joinFile.url), tokens: scopedTokens(joinFile.tokens) };
+  const path = join(root, 'control', 'join.json');
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = `${path}.${randomBytes(8).toString('hex')}.tmp`;
+  try {
+    writeFileSync(temp, JSON.stringify(value), { flag: 'wx', mode: 0o600 });
+    renameSync(temp, path);
+    chmodSync(path, 0o600);
+  } finally {
+    rmSync(temp, { force: true });
+  }
+}
+
+/** A missing or damaged join file is not a source of authority. */
+export function readPrimaryJoin(root: string = effectiveInstanceRoot()): PrimaryJoin | undefined {
+  try {
+    const path = join(root, 'control', 'join.json');
+    if ((statSync(path).mode & 0o077) !== 0) return undefined;
+    const value: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+    const row = value as Record<string, unknown>;
+    if (typeof row.url !== 'string') return undefined;
+    const url = address(row.url);
+    if (row.machine !== undefined || row.token !== undefined) {
+      if (typeof row.machine !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(row.machine) ||
+          ['__proto__', 'constructor', 'prototype'].includes(row.machine) ||
+          typeof row.token !== 'string' || !TOKEN_PATTERN.test(row.token)) return undefined;
+      return { url, machine: row.machine, tokens: { member: row.token } };
+    }
+    return { url, tokens: scopedTokens(row.tokens) };
+  } catch {
+    return undefined;
+  }
+}
+
+function localToken(root: string, role: ControlScope): string | undefined {
+  try {
+    const value: unknown = JSON.parse(readFileSync(join(root, 'control', 'tokens.json'), 'utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+    const token = (value as Record<string, unknown>)[role];
+    return typeof token === 'string' && TOKEN_PATTERN.test(token) ? token : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export interface ResolvePrimaryOptions {
+  root?: string;
+  config?: PrimaryConfig;
+  role: ControlScope;
+  port?: number;
+  fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+}
+
+/** URL precedence is independent of credentials: never send a token to a different address. */
+export function resolvePrimary(opts: ResolvePrimaryOptions & { config?: PrimaryConfig & { primaryCandidates?: never } }): PrimaryAddress;
+export function resolvePrimary(opts: ResolvePrimaryOptions & { config: PrimaryConfig & { primaryCandidates: NonNullable<PrimaryConfig['primaryCandidates']> } }): Promise<PrimaryAddress>;
+export function resolvePrimary(opts: ResolvePrimaryOptions): PrimaryAddress | Promise<PrimaryAddress>;
+export function resolvePrimary(opts: ResolvePrimaryOptions): PrimaryAddress | Promise<PrimaryAddress> {
+  const candidates = opts.config?.primaryCandidates;
+  if (candidates?.length) return resolveLeasePrimary(opts, candidates);
+  return resolveStaticPrimary(opts);
+}
+
+async function resolveLeasePrimary(opts: ResolvePrimaryOptions, candidates: NonNullable<PrimaryConfig['primaryCandidates']>): Promise<PrimaryAddress> {
+  const normalized = candidates.map(candidate => {
+    if (!/^[a-z0-9][a-z0-9-]{0,31}$/.test(candidate.machine)) throw new Error('invalid primary candidate machine');
+    return { machine: candidate.machine, url: address(candidate.url),
+      tokens: candidate.tokens === undefined ? undefined : scopedTokens(candidate.tokens) };
+  });
+  let winner: (typeof normalized)[number] & { generation: number } | undefined;
+  if (new Set(normalized.map(candidate => candidate.machine)).size !== normalized.length) throw new Error('duplicate primary candidate machine');
+  for (const candidate of normalized) {
+    try {
+      const response = await (opts.fetch ?? globalThis.fetch)(`${candidate.url}/v1/primary`, { signal: AbortSignal.timeout(5_000) });
+      if (!response.ok) continue;
+      const body: unknown = await response.json();
+      if (!body || typeof body !== 'object' || Array.isArray(body)) continue;
+      const value = body as Record<string, unknown>;
+      if (value.known !== true || typeof value.holder !== 'string' ||
+          !Number.isSafeInteger(value.generation) || (value.generation as number) < 1) continue;
+      const holder = normalized.find(item => item.machine === value.holder);
+      if (holder && (!winner || (value.generation as number) > winner.generation)) {
+        winner = { ...holder, generation: value.generation as number };
+      }
+    } catch { /* Unreachable candidate: try the next one. */ }
+  }
+  const selected = winner ?? normalized[0]!;
+  debug.log('control.primary', 'resolved', { source: 'lease', holder: winner?.machine ?? null, generation: winner?.generation ?? null });
+  const root = opts.root ?? effectiveInstanceRoot();
+  const joinFile = readPrimaryJoin(root);
+  const role = opts.role;
+  const configured = selected.tokens?.[role]
+    ?? (opts.config?.url && address(opts.config.url) === selected.url ? opts.config.tokens?.[role] : undefined);
+  if (configured !== undefined && !TOKEN_PATTERN.test(configured)) throw new Error('invalid primary token');
+  const joinToken = joinFile?.url === selected.url
+    ? (joinFile.tokens[role] ?? (role === 'query' ? joinFile.tokens.member : undefined)) : undefined;
+  const token = configured ?? joinToken
+    ?? (selected.url === `http://${CONTROL_HOSTNAME}:${opts.port ?? DEFAULT_CONTROL_PORT}` && joinFile?.url !== selected.url
+      ? localToken(root, role) : undefined);
+  return { url: selected.url, token, source: 'lease',
+    ...(joinFile?.url === selected.url && token !== undefined && token === joinToken && joinFile.machine ? { machine: joinFile.machine } : {}) };
+}
+
+function resolveStaticPrimary(opts: ResolvePrimaryOptions): PrimaryAddress {
+  const root = opts.root ?? effectiveInstanceRoot();
+  const joinFile = readPrimaryJoin(root);
+  const configUrl = opts.config?.url ? address(opts.config.url) : undefined;
+  const port = opts.port ?? DEFAULT_CONTROL_PORT;
+  const localUrl = `http://${CONTROL_HOSTNAME}:${port}`;
+  const url = configUrl ?? joinFile?.url ?? localUrl;
+  const source = configUrl ? 'config' : joinFile ? 'join' : 'local';
+  if (source === 'local' && (!Number.isInteger(port) || port < 1 || port > 65535)) throw new Error('invalid control port');
+  const configToken = opts.config?.tokens?.[opts.role];
+  if (configToken !== undefined && !TOKEN_PATTERN.test(configToken)) throw new Error('invalid primary token');
+  const joinToken = joinFile?.url === url
+    ? (joinFile.tokens[opts.role] ?? (opts.role === 'query' ? joinFile.tokens.member : undefined))
+    : undefined;
+  const token = configToken ?? joinToken
+    ?? (url === localUrl && joinFile?.url !== url ? localToken(root, opts.role) : undefined);
+  return { url, token, source, ...(joinFile?.url === url && token !== undefined && token === joinToken && joinFile.machine ? { machine: joinFile.machine } : {}) };
+}