@onlyne/lib 3.1.0 → 3.2.0

package/src/core.ts

@@ -1,114 +0,0 @@
-import type { AdmissionContext, Auth, ErrorCode, Failure, Mutation, NodeId, NodeOptions, Page, PageOptions, Storage, Transaction, TrustEntry } from './types.ts';
-import { trustPhase } from './types.ts';
-
-const statuses: Record<ErrorCode, number> = {
-  invalid_request: 400, unauthenticated: 401, forbidden: 403, not_a_member: 403,
-  not_found: 404, id_conflict: 409, revision_conflict: 409, request_in_progress: 409,
-  conflict: 409, thread_closed: 410, context_lost: 410, retry_window_expired: 410, cursor_expired: 410,
-  payload_too_large: 413, unsupported_media_type: 415, unsupported_delivery: 422,
-  ambiguous_target: 422, ambiguous_resource: 422, capacity_exceeded: 429,
-  internal: 500, unavailable: 503, decision_unavailable: 503,
-};
-export class OnlyneError extends Error {
-  readonly status: number;
-  readonly error: Failure;
-  constructor(code: ErrorCode, message: string, details?: Failure['details']) {
-    super(message);
-    this.status = statuses[code];
-    this.error = { code, message, retryable: code === 'unavailable' || code === 'decision_unavailable' || code === 'request_in_progress', ...(details === undefined ? {} : { details }) };
-  }
-}
-export function fail(code: ErrorCode, message: string, details?: Failure['details']): never { throw new OnlyneError(code, message, details); }
-export function requireValue<T>(value: T | undefined | null, code: ErrorCode = 'not_found'): T {
-  if (value == null) fail(code, 'The requested record is unavailable.');
-  return value;
-}
-export function key(...parts: string[]): string { return parts.map(encodeURIComponent).join('/'); }
-/**
- * The durable facts an admission policy decides from, bound to the transaction that is admitting
- * the message (RFC 0017 §4). A policy that opens its own storage transaction deadlocks: the
- * admission transaction still holds the store.
- */
-export function admissionView(tx: Transaction): AdmissionContext {
-  return {
-    async trust(node: NodeId) {
-      const entry = await tx.get<TrustEntry>(key('trust', node));
-      return entry === undefined ? undefined : trustPhase(entry);
-    },
-  };
-}
-export function canonical(value: unknown): string {
-  if (value === undefined) return 'null';
-  if (value === null || typeof value !== 'object') return JSON.stringify(value);
-  if (Array.isArray(value)) return '[' + value.map(canonical).join(',') + ']';
-  const record = value as Record<string, unknown>;
-  return '{' + Object.keys(record).filter(k => record[k] !== undefined).sort().map(k => JSON.stringify(k) + ':' + canonical(record[k])).join(',') + '}';
-}
-export function same(a: unknown, b: unknown): boolean { return canonical(a) === canonical(b); }
-
-/** Stable one-way digest of a canonical form. Tombstones keep digests, never content. */
-export async function fingerprint(value: unknown): Promise<string> {
-  const bytes = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonical(value)));
-  return Array.from(new Uint8Array(bytes)).map(b => b.toString(16).padStart(2, '0')).join('');
-}
-export function decimal(value: string): bigint {
-  if (!/^(0|[1-9][0-9]*)$/.test(value)) fail('invalid_request', 'Expected a decimal sequence string.');
-  return BigInt(value);
-}
-export function utc(value: string): number {
-  if (typeof value !== 'string' || !/^\d{4}-\d\d-\d\dT.*Z$/.test(value) || !Number.isFinite(Date.parse(value))) fail('invalid_request', 'Expected a UTC RFC3339 deadline.');
-  return Date.parse(value);
-}
-export function page<T>(items: T[], options: PageOptions, scope: unknown, position: (item: T) => string, compare: (a: string, b: string) => number = (a, b) => a < b ? -1 : a > b ? 1 : 0): Page<T> {
-  const size = options.page_size ?? 50;
-  if (!Number.isInteger(size) || size < 1 || size > 100) fail('invalid_request', 'page_size must be from 1 to 100.');
-  let after: string | undefined;
-  if (options.cursor) {
-    let cursor: { scope: unknown; after: string } | null;
-    try { cursor = JSON.parse(decodeURIComponent(options.cursor)); } catch { return fail('invalid_request', 'Invalid cursor.'); }
-    if (cursor === null || typeof cursor !== 'object' || !same(cursor.scope, scope) || typeof cursor.after !== 'string') fail('invalid_request', 'Cursor belongs to another query.');
-    after = cursor.after;
-  }
-  const remaining = after === undefined ? items : items.filter(item => compare(position(item), after!) > 0);
-  const selected = remaining.slice(0, size);
-  return { items: selected, next_cursor: remaining.length > size ? encodeURIComponent(canonical({ scope, after: position(selected[selected.length - 1]!) })) : null };
-}
-export interface Context {
-  node: string; baseUrl: string; instanceId: string; storage: Storage; options: NodeOptions;
-  now(): number; id(): string;
-  owner(owner: string): void;
-  deadline(retry_until: string): void;
-  mutate<T>(auth: Auth, operation: string, mutation: Mutation, body: unknown, work: (tx: Transaction) => Promise<T>): Promise<T>;
-}
-
-
-export function createContext(options: NodeOptions): Context {
-  const ctx: Context = {
-    node: options.node_id, baseUrl: options.base_url, instanceId: options.instance_id ?? crypto.randomUUID(), storage: options.plugins.storage, options,
-    now: options.now, id: options.id,
-    owner(owner) { if (owner !== options.node_id) fail('forbidden', 'This node does not serve the requested owner.'); },
-    deadline(until) {
-      const time = utc(until);
-      if (time <= ctx.now()) fail('retry_window_expired', 'The admission window expired.');
-      if (time > ctx.now() + (options.retry_max_ms ?? 86_400_000)) fail('invalid_request', 'The admission window exceeds the supported maximum.');
-    },
-    async mutate(auth, operation, mutation, body, work) {
-      if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
-      if (!mutation.idempotency_key) fail('invalid_request', 'An idempotency key is required.');
-      const slot = key('idempotency', auth.actor, operation, mutation.idempotency_key);
-      const digest = await fingerprint({ body, retry_until: mutation.retry_until });
-      return ctx.storage.transaction(async tx => {
-        const previous = await tx.get<{ digest: string; result: unknown }>(slot);
-        if (previous) {
-          if (previous.digest !== digest) fail('id_conflict', 'The idempotency key is bound to another request.');
-          return previous.result as never;
-        }
-        ctx.deadline(mutation.retry_until);
-        const result = await work(tx);
-        await tx.put(slot, { digest, result });
-        return result;
-      });
-    },
-  };
-  return ctx;
-}

