@modelprofile.com/authswitch 7.0.0 → 8.1.0

package/ts/classes.authorityrehearsal.ts

@@ -1,625 +0,0 @@
-import * as plugins from './plugins.js';
-import { commitinfo } from './00_commitinfo_data.js';
-import { assertAuthorityStoredRecord } from './classes.authorityregistry.js';
-import type {
-  IAuthorityBackupRehearsal,
-  IAuthorityBackupRehearsalReadback,
-  IAuthorityRestoredRecord,
-  IAuthorityRestoredSource,
-  TAuthorityRestoredEntry,
-} from './classes.authoritybackup.js';
-
-export const authorityRehearsalProtocolVersion = 1 as const;
-export const authorityRehearsalMaximumFrameBytes = 8 * 1024 * 1024;
-export const authorityRehearsalMaximumRecordBytes = 1024 * 1024;
-export const authorityRehearsalMaximumSourceBytes = 4 * 1024 * 1024;
-const defaultRequestTimeoutMs = 120_000;
-const terminationGraceMs = 2_000;
-
-const object = (value: unknown): value is Record<string, unknown> => value !== null
-  && typeof value === 'object' && !Array.isArray(value)
-  && [Object.prototype, null].includes(Object.getPrototypeOf(value));
-const exactKeys = (value: Record<string, unknown>, keys: readonly string[]): boolean =>
-  Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
-const name = (value: unknown): value is string => typeof value === 'string'
-  && /^[a-zA-Z0-9_.:-]{1,256}$/.test(value);
-const hash = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
-const sequence = (value: unknown): value is number => Number.isSafeInteger(value) && Number(value) >= 0;
-const digestField = (value: unknown): value is IAuthorityRestoredSource['linkedDigestField'] =>
-  value === 'sourceDigest' || value === 'before.credentialDigest' || value === 'before.configDigest';
-const sourceDigest = (bytes: Uint8Array): string =>
-  plugins.crypto.createHash('sha256').update(bytes).digest('hex');
-
-export interface IAuthorityRehearsalWireSource {
-  kind: 'source';
-  sourceKind: string;
-  sourceId: string;
-  sourceDigest: string;
-  linkedModel: string;
-  linkedId: string;
-  linkedDigestField: IAuthorityRestoredSource['linkedDigestField'];
-  bytesBase64url: string;
-}
-
-export type TAuthorityRehearsalWireEntry = IAuthorityRestoredRecord | IAuthorityRehearsalWireSource;
-
-export type TAuthorityRehearsalParentMessage =
-  | { version: 1; type: 'stage'; sequence: number; entry: TAuthorityRehearsalWireEntry }
-  | { version: 1; type: 'finish'; sequence: number }
-  | { version: 1; type: 'restore.next' }
-  | { version: 1; type: 'record.next' }
-  | { version: 1; type: 'source.next' }
-  | { version: 1; type: 'close' };
-
-export type TAuthorityRehearsalChildMessage =
-  | { version: 1; type: 'ready' }
-  | { version: 1; type: 'staged'; sequence: number }
-  | { version: 1; type: 'input.complete' }
-  | { version: 1; type: 'restore.progress'; done: boolean }
-  | { version: 1; type: 'record'; record: IAuthorityRestoredRecord | null }
-  | { version: 1; type: 'source'; source: IAuthorityRehearsalWireSource | null }
-  | { version: 1; type: 'closed' }
-  | { version: 1; type: 'failed'; phase: 'protocol' | 'staging' | 'restore' | 'readback' | 'cleanup' };
-
-const assertWireSource: (value: unknown) => asserts value is IAuthorityRehearsalWireSource = value => {
-  if (!object(value) || !exactKeys(value, ['kind', 'sourceKind', 'sourceId', 'sourceDigest',
-    'linkedModel', 'linkedId', 'linkedDigestField', 'bytesBase64url'])
-    || value.kind !== 'source' || !name(value.sourceKind) || !name(value.sourceId)
-    || !hash(value.sourceDigest) || !name(value.linkedModel) || !name(value.linkedId)
-    || !digestField(value.linkedDigestField) || typeof value.bytesBase64url !== 'string'
-    || value.bytesBase64url.length === 0
-    || value.bytesBase64url.length > Math.ceil(authorityRehearsalMaximumSourceBytes * 4 / 3)
-    || !/^[A-Za-z0-9_-]+$/.test(value.bytesBase64url)) {
-    throw new Error('Invalid rehearsal source frame.');
-  }
-  const bytes = Buffer.from(value.bytesBase64url, 'base64url');
-  try {
-    if (bytes.byteLength === 0 || bytes.byteLength > authorityRehearsalMaximumSourceBytes
-      || bytes.toString('base64url') !== value.bytesBase64url
-      || sourceDigest(bytes) !== value.sourceDigest) throw new Error('Invalid rehearsal source bytes.');
-  } finally { bytes.fill(0); }
-};
-
-const assertWireRecord: (value: unknown) => asserts value is IAuthorityRestoredRecord = value => {
-  if (!object(value) || !exactKeys(value, ['model', 'id', 'value'])
-    || !name(value.model) || !name(value.id)) throw new Error('Invalid rehearsal record frame.');
-  const encoded = Buffer.from(JSON.stringify(value.value), 'utf8');
-  try {
-    if (encoded.byteLength > authorityRehearsalMaximumRecordBytes) {
-      throw new Error('Rehearsal record exceeds its size bound.');
-    }
-  } finally { encoded.fill(0); }
-  assertAuthorityStoredRecord(value as unknown as IAuthorityRestoredRecord);
-};
-
-export const parseAuthorityRehearsalWireEntry = (value: unknown): TAuthorityRehearsalWireEntry => {
-  if (object(value) && value.kind === 'source') {
-    assertWireSource(value);
-    return value;
-  }
-  assertWireRecord(value);
-  return value;
-};
-
-export const restoredEntryToWire = (entry: TAuthorityRestoredEntry): TAuthorityRehearsalWireEntry => {
-  if ('kind' in entry) {
-    if (!(entry.bytes instanceof Uint8Array) || entry.bytes.byteLength === 0
-      || entry.bytes.byteLength > authorityRehearsalMaximumSourceBytes
-      || sourceDigest(entry.bytes) !== entry.sourceDigest) throw new Error('Invalid rehearsal source entry.');
-    const wire: IAuthorityRehearsalWireSource = {
-      kind: 'source', sourceKind: entry.sourceKind, sourceId: entry.sourceId,
-      sourceDigest: entry.sourceDigest, linkedModel: entry.linkedModel, linkedId: entry.linkedId,
-      linkedDigestField: entry.linkedDigestField,
-      bytesBase64url: Buffer.from(entry.bytes).toString('base64url'),
-    };
-    assertWireSource(wire);
-    return wire;
-  }
-  assertWireRecord(entry);
-  return entry;
-};
-
-export const wireSourceToRestored = (source: IAuthorityRehearsalWireSource): IAuthorityRestoredSource => {
-  assertWireSource(source);
-  return {
-    kind: 'source', sourceKind: source.sourceKind, sourceId: source.sourceId,
-    sourceDigest: source.sourceDigest, linkedModel: source.linkedModel, linkedId: source.linkedId,
-    linkedDigestField: source.linkedDigestField, bytes: Buffer.from(source.bytesBase64url, 'base64url'),
-  };
-};
-
-export const parseAuthorityRehearsalParentMessage = (value: unknown): TAuthorityRehearsalParentMessage => {
-  if (!object(value) || value.version !== authorityRehearsalProtocolVersion || typeof value.type !== 'string') {
-    throw new Error('Invalid rehearsal parent frame.');
-  }
-  if (value.type === 'stage') {
-    if (!exactKeys(value, ['version', 'type', 'sequence', 'entry']) || !sequence(value.sequence)) {
-      throw new Error('Invalid rehearsal stage frame.');
-    }
-    return { version: 1, type: 'stage', sequence: value.sequence, entry: parseAuthorityRehearsalWireEntry(value.entry) };
-  }
-  if (value.type === 'finish') {
-    if (!exactKeys(value, ['version', 'type', 'sequence']) || !sequence(value.sequence)) {
-      throw new Error('Invalid rehearsal finish frame.');
-    }
-    return value as TAuthorityRehearsalParentMessage;
-  }
-  if (!['restore.next', 'record.next', 'source.next', 'close'].includes(value.type)
-    || !exactKeys(value, ['version', 'type'])) throw new Error('Invalid rehearsal control frame.');
-  return value as TAuthorityRehearsalParentMessage;
-};
-
-export const parseAuthorityRehearsalChildMessage = (value: unknown): TAuthorityRehearsalChildMessage => {
-  if (!object(value) || value.version !== authorityRehearsalProtocolVersion || typeof value.type !== 'string') {
-    throw new Error('Invalid rehearsal child frame.');
-  }
-  if (['ready', 'input.complete', 'closed'].includes(value.type)) {
-    if (!exactKeys(value, ['version', 'type'])) throw new Error('Invalid rehearsal lifecycle frame.');
-    return value as TAuthorityRehearsalChildMessage;
-  }
-  if (value.type === 'staged') {
-    if (!exactKeys(value, ['version', 'type', 'sequence']) || !sequence(value.sequence)) {
-      throw new Error('Invalid rehearsal staged frame.');
-    }
-    return value as TAuthorityRehearsalChildMessage;
-  }
-  if (value.type === 'restore.progress') {
-    if (!exactKeys(value, ['version', 'type', 'done']) || typeof value.done !== 'boolean') {
-      throw new Error('Invalid rehearsal restore frame.');
-    }
-    return value as TAuthorityRehearsalChildMessage;
-  }
-  if (value.type === 'record') {
-    if (!exactKeys(value, ['version', 'type', 'record'])) throw new Error('Invalid rehearsal record response.');
-    if (value.record !== null) assertWireRecord(value.record);
-    return value as TAuthorityRehearsalChildMessage;
-  }
-  if (value.type === 'source') {
-    if (!exactKeys(value, ['version', 'type', 'source'])) throw new Error('Invalid rehearsal source response.');
-    if (value.source !== null) assertWireSource(value.source);
-    return value as TAuthorityRehearsalChildMessage;
-  }
-  if (value.type === 'failed') {
-    if (!exactKeys(value, ['version', 'type', 'phase'])
-      || !['protocol', 'staging', 'restore', 'readback', 'cleanup'].includes(String(value.phase))) {
-      throw new Error('Invalid rehearsal failure frame.');
-    }
-    return value as TAuthorityRehearsalChildMessage;
-  }
-  throw new Error('Unknown rehearsal child frame.');
-};
-
-/** Single-reader/single-writer bounded transport for the isolated rehearsal child. */
-export class AuthorityRehearsalFramedTransport<TIncoming, TOutgoing> {
-  private readonly header = Buffer.allocUnsafe(4);
-  private headerOffset = 0;
-  private body?: Buffer;
-  private bodyOffset = 0;
-  private queued?: TIncoming;
-  private waiting?: { resolve: (value: TIncoming) => void; reject: (error: Error) => void };
-  private failure?: Error;
-  private closed = false;
-  private sending = false;
-
-  constructor(private readonly options: {
-    readable: plugins.stream.Readable;
-    writable: plugins.stream.Writable;
-    parseIncoming: (value: unknown) => TIncoming;
-    validateOutgoing: (value: unknown) => TOutgoing;
-  }) {
-    options.readable.on('data', this.onData);
-    options.readable.once('error', this.onReadError);
-    options.readable.once('end', this.onReadableClose);
-    options.readable.once('close', this.onReadableClose);
-    options.writable.once('error', this.onWriteError);
-  }
-
-  public async send(message: TOutgoing, timeoutMs: number, signal?: AbortSignal): Promise<void> {
-    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new Error('Invalid rehearsal write deadline.');
-    signal?.throwIfAborted();
-    if (this.closed || this.failure || this.sending || this.options.writable.destroyed
-      || this.options.writable.writableEnded) throw new Error('Rehearsal transport is unavailable.');
-    this.options.validateOutgoing(message);
-    const serialized = Buffer.from(JSON.stringify(message), 'utf8');
-    if (serialized.byteLength > authorityRehearsalMaximumFrameBytes) {
-      serialized.fill(0);
-      throw new Error('Rehearsal IPC frame exceeds its size bound.');
-    }
-    const frame = Buffer.allocUnsafe(4 + serialized.byteLength);
-    frame.writeUInt32BE(serialized.byteLength, 0);
-    serialized.copy(frame, 4);
-    serialized.fill(0);
-    this.sending = true;
-    try {
-      await new Promise<void>((resolve, reject) => {
-        let settled = false;
-        let timer: ReturnType<typeof setTimeout> | undefined;
-        const cleanup = () => {
-          if (timer) clearTimeout(timer);
-          signal?.removeEventListener('abort', abort);
-          this.options.writable.removeListener('close', closed);
-        };
-        const finish = (error?: Error | null) => {
-          if (settled) return;
-          settled = true;
-          cleanup();
-          if (error) reject(error); else resolve();
-        };
-        const interrupt = (messageArg: string) => {
-          const error = new Error(messageArg);
-          this.fail(error);
-          // Writable.destroy() releases pending chunks before its close event. Do not settle or wipe here.
-        };
-        const abort = () => interrupt('Rehearsal write was cancelled.');
-        const closed = () => finish(this.failure ?? new Error('Rehearsal transport closed during its write.'));
-        timer = setTimeout(() => interrupt('Rehearsal child exceeded its write deadline.'), timeoutMs);
-        timer.unref?.();
-        this.options.writable.once('close', closed);
-        signal?.addEventListener('abort', abort, { once: true });
-        if (signal?.aborted) abort();
-        if (!this.failure) {
-          try {
-            this.options.writable.write(frame, (error?: Error | null) => finish(error ?? this.failure));
-          } catch (error) {
-            finish(error instanceof Error ? error : new Error('Rehearsal IPC write failed.'));
-          }
-        }
-      });
-    } finally {
-      this.sending = false;
-      frame.fill(0);
-    }
-  }
-
-  public receive(timeoutMs: number, signal?: AbortSignal): Promise<TIncoming> {
-    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new Error('Invalid rehearsal request deadline.');
-    signal?.throwIfAborted();
-    if (this.queued !== undefined) {
-      const value = this.queued;
-      this.queued = undefined;
-      return Promise.resolve(value);
-    }
-    if (this.failure) return Promise.reject(this.failure);
-    if (this.closed) return Promise.reject(new Error('Rehearsal transport closed before its response.'));
-    if (this.waiting) return Promise.reject(new Error('Rehearsal transport already has a waiting reader.'));
-    return new Promise<TIncoming>((resolve, reject) => {
-      let timer: ReturnType<typeof setTimeout> | undefined;
-      const abort = () => this.fail(new Error('Rehearsal request was cancelled.'));
-      const finish = (error?: Error, value?: TIncoming) => {
-        if (this.waiting?.resolve !== waiting.resolve) return;
-        this.waiting = undefined;
-        if (timer) clearTimeout(timer);
-        signal?.removeEventListener('abort', abort);
-        if (error) reject(error); else resolve(value!);
-      };
-      const waiting = { resolve: (value: TIncoming) => finish(undefined, value), reject: (error: Error) => finish(error) };
-      this.waiting = waiting;
-      timer = setTimeout(() => this.fail(new Error('Rehearsal child exceeded its response deadline.')), timeoutMs);
-      timer.unref?.();
-      signal?.addEventListener('abort', abort, { once: true });
-    });
-  }
-
-  public async finishWritable(): Promise<void> {
-    if (this.options.writable.destroyed || this.options.writable.writableEnded) return;
-    await new Promise<void>((resolve, reject) => {
-      this.options.writable.end((error?: Error | null) => error ? reject(error) : resolve());
-    });
-  }
-
-  public destroy(): void {
-    this.closed = true;
-    this.detach();
-    this.body?.fill(0);
-    this.body = undefined;
-    this.options.readable.destroy();
-    this.options.writable.destroy();
-    this.waiting?.reject(new Error('Rehearsal transport was destroyed.'));
-  }
-
-  private readonly onData = (chunkValue: unknown): void => {
-    if (this.closed || this.failure) return;
-    const chunk = chunkValue instanceof Uint8Array
-      ? Buffer.from(chunkValue.buffer, chunkValue.byteOffset, chunkValue.byteLength) : undefined;
-    if (!chunk) return this.fail(new Error('Rehearsal IPC received a non-byte chunk.'));
-    let offset = 0;
-    try {
-      while (offset < chunk.byteLength) {
-        if (!this.body) {
-          const count = Math.min(4 - this.headerOffset, chunk.byteLength - offset);
-          chunk.copy(this.header, this.headerOffset, offset, offset + count);
-          this.headerOffset += count; offset += count;
-          if (this.headerOffset < 4) continue;
-          const length = this.header.readUInt32BE(0);
-          if (length < 1 || length > authorityRehearsalMaximumFrameBytes) {
-            throw new Error('Rehearsal IPC frame exceeds its size bound.');
-          }
-          this.body = Buffer.allocUnsafe(length); this.bodyOffset = 0;
-          continue;
-        }
-        const count = Math.min(this.body.byteLength - this.bodyOffset, chunk.byteLength - offset);
-        chunk.copy(this.body, this.bodyOffset, offset, offset + count);
-        this.bodyOffset += count; offset += count;
-        if (this.bodyOffset === this.body.byteLength) this.finishBody();
-      }
-    } catch (error) { this.fail(error instanceof Error ? error : new Error('Rehearsal IPC framing failed.')); }
-  };
-
-  private finishBody(): void {
-    const body = this.body;
-    this.body = undefined; this.bodyOffset = 0; this.headerOffset = 0;
-    if (!body) throw new Error('Rehearsal IPC lost its frame body.');
-    let value: unknown;
-    try { value = JSON.parse(body.toString('utf8')) as unknown; }
-    catch { throw new Error('Rehearsal IPC frame contains invalid JSON.'); }
-    finally { body.fill(0); }
-    const message = this.options.parseIncoming(value);
-    if (this.waiting) this.waiting.resolve(message);
-    else if (this.queued === undefined) this.queued = message;
-    else throw new Error('Rehearsal peer violated serialized request flow.');
-  }
-
-  private readonly onReadError = (error: Error): void => this.fail(error);
-  private readonly onWriteError = (error: Error): void => this.fail(error);
-  private readonly onReadableClose = (): void => {
-    if (this.failure) return;
-    if (this.headerOffset || this.body) return this.fail(new Error('Rehearsal IPC ended within a frame.'));
-    this.fail(new Error('Rehearsal IPC closed before its response.'));
-  };
-
-  private fail(error: Error): void {
-    if (this.failure) return;
-    this.failure = error;
-    this.closed = true;
-    this.detach();
-    this.body?.fill(0); this.body = undefined;
-    this.waiting?.reject(error);
-    this.options.readable.destroy();
-    this.options.writable.destroy();
-  }
-
-  private detach(): void {
-    this.options.readable.removeListener('data', this.onData);
-    this.options.readable.removeListener('error', this.onReadError);
-    this.options.readable.removeListener('end', this.onReadableClose);
-    this.options.readable.removeListener('close', this.onReadableClose);
-    this.options.writable.removeListener('error', this.onWriteError);
-  }
-}
-
-export interface IAuthorityRehearsalChildLaunch {
-  entryPath: string;
-  args: string[];
-  options: plugins.childProcess.SpawnOptions;
-}
-
-export type TAuthorityRehearsalChildFactory =
-  (launch: IAuthorityRehearsalChildLaunch) => plugins.childProcess.ChildProcess;
-
-export interface IAuthSwitchAuthorityRehearsalOptions {
-  signal?: AbortSignal;
-  requestTimeoutMs?: number;
-  /** Test-only source runner seam. Never populate this from CLI, RPC or management input. */
-  childFactory?: TAuthorityRehearsalChildFactory;
-}
-
-const sanitizedEnvironment = (): NodeJS.ProcessEnv => {
-  const result: NodeJS.ProcessEnv = {};
-  for (const key of ['PATH', 'PATHEXT', 'SYSTEMROOT', 'WINDIR', 'COMSPEC', 'TEMP', 'TMP', 'TMPDIR',
-    'LANG', 'LC_ALL', 'TZ'] as const) {
-    if (process.env[key] !== undefined) result[key] = process.env[key];
-  }
-  return result;
-};
-
-export const resolveAuthorityRehearsalChildEntryPath = (): string => {
-  const sourceDirectory = plugins.path.dirname(plugins.fileURLToPath(import.meta.url));
-  const packageDirectory = plugins.fs.realpathSync.native(plugins.path.dirname(sourceDirectory));
-  const manifestPath = plugins.fs.realpathSync.native(plugins.path.join(packageDirectory, 'package.json'));
-  const manifest = JSON.parse(plugins.fs.readFileSync(manifestPath, 'utf8')) as unknown;
-  if (!object(manifest) || manifest.name !== commitinfo.name) {
-    throw new Error('The rehearsal child package identity is invalid.');
-  }
-  const entryPath = plugins.fs.realpathSync.native(
-    plugins.path.join(packageDirectory, 'dist_ts', 'authorityrehearsal.child.js'));
-  if (plugins.path.relative(packageDirectory, entryPath)
-      !== plugins.path.join('dist_ts', 'authorityrehearsal.child.js')
-    || !plugins.fs.statSync(entryPath).isFile()) {
-    throw new Error('The rehearsal child entry escaped its package.');
-  }
-  return entryPath;
-};
-
-interface IChildOutcome { code: number | null; signal: NodeJS.Signals | null; error?: Error }
-
-const observeClose = (child: plugins.childProcess.ChildProcess): Promise<IChildOutcome> =>
-  new Promise(resolve => {
-    let error: Error | undefined;
-    child.once('error', value => { error = value; });
-    child.once('close', (code, signal) => resolve({ code, signal, error }));
-  });
-
-const within = async <T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T> => {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  try {
-    return await Promise.race([promise, new Promise<never>((_, reject) => {
-      timer = setTimeout(() => reject(new Error(message)), timeoutMs);
-      timer.unref?.();
-    })]);
-  } finally { if (timer) clearTimeout(timer); }
-};
-
-export class AuthSwitchAuthorityRehearsal implements IAuthorityBackupRehearsal {
-  private readonly requestTimeoutMs: number;
-
-  constructor(private readonly options: IAuthSwitchAuthorityRehearsalOptions = {}) {
-    this.requestTimeoutMs = options.requestTimeoutMs ?? defaultRequestTimeoutMs;
-    if (!Number.isSafeInteger(this.requestTimeoutMs) || this.requestTimeoutMs < 1) {
-      throw new Error('Invalid rehearsal child deadline.');
-    }
-  }
-
-  public async restoreClosed(entries: AsyncIterable<TAuthorityRestoredEntry>): Promise<IAuthorityBackupRehearsalReadback> {
-    this.options.signal?.throwIfAborted();
-    const root = await plugins.fs.promises.mkdtemp(plugins.path.join(plugins.os.tmpdir(), 'authswitch-rehearsal-'));
-    await plugins.fs.promises.chmod(root, 0o700);
-    let child: plugins.childProcess.ChildProcess | undefined;
-    let transport: AuthorityRehearsalFramedTransport<TAuthorityRehearsalChildMessage,
-      TAuthorityRehearsalParentMessage> | undefined;
-    let lifecycle: Promise<IChildOutcome> | undefined;
-    let handedOff = false;
-    try {
-      const sourceEntry = plugins.fileURLToPath(new URL('./authorityrehearsal.child.ts', import.meta.url));
-      const entryPath = this.options.childFactory ? sourceEntry : resolveAuthorityRehearsalChildEntryPath();
-      const packageDirectory = plugins.path.dirname(plugins.path.dirname(entryPath));
-      const launch: IAuthorityRehearsalChildLaunch = { entryPath, args: [root], options: {
-        cwd: packageDirectory, env: sanitizedEnvironment(), shell: false, windowsHide: true,
-        stdio: ['ignore', 'ignore', 'ignore', 'pipe', 'pipe'],
-      } };
-      child = (this.options.childFactory ?? (input =>
-        plugins.childProcess.spawn(process.execPath, [input.entryPath, ...input.args], input.options)))(launch);
-      lifecycle = observeClose(child);
-      if (!child.pid) throw new Error('The rehearsal child did not start.');
-      const writer = child.stdio[3];
-      const reader = child.stdio[4];
-      if (!(writer instanceof plugins.stream.Writable) || !(reader instanceof plugins.stream.Readable)) {
-        throw new Error('The rehearsal child control pipes were not created.');
-      }
-      transport = new AuthorityRehearsalFramedTransport({ readable: reader, writable: writer,
-        parseIncoming: parseAuthorityRehearsalChildMessage,
-        validateOutgoing: parseAuthorityRehearsalParentMessage });
-      const first = await transport.receive(this.requestTimeoutMs, this.options.signal);
-      this.expect(first, 'ready');
-      let itemSequence = 0;
-      for await (const entry of entries) {
-        this.options.signal?.throwIfAborted();
-        const response = await this.exchange(transport,
-          { version: 1, type: 'stage', sequence: itemSequence, entry: restoredEntryToWire(entry) },
-          this.options.signal);
-        if (response.type !== 'staged' || response.sequence !== itemSequence) {
-          throw new Error('The rehearsal child did not acknowledge the staged entry.');
-        }
-        itemSequence++;
-      }
-      this.expect(await this.exchange(transport,
-        { version: 1, type: 'finish', sequence: itemSequence }, this.options.signal), 'input.complete');
-      while (true) {
-        const response = await this.exchange(transport, { version: 1, type: 'restore.next' }, this.options.signal);
-        if (response.type !== 'restore.progress') throw new Error('The rehearsal child returned an invalid restore response.');
-        if (response.done) break;
-      }
-
-      let recordsStarted = false;
-      let recordsDone = false;
-      let sourcesStarted = false;
-      let sourcesDone = false;
-      let closePromise: Promise<void> | undefined;
-      const close = (): Promise<void> => {
-        if (closePromise) return closePromise;
-        closePromise = this.closeReadback({ child: child!, lifecycle: lifecycle!, transport: transport!, root,
-          complete: recordsDone && sourcesDone });
-        return closePromise;
-      };
-      const self = this;
-      const records = async function* (): AsyncGenerator<IAuthorityRestoredRecord> {
-        if (recordsStarted) throw new Error('Rehearsal records may only be read once.');
-        recordsStarted = true;
-        while (true) {
-          const response = await self.exchange(transport!, { version: 1, type: 'record.next' }, self.options.signal);
-          if (response.type !== 'record') throw new Error('The rehearsal child returned an invalid record response.');
-          if (response.record === null) { recordsDone = true; return; }
-          yield response.record;
-        }
-      };
-      const sources = async function* (): AsyncGenerator<IAuthorityRestoredSource> {
-        if (!recordsDone) throw new Error('Rehearsal sources require complete record readback first.');
-        if (sourcesStarted) throw new Error('Rehearsal sources may only be read once.');
-        sourcesStarted = true;
-        while (true) {
-          const response = await self.exchange(transport!, { version: 1, type: 'source.next' }, self.options.signal);
-          if (response.type !== 'source') throw new Error('The rehearsal child returned an invalid source response.');
-          if (response.source === null) { sourcesDone = true; return; }
-          yield wireSourceToRestored(response.source);
-        }
-      };
-      handedOff = true;
-      return { records: records(), sources: sources(), close };
-    } catch (error) {
-      if (child && lifecycle) {
-        try { await this.abortChild(child, lifecycle, transport, !this.options.signal?.aborted); }
-        catch (cleanupError) { throw new AggregateError([error, cleanupError], 'Rehearsal restore and cleanup failed.'); }
-      }
-      throw error;
-    } finally {
-      if (!handedOff) await plugins.fs.promises.rm(root, { recursive: true, force: true });
-    }
-  }
-
-  private async exchange(transport: AuthorityRehearsalFramedTransport<TAuthorityRehearsalChildMessage,
-    TAuthorityRehearsalParentMessage>, message: TAuthorityRehearsalParentMessage,
-    signal?: AbortSignal): Promise<TAuthorityRehearsalChildMessage> {
-    const deadline = Date.now() + this.requestTimeoutMs;
-    await transport.send(message, this.requestTimeoutMs, signal);
-    const remaining = deadline - Date.now();
-    if (remaining < 1) {
-      transport.destroy();
-      throw new Error('The rehearsal child exceeded its request deadline.');
-    }
-    const response = await transport.receive(remaining, signal);
-    if (response.type === 'failed') throw new Error(`The rehearsal child failed during ${response.phase}.`);
-    return response;
-  }
-
-  private expect(message: TAuthorityRehearsalChildMessage, type: TAuthorityRehearsalChildMessage['type']): void {
-    if (message.type === 'failed') throw new Error(`The rehearsal child failed during ${message.phase}.`);
-    if (message.type !== type) throw new Error(`The rehearsal child did not return ${type}.`);
-  }
-
-  private async closeReadback(input: { child: plugins.childProcess.ChildProcess; lifecycle: Promise<IChildOutcome>;
-    transport: AuthorityRehearsalFramedTransport<TAuthorityRehearsalChildMessage, TAuthorityRehearsalParentMessage>;
-    root: string; complete: boolean }): Promise<void> {
-    let failure: unknown;
-    try {
-      if (!input.complete) throw new Error('The rehearsal readback was not consumed completely.');
-      this.expect(await this.exchange(input.transport, { version: 1, type: 'close' }), 'closed');
-      await input.transport.finishWritable();
-      const outcome = await within(input.lifecycle, this.requestTimeoutMs,
-        'The rehearsal child did not close after cleanup.');
-      if (outcome.error || outcome.signal !== null || outcome.code !== 0) {
-        throw new Error('The rehearsal child did not close cleanly.');
-      }
-    } catch (error) {
-      failure = error;
-      try { await this.abortChild(input.child, input.lifecycle, input.transport, !this.options.signal?.aborted); }
-      catch (cleanupError) { failure = new AggregateError([error, cleanupError], 'Rehearsal close cleanup failed.'); }
-    } finally {
-      input.transport.destroy();
-      try { await plugins.fs.promises.rm(input.root, { recursive: true, force: false }); }
-      catch (error) { failure = failure
-        ? new AggregateError([failure, error], 'Rehearsal artifact cleanup failed.') : error; }
-    }
-    if (failure) throw failure;
-  }
-
-  private async abortChild(child: plugins.childProcess.ChildProcess, lifecycle: Promise<IChildOutcome>,
-    transport?: AuthorityRehearsalFramedTransport<TAuthorityRehearsalChildMessage,
-      TAuthorityRehearsalParentMessage>, graceful = true): Promise<void> {
-    if (transport && graceful) {
-      try {
-        const response = await within(this.exchange(transport, { version: 1, type: 'close' }),
-          terminationGraceMs, 'Rehearsal child close request timed out.');
-        if (response.type === 'closed') await transport.finishWritable();
-      } catch { /* The child may already be failed or gone. */ }
-    }
-    if (!graceful) transport?.destroy();
-    try { await within(lifecycle, terminationGraceMs, 'Rehearsal child did not close voluntarily.'); }
-    catch {
-      child.kill('SIGTERM');
-      try { await within(lifecycle, terminationGraceMs, 'Rehearsal child ignored SIGTERM.'); }
-      catch {
-        child.kill('SIGKILL');
-        await within(lifecycle, this.requestTimeoutMs, 'Rehearsal child exit could not be confirmed.');
-      }
-    } finally { transport?.destroy(); }
-  }
-}