mecord-connect 1.0.0

package/runtime/app/src/core/relay-result-store.js

@@ -0,0 +1,321 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { OperatorError } from './errors.js';
+                                                                        
+import { readDurableStateText, writeDurableStateText } from './durable-state.js';
+
+const MAX_STREAMS = 10_000;
+const MAX_RESULTS_PER_STREAM = 10_000;
+const MAX_RESULT_BYTES = 256 * 1024;
+const DEFAULT_RETENTION_MS = 24 * 60 * 60_000;
+const MAX_RETENTION_MS = 30 * 24 * 60 * 60_000;
+
+                                          
+
+                          
+              
+                     
+                      
+                       
+                          
+                                           
+                     
+                      
+  
+
+                                                                       
+                                                           
+
+export class RelayResultStore {
+  #file        ;
+  #queue                = Promise.resolve();
+  #clock            ;
+  #retentionMs        ;
+
+  constructor(stateDir        , options                                               = {}) {
+    this.#file = path.join(path.resolve(stateDir), 'relay-results.json');
+    this.#clock = options.clock ?? (() => new Date());
+    this.#retentionMs = boundedRetention(options.retentionMs);
+  }
+
+  async put(deviceIdInput        , seqInput        , deliveryIdInput        , resultInput            , idempotencyKeyInput         , replayAuthorityInput                         )                                                             {
+    const deviceId = validUuid(deviceIdInput, 'deviceId');
+    const seq = validSeq(seqInput);
+    const deliveryId = validUuid(deliveryIdInput, 'deliveryId');
+    const idempotencyKey = idempotencyKeyInput === undefined ? undefined : validIdempotencyKey(idempotencyKeyInput);
+    const replayAuthority = replayAuthorityInput === undefined ? undefined : safeReplayAuthority(replayAuthorityInput, deviceId);
+    if (replayAuthority && !idempotencyKey) throw new OperatorError('RELAY_RESULT_AUTHORITY_INVALID', 'Replay authority requires an idempotency key.');
+    const result = safeResult(resultInput);
+    const resultSha256 = hashResult(result);
+    return await this.#mutate((state) => {
+      pruneExpired(state, this.#clock().getTime(), this.#retentionMs);
+      let stream = state.streams.find((candidate) => candidate.deviceId === deviceId);
+      if (!stream) {
+        if (state.streams.length >= MAX_STREAMS) throw new OperatorError('RELAY_RESULT_STREAM_LIMIT', 'Relay result stream limit reached.');
+        stream = { deviceId, results: [] };
+        state.streams.push(stream);
+        state.streams.sort((a, b) => a.deviceId.localeCompare(b.deviceId));
+      }
+      const existing = stream.results.find((entry) => entry.seq === seq || entry.deliveryId === deliveryId);
+      if (existing) {
+        if (existing.seq !== seq || existing.deliveryId !== deliveryId || existing.resultSha256 !== resultSha256) {
+          throw new OperatorError('RELAY_RESULT_CONFLICT', 'A different result is already stored for this delivery sequence or ID.');
+        }
+        if (idempotencyKey && existing.idempotencyKey && existing.idempotencyKey !== idempotencyKey) {
+          throw new OperatorError('RELAY_RESULT_CONFLICT', 'Stored result replay authority does not match this delivery.');
+        }
+        if (replayAuthority && existing.replayAuthority && !sameReplayAuthority(existing.replayAuthority, replayAuthority)) {
+          throw new OperatorError('RELAY_RESULT_CONFLICT', 'Stored result account authority does not match this delivery.');
+        }
+        if (idempotencyKey && !existing.idempotencyKey && !existing.consumedAt) existing.idempotencyKey = idempotencyKey;
+        if (replayAuthority && !existing.replayAuthority && !existing.consumedAt) existing.replayAuthority = replayAuthority;
+        return { result: clone(existing), duplicate: true };
+      }
+      if (stream.results.length >= MAX_RESULTS_PER_STREAM) throw new OperatorError('RELAY_RESULT_LIMIT', 'Relay result retention limit reached for this device.');
+      const stored                    = { seq, deliveryId, result, resultSha256, idempotencyKey, replayAuthority, recordedAt: this.#clock().toISOString() };
+      stream.results.push(stored);
+      stream.results.sort((a, b) => a.seq - b.seq);
+      return { result: clone(stored), duplicate: false };
+    });
+  }
+
+  async get(deviceIdInput        , seqInput        )                                    {
+    const deviceId = validUuid(deviceIdInput, 'deviceId');
+    const seq = validSeq(seqInput);
+    const state = await this.#read();
+    const result = state.streams.find((stream) => stream.deviceId === deviceId)?.results.find((entry) => entry.seq === seq);
+    if (!result || result.consumedAt || isExpired(result, this.#clock().getTime(), this.#retentionMs)) return null;
+    return clone(result);
+  }
+
+  async findByIdempotencyKey(idempotencyKeyInput        )                                                                  {
+    const idempotencyKey = validIdempotencyKey(idempotencyKeyInput);
+    return await this.#mutate((state) => {
+      pruneExpired(state, this.#clock().getTime(), this.#retentionMs);
+      let found                                                         = null;
+      for (const stream of state.streams) {
+        const match = stream.results.find((entry) => !entry.consumedAt && entry.idempotencyKey === idempotencyKey);
+        if (!match) continue;
+        if (found) throw new OperatorError('RELAY_RESULT_STATE_CORRUPT', 'Relay result replay authority is duplicated.');
+        found = { deviceId: stream.deviceId, result: clone(match) };
+      }
+      return found;
+    });
+  }
+
+  async consume(deviceIdInput        , seqInput        , deliveryIdInput        )                                    {
+    const deviceId = validUuid(deviceIdInput, 'deviceId');
+    const seq = validSeq(seqInput);
+    const deliveryId = validUuid(deliveryIdInput, 'deliveryId');
+    return await this.#mutate((state) => {
+      pruneExpired(state, this.#clock().getTime(), this.#retentionMs);
+      const entry = state.streams.find((stream) => stream.deviceId === deviceId)?.results.find((candidate) => candidate.seq === seq);
+      if (!entry || entry.consumedAt) return null;
+      if (entry.deliveryId !== deliveryId) throw new OperatorError('RELAY_RESULT_DELIVERY_MISMATCH', 'Stored result does not match the requested delivery ID.');
+      if (!entry.result) throw new OperatorError('RELAY_RESULT_STATE_CORRUPT', 'Available relay result is missing its payload.');
+      const consumed = clone(entry);
+      entry.result = undefined;
+      entry.idempotencyKey = undefined;
+      entry.replayAuthority = undefined;
+      entry.consumedAt = this.#clock().toISOString();
+      return consumed;
+    });
+  }
+
+  async removeExact(deviceIdInput        , seqInput        , deliveryIdInput        )                   {
+    const deviceId = validUuid(deviceIdInput, 'deviceId');
+    const seq = validSeq(seqInput);
+    const deliveryId = validUuid(deliveryIdInput, 'deliveryId');
+    return await this.#mutate((state) => {
+      const stream = state.streams.find((item) => item.deviceId === deviceId);
+      if (!stream) return false;
+      const before = stream.results.length;
+      stream.results = stream.results.filter((entry) => !(entry.seq === seq && entry.deliveryId === deliveryId));
+      if (stream.results.length === 0) state.streams = state.streams.filter((item) => item !== stream);
+      return stream.results.length !== before;
+    });
+  }
+
+  async pruneExpired()                  {
+    return await this.#mutate((state) => pruneExpired(state, this.#clock().getTime(), this.#retentionMs));
+  }
+
+  async has(deviceIdInput        , seqInput        , deliveryIdInput        )                   {
+    const deviceId = validUuid(deviceIdInput, 'deviceId');
+    const seq = validSeq(seqInput);
+    const deliveryId = validUuid(deliveryIdInput, 'deliveryId');
+    const result = await this.get(deviceId, seq);
+    return Boolean(result && result.deliveryId === deliveryId);
+  }
+
+  async purgeDevice(deviceIdInput        )                  {
+    const deviceId = validUuid(deviceIdInput, 'deviceId');
+    return await this.#mutate((state) => {
+      const stream = state.streams.find((item) => item.deviceId === deviceId);
+      if (!stream) return 0;
+      const removed = stream.results.length;
+      state.streams = state.streams.filter((item) => item.deviceId !== deviceId);
+      return removed;
+    });
+  }
+
+  async #read()                       {
+    try {
+      const text = await readDurableStateText(this.#file, {
+        maxBytes: 256 * 1024 * 1024,
+        errorCode: 'RELAY_RESULT_STATE_CORRUPT',
+        invalidMessage: 'Relay result state is invalid.'
+      });
+      return validateState(JSON.parse(text));
+    } catch (error) {
+      if ((error                         ).code === 'ENOENT') return { version: 1, streams: [] };
+      if (error instanceof OperatorError) throw error;
+      throw new OperatorError('RELAY_RESULT_STATE_CORRUPT', 'Relay result state could not be read.');
+    }
+  }
+
+  async #write(stateInput             )                {
+    const state = validateState(stateInput);
+    await writeDurableStateText(this.#file, JSON.stringify(state, null, 2), {
+      maxBytes: 256 * 1024 * 1024,
+      errorCode: 'RELAY_RESULT_STATE_CORRUPT',
+      invalidMessage: 'Relay result state is invalid.'
+    });
+  }
+
+  async #mutate   (mutator                                        )             {
+    let release             ;
+    const previous = this.#queue;
+    this.#queue = new Promise      ((resolve) => { release = resolve; });
+    await previous;
+    try {
+      const state = await this.#read();
+      const value = await mutator(state);
+      await this.#write(state);
+      return value;
+    } finally {
+      release();
+    }
+  }
+}
+
+function boundedRetention(value                    )         {
+  if (value === undefined) return DEFAULT_RETENTION_MS;
+  if (!Number.isFinite(value) || value < 60_000 || value > MAX_RETENTION_MS) {
+    throw new OperatorError('RELAY_RESULT_RETENTION_INVALID', `Relay result retention must be between 60000 and ${MAX_RETENTION_MS} ms.`);
+  }
+  return Math.trunc(value);
+}
+
+function isExpired(result                   , now        , retentionMs        )          {
+  return Date.parse(result.recordedAt) <= now - retentionMs;
+}
+
+function pruneExpired(state             , now        , retentionMs        )         {
+  let removed = 0;
+  for (const stream of state.streams) {
+    const kept = stream.results.filter((entry) => !isExpired(entry, now, retentionMs));
+    removed += stream.results.length - kept.length;
+    stream.results = kept;
+  }
+  state.streams = state.streams.filter((stream) => stream.results.length > 0);
+  return removed;
+}
+
+function safeResult(input         )             {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new OperatorError('RELAY_RESULT_INVALID', 'Relay result must be a JSON object.');
+  let text        ;
+  try { text = JSON.stringify(input); } catch { throw new OperatorError('RELAY_RESULT_INVALID', 'Relay result is not JSON serializable.'); }
+  if (!text || Buffer.byteLength(text, 'utf8') > MAX_RESULT_BYTES) throw new OperatorError('RELAY_RESULT_TOO_LARGE', 'Relay result exceeds the bounded size.');
+  const parsed = JSON.parse(text);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new OperatorError('RELAY_RESULT_INVALID', 'Relay result must remain a JSON object after serialization.');
+  return parsed              ;
+}
+
+function hashResult(result            )         {
+  return crypto.createHash('sha256').update(JSON.stringify(result)).digest('hex');
+}
+
+function validateState(input             )              {
+  if (!input || typeof input !== 'object' || input.version !== 1 || !Array.isArray(input.streams) || input.streams.length > MAX_STREAMS) throw new OperatorError('RELAY_RESULT_STATE_CORRUPT', 'Relay result state structure is invalid.');
+  const devices = new Set        ();
+  const replayKeys = new Set        ();
+  const streams = input.streams.map((raw) => {
+    const deviceId = validUuid(raw.deviceId, 'deviceId');
+    if (devices.has(deviceId)) throw new OperatorError('RELAY_RESULT_STATE_CORRUPT', 'Relay result state contains duplicate device streams.');
+    devices.add(deviceId);
+    if (!Array.isArray(raw.results) || raw.results.length > MAX_RESULTS_PER_STREAM) throw new OperatorError('RELAY_RESULT_STATE_CORRUPT', 'Relay result stream exceeds the retention limit.');
+    const seqs = new Set        ();
+    const ids = new Set        ();
+    const results = raw.results.map((entry) => {
+      const seq = validSeq(entry.seq);
+      const deliveryId = validUuid(entry.deliveryId, 'deliveryId');
+      if (seqs.has(seq) || ids.has(deliveryId)) throw new OperatorError('RELAY_RESULT_STATE_CORRUPT', 'Relay result state contains duplicate sequence or delivery ID.');
+      seqs.add(seq); ids.add(deliveryId);
+      const resultSha256 = String(entry.resultSha256 ?? '');
+      if (!/^[0-9a-f]{64}$/.test(resultSha256)) throw new OperatorError('RELAY_RESULT_STATE_CORRUPT', 'Relay result hash is invalid.');
+      const idempotencyKey = entry.idempotencyKey === undefined ? undefined : validIdempotencyKey(String(entry.idempotencyKey));
+      const replayAuthority = entry.replayAuthority === undefined ? undefined : safeReplayAuthority(entry.replayAuthority, deviceId);
+      if (replayAuthority && !idempotencyKey) throw new OperatorError('RELAY_RESULT_STATE_CORRUPT', 'Relay replay authority requires an idempotency key.');
+      if (idempotencyKey) {
+        if (replayKeys.has(idempotencyKey)) throw new OperatorError('RELAY_RESULT_STATE_CORRUPT', 'Relay result state contains duplicate replay authority.');
+        replayKeys.add(idempotencyKey);
+      }
+      const recordedAt = validIso(String(entry.recordedAt ?? ''));
+      const consumedAt = entry.consumedAt === undefined ? undefined : validIso(String(entry.consumedAt));
+      let result                        ;
+      if (consumedAt) {
+        if (entry.result !== undefined || idempotencyKey || replayAuthority) throw new OperatorError('RELAY_RESULT_STATE_CORRUPT', 'Consumed relay result must not retain payload or replay authority.');
+      } else {
+        try { result = safeResult(entry.result); }
+        catch { throw new OperatorError('RELAY_RESULT_STATE_CORRUPT', 'Available relay result payload is invalid.'); }
+        if (resultSha256 !== hashResult(result)) throw new OperatorError('RELAY_RESULT_STATE_CORRUPT', 'Relay result hash does not match its stored result.');
+      }
+      return { seq, deliveryId, result, resultSha256, idempotencyKey, replayAuthority, recordedAt, consumedAt }                            ;
+    }).sort((a, b) => a.seq - b.seq);
+    return { deviceId, results };
+  });
+  return { version: 1, streams };
+}
+
+function clone(result                   )                    {
+  return { ...result, result: result.result === undefined ? undefined : structuredClone(result.result), replayAuthority: result.replayAuthority ? { ...result.replayAuthority } : undefined };
+}
+
+function safeReplayAuthority(input         , expectedDeviceId        )                         {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new OperatorError('RELAY_RESULT_AUTHORITY_INVALID', 'Relay result replay authority is invalid.');
+  const raw = input                           ;
+  const accountId = validUuid(String(raw.accountId ?? ''), 'authority accountId');
+  const deviceId = validUuid(String(raw.deviceId ?? ''), 'authority deviceId');
+  const generation = Number(raw.generation);
+  if (deviceId !== expectedDeviceId || !Number.isSafeInteger(generation) || generation < 1) throw new OperatorError('RELAY_RESULT_AUTHORITY_INVALID', 'Relay result replay authority is invalid.');
+  return { accountId, deviceId, generation };
+}
+
+function sameReplayAuthority(a                        , b                        )          {
+  return a.accountId === b.accountId && a.deviceId === b.deviceId && a.generation === b.generation;
+}
+
+function validIdempotencyKey(input        )         {
+  const value = String(input ?? '').toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(value)) throw new OperatorError('RELAY_IDEMPOTENCY_INVALID', 'Relay idempotency key is invalid.');
+  return value;
+}
+
+function validSeq(input        )         {
+  const seq = Number(input);
+  if (!Number.isSafeInteger(seq) || seq < 1) throw new OperatorError('RELAY_RESULT_SEQUENCE_INVALID', 'Relay result sequence must be a positive safe integer.');
+  return seq;
+}
+
+function validUuid(input        , label        )         {
+  const value = String(input ?? '');
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)) throw new OperatorError('RELAY_RESULT_ID_INVALID', `${label} must be a UUID.`);
+  return value.toLowerCase();
+}
+
+function validIso(input        )         {
+  const time = Date.parse(input);
+  if (!Number.isFinite(time) || new Date(time).toISOString() !== input) throw new OperatorError('RELAY_RESULT_STATE_CORRUPT', 'Relay result timestamp must be ISO format.');
+  return input;
+}