package/src/discovery.ts

@@ -1,275 +0,0 @@
-import { OnlyneError, fail, key, page, type Context } from './core.ts';
-import { membershipRecord, validateDomainId } from './domains.ts';
-import type {
-  DiscoveryCandidate, DiscoveryRecord, DomainId, Failure, NodeId, Page, PageOptions, ServiceDescription, Target,
-} from './types.ts';
-
-/** How long candidate evidence stays current. An expired record is history, not a live address. */
-const FRESH_MS = 120_000;
-const PREFIX = 'discovery';
-
-function iso(at: number): string { return new Date(at).toISOString(); }
-
-function order(a: string, b: string): number { return a < b ? -1 : a > b ? 1 : 0; }
-
-function position(candidate: DiscoveryCandidate): string {
-  return `${candidate.node_id}\u0000${candidate.instance_id}\u0000${candidate.base_url}`;
-}
-
-function hostOf(url: URL): string { return url.hostname.replace(/^\[|\]$/g, '').toLowerCase(); }
-
-/** Loopback may be spoken to over plain HTTP; every other peer must use HTTPS. */
-function loopback(url: URL): boolean {
-  const host = hostOf(url);
-  return host === 'localhost' || host === '::1' || /^127\./.test(host);
-}
-
-/** True for an address another host could use. Loopback, wildcard and unscoped link-local stay home. */
-function exchangeable(value: string, allowLoopback = false): boolean {
-  let url: URL;
-  try { url = new URL(value); } catch { return false; }
-  if (url.protocol !== 'http:' && url.protocol !== 'https:') return false;
-  const host = hostOf(url);
-  if ((!allowLoopback && loopback(url)) || host === '0.0.0.0' || host === '::') return false;
-  if (/^169\.254\./.test(host)) return false;
-  return !(/^fe80:/.test(host) && !host.includes('%'));
-}
-
-function address(value: string): URL {
-  let url: URL | undefined;
-  try { url = new URL(value); } catch { /* reported below */ }
-  if (url === undefined) fail('invalid_request', 'A discovery address must be an absolute URL.');
-  if (url.protocol !== 'http:' && url.protocol !== 'https:') fail('invalid_request', 'A discovery address must be HTTP or HTTPS.');
-  if (url.search !== '' || url.hash !== '') fail('invalid_request', 'A discovery address carries no query or fragment.');
-  return url;
-}
-
-function field(value: unknown, name: string): string {
-  if (typeof value !== 'string' || value.length === 0) fail('unavailable', `The candidate published no ${name}.`);
-  return value;
-}
-
-function isFailureRecord(value: unknown): value is Failure {
-  if (value === null || typeof value !== 'object' || !('code' in value) || !('message' in value)) return false;
-  return typeof value.code === 'string' && typeof value.message === 'string';
-}
-
-function names(value: unknown, what: string): string[] {
-  if (!Array.isArray(value) || !value.every(entry => typeof entry === 'string')) fail('unavailable', `The candidate published unreadable ${what}.`);
-  return value;
-}
-
-/**
- * A service description is the candidate's own declaration. It must speak onlyne/3, name an
- * instance, and publish a membership that agrees with the identity it claims.
- */
-function published(value: unknown): ServiceDescription {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) fail('unavailable', 'The candidate returned no service description.');
-  if (!('protocol' in value) || !('node_id' in value) || !('instance_id' in value) || !('base_url' in value)
-    || !('features' in value) || !('authentication' in value) || !('membership' in value) || !('domain' in value)) {
-    fail('unavailable', 'The candidate returned an incomplete service description.');
-  }
-  if (value.protocol !== 'onlyne/3') fail('unavailable', 'The candidate does not speak onlyne/3.');
-  const node_id = field(value.node_id, 'node identity');
-  const instance_id = field(value.instance_id, 'instance identity');
-  const base_url = field(value.base_url, 'base address');
-  let parsed: URL | undefined;
-  try { parsed = new URL(base_url); } catch { /* reported below */ }
-  if (parsed === undefined) fail('unavailable', 'The candidate published an unreadable base address.');
-  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') fail('unavailable', 'The candidate published a base address this protocol cannot use.');
-  const features = names(value.features, 'features');
-  const authentication = names(value.authentication, 'authentication schemes');
-  const membership = membershipRecord(value.membership);
-  if (membership === undefined) fail('unavailable', 'The candidate published an unreadable membership.');
-  if (membership !== null && membership.node_id !== node_id) fail('unavailable', 'The candidate published a membership for another node.');
-  const domain = value.domain;
-  if (domain !== null && typeof domain !== 'string') fail('unavailable', 'The candidate published an unreadable region.');
-  if (domain !== null && (membership === null || membership.domain_id !== domain)) fail('unavailable', 'The candidate published a region its membership does not match.');
-  return {
-    protocol: 'onlyne/3', node_id, instance_id, base_url,
-    features, authentication, domain, membership,
-  };
-}
-
-/**
- * The local discovery catalog. It holds one record per (node, address), so two addresses for the
- * same node stay two observations until a direct answer shows they are the same instance.
- *
- * Nothing here trusts a third party: a record enters the catalog as a candidate clue, and only a
- * direct `GET /description` makes it usable for routing.
- */
-export class DiscoveryService {
-  /** Directly verified identities in this process; lets admission policies answer without nested storage work. */
-  readonly #known = new Set<NodeId>();
-  readonly #ctx: Context;
-  readonly #fetcher: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
-
-  constructor(ctx: Context, fetcher: (input: string | URL | Request, init?: RequestInit) => Promise<Response> = fetch) {
-    this.#ctx = ctx;
-    this.#fetcher = fetcher;
-  }
-
-  /** Whether this process has directly verified this identity at least once. */
-  known(node_id: NodeId): boolean { return this.#known.has(node_id); }
-
-  get #allowLoopback(): boolean { return Boolean(this.#ctx.options.plugins.allow_loopback); }
-
-  /**
-   * Reads `base_url`'s service description and records what it declares. A failed observation
-   * keeps the last verified identity of the address and stores the failure beside it.
-   */
-  async observe(base_url: string, source: string, expectedNode?: NodeId, signal?: AbortSignal): Promise<DiscoveryRecord> {
-    if (source.length === 0) fail('invalid_request', 'A discovery record needs a source.');
-    const url = address(base_url);
-    if (url.protocol === 'http:' && !loopback(url)) fail('unavailable', 'Plain HTTP is limited to loopback; cross-host candidates must use HTTPS.');
-    const at = this.#ctx.now();
-    let description: ServiceDescription;
-    try {
-      description = published(await this.#read(url, signal));
-      if (expectedNode !== undefined && description.node_id !== expectedNode) {
-        fail('unavailable', 'The candidate description names another node.');
-      }
-    } catch (error) {
-      if (signal?.aborted) throw signal.reason;
-      await this.#failed(base_url, source, at,
-        error instanceof OnlyneError ? error.error : { code: 'internal', message: 'The candidate observation failed.', retryable: false });
-      throw error;
-    }
-    const record: DiscoveryRecord = {
-      node_id: description.node_id,
-      instance_id: description.instance_id,
-      base_url,
-      last_seen: iso(at),
-      source,
-      received_at: iso(at),
-      expires_at: iso(at + FRESH_MS),
-      verified_at: iso(at),
-      membership: description.membership,
-    };
-    await this.#ctx.storage.transaction(async tx => { await tx.put(key(PREFIX, record.node_id, base_url), record); });
-    this.#known.add(record.node_id);
-    return record;
-  }
-
-  /** The public candidate exchange: verified, fresh and reachable from somewhere other than this host. */
-  async list(options: PageOptions = {}): Promise<Page<DiscoveryCandidate>> {
-    const at = this.#ctx.now();
-    const candidates = (await this.listRecords())
-      .filter(record => record.verified_at !== undefined && record.instance_id !== ''
-        && exchangeable(record.base_url, this.#allowLoopback) && Date.parse(record.expires_at) > at)
-      .map(record => ({ node_id: record.node_id, instance_id: record.instance_id, base_url: record.base_url, last_seen: record.last_seen }))
-      .sort((a, b) => order(position(a), position(b)));
-    return page(candidates, options, { kind: 'discovery', node: this.#ctx.node }, position);
-  }
-
-  /** Every observation this node holds, expired and failed ones included. */
-  async listRecords(): Promise<DiscoveryRecord[]> {
-    const rows = await this.#ctx.storage.transaction(tx => tx.scan<DiscoveryRecord>(`${PREFIX}/`));
-    return rows.map(row => row.value).sort((a, b) => order(position(a), position(b)));
-  }
-
-  /**
-   * Rechecks every recorded address for one identity. Two live instances of one NodeId are a
-   * conflict; the same instance at several addresses is one target. An address that no longer
-   * answers is skipped, so a restarted node's new address is usable immediately.
-   */
-  async resolve(node_id: NodeId): Promise<Target> {
-    const records = (await this.listRecords()).filter(record => record.node_id === node_id);
-    if (records.length === 0) fail('not_found', 'No discovery record names this node.');
-    const answers = await Promise.all(records.map(async record => {
-      try { return await this.observe(record.base_url, record.source, node_id); } catch { return undefined; }
-    }));
-    const live = new Map<string, string[]>();
-    for (const record of answers) {
-      if (record === undefined) continue;
-      const addresses = live.get(record.instance_id) ?? [];
-      addresses.push(record.base_url);
-      live.set(record.instance_id, addresses);
-    }
-    if (live.size > 1) fail('conflict', 'More than one live instance answers for this node.');
-    const entries = [...live.entries()];
-    if (entries.length === 0) fail('unavailable', 'No recorded address for this node answered.');
-    const addresses = entries[0]![1].sort(order);
-    return { node_id, base_url: addresses[0]! };
-  }
-
-  /** Verified, fresh candidates that declare exactly this region. */
-  async candidates(domain_id: DomainId): Promise<NodeId[]> {
-    validateDomainId(domain_id);
-    const at = this.#ctx.now();
-    const nodes = new Set<NodeId>();
-    for (const record of await this.listRecords()) {
-      if (record.verified_at === undefined || record.instance_id === '') continue;
-      if (Date.parse(record.expires_at) <= at || !exchangeable(record.base_url, this.#allowLoopback)) continue;
-      const membership = record.membership;
-      if (membership === null || membership === undefined || membership.state !== 'active' || membership.domain_id !== domain_id) continue;
-      nodes.add(record.node_id);
-    }
-    return [...nodes].sort(order);
-  }
-
-  /** Reobserves every recorded address. One unreachable candidate commits its own failure and no other. */
-  async refresh(signal?: AbortSignal): Promise<void> {
-    const records = await this.listRecords();
-    await Promise.all(records.map(record => this.observe(record.base_url, record.source, record.node_id, signal).then(() => undefined, () => undefined)));
-    if (signal?.aborted) throw signal.reason;
-  }
-
-  async #read(url: URL, signal?: AbortSignal): Promise<unknown> {
-    const target = new URL('./description', url.href.endsWith('/') ? url.href : `${url.href}/`);
-    const controller = new AbortController();
-    const relay = () => controller.abort(signal?.reason);
-    if (signal?.aborted) controller.abort(signal.reason);
-    else signal?.addEventListener('abort', relay, { once: true });
-    const gate = Promise.withResolvers<never>();
-    controller.signal.addEventListener('abort', () => gate.reject(controller.signal.reason), { once: true });
-    const timeout = setTimeout(
-      () => controller.abort(new OnlyneError('unavailable', 'The candidate description lookup timed out.')),
-      this.#ctx.options.wait_ms ?? 30_000,
-    );
-    let response: Response;
-    try {
-      response = await Promise.race([
-        this.#fetcher(target, { method: 'GET', headers: { accept: 'application/json' }, signal: controller.signal }),
-        gate.promise,
-      ]);
-    } catch (error) {
-      if (signal?.aborted) throw signal.reason;
-      throw error instanceof OnlyneError ? error : new OnlyneError('unavailable', 'The candidate could not be reached.');
-    } finally {
-      clearTimeout(timeout);
-      signal?.removeEventListener('abort', relay);
-    }
-
-    let text: string;
-    try { text = await response.text(); } catch { throw new OnlyneError('unavailable', 'The candidate response could not be read.'); }
-    let parsed: unknown;
-    try { parsed = text === '' ? undefined : JSON.parse(text); } catch { parsed = undefined; }
-    if (!response.ok) {
-      const record = parsed !== null && typeof parsed === 'object' && 'error' in parsed ? parsed.error : parsed;
-      if (isFailureRecord(record)) throw new OnlyneError(record.code, record.message, record.details);
-      throw new OnlyneError('unavailable', `The candidate answered HTTP ${response.status} without a service description.`);
-    }
-    if (parsed === undefined) throw new OnlyneError('unavailable', 'The candidate returned no service description.');
-    return parsed;
-  }
-
-  /**
-   * A failure is recorded beside addresses this node already observed; a clue that never
-   * verified leaves no record. A record whose freshness window has already lapsed is
-   * deleted instead: a row nobody can reach and nobody would trust as fresh is a
-   * candidate that has to be rediscovered, not a permanent entry.
-   */
-  async #failed(base_url: string, source: string, at: number, error: Failure): Promise<void> {
-    await this.#ctx.storage.transaction(async tx => {
-      const rows = (await tx.scan<DiscoveryRecord>(`${PREFIX}/`)).filter(row => row.value.base_url === base_url);
-      for (const row of rows) {
-        if (row.value.verified_at !== undefined) {
-          await tx.put(row.key, { ...row.value, source, received_at: iso(at), error });
-          continue;
-        }
-        await tx.delete(row.key);
-      }
-    });
-  }
-}

package/src/domains.ts

@@ -1,213 +0,0 @@
-import { fail, key, OnlyneError, page, requireValue, type Context } from './core.ts';
-import { serviceBase } from './transport.ts';
-import type { Auth, DomainDiscovery, DomainMembership, DomainMutation, Mutation, PageOptions, Transaction } from './types.ts';
-
-export function validateDomainId(value: unknown): string {
-  if (typeof value !== 'string' || !/^[A-Za-z][A-Za-z0-9+.-]*:[^\s]+$/.test(value)) {
-    fail('invalid_request', 'A domain_id must be an absolute URI.');
-  }
-  return value;
-}
-
-/**
- * Shape check for a membership as published on the wire. `null` is a valid declaration of no
- * membership; `undefined` means the value is not a membership at all.
- */
-export function membershipRecord(value: unknown): DomainMembership | null | undefined {
-  if (value === null) return null;
-  if (typeof value !== 'object' || Array.isArray(value)) return undefined;
-  if (!('domain_id' in value) || !('node_id' in value) || !('state' in value) || !('revision' in value)) return undefined;
-  const { domain_id, node_id, state, revision } = value;
-  if (typeof domain_id !== 'string' || !/^[A-Za-z][A-Za-z0-9+.-]*:[^\s]+$/.test(domain_id)) return undefined;
-  if (typeof node_id !== 'string' || node_id.length === 0) return undefined;
-  if (state !== 'active' && state !== 'left') return undefined;
-  if (typeof revision !== 'string' || revision.length === 0) return undefined;
-  return { domain_id, node_id, state, revision };
-}
-
-/**
- * A service description is valid evidence only when it speaks this protocol, names the node that
- * answered, and publishes a membership record for that same node.
- */
-function declared(value: unknown, node: string): { membership: DomainMembership | null } | undefined {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined;
-  if (!('protocol' in value) || !('node_id' in value) || !('membership' in value)) return undefined;
-  if (value.protocol !== 'onlyne/3' || value.node_id !== node) return undefined;
-  const membership = membershipRecord(value.membership);
-  if (membership === undefined || (membership !== null && membership.node_id !== node)) return undefined;
-  return { membership };
-}
-
-async function activeRows(tx: Transaction, node: string): Promise<DomainMembership[]> {
-  return (await tx.scan<DomainMembership>(key('domain') + '/'))
-    .map(row => row.value)
-    .filter(row => row.node_id === node && row.state === 'active');
-}
-
-/**
- * The one active membership a node may hold, read inside the caller's transaction.
- * Storage written by another revision can hold several; that state is refused instead of
- * silently choosing one, so the single-membership rule stays visible to the host.
- */
-async function activeMembership(tx: Transaction, node: string): Promise<DomainMembership | undefined> {
-  const rows = await activeRows(tx, node);
-  if (rows.length > 1) fail('conflict', 'This node holds more than one active domain membership; resolve it before continuing.');
-  return rows[0];
-}
-
-export class DomainService {
-  readonly #ctx: Context;
-  readonly #fetcher: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
-
-  constructor(ctx: Context, fetcher: (input: string | URL | Request, init?: RequestInit) => Promise<Response> = fetch) {
-    this.#ctx = ctx;
-    this.#fetcher = fetcher;
-  }
-
-  private authenticate(auth: Auth): void {
-    if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
-  }
-
-  private self(auth: Auth): void {
-    this.authenticate(auth);
-    if (auth.actor !== this.#ctx.node) fail('forbidden', 'A node may only change its own domain membership.');
-  }
-
-  async create(auth: Auth, mutation: Mutation): Promise<DomainMembership> {
-    this.self(auth);
-    return this.#ctx.mutate(auth, 'domain.create', mutation, {}, async tx => {
-      if (await activeMembership(tx, this.#ctx.node)) {
-        fail('conflict', 'This node already belongs to a domain; leave it before creating another.');
-      }
-      const domain_id = validateDomainId(`urn:onlyne:region:${this.#ctx.id()}`);
-      const slot = key('domain', domain_id);
-      if (await tx.get(slot)) fail('id_conflict', 'The domain identifier is already recorded here.');
-      const record: DomainMembership = { domain_id, node_id: this.#ctx.node, state: 'active', revision: this.#ctx.id() };
-      await tx.put(slot, record);
-      return record;
-    });
-  }
-
-  async join(auth: Auth, id: string, mutation: DomainMutation): Promise<DomainMembership> {
-    return this.change(auth, id, 'active', mutation);
-  }
-
-  async leave(auth: Auth, id: string, mutation: DomainMutation): Promise<DomainMembership> {
-    return this.change(auth, id, 'left', mutation);
-  }
-
-  private async change(auth: Auth, id: string, state: DomainMembership['state'], mutation: DomainMutation): Promise<DomainMembership> {
-    this.self(auth);
-    validateDomainId(id);
-    return this.#ctx.mutate(auth, `domain.${state}/${id}`, mutation, { expected_revision: mutation.expected_revision ?? null }, async tx => {
-      const slot = key('domain', id);
-      const current = await tx.get<DomainMembership>(slot);
-      if (!current && state === 'left') fail('not_found', 'No membership is recorded for this domain.');
-      // A node belongs to one domain. Cross-domain reach is a property of threads and ingress, not of membership.
-      const active = await activeMembership(tx, this.#ctx.node);
-      if (state === 'active' && active !== undefined && active.domain_id !== id) {
-        fail('conflict', 'This node already belongs to another domain; leave it first.');
-      }
-      if (current?.revision !== mutation.expected_revision) {
-        fail('revision_conflict', 'The local domain membership changed.', current ? { current_revision: current.revision } : undefined);
-      }
-      if (current?.state === state) return current;
-      const revision = this.#ctx.id();
-      if (revision === current?.revision) fail('internal', 'The revision source reused the current membership revision.');
-      const record: DomainMembership = { domain_id: id, node_id: this.#ctx.node, state, revision };
-      await tx.put(slot, record);
-      return record;
-    });
-  }
-
-  async list(auth: Auth, options: PageOptions = {}) {
-    this.authenticate(auth);
-    return this.#ctx.storage.transaction(async tx => {
-      const current = await activeMembership(tx, this.#ctx.node);
-      const records = current === undefined ? [] : [current];
-      records.sort((a, b) => a.domain_id < b.domain_id ? -1 : a.domain_id > b.domain_id ? 1 : 0);
-      return page(records, options, { kind: 'domains', node: this.#ctx.node, actor: auth.actor }, row => row.domain_id);
-    });
-  }
-
-  async describe(auth: Auth, id: string): Promise<DomainMembership> {
-    this.authenticate(auth);
-    validateDomainId(id);
-    return this.#ctx.storage.transaction(async tx => requireValue(await tx.get<DomainMembership>(key('domain', id))));
-  }
-
-  async discover(auth: Auth, id: string, signal?: AbortSignal): Promise<DomainDiscovery> {
-    this.authenticate(auth);
-    validateDomainId(id);
-    if ((await this.describe(auth, id)).state !== 'active') fail('not_a_member', 'This node has left the domain.');
-    const candidates = this.#ctx.options.plugins.domainCandidates;
-    if (!candidates) fail('unsupported_delivery', 'The host provides no domain discovery source.');
-    signal?.throwIfAborted();
-    const nodes = [...new Set([this.#ctx.node, ...await candidates(id)])].sort();
-    const members: DomainMembership[] = [];
-    const unavailable: string[] = [];
-    for (const node of nodes) {
-      signal?.throwIfAborted();
-      if (typeof node !== 'string' || node.length === 0) fail('invalid_request', 'Domain candidates must be node identities.');
-      if (node === this.#ctx.node) {
-        const current = await this.describe(auth, id);
-        if (current.state === 'active') members.push(current);
-        continue;
-      }
-      try {
-        // Only the candidate's own description is evidence: protocol and identity must agree, and
-        // a node that declares another region (or none) is excluded rather than called unreachable.
-        const declaration = declared(await this.query(node, signal), node);
-        if (declaration === undefined) unavailable.push(node);
-        else if (declaration.membership !== null && declaration.membership.domain_id === id && declaration.membership.state === 'active') members.push(declaration.membership);
-      } catch {
-        signal?.throwIfAborted();
-        unavailable.push(node);
-      }
-    }
-    return { domain_id: id, members, unavailable };
-  }
-
-  private async query(node: string, signal?: AbortSignal): Promise<unknown> {
-    // A candidate's service description is public: it is read before any key exchange, so
-    // it never goes through the signing transport (RFC 0011 §5, RFC 0017 §4).
-    const target = await this.#ctx.options.plugins.resolve(node);
-    if (target.node_id !== node) fail('unavailable', 'The resolver returned a target for another identity.');
-    const base = serviceBase(target.base_url);
-    const url = new URL('./description', base.href.endsWith('/') ? base.href : `${base.href}/`);
-    const controller = new AbortController();
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    const onAbort = () => controller.abort(signal?.reason);
-    signal?.addEventListener('abort', onAbort, { once: true });
-    if (signal?.aborted) controller.abort(signal.reason);
-    const aborted = new Promise<never>((_, reject) => {
-      controller.signal.addEventListener('abort', () => reject(controller.signal.reason), { once: true });
-      if (controller.signal.aborted) reject(controller.signal.reason);
-    });
-    timer = setTimeout(() => controller.abort(new OnlyneError('unavailable', 'Service description lookup timed out.')), this.#ctx.options.wait_ms ?? 30_000);
-    try {
-      const response = await Promise.race([
-        this.#fetcher(url, { method: 'GET', headers: { accept: 'application/json' }, signal: controller.signal }),
-        aborted,
-      ]);
-      const text = await response.text().catch(() => '');
-      let parsed: unknown;
-      try { parsed = text === '' ? undefined : JSON.parse(text); } catch { parsed = undefined; }
-      if (!response.ok) {
-        const record = parsed !== null && typeof parsed === 'object' && 'error' in parsed ? (parsed as { error: unknown }).error : parsed;
-        if (record !== null && typeof record === 'object' && 'code' in record && 'message' in record) {
-          const failure = record as { code: string; message: string; retryable?: boolean };
-          const rejection = new OnlyneError(failure.code as never, failure.message);
-          if (typeof failure.retryable === 'boolean') rejection.error.retryable = failure.retryable;
-          throw rejection;
-        }
-        fail('unavailable', `The candidate answered HTTP ${response.status} without a service description.`);
-      }
-      if (parsed === undefined) fail('unavailable', 'The candidate returned no service description.');
-      return parsed;
-    } finally {
-      clearTimeout(timer);
-      signal?.removeEventListener('abort', onAbort);
-    }
-  }
-}