@amalgm/shell 0.1.163 → 0.1.164-main.34182640231

package/examinations/native-service.mjs

@@ -0,0 +1,92 @@
+import assert from 'node:assert/strict';
+import { randomUUID, createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { handleMachineControlRequest } from './fixtures/machine-control-plane.js';
+import { createPrivateWireAuthority } from './fixtures/private-wire-authority.js';
+
+/** Enroll the actual installed Shell through setup, with test cloud inputs.
+ * The process tree and OS service are real; this helper neither supplies a
+ * substitute child nor alters the package under examination. */
+export async function nativeInstalledService({ packageRoot = fileURLToPath(new URL('../', import.meta.url)), label }) {
+  assert.equal(process.env.CI, 'true', 'Installed service certification requires a disposable native CI account');
+  assert.ok(['main', 'preview'].includes(label));
+  packageRoot = await fs.realpath(packageRoot);
+  const manifest = JSON.parse(await fs.readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+  assert.ok(['amalgm', '@amalgm/shell'].includes(manifest.name));
+  const load = file => import(pathToFileURL(path.join(packageRoot, 'dist', file)).href);
+  const [{ serviceIdentity, detectBackend, readRegistration }, { ownerFor }, { userSystemdAvailable },
+    { keepaliveStatus }, { MachineHost }, { installationDeviceKeyStores }] = await Promise.all([
+    load('service/registration.js'), load('service/owner.js'), load('service/systemd.js'),
+    load('service/control.js'), load('machine-host.js'), load('authorization/index.js'),
+  ]);
+  const backend = detectBackend('auto', { platform: process.platform, userSystemd: userSystemdAvailable });
+  assert.notEqual(backend, 'portable', 'Shell survival certification requires the real OS service manager');
+  const owner = ownerFor(backend);
+  const home = await fs.mkdtemp(path.join(os.tmpdir(), 'amalgm-installed-service-'));
+  const user = `desktop-upgrade-${randomUUID()}@example.test`;
+  const identity = serviceIdentity({ runtimeLabel: label, branch: label, user, home });
+  let wireUrl; let setupChild; let stateFiles = [];
+  const authority = createPrivateWireAuthority({ token: 'desktop-upgrade-examination', onRequest: (request, response) => {
+    void handleMachineControlRequest(request, response, { userEmail: user, userId: user,
+      wireUrl: () => wireUrl, tunnelToken: 'desktop-upgrade-examination' });
+  } });
+  const close = async () => {
+    if (setupChild?.exitCode === null) setupChild.kill('SIGKILL');
+    await owner.uninstall(identity);
+    for (const socket of authority.sockets.clients) socket.terminate();
+    await new Promise(resolve => authority.sockets.close(resolve));
+    authority.server.closeAllConnections();
+    await new Promise(resolve => authority.server.close(resolve));
+    const stateDir = path.join(identity.amalgmRoot, '.amalgm');
+    try {
+      const { device_id: deviceId } = JSON.parse(await fs.readFile(path.join(stateDir, 'device.json'), 'utf8'));
+      const stores = installationDeviceKeyStores({ stateDir, deviceId });
+      await stores.active.remove(); await stores.pending.remove();
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    await fs.rm(home, { recursive: true, force: true, maxRetries: 5 });
+  };
+  try {
+    await new Promise(resolve => authority.server.listen(0, '127.0.0.1', resolve));
+    const appUrl = `http://127.0.0.1:${authority.server.address().port}`;
+    wireUrl = appUrl.replace('http:', 'ws:') + '/wire';
+    const args = [...(label === 'preview' ? ['preview'] : []), 'setup', '--setup-code', 'ABCD-EFGH-JKLM-NPQR',
+      '--home', home, '--app-url', appUrl, '--no-open'];
+    await new Promise((resolve, reject) => {
+      setupChild = spawn(process.execPath, [path.join(packageRoot, 'dist/main.js'), ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
+      let output = '';
+      const collect = bytes => { output = (output + bytes).slice(-24_000); };
+      setupChild.stdout.on('data', collect); setupChild.stderr.on('data', collect);
+      const timer = setTimeout(() => { setupChild.kill('SIGTERM'); reject(new Error(`Installed Shell setup timed out: ${output}`)); }, 90_000);
+      setupChild.once('error', error => { clearTimeout(timer); reject(error); });
+      setupChild.once('exit', code => { clearTimeout(timer); if (code === 0 && /AMALGM_SETUP_COMPLETE/.test(output)) resolve(); else reject(new Error(`Installed Shell setup failed (${code}): ${output}`)); });
+    });
+    const registration = readRegistration(identity);
+    assert.equal(await fs.realpath(registration.package_root), packageRoot, 'OS service must execute the package under examination');
+    assert.equal(registration.package_version, manifest.version);
+    const host = new MachineHost({ runtimeLabel: label, branch: label, homedir: home, appUrl, userEmail: user,
+      runtimeVersion: manifest.version });
+    const selected = host.selectedPaths();
+    stateFiles = [host.deviceFile, selected.publicRecord, selected.secretAuth, selected.installation];
+    await host.close();
+    const status = async () => {
+      const controller = await keepaliveStatus(identity);
+      assert.ok(controller?.childPid && controller.phase === 'running', 'Installed Shell has no authenticated healthy controller and child');
+      assert.equal((await owner.status(identity)).pid, controller.bootstrapPid ?? controller.pid);
+      process.kill(controller.childPid, 0);
+      const current = readRegistration(identity);
+      const currentPackage = JSON.parse(await fs.readFile(path.join(current.package_root, 'package.json'), 'utf8'));
+      const durable = [];
+      for (const file of stateFiles) durable.push({ name: path.basename(file), sha256: createHash('sha256').update(await fs.readFile(file)).digest('hex') });
+      return { package: currentPackage.name, version: currentPackage.version, source: currentPackage.amalgmSource ?? null,
+        backend, binding: identity.binding, controllerPid: controller.pid, childPid: controller.childPid,
+        bootstrapPid: controller.bootstrapPid ?? null, instanceId: controller.instanceId,
+        updates: controller.update ?? null, durable };
+    };
+    await status();
+    return { identity, paths: { ...selected, deviceFile: host.deviceFile }, status, close };
+  } catch (error) { await close(); throw error; }
+}

package/examinations/network-view.mjs

@@ -0,0 +1,202 @@
+// Disposable CI network transport shared by packaged runtime and desktop gates.
+// Callers supply exact exported authority bytes; this module never signs or
+// interprets release metadata and is never imported by the product runtime.
+import assert from 'node:assert/strict';
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import { createReadStream, realpathSync } from 'node:fs';
+import https from 'node:https';
+import path from 'node:path';
+import readline from 'node:readline';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { spawn, execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+export const canonicalHost = 'amalgm-desktop-releases.fly.dev';
+const run = (file, args, options = {}) => execFileSync(file, args, { encoding: 'utf8', timeout: 30_000, ...options });
+const sudo = (file, args) => run('sudo', ['-n', file, ...args]);
+const powershell = (source, env = {}) => run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', source], { env: { ...process.env, ...env } });
+
+export async function startNetworkView({ temporary, immutable, previous = {}, candidate, artifacts = [], events, hint = {}, serviceEnvironment = false }) {
+  assert.equal(process.env.CI, 'true');
+  assert.equal(process.env.GITHUB_ACTIONS, 'true', 'Never replace DNS or TLS trust on a developer account');
+  assert.ok(['darwin', 'linux', 'win32'].includes(process.platform));
+  for (const resources of [immutable, previous, candidate]) assert.ok(resources && typeof resources === 'object');
+  assert.ok(typeof events === 'string' && events.startsWith('/trust/'));
+  const view = { immutable, previous, candidate, artifacts, events, hint };
+  const directory = path.join(temporary, 'network'); await fs.mkdir(directory, { mode: 0o700 });
+  const ca = path.join(directory, 'ca.crt');
+  const key = path.join(directory, 'server.key');
+  const certificate = path.join(directory, 'server.crt');
+  const name = `Amalgm disposable native examination ${crypto.randomUUID()}`;
+  const extension = path.join(directory, 'server.ext');
+  await fs.writeFile(extension, `subjectAltName=DNS:${canonicalHost}\nextendedKeyUsage=serverAuth\n`);
+  run('openssl', ['req', '-x509', '-newkey', 'rsa:2048', '-nodes', '-days', '1', '-subj', `/CN=${name}`, '-keyout', path.join(directory, 'ca.key'), '-out', ca], { stdio: 'pipe' });
+  run('openssl', ['req', '-newkey', 'rsa:2048', '-nodes', '-subj', `/CN=${canonicalHost}`, '-keyout', key, '-out', path.join(directory, 'server.csr')], { stdio: 'pipe' });
+  run('openssl', ['x509', '-req', '-in', path.join(directory, 'server.csr'), '-CA', ca, '-CAkey', path.join(directory, 'ca.key'), '-CAcreateserial', '-days', '1', '-extfile', extension, '-out', certificate], { stdio: 'pipe' });
+  // The server never needs even the temporary CA private key after issuing TLS.
+  await fs.rm(path.join(directory, 'ca.key'));
+  const hostsFile = process.platform === 'win32' ? path.join(process.env.SystemRoot, 'System32/drivers/etc/hosts') : '/etc/hosts';
+  const originalHosts = await fs.readFile(hostsFile);
+  const hosts = path.join(directory, 'hosts');
+  await fs.writeFile(hosts, Buffer.concat([originalHosts, Buffer.from(`\n127.0.0.1 ${canonicalHost}\n`)]));
+  const original = path.join(directory, 'hosts.original'); await fs.writeFile(original, originalHosts);
+  const linuxCa = `/usr/local/share/ca-certificates/amalgm-examination-${crypto.randomUUID()}.crt`;
+  const nss = path.join(process.env.HOME || process.env.USERPROFILE, '.pki/nssdb');
+  const fingerprint = run('openssl', ['x509', '-in', ca, '-noout', '-fingerprint', '-sha1']).split('=')[1].trim().replace(/:/g, '');
+  let child; let changedHosts = false; let trusted = false; let nssTrusted = false;
+  let changedServiceEnvironment = false; let priorServiceCa = null;
+  const serviceCa = value => {
+    if (process.platform === 'darwin') run('launchctl', value === null ? ['unsetenv', 'NODE_EXTRA_CA_CERTS'] : ['setenv', 'NODE_EXTRA_CA_CERTS', value]);
+    else if (process.platform === 'linux') run('systemctl', ['--user', value === null ? 'unset-environment' : 'set-environment', value === null ? 'NODE_EXTRA_CA_CERTS' : `NODE_EXTRA_CA_CERTS=${value}`]);
+    else powershell("[Environment]::SetEnvironmentVariable('NODE_EXTRA_CA_CERTS', $env:AMALGM_EXAMINATION_CA, 'User')", { AMALGM_EXAMINATION_CA: value ?? '' });
+  };
+  const copyHosts = async source => {
+    if (process.platform === 'win32') await fs.copyFile(source, hostsFile);
+    else sudo('cp', [source, hostsFile]);
+  };
+  const close = async () => {
+    const errors = [];
+    try {
+      if (child && child.exitCode === null) {
+        child.stdin.end();
+        await new Promise((resolve, reject) => {
+          const timeout = setTimeout(() => reject(new Error('Privileged examination transport did not stop')), 10_000);
+          child.once('exit', () => { clearTimeout(timeout); resolve(); });
+        });
+      }
+    } catch (error) { errors.push(error); }
+    if (changedHosts) await copyHosts(original);
+    if (changedServiceEnvironment) serviceCa(priorServiceCa);
+    if (process.platform === 'darwin') {
+      if (trusted) sudo('security', ['remove-trusted-cert', '-d', ca]);
+      sudo('dscacheutil', ['-flushcache']);
+      sudo('killall', ['-HUP', 'mDNSResponder']);
+    } else if (process.platform === 'linux') {
+      if (nssTrusted) run('certutil', ['-D', '-d', `sql:${nss}`, '-n', name]);
+      if (trusted) { sudo('rm', ['-f', linuxCa]); sudo('update-ca-certificates', []); }
+    } else {
+      if (trusted) run('certutil.exe', ['-user', '-delstore', 'Root', fingerprint]);
+      run('ipconfig.exe', ['/flushdns']);
+    }
+    if (errors.length) throw new AggregateError(errors, 'Examination transport cleanup failed');
+  };
+  try {
+    if (process.platform === 'darwin') {
+      sudo('security', ['add-trusted-cert', '-d', '-r', 'trustRoot', '-k', '/Library/Keychains/System.keychain', ca]); trusted = true;
+    } else if (process.platform === 'linux') {
+      sudo('cp', [ca, linuxCa]); trusted = true; sudo('update-ca-certificates', []);
+      await fs.mkdir(nss, { recursive: true });
+      try { await fs.access(path.join(nss, 'cert9.db')); }
+      catch { run('certutil', ['-N', '--empty-password', '-d', `sql:${nss}`]); }
+      run('certutil', ['-A', '-d', `sql:${nss}`, '-n', name, '-t', 'C,,', '-i', ca]); nssTrusted = true;
+    } else {
+      powershell("if (-not ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) { throw 'Disposable Windows CI account must be an administrator' }");
+      run('certutil.exe', ['-user', '-addstore', 'Root', ca]); trusted = true;
+    }
+    if (serviceEnvironment) {
+      if (process.platform === 'darwin') { try { priorServiceCa = run('launchctl', ['getenv', 'NODE_EXTRA_CA_CERTS']).trim() || null; } catch { /* unset */ } }
+      else if (process.platform === 'linux') priorServiceCa = run('systemctl', ['--user', 'show-environment']).split('\n').find(line => line.startsWith('NODE_EXTRA_CA_CERTS='))?.slice('NODE_EXTRA_CA_CERTS='.length) ?? null;
+      else priorServiceCa = JSON.parse(powershell("ConvertTo-Json -Compress -InputObject ([Environment]::GetEnvironmentVariable('NODE_EXTRA_CA_CERTS', 'User'))"));
+      serviceCa(ca); changedServiceEnvironment = true;
+    }
+    await copyHosts(hosts); changedHosts = true;
+    if (process.platform === 'darwin') { sudo('dscacheutil', ['-flushcache']); sudo('killall', ['-HUP', 'mDNSResponder']); }
+    else if (process.platform === 'win32') run('ipconfig.exe', ['/flushdns']);
+    const config = path.join(directory, 'config.json');
+    await fs.writeFile(config, JSON.stringify({ ...view, key, certificate }), { mode: 0o600 });
+    child = spawn(process.platform === 'win32' ? process.execPath : 'sudo', [
+      ...(process.platform === 'win32' ? [] : ['-n', process.execPath]), fileURLToPath(import.meta.url), '--serve', config], {
+      env: { ...process.env, CI: 'true', GITHUB_ACTIONS: 'true' }, stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let stderr = ''; let sequence = 0; const pending = new Map();
+    child.stderr.on('data', data => { stderr = (stderr + data).slice(-8000); });
+    const messages = readline.createInterface({ input: child.stdout });
+    messages.on('line', line => {
+      const value = JSON.parse(line); const callback = pending.get(value.id);
+      if (callback) { pending.delete(value.id); value.error ? callback.reject(new Error(value.error)) : callback.resolve(value); }
+    });
+    child.on('error', error => { for (const callback of pending.values()) callback.reject(error); pending.clear(); });
+    child.on('exit', () => { for (const callback of pending.values()) callback.reject(new Error(`Examination transport stopped: ${stderr}`)); pending.clear(); });
+    const command = async operation => {
+      const id = ++sequence;
+      return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => { pending.delete(id); reject(new Error(`Examination transport timed out: ${stderr}`)); }, 15_000);
+        pending.set(id, { resolve: value => { clearTimeout(timeout); resolve(value); }, reject: error => { clearTimeout(timeout); reject(error); } });
+        child.stdin.write(JSON.stringify({ id, ...operation }) + '\n');
+      });
+    };
+    await command({ operation: 'status' });
+    return { ca, close, command };
+  } catch (error) { await close(); throw error; }
+}
+
+async function serve(configFile) {
+  // Only this disposable CI process needs the privileged HTTPS listening port.
+  if (process.platform !== 'win32') assert.equal(process.getuid(), 0);
+  const config = JSON.parse(await fs.readFile(configFile, 'utf8'));
+  const immutable = config.immutable;
+  let selected = config.previous; let unavailable = false; let fault = false; let failures = 0; let artifactRequests = 0;
+  const streams = new Set(); const sockets = new Set();
+  const artifacts = new Map(config.artifacts.map(entry => [entry.path, entry]));
+  const server = https.createServer({ key: await fs.readFile(config.key), cert: await fs.readFile(config.certificate) }, async (req, res) => {
+    try {
+      const url = new URL(req.url, `https://${canonicalHost}`);
+      if (req.headers.host !== canonicalHost || !['GET', 'HEAD'].includes(req.method)) { res.writeHead(400).end(); return; }
+      if (url.pathname === config.events) {
+        if (unavailable) { res.writeHead(503).end(); return; }
+        res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-store' });
+        streams.add(res); res.on('close', () => streams.delete(res)); res.write('event: ready\ndata: {}\n\n'); return;
+      }
+      const resource = selected[url.pathname] ?? immutable[url.pathname];
+      if (resource) {
+        const bytes = Buffer.from(resource.body, 'base64');
+        res.writeHead(200, { 'content-type': resource.contentType || 'application/json', 'content-length': bytes.length });
+        res.end(req.method === 'HEAD' ? undefined : bytes); return;
+      }
+      const artifact = artifacts.get(url.pathname);
+      if (artifact) {
+        artifactRequests++;
+        const corrupt = fault && artifact.faultable !== false;
+        if (corrupt) failures++;
+        res.writeHead(200, { 'content-length': artifact.size, 'content-type': 'application/octet-stream' });
+        if (req.method === 'HEAD') { res.end(); return; }
+        let first = true;
+        const transport = new Transform({ transform(chunk, _encoding, callback) {
+          if (first && corrupt) chunk[0] ^= 1;
+          first = false; callback(null, chunk);
+        } });
+        await pipeline(createReadStream(artifact.file), transport, res);
+        return;
+      }
+      res.writeHead(404).end();
+    } catch (error) { res.destroy(error); }
+  });
+  server.on('connection', socket => { sockets.add(socket); socket.on('close', () => sockets.delete(socket)); });
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(443, '127.0.0.1', resolve); });
+  const heartbeat = setInterval(() => { for (const stream of streams) stream.write(': keepalive\n\n'); }, 15_000);
+  for await (const line of readline.createInterface({ input: process.stdin })) {
+    const command = JSON.parse(line);
+    try {
+      if (command.operation === 'publish') {
+        selected = config.candidate; unavailable = false; fault = command.corrupt === true;
+        for (const stream of streams) stream.write(`event: promotion\ndata: ${JSON.stringify(config.hint)}\n\n`);
+      } else if (command.operation === 'reset') { selected = config.previous; unavailable = false; fault = false; }
+      else if (command.operation === 'unavailable') {
+        selected = {}; unavailable = true; fault = false;
+        for (const stream of streams) stream.end();
+      }
+      else assert.equal(command.operation, 'status');
+      process.stdout.write(JSON.stringify({ id: command.id, subscribers: streams.size, failures, artifactRequests }) + '\n');
+    } catch (error) { process.stdout.write(JSON.stringify({ id: command.id, error: error.message }) + '\n'); }
+  }
+  clearInterval(heartbeat);
+  for (const stream of streams) stream.end();
+  for (const socket of sockets) socket.destroy();
+  await new Promise(resolve => server.close(resolve));
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)) && process.argv[2] === '--serve') {
+  await serve(process.argv[3]);
+}

package/examinations/runtime-upgrade.native-test.mjs

@@ -0,0 +1,198 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import { createWriteStream } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+import { DatabaseSync } from 'node:sqlite';
+import { Metadata, MetadataKind } from '@tufjs/models';
+import { admitManagedRuntimeRelease } from '@amalgm/core/supervision';
+import { runtimeRoot } from '../dist/updates/trust.js';
+import { examineArchive, hashFile, runIsolated } from '../dist/updates/artifacts.js';
+import { runtimeHost } from '../dist/updates/store.js';
+import { canonicalHost, startNetworkView } from './network-view.mjs';
+
+const encode = value => Buffer.from(JSON.stringify(value) + '\n');
+const digest = value => crypto.createHash('sha256').update(encode(value)).digest('hex');
+const resource = value => ({ body: encode(value).toString('base64') });
+const readJson = async file => JSON.parse(await fs.readFile(file, 'utf8'));
+const pause = ms => new Promise(resolve => setTimeout(resolve, ms));
+async function until(description, action, timeout = 600_000) {
+  const deadline = Date.now() + timeout; let last;
+  do {
+    try { const value = await action(); if (value) return value; }
+    catch (error) { last = error; }
+    await pause(250);
+  } while (Date.now() < deadline);
+  throw new Error(`${description} did not complete${last ? `: ${last.message}` : ''}`);
+}
+function journal(identity) {
+  const db = new DatabaseSync(path.toNamespacedPath(path.join(identity.serviceDir, 'updates.sqlite')), { readOnly: true });
+  try {
+    const read = key => {
+      const row = db.prepare('SELECT value FROM update_state WHERE key = ?').get(key);
+      return row ? JSON.parse(row.value) : null;
+    };
+    return { launch: read('launch'), policy: read('policy') };
+  } finally { db.close(); }
+}
+function validateReceipt(receipt, roots, lane) {
+  assert.ok(receipt?.target && receipt.authorization, 'An exact signed installed receipt is required');
+  const target = receipt.target;
+  const authorization = Metadata.fromJSON(MetadataKind.Targets, receipt.authorization);
+  let verified = false;
+  for (const root of roots) {
+    try { root.verifyDelegate('targets', authorization); verified = true; break; } catch { /* Another historical root may own the receipt. */ }
+  }
+  assert.ok(verified, 'Installed receipt has no signature from its scoped public root history');
+  const entry = authorization.signed.targets['current.json'];
+  assert.equal(Object.keys(authorization.signed.targets).length, 1);
+  assert.equal(authorization.signed.delegations, undefined);
+  assert.equal(entry.custom.amalgm, `runtime/${lane}`);
+  assert.equal(entry.length, encode(target).length); assert.equal(entry.hashes.sha256, digest(target));
+  return admitManagedRuntimeRelease(target, digest(target), { runtimeLabel: lane, branch: lane }, runtimeHost());
+}
+
+/** The producer's public roots and signed prepared generation are input bytes.
+ * No native job receives a release key or advances the actual selected head. */
+export function runtimeExaminationView(examination, baselineReceipt) {
+  assert.equal(examination.schema, 1);
+  const lane = examination.lane;
+  assert.ok(['main', 'preview'].includes(lane));
+  assert.equal(examination.id, examination.candidate.target.id);
+  const scope = `/trust/runtime/${lane}`;
+  const immutable = {};
+  assert.ok(Array.isArray(examination.roots) && examination.roots.length);
+  const roots = examination.roots.map((value, index) => {
+    const root = runtimeRoot(value, lane);
+    assert.equal(root.signed.version, index + 1);
+    if (index) runtimeRoot(examination.roots[index - 1], lane).verifyDelegate('root', root);
+    immutable[`${scope}/metadata/${index + 1}.root.json`] = resource(value);
+    return root;
+  });
+  for (const generation of [examination.previous, examination.candidate].filter(Boolean)) {
+    validateReceipt(generation, roots, lane);
+    const root = roots[generation.rootVersion - 1]; assert.ok(root);
+    root.verifyDelegate('targets', Metadata.fromJSON(MetadataKind.Targets, generation.authorization));
+    const snapshot = Metadata.fromJSON(MetadataKind.Snapshot, generation.snapshot);
+    const timestamp = Metadata.fromJSON(MetadataKind.Timestamp, generation.timestamp);
+    root.verifyDelegate('snapshot', snapshot); root.verifyDelegate('timestamp', timestamp);
+    for (const [parent, child, filename] of [[generation.snapshot, generation.authorization, 'targets.json'], [generation.timestamp, generation.snapshot, 'snapshot.json']]) {
+      const link = parent.signed.meta[filename];
+      assert.equal(link.version, child.signed.version); assert.equal(link.length, encode(child).length);
+      assert.equal(link.hashes.sha256, digest(child));
+    }
+    if (generation === examination.candidate) {
+      for (const value of [generation.authorization, generation.snapshot, generation.timestamp, examination.roots[generation.rootVersion - 1]]) {
+        assert.ok(Date.parse(value.signed.expires) > Date.now(), 'The candidate authority must remain fresh throughout certification');
+      }
+    }
+    immutable[`${scope}/metadata/${generation.authorization.signed.version}.targets.json`] = resource(generation.authorization);
+    immutable[`${scope}/metadata/${generation.version}.snapshot.json`] = resource(generation.snapshot);
+    immutable[`${scope}/targets/${digest(generation.target)}.current.json`] = resource(generation.target);
+    immutable[`${scope}/releases/${generation.target.id}/receipt.json`] = resource({ target: generation.target, authorization: generation.authorization });
+  }
+  const receipt = examination.previous ?? baselineReceipt;
+  const baseline = validateReceipt(receipt, roots, lane);
+  const candidate = validateReceipt(examination.candidate, roots, lane);
+  assert.ok(candidate.target.sequence > baseline.target.sequence);
+  assert.notEqual(candidate.target.id, baseline.target.id);
+  immutable[`${scope}/releases/${baseline.target.id}/receipt.json`] = resource({ target: receipt.target, authorization: receipt.authorization });
+  const view = generation => generation ? { [`${scope}/metadata/timestamp.json`]: resource(generation.timestamp) } : {};
+  return { baseline, candidate, immutable, previous: view(examination.previous), candidateView: view(examination.candidate), events: `${scope}/events` };
+}
+
+test('the real native Shell service replaces its authorized package and survives OS restart with identity and state intact', {
+  skip: process.env.AMALGM_TEST_NATIVE_RUNTIME_UPDATES !== '1', timeout: 1_800_000,
+}, async t => {
+  assert.equal(process.env.CI, 'true'); assert.equal(process.env.GITHUB_ACTIONS, 'true');
+  assert.ok(['darwin', 'linux', 'win32'].includes(process.platform));
+  assert.ok(process.env.AMALGM_RUNTIME_EXAMINATION_DIR, 'The producer must supply signed examination inputs');
+  const directory = path.resolve(process.env.AMALGM_RUNTIME_EXAMINATION_DIR);
+  const examination = await readJson(path.join(directory, 'examination.json'));
+  const baselineReceipt = examination.previous ? null : await readJson(path.join(directory, 'baseline.json'));
+  const view = runtimeExaminationView(examination, baselineReceipt);
+  const artifact = view.baseline.target.release.units[0].artifact;
+  const nextArtifact = view.candidate.target.release.units[0].artifact;
+  const proof = { schema: 1, lane: examination.lane, platform: process.platform, architecture: process.arch,
+    previous: view.baseline.target.id, candidate: view.candidate.target.id,
+    previousDigest: view.baseline.digest, candidateDigest: view.candidate.digest,
+    bootstrapProof: examination.previous === null, legacyAdoptionCertified: false, passed: false,
+    previousArtifact: artifact, candidateArtifact: nextArtifact, checkpoints: [] };
+  const temporary = await fs.mkdtemp(path.join(os.tmpdir(), 'amalgm-native-runtime-update-'));
+  let network; let service;
+  t.after(async () => {
+    const errors = [];
+    try { await service?.close(); } catch (error) { errors.push(error); }
+    try { await network?.close(); } catch (error) { errors.push(error); }
+    if (errors.length) { proof.passed = false; proof.cleanupErrors = errors.map(error => error.message); }
+    await fs.writeFile(path.join(directory, `runtime-update-${process.platform}.json`), JSON.stringify(proof, null, 2) + '\n');
+    await fs.rm(temporary, { recursive: true, force: true, maxRetries: 5 });
+    if (errors.length) throw new AggregateError(errors, 'Native runtime examination cleanup failed');
+  });
+  const archive = path.join(temporary, 'baseline.tgz');
+  const response = await fetch(`https://registry.npmjs.org/amalgm/-/amalgm-${artifact.version}.tgz`, { redirect: 'error', signal: AbortSignal.timeout(180_000) });
+  assert.equal(response.status, 200, 'The exact baseline public package must be available');
+  await pipeline(Readable.fromWeb(response.body), createWriteStream(archive, { flags: 'wx' }));
+  assert.equal(await hashFile(archive), artifact.sha512);
+  await examineArchive(archive, temporary);
+  const packageRoot = path.join(temporary, 'package');
+  const manifest = await readJson(path.join(packageRoot, 'package.json'));
+  assert.equal(manifest.name, 'amalgm'); assert.equal(manifest.version, artifact.version);
+  for (const name of ['repository', 'branch', 'commit']) assert.equal(manifest.amalgmSource[name], artifact.source[name]);
+  assert.equal(await hashFile(path.join(packageRoot, 'npm-shrinkwrap.json')), artifact.lockSha512);
+  const shippedRoot = await readJson(path.join(packageRoot, 'config/releases/trust/runtime', `${examination.lane}.root.json`));
+  assert.deepEqual(shippedRoot, examination.roots[shippedRoot.signed.version - 1], 'The package must carry the actual reviewed trust root');
+  const npm = path.join(path.dirname(createRequire(import.meta.url).resolve('npm/package.json')), 'bin/npm-cli.js');
+  await runIsolated(process.execPath, [npm, 'ci', '--omit=dev', '--strict-allow-scripts', '--no-audit', '--no-fund'], packageRoot, new AbortController().signal);
+  network = await startNetworkView({ temporary, immutable: view.immutable, previous: view.previous, candidate: view.candidateView,
+    events: view.events, hint: { id: examination.id, sequence: examination.candidate.target.sequence }, serviceEnvironment: true });
+  const { nativeInstalledService } = await import(pathToFileURL(path.join(packageRoot, 'examinations/native-service.mjs')).href);
+  service = await nativeInstalledService({ packageRoot, label: examination.lane });
+  const baseline = await until('Verified installed baseline and native service health', async () => {
+    const state = journal(service.identity); const status = await service.status();
+    return state.policy?.active?.digest === view.baseline.digest && state.policy.activeHealthy
+      && !state.policy.transaction && status.version === artifact.version ? status : null;
+  });
+  assert.ok(baseline.bootstrapPid && baseline.bootstrapPid !== baseline.controllerPid, 'The OS must own the stable launcher independently of the controller package');
+  const marker = crypto.randomUUID();
+  const workspace = path.join(service.paths.userRoot, 'workspaces'); await fs.mkdir(workspace, { recursive: true });
+  const markerFile = path.join(workspace, 'native-runtime-upgrade-marker.txt'); await fs.writeFile(markerFile, marker);
+  await until('Runtime promotion event subscription', async () => (await network.command({ operation: 'status' })).subscribers > 0);
+  proof.checkpoints.push({ phase: 'baseline', bootstrapPid: baseline.bootstrapPid, controllerPid: baseline.controllerPid, childPid: baseline.childPid });
+  await network.command({ operation: 'publish' });
+  const current = await until('Event-driven staging, controller replacement, and native runtime healthy commit', async () => {
+    const state = journal(service.identity); const status = await service.status();
+    return state.policy?.active?.digest === view.candidate.digest && state.policy.activeHealthy
+      && !state.policy.transaction && state.launch.pending === null && status.version === nextArtifact.version ? status : null;
+  });
+  assert.equal(current.bootstrapPid, baseline.bootstrapPid, 'A package handover must preserve the stable OS-owned launcher');
+  assert.notEqual(current.controllerPid, baseline.controllerPid); assert.notEqual(current.childPid, baseline.childPid);
+  assert.deepEqual(current.binding, baseline.binding);
+  assert.deepEqual(current.durable, baseline.durable, 'Native replacement must preserve registration and credentials byte for byte');
+  assert.equal(await fs.readFile(markerFile, 'utf8'), marker);
+  for (const name of ['repository', 'branch', 'commit']) assert.equal(current.source[name], nextArtifact.source[name]);
+  const selected = journal(service.identity).launch.current;
+  const actual = await readJson(path.resolve(selected.bin, '../../package.json'));
+  assert.equal(actual.version, nextArtifact.version);
+  assert.equal(await hashFile(path.resolve(selected.bin, '../../npm-shrinkwrap.json')), nextArtifact.lockSha512);
+  proof.checkpoints.push({ phase: 'committed-candidate', bootstrapPid: current.bootstrapPid, controllerPid: current.controllerPid, childPid: current.childPid });
+  const selectors = ['--user', service.identity.user, '--home', service.identity.home, '--amalgm-root', service.identity.amalgmRoot, '--branch', examination.lane];
+  const prefix = examination.lane === 'preview' ? ['preview'] : [];
+  const invoke = verb => runIsolated(selected.node, [selected.bin, ...prefix, 'service', verb, ...selectors], temporary, new AbortController().signal, 90_000);
+  await invoke('stop');
+  await invoke('start');
+  const restarted = await until('Native OS restart preserves committed candidate', async () => {
+    const state = journal(service.identity); const status = await service.status();
+    return status.version === nextArtifact.version && status.bootstrapPid !== current.bootstrapPid
+      && state.policy?.active?.digest === view.candidate.digest && !state.policy.transaction && state.launch.pending === null ? status : null;
+  });
+  assert.deepEqual(restarted.durable, baseline.durable); assert.equal(await fs.readFile(markerFile, 'utf8'), marker);
+  proof.checkpoints.push({ phase: 'native-os-restart', bootstrapPid: restarted.bootstrapPid, controllerPid: restarted.controllerPid, childPid: restarted.childPid });
+  proof.passed = true;
+});