package/runtime/app/src/core/release-update.js

@@ -0,0 +1,253 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { OperatorError } from './errors.js';
+import { createDurableStateBytes, readDurableStateBytes } from './durable-state.js';
+
+const MAX_MANIFEST_BYTES = 256 * 1024;
+const MAX_ARTIFACTS = 32;
+const MAX_ARTIFACT_BYTES = 512 * 1024 * 1024;
+const PRODUCT = 'operator-runtime';
+const UPDATE_STAGE_OPTIONS = {
+  maxBytes: MAX_ARTIFACT_BYTES,
+  errorCode: 'UPDATE_STAGE_INVALID',
+  invalidMessage: 'Staged update artifact is invalid.'
+}         ;
+
+                                               
+                                                                
+
+                                  
+                                         
+                        
+                            
+              
+                 
+                    
+ 
+
+                                  
+                   
+                          
+                          
+                  
+                      
+                               
+ 
+
+                                        
+                            
+                    
+ 
+
+export class ReleaseUpdateVerifier {
+  #publicKeyPem        ;
+
+  constructor(publicKeyPem        ) {
+    const key = crypto.createPublicKey(publicKeyPem);
+    if (key.asymmetricKeyType !== 'ed25519') throw new OperatorError('UPDATE_KEY_INVALID', 'Release verification key must be Ed25519.');
+    this.#publicKeyPem = key.export({ format: 'pem', type: 'spki' }).toString();
+  }
+
+  verifySignedManifest(input                       , options                                                                 )                  {
+    const manifest = validateManifest(input.manifest);
+    if (manifest.channel !== options.channel) throw new OperatorError('UPDATE_CHANNEL_MISMATCH', 'Release manifest channel does not match the configured update channel.');
+    if (manifest.channel === 'stable' && manifest.version.includes('-')) throw new OperatorError('UPDATE_CHANNEL_MISMATCH', 'Stable channel manifests cannot publish prerelease versions.');
+    const current = validVersion(options.currentVersion);
+    if (compareVersions(manifest.version, current) <= 0) throw new OperatorError('UPDATE_NOT_NEWER', 'Release manifest version is not newer than the installed version.');
+    const now = options.now ?? new Date();
+    const publishedMs = Date.parse(manifest.publishedAt);
+    if (publishedMs > now.getTime() + 5 * 60_000) throw new OperatorError('UPDATE_MANIFEST_FUTURE', 'Release manifest publication time is too far in the future.');
+    const signature = String(input.signature ?? '');
+    if (!/^[A-Za-z0-9_-]{40,256}$/.test(signature)) throw new OperatorError('UPDATE_SIGNATURE_INVALID', 'Release manifest signature is invalid.');
+    const bytes = encodeManifest(manifest);
+    const ok = crypto.verify(null, bytes, this.#publicKeyPem, Buffer.from(signature, 'base64url'));
+    if (!ok) throw new OperatorError('UPDATE_SIGNATURE_INVALID', 'Release manifest signature could not be verified.');
+    return manifest;
+  }
+
+  selectArtifact(manifestInput                 , target                                                                   )                  {
+    const manifest = validateManifest(manifestInput);
+    const kinds = target.kinds ?? ['msixbundle', 'msix', 'zip'];
+    for (const kind of kinds) {
+      const matches = manifest.artifacts.filter((artifact) => artifact.platform === target.platform && artifact.arch === target.arch && artifact.kind === kind);
+      if (matches.length > 1) throw new OperatorError('UPDATE_ARTIFACT_AMBIGUOUS', 'Release manifest contains multiple matching artifacts.');
+      if (matches.length === 1) return { ...matches[0] };
+    }
+    throw new OperatorError('UPDATE_ARTIFACT_NOT_FOUND', 'Release manifest has no artifact for this platform and architecture.');
+  }
+
+  async verifyAndStageArtifact(artifactInput                 , bytesInput            , stateDir        , version        )                                                               {
+    const artifact = validateArtifact(artifactInput);
+    const versionText = validVersion(version);
+    const bytes = Buffer.from(bytesInput);
+    if (bytes.byteLength !== artifact.sizeBytes) throw new OperatorError('UPDATE_SIZE_MISMATCH', 'Downloaded update size does not match the signed release manifest.');
+    if (bytes.byteLength > MAX_ARTIFACT_BYTES) throw new OperatorError('UPDATE_ARTIFACT_TOO_LARGE', 'Update artifact exceeds the maximum allowed size.');
+    const sha256 = crypto.createHash('sha256').update(bytes).digest('hex');
+    if (sha256 !== artifact.sha256) throw new OperatorError('UPDATE_HASH_MISMATCH', 'Downloaded update hash does not match the signed release manifest.');
+
+    const root = path.resolve(stateDir);
+    const updatesDir = path.join(root, 'updates');
+    const stagingDir = path.join(updatesDir, versionText);
+    await ensureRealUpdateDirectory(root, true);
+    await ensureRealUpdateDirectory(updatesDir);
+    await ensureRealUpdateDirectory(stagingDir);
+    const extension = artifact.kind === 'msixbundle' ? '.msixbundle' : artifact.kind === 'msix' ? '.msix' : '.zip';
+    const finalPath = path.join(stagingDir, `operator-${artifact.platform}-${artifact.arch}${extension}`);
+
+    try {
+      const existing = await readDurableStateBytes(finalPath, UPDATE_STAGE_OPTIONS);
+      const existingSha = crypto.createHash('sha256').update(existing).digest('hex');
+      if (existing.byteLength === bytes.byteLength && existingSha === sha256) return { path: finalPath, sha256, sizeBytes: bytes.byteLength };
+      throw new OperatorError('UPDATE_STAGE_CONFLICT', 'A different artifact is already staged for this release target.');
+    } catch (error) {
+      if (error instanceof OperatorError) throw error;
+      if ((error                         ).code !== 'ENOENT') throw error;
+    }
+
+    try {
+      await createDurableStateBytes(finalPath, bytes, UPDATE_STAGE_OPTIONS);
+    } catch (error) {
+      if ((error                         ).code === 'EEXIST') {
+        throw new OperatorError('UPDATE_STAGE_CONFLICT', 'An update artifact appeared concurrently at the staging path.');
+      }
+      throw error;
+    }
+
+    const committed = await readDurableStateBytes(finalPath, UPDATE_STAGE_OPTIONS);
+    const committedSha = crypto.createHash('sha256').update(committed).digest('hex');
+    if (committed.byteLength !== bytes.byteLength || committedSha !== sha256) {
+      throw new OperatorError('UPDATE_STAGE_INVALID', 'Staged update artifact failed post-write verification.');
+    }
+    return { path: finalPath, sha256, sizeBytes: bytes.byteLength };
+  }
+}
+
+export function signReleaseManifest(manifestInput                 , privateKeyPem        )                        {
+  const manifest = validateManifest(manifestInput);
+  const key = crypto.createPrivateKey(privateKeyPem);
+  if (key.asymmetricKeyType !== 'ed25519') throw new OperatorError('UPDATE_KEY_INVALID', 'Release signing key must be Ed25519.');
+  return {
+    manifest,
+    signature: crypto.sign(null, encodeManifest(manifest), key).toString('base64url')
+  };
+}
+
+function encodeManifest(manifestInput                 )         {
+  const manifest = validateManifest(manifestInput);
+  const canonical = {
+    schemaVersion: 1,
+    product: PRODUCT,
+    channel: manifest.channel,
+    version: manifest.version,
+    publishedAt: manifest.publishedAt,
+    artifacts: manifest.artifacts.map((artifact) => ({
+      platform: artifact.platform,
+      arch: artifact.arch,
+      kind: artifact.kind,
+      url: artifact.url,
+      sha256: artifact.sha256,
+      sizeBytes: artifact.sizeBytes
+    }))
+  };
+  const bytes = Buffer.from(JSON.stringify(canonical), 'utf8');
+  if (bytes.byteLength > MAX_MANIFEST_BYTES) throw new OperatorError('UPDATE_MANIFEST_TOO_LARGE', 'Release manifest exceeds the maximum allowed size.');
+  return bytes;
+}
+
+function validateManifest(input                 )                  {
+  if (!input || typeof input !== 'object' || input.schemaVersion !== 1 || input.product !== PRODUCT) throw new OperatorError('UPDATE_MANIFEST_INVALID', 'Release manifest schema or product is invalid.');
+  const channel = input.channel === 'stable' ? 'stable' : input.channel === 'beta' ? 'beta' : null;
+  if (!channel) throw new OperatorError('UPDATE_MANIFEST_INVALID', 'Release channel is invalid.');
+  const version = validVersion(String(input.version ?? ''));
+  const publishedAt = validIso(String(input.publishedAt ?? ''));
+  if (!Array.isArray(input.artifacts) || input.artifacts.length < 1 || input.artifacts.length > MAX_ARTIFACTS) throw new OperatorError('UPDATE_MANIFEST_INVALID', `Release manifest must contain 1-${MAX_ARTIFACTS} artifacts.`);
+  const artifacts = input.artifacts.map(validateArtifact);
+  const seen = new Set        ();
+  for (const artifact of artifacts) {
+    const key = `${artifact.platform}:${artifact.arch}:${artifact.kind}`;
+    if (seen.has(key)) throw new OperatorError('UPDATE_MANIFEST_INVALID', `Duplicate release artifact ${key}.`);
+    seen.add(key);
+  }
+  artifacts.sort((a, b) => `${a.platform}:${a.arch}:${a.kind}`.localeCompare(`${b.platform}:${b.arch}:${b.kind}`));
+  return { schemaVersion: 1, product: PRODUCT, channel, version, publishedAt, artifacts };
+}
+
+function validateArtifact(input                 )                  {
+  if (!input || typeof input !== 'object') throw new OperatorError('UPDATE_ARTIFACT_INVALID', 'Release artifact is invalid.');
+  const platform = input.platform === 'win32' || input.platform === 'linux' || input.platform === 'darwin' ? input.platform : null;
+  const arch = input.arch === 'x64' || input.arch === 'arm64' ? input.arch : null;
+  const kind = input.kind === 'msix' || input.kind === 'msixbundle' || input.kind === 'zip' ? input.kind : null;
+  if (!platform || !arch || !kind) throw new OperatorError('UPDATE_ARTIFACT_INVALID', 'Release artifact platform, architecture, or kind is invalid.');
+  let url     ;
+  try { url = new URL(String(input.url)); } catch { throw new OperatorError('UPDATE_URL_INVALID', 'Release artifact URL is invalid.'); }
+  if (url.protocol !== 'https:' || url.username || url.password) throw new OperatorError('UPDATE_URL_INVALID', 'Release artifact URL must use HTTPS and must not contain credentials.');
+  const sha256 = String(input.sha256 ?? '').toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(sha256)) throw new OperatorError('UPDATE_HASH_INVALID', 'Release artifact SHA-256 is invalid.');
+  const sizeBytes = Number(input.sizeBytes);
+  if (!Number.isSafeInteger(sizeBytes) || sizeBytes < 1 || sizeBytes > MAX_ARTIFACT_BYTES) throw new OperatorError('UPDATE_SIZE_INVALID', 'Release artifact size is outside the allowed range.');
+  return { platform, arch, kind, url: url.toString(), sha256, sizeBytes };
+}
+
+function validVersion(value        )         {
+  const text = String(value ?? '');
+  if (!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/.test(text) || text.length > 128) {
+    throw new OperatorError('UPDATE_VERSION_INVALID', 'Release version must be a bounded semantic version.');
+  }
+  const prerelease = text.split('-', 2)[1];
+  if (prerelease) {
+    for (const identifier of prerelease.split('.')) {
+      if (/^\d+$/.test(identifier) && identifier.length > 1 && identifier.startsWith('0')) {
+        throw new OperatorError('UPDATE_VERSION_INVALID', 'Numeric prerelease identifiers must not contain leading zeroes.');
+      }
+    }
+  }
+  return text;
+}
+
+function compareVersions(aInput        , bInput        )         {
+  const a = parseVersion(validVersion(aInput));
+  const b = parseVersion(validVersion(bInput));
+  for (let i = 0; i < 3; i += 1) {
+    if (a.nums[i] !== b.nums[i]) return a.nums[i]  > b.nums[i]  ? 1 : -1;
+  }
+  if (a.pre.length === 0 && b.pre.length === 0) return 0;
+  if (a.pre.length === 0) return 1;
+  if (b.pre.length === 0) return -1;
+  const length = Math.max(a.pre.length, b.pre.length);
+  for (let i = 0; i < length; i += 1) {
+    const left = a.pre[i]; const right = b.pre[i];
+    if (left === undefined) return -1;
+    if (right === undefined) return 1;
+    if (left === right) continue;
+    const leftNumeric = /^\d+$/.test(left);
+    const rightNumeric = /^\d+$/.test(right);
+    if (leftNumeric && rightNumeric) return BigInt(left) > BigInt(right) ? 1 : -1;
+    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
+    return left > right ? 1 : -1;
+  }
+  return 0;
+}
+
+function parseVersion(value        )                                    {
+  const [core, prerelease] = value.split('-', 2);
+  return { nums: core.split('.').map((part) => BigInt(part)), pre: prerelease ? prerelease.split('.') : [] };
+}
+
+function validIso(value        )         {
+  const time = Date.parse(value);
+  if (!Number.isFinite(time) || new Date(time).toISOString() !== value) throw new OperatorError('UPDATE_TIME_INVALID', 'Release publication time must be an ISO timestamp.');
+  return value;
+}
+
+async function ensureRealUpdateDirectory(directory        , recursive = false)                {
+  try {
+    await fs.mkdir(directory, { recursive, mode: 0o700 });
+  } catch (error) {
+    if ((error                         ).code !== 'EEXIST') throw error;
+  }
+  const stat = await fs.lstat(directory);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new OperatorError('UPDATE_STAGE_INVALID', 'Update staging directories must be real directories, not links or special files.');
+  }
+}

package/runtime/app/src/core/router.js

@@ -0,0 +1,96 @@
+                                                                                                 
+import { OperatorError } from './errors.js';
+                                                               
+
+const WEIGHTS                                        = {
+  reliability: 0.24,
+  latency: 0.13,
+  determinism: 0.19,
+  security: 0.17,
+  reversibility: 0.10,
+  informationQuality: 0.12,
+  interactionCost: 0.05
+};
+
+function normalize(score        )         {
+  if (!Number.isFinite(score)) return 0;
+  return Math.max(0, Math.min(1, score));
+}
+
+function weightedScore(score                 )         {
+  return Object.entries(WEIGHTS).reduce((total, [key, weight]) => {
+    const raw = score[key                         ];
+    const value = key === 'latency' || key === 'interactionCost' ? 1 - normalize(raw) : normalize(raw);
+    return total + value * weight;
+  }, 0);
+}
+
+export class CapabilityRouter {
+  #providers                       = [];
+  #learning                   ;
+
+  constructor(options                                  = {}) {
+    this.#learning = options.learning;
+  }
+
+  register(provider                    )       {
+    this.#providers.push(provider);
+  }
+
+  async supports(action               )                   {
+    for (const provider of this.#providers) {
+      if (await provider.supports(action)) return true;
+    }
+    return false;
+  }
+
+  async advertises(action               )                   {
+    for (const provider of this.#providers) {
+      if (!await provider.supports(action)) continue;
+      if (!provider.advertises || await provider.advertises(action)) return true;
+    }
+    return false;
+  }
+
+  async rank(action               , learningContext = 'global')                                                                                                                {
+    const candidates                                                                                                       = [];
+    for (const provider of this.#providers) {
+      if (await provider.supports(action)) {
+        const baseScore = weightedScore(await provider.score(action));
+        const learnedAdjustment = this.#learning ? await this.#learning.adjustment(action.capability, provider.name, learningContext) : 0;
+        candidates.push({ provider, baseScore, learnedAdjustment, score: normalize(baseScore + learnedAdjustment) });
+      }
+    }
+    candidates.sort((a, b) => b.score - a.score || b.baseScore - a.baseScore || a.provider.name.localeCompare(b.provider.name));
+    return candidates;
+  }
+
+  async recordOutcome(capability        , providerName        , outcome                       , metadata                                            = {})                   {
+    if (!this.#learning) return false;
+    if (!this.#providers.some((provider) => provider.name === providerName)) return false;
+    await this.#learning.record(capability, providerName, outcome, metadata);
+    return true;
+  }
+
+  async resolveRisk(action               )                      {
+    const risks = new Set            ();
+    for (const provider of this.#providers) {
+      if (await provider.supports(action) && provider.resolveRisk) risks.add(await provider.resolveRisk(action));
+    }
+    if (risks.size !== 1) throw new OperatorError('CAPABILITY_RISK_UNRESOLVED', `Capability ${action.capability} does not have one trusted dynamic risk.`);
+    return [...risks][0] ;
+  }
+
+  async select(action               , learningContext = 'global')                              {
+    const ranked = await this.rank(action, learningContext);
+    if (!ranked[0]) {
+      throw new OperatorError('CAPABILITY_UNAVAILABLE', `No provider can execute ${action.capability}.`);
+    }
+    return ranked[0].provider;
+  }
+
+  async closeAll()                {
+    const providers = [...this.#providers].reverse();
+    await Promise.allSettled(providers.map(async (provider) => provider.close?.()));
+  }
+}