mecord-connect 1.0.0

package/runtime/app/src/core/device-routing.js

@@ -0,0 +1,305 @@
+import path from 'node:path';
+import { DeviceRegistryStore,                       } from './device-registry.js';
+import { OperatorError } from './errors.js';
+import { readDurableStateText, writeDurableStateText } from './durable-state.js';
+
+const MAX_BINDINGS = 4096;
+const MAX_ONLINE_DEVICES = 1000;
+const MAX_CAPABILITIES = 256;
+const DEFAULT_LIVENESS_MS = 45_000;
+const MAX_LIVENESS_MS = 5 * 60_000;
+
+                        
+
+                                       
+                     
+                   
+                    
+ 
+
+                        
+             
+                                   
+ 
+
+                                         
+                   
+                    
+                         
+                      
+                     
+ 
+
+                                     
+                                  
+                            
+                      
+                      
+ 
+
+                                      
+                   
+                    
+                      
+                                
+                                                              
+ 
+
+export class DeviceRoutingStore {
+  #file        ;
+  #registry                     ;
+  #clock       ;
+  #queue                = Promise.resolve();
+
+  constructor(stateDir        , registry                     , options                    = {}) {
+    this.#file = path.join(path.resolve(stateDir), 'device-routing.json');
+    this.#registry = registry;
+    this.#clock = options.clock ?? (() => new Date());
+  }
+
+  async listBindings()                                  {
+    const state = await this.#read();
+    return state.bindings.map((binding) => ({ ...binding }));
+  }
+
+  async bindProject(projectKeyInput        , deviceIdInput        )                                {
+    const projectKey = validProjectKey(projectKeyInput);
+    const deviceId = validUuid(deviceIdInput, 'deviceId');
+    await this.#requireActiveDevice(deviceId);
+    return await this.#mutate((state) => {
+      const existing = state.bindings.find((binding) => binding.projectKey === projectKey);
+      const updatedAt = this.#clock().toISOString();
+      if (existing) {
+        existing.deviceId = deviceId;
+        existing.updatedAt = updatedAt;
+        return { ...existing };
+      }
+      if (state.bindings.length >= MAX_BINDINGS) throw new OperatorError('ROUTE_BINDING_LIMIT', `At most ${MAX_BINDINGS} project bindings may be stored.`);
+      const binding = { projectKey, deviceId, updatedAt };
+      state.bindings.push(binding);
+      state.bindings.sort((a, b) => a.projectKey.localeCompare(b.projectKey));
+      return { ...binding };
+    });
+  }
+
+  async unbindProject(projectKeyInput        )                   {
+    const projectKey = validProjectKey(projectKeyInput);
+    return await this.#mutate((state) => {
+      const before = state.bindings.length;
+      state.bindings = state.bindings.filter((binding) => binding.projectKey !== projectKey);
+      return state.bindings.length !== before;
+    });
+  }
+
+  async unbindDevice(deviceIdInput        )                  {
+    const deviceId = validUuid(deviceIdInput, 'deviceId');
+    return await this.#mutate((state) => {
+      const before = state.bindings.length;
+      state.bindings = state.bindings.filter((binding) => binding.deviceId !== deviceId);
+      return before - state.bindings.length;
+    });
+  }
+
+  async resolve(requestInput                    , onlineInput                          )                               {
+    const request = validateRequest(requestInput);
+    const online = validateOnlineDevices(onlineInput, this.#clock(), request.livenessMs);
+    const registered = await this.#registry.listDevices();
+    const active = new Map(registered.filter((device) => device.status === 'active').map((device) => [device.deviceId, device]));
+    const bindings = (await this.#read()).bindings;
+    const binding = request.projectKey ? bindings.find((candidate) => candidate.projectKey === request.projectKey) : undefined;
+
+    if (request.explicitDeviceId && binding && request.explicitDeviceId !== binding.deviceId) {
+      throw new OperatorError('ROUTE_PROJECT_DEVICE_CONFLICT', 'Explicit device conflicts with the persisted project-to-device binding.', {
+        details: { projectKey: request.projectKey, boundDeviceId: binding.deviceId, explicitDeviceId: request.explicitDeviceId }
+      });
+    }
+
+    if (request.explicitDeviceId) {
+      const candidate = requireRoutable(request.explicitDeviceId, online, active, request.requiredCapabilities, 'explicit');
+      return decision(candidate, request, 'explicit');
+    }
+
+    if (binding) {
+      const candidate = requireRoutable(binding.deviceId, online, active, request.requiredCapabilities, 'project binding');
+      return decision(candidate, request, 'project-binding');
+    }
+
+    const candidates = online.filter((candidate) => active.has(candidate.deviceId) && hasCapabilities(candidate, request.requiredCapabilities));
+    if (candidates.length === 0) {
+      if (request.projectKey) {
+        throw new OperatorError('ROUTE_PROJECT_UNBOUND', 'Project has no device binding and no unique eligible online device can be inferred safely.', {
+          details: { projectKey: request.projectKey }
+        });
+      }
+      throw new OperatorError('ROUTE_NO_DEVICE', 'No active online device satisfies the requested capabilities.');
+    }
+    if (candidates.length > 1) {
+      throw new OperatorError('ROUTE_AMBIGUOUS', 'Multiple active online devices satisfy the route; select a device explicitly or bind the project.', {
+        details: { candidateDeviceIds: candidates.map((candidate) => candidate.deviceId).sort() }
+      });
+    }
+    return decision(candidates[0], request, 'unique-candidate');
+  }
+
+  async #requireActiveDevice(deviceId        )                            {
+    const device = (await this.#registry.listDevices()).find((candidate) => candidate.deviceId === deviceId);
+    if (!device) throw new OperatorError('DEVICE_NOT_FOUND', 'Cannot bind an unpaired device.');
+    if (device.status !== 'active') throw new OperatorError('DEVICE_REVOKED', 'Cannot bind a revoked device.');
+    return device;
+  }
+
+  async #read()                        {
+    try {
+      const text = await readDurableStateText(this.#file, {
+        maxBytes: 512 * 1024,
+        errorCode: 'ROUTE_STATE_CORRUPT',
+        invalidMessage: 'Device routing state is invalid.'
+      });
+      return validateState(JSON.parse(text));
+    } catch (error) {
+      if ((error                         ).code === 'ENOENT') return { version: 1, bindings: [] };
+      if (error instanceof OperatorError) throw error;
+      throw new OperatorError('ROUTE_STATE_CORRUPT', 'Device routing state could not be read.');
+    }
+  }
+
+  async #write(stateInput              )                {
+    const state = validateState(stateInput);
+    await writeDurableStateText(this.#file, JSON.stringify(state, null, 2), {
+      maxBytes: 512 * 1024,
+      errorCode: 'ROUTE_STATE_CORRUPT',
+      invalidMessage: 'Device routing 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 result = await mutator(state);
+      await this.#write(state);
+      return result;
+    } finally {
+      release();
+    }
+  }
+}
+
+function validateRequest(input                    )                                                                                                                                          {
+  if (!input || typeof input !== 'object') throw new OperatorError('ROUTE_REQUEST_INVALID', 'Device route request is invalid.');
+  const requiredCapabilities = validCapabilities(input.requiredCapabilities ?? []);
+  const explicitDeviceId = input.explicitDeviceId === undefined ? undefined : validUuid(input.explicitDeviceId, 'explicitDeviceId');
+  const projectKey = input.projectKey === undefined ? undefined : validProjectKey(input.projectKey);
+  const livenessMs = Number(input.livenessMs ?? DEFAULT_LIVENESS_MS);
+  if (!Number.isInteger(livenessMs) || livenessMs < 5_000 || livenessMs > MAX_LIVENESS_MS) {
+    throw new OperatorError('ROUTE_LIVENESS_INVALID', `livenessMs must be between 5000 and ${MAX_LIVENESS_MS}.`);
+  }
+  return { requiredCapabilities, explicitDeviceId, projectKey, livenessMs };
+}
+
+function validateOnlineDevices(input                          , now      , livenessMs        )                           {
+  if (!Array.isArray(input) || input.length > MAX_ONLINE_DEVICES) throw new OperatorError('ROUTE_ONLINE_STATE_INVALID', `Online device list must contain at most ${MAX_ONLINE_DEVICES} entries.`);
+  const seenDevices = new Set        ();
+  const seenSessions = new Set        ();
+  const nowMs = now.getTime();
+  const result                           = [];
+  for (const raw of input) {
+    if (!raw || typeof raw !== 'object') throw new OperatorError('ROUTE_ONLINE_STATE_INVALID', 'Online device descriptor is invalid.');
+    const deviceId = validUuid(raw.deviceId, 'online deviceId');
+    const sessionId = validSessionId(raw.sessionId);
+    if (seenDevices.has(deviceId)) throw new OperatorError('ROUTE_ONLINE_STATE_INVALID', 'Online device list contains duplicate device IDs.');
+    if (seenSessions.has(sessionId)) throw new OperatorError('ROUTE_ONLINE_STATE_INVALID', 'Online device list contains duplicate session IDs.');
+    seenDevices.add(deviceId);
+    seenSessions.add(sessionId);
+    const capabilities = validCapabilities(raw.capabilities);
+    const connectedAt = validIso(raw.connectedAt, 'connectedAt');
+    const lastSeenAt = validIso(raw.lastSeenAt, 'lastSeenAt');
+    const connectedMs = Date.parse(connectedAt);
+    const seenMs = Date.parse(lastSeenAt);
+    if (seenMs < connectedMs || seenMs > nowMs + 30_000) throw new OperatorError('ROUTE_ONLINE_STATE_INVALID', 'Online device timestamps are inconsistent.');
+    if (nowMs - seenMs > livenessMs) continue;
+    result.push({ deviceId, sessionId, capabilities, connectedAt, lastSeenAt });
+  }
+  return result;
+}
+
+function requireRoutable(
+  deviceId        ,
+  online                          ,
+  active                               ,
+  capabilities          ,
+  source        
+)                         {
+  if (!active.has(deviceId)) throw new OperatorError('ROUTE_DEVICE_INACTIVE', `The ${source} device is not an active paired device.`, { details: { deviceId } });
+  const candidate = online.find((device) => device.deviceId === deviceId);
+  if (!candidate) throw new OperatorError('ROUTE_DEVICE_OFFLINE', `The ${source} device is offline or stale.`, { retryable: true, details: { deviceId } });
+  const missing = capabilities.filter((capability) => !candidate.capabilities.includes(capability));
+  if (missing.length) throw new OperatorError('ROUTE_CAPABILITY_MISMATCH', `The ${source} device does not advertise every required capability.`, { details: { deviceId, missing } });
+  return candidate;
+}
+
+function decision(candidate                        , request                                    , reason                               )                      {
+  return {
+    deviceId: candidate.deviceId,
+    sessionId: candidate.sessionId,
+    projectKey: request.projectKey,
+    matchedCapabilities: [...request.requiredCapabilities],
+    reason
+  };
+}
+
+function hasCapabilities(device                        , required          )          {
+  return required.every((capability) => device.capabilities.includes(capability));
+}
+
+function validateState(input              )               {
+  if (!input || typeof input !== 'object' || input.version !== 1 || !Array.isArray(input.bindings) || input.bindings.length > MAX_BINDINGS) {
+    throw new OperatorError('ROUTE_STATE_CORRUPT', 'Device routing state structure is invalid.');
+  }
+  const projects = new Set        ();
+  const bindings = input.bindings.map((raw) => {
+    const projectKey = validProjectKey(raw.projectKey);
+    if (projects.has(projectKey)) throw new OperatorError('ROUTE_STATE_CORRUPT', 'Device routing state contains duplicate project keys.');
+    projects.add(projectKey);
+    return { projectKey, deviceId: validUuid(raw.deviceId, 'deviceId'), updatedAt: validIso(raw.updatedAt, 'updatedAt') };
+  });
+  return { version: 1, bindings };
+}
+
+function validCapabilities(input         )           {
+  if (!Array.isArray(input) || input.length > MAX_CAPABILITIES) throw new OperatorError('ROUTE_CAPABILITY_INVALID', `Capabilities must contain at most ${MAX_CAPABILITIES} entries.`);
+  const capabilities = input.map(String);
+  for (const capability of capabilities) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:/*-]{0,127}$/.test(capability)) throw new OperatorError('ROUTE_CAPABILITY_INVALID', `Invalid capability ${capability}.`);
+  }
+  return [...new Set(capabilities)].sort();
+}
+
+function validProjectKey(value        )         {
+  const key = String(value ?? '');
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(key)) throw new OperatorError('ROUTE_PROJECT_KEY_INVALID', 'projectKey must be an opaque logical identifier, not a filesystem path.');
+  if (key.includes('/') || key.includes('\\')) throw new OperatorError('ROUTE_PROJECT_KEY_INVALID', 'projectKey must not contain path separators.');
+  return key;
+}
+
+function validSessionId(value        )         {
+  const id = String(value ?? '');
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(id)) throw new OperatorError('ROUTE_ONLINE_STATE_INVALID', 'Relay session ID is invalid.');
+  return id;
+}
+
+function validUuid(value        , label        )         {
+  const text = String(value ?? '');
+  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(text)) throw new OperatorError('ROUTE_DEVICE_ID_INVALID', `${label} must be a UUID.`);
+  return text.toLowerCase();
+}
+
+function validIso(value        , label        )         {
+  const text = String(value ?? '');
+  const time = Date.parse(text);
+  if (!Number.isFinite(time) || new Date(time).toISOString() !== text) throw new OperatorError('ROUTE_STATE_INVALID', `${label} must be an ISO timestamp.`);
+  return text;
+}

package/runtime/app/src/core/durable-state.js

@@ -0,0 +1,306 @@
+import crypto from 'node:crypto';
+import { constants as fsConstants,            } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { OperatorError } from './errors.js';
+
+                                      
+                   
+                    
+                         
+ 
+
+export async function readDurableStateText(file        , options                     )                  {
+  return (await readDurableStateBytes(file, options)).toString('utf8');
+}
+
+class DurableStateReadRace extends Error {}
+
+export async function readDurableStateBytes(file        , options                     )                  {
+  validateOptions(options);
+  let lastRace                                  ;
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    try {
+      return await readDurableStateBytesOnce(file, options);
+    } catch (error) {
+      if (!(error instanceof DurableStateReadRace)) throw error;
+      lastRace = error;
+    }
+  }
+  throw invalid(options, lastRace?.message ?? 'State file changed while it was being read.');
+}
+
+async function readDurableStateBytesOnce(file        , options                     )                  {
+  const initial = await fs.lstat(file);
+  assertStableRegular(initial, options);
+
+  const noFollow = process.platform === 'win32'
+    ? 0
+    : Number((fsConstants                                     ).O_NOFOLLOW ?? 0);
+  let handle;
+  try {
+    handle = await fs.open(file, fsConstants.O_RDONLY | noFollow);
+  } catch (error) {
+    const code = (error                         ).code;
+    if (code === 'ELOOP') throw invalid(options, 'Symbolic links are not permitted.');
+    if (code === 'ENOENT') throw new DurableStateReadRace('State file changed while it was being opened.');
+    throw error;
+  }
+
+  try {
+    const opened = await handle.stat();
+    assertOpenedRegular(opened, options, 'State file changed while it was being opened.');
+    if (!sameFile(initial, opened)) throw new DurableStateReadRace('State file changed while it was being opened.');
+
+    const bytes = await handle.readFile();
+    if (bytes.byteLength > options.maxBytes) throw invalid(options, 'State file exceeds the bounded size.');
+    const afterRead = await handle.stat();
+    assertOpenedRegular(afterRead, options, 'State file changed while it was being read.');
+    if (!sameFile(opened, afterRead) || opened.size !== afterRead.size || opened.mtimeMs !== afterRead.mtimeMs || opened.ctimeMs !== afterRead.ctimeMs) {
+      throw new DurableStateReadRace('State file changed while it was being read.');
+    }
+
+    let current       ;
+    try {
+      current = await fs.lstat(file);
+    } catch (error) {
+      if ((error                         ).code === 'ENOENT') throw new DurableStateReadRace('State file path changed while it was being read.');
+      throw error;
+    }
+    assertStableRegular(current, options);
+    if (!sameFile(afterRead, current)) throw new DurableStateReadRace('State file path changed while it was being read.');
+    return bytes;
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function appendDurableStateText(file        , content        , options                     )                {
+  validateOptions(options);
+  const byteLength = Buffer.byteLength(content, 'utf8');
+  if (byteLength < 1 || byteLength > options.maxBytes) throw invalid(options, 'Appended state content is empty or exceeds the bounded size.');
+
+  const directory = path.dirname(file);
+  await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+
+  let initial               = null;
+  try {
+    initial = await fs.lstat(file);
+    assertStableRegular(initial, options);
+  } catch (error) {
+    if ((error                         ).code !== 'ENOENT') throw error;
+  }
+
+  const noFollow = process.platform === 'win32'
+    ? 0
+    : Number((fsConstants                                     ).O_NOFOLLOW ?? 0);
+  let handle;
+  let created = false;
+  try {
+    if (initial) {
+      handle = await fs.open(file, fsConstants.O_WRONLY | fsConstants.O_APPEND | noFollow);
+    } else {
+      handle = await fs.open(file, 'wx', 0o600);
+      created = true;
+    }
+  } catch (error) {
+    if ((error                         ).code === 'ELOOP') throw invalid(options, 'Symbolic links are not permitted.');
+    throw error;
+  }
+
+  try {
+    const opened = await handle.stat();
+    assertStableRegular(opened, options);
+    if (initial && !sameFile(initial, opened)) throw invalid(options, 'State file changed while it was being opened for append.');
+
+    const current = await fs.lstat(file);
+    assertStableRegular(current, options);
+    if (!sameFile(opened, current)) throw invalid(options, 'State file path changed before append.');
+    if (opened.size + byteLength > options.maxBytes) throw invalid(options, 'State file would exceed the bounded size after append.');
+
+    await handle.writeFile(content, { encoding: 'utf8' });
+    await handle.sync();
+
+    const appended = await handle.stat();
+    assertStableRegular(appended, options);
+    if (!sameFile(opened, appended) || appended.size !== opened.size + byteLength) {
+      throw invalid(options, 'State append did not produce the expected file size.');
+    }
+    const committed = await fs.lstat(file);
+    assertStableRegular(committed, options);
+    if (!sameFile(appended, committed)) throw invalid(options, 'State file path changed during append.');
+  } finally {
+    await handle.close();
+  }
+
+  if (created && process.platform !== 'win32') await syncDirectory(directory);
+}
+
+export async function writeDurableStateText(file        , content        , options                     )                {
+  await writeDurableStateBytes(file, Buffer.from(content, 'utf8'), options);
+}
+
+export async function writeDurableStateBytes(file        , content            , options                     )                {
+  validateOptions(options);
+  const bytes = Buffer.from(content);
+  const byteLength = bytes.byteLength;
+  if (byteLength > options.maxBytes) throw invalid(options, 'Serialized state exceeds the bounded size.');
+
+  const directory = path.dirname(file);
+  await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+  await assertReplaceTarget(file, options);
+
+  const temp = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  let renamed = false;
+  let handle;
+  try {
+    handle = await fs.open(temp, 'wx', 0o600);
+    try {
+      await handle.writeFile(bytes);
+      await handle.sync();
+    } finally {
+      await handle.close();
+      handle = undefined;
+    }
+
+    const staged = await fs.lstat(temp);
+    assertStableRegular(staged, options);
+    if (staged.size !== byteLength) throw invalid(options, 'Staged state size did not match the serialized state.');
+
+    await publishDurableReplacement(temp, file, options);
+    renamed = true;
+
+    const committed = await fs.lstat(file);
+    assertStableRegular(committed, options);
+    if (committed.size !== byteLength) throw invalid(options, 'Committed state size did not match the serialized state.');
+
+    if (process.platform !== 'win32') await syncDirectory(directory);
+  } finally {
+    if (handle) await handle.close().catch(() => undefined);
+    if (!renamed) await fs.rm(temp, { force: true }).catch(() => undefined);
+  }
+}
+
+export async function createDurableStateBytes(file        , content            , options                     )                {
+  validateOptions(options);
+  const bytes = Buffer.from(content);
+  const byteLength = bytes.byteLength;
+  if (byteLength > options.maxBytes) throw invalid(options, 'Serialized state exceeds the bounded size.');
+
+  const directory = path.dirname(file);
+  await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+  try {
+    const existing = await fs.lstat(file);
+    assertStableRegular(existing, options);
+    const exists = new Error('State file already exists.')                         ;
+    exists.code = 'EEXIST';
+    throw exists;
+  } catch (error) {
+    if ((error                         ).code !== 'ENOENT') throw error;
+  }
+
+  const temp = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  let handle;
+  let published = false;
+  try {
+    handle = await fs.open(temp, 'wx', 0o600);
+    try {
+      await handle.writeFile(bytes);
+      await handle.sync();
+    } finally {
+      await handle.close();
+      handle = undefined;
+    }
+
+    const staged = await fs.lstat(temp);
+    assertStableRegular(staged, options);
+    if (staged.size !== byteLength) throw invalid(options, 'Staged state size did not match the serialized state.');
+
+    await fs.link(temp, file);
+    published = true;
+    await fs.rm(temp);
+
+    const committed = await fs.lstat(file);
+    assertStableRegular(committed, options);
+    if (committed.size !== byteLength) throw invalid(options, 'Committed state size did not match the serialized state.');
+
+    if (process.platform !== 'win32') await syncDirectory(directory);
+  } finally {
+    if (handle) await handle.close().catch(() => undefined);
+    await fs.rm(temp, { force: true }).catch(() => undefined);
+    if (published) {
+      try {
+        const committed = await fs.lstat(file);
+        assertStableRegular(committed, options);
+      } catch (error) {
+        if ((error                         ).code !== 'ENOENT') throw error;
+      }
+    }
+  }
+}
+
+async function assertReplaceTarget(file        , options                     )                {
+  try {
+    const stat = await fs.lstat(file);
+    assertStableRegular(stat, options);
+  } catch (error) {
+    if ((error                         ).code === 'ENOENT') return;
+    throw error;
+  }
+}
+
+async function publishDurableReplacement(temp        , file        , options                     )                {
+  const retryDelaysMs = [5, 10, 25, 50, 100];
+  for (let attempt = 0; ; attempt += 1) {
+    const staged = await fs.lstat(temp);
+    assertStableRegular(staged, options);
+    await assertReplaceTarget(file, options);
+    try {
+      await fs.rename(temp, file);
+      return;
+    } catch (error) {
+      const code = (error                         ).code;
+      const transientWindowsRename =
+        process.platform === 'win32' && (code === 'EPERM' || code === 'EACCES' || code === 'EBUSY');
+      if (!transientWindowsRename || attempt >= retryDelaysMs.length) throw error;
+      await new Promise      ((resolve) => setTimeout(resolve, retryDelaysMs[attempt]));
+    }
+  }
+}
+
+function assertOpenedRegular(stat       , options                     , raceMessage        )       {
+  if (!stat.isFile()) throw invalid(options, 'Opened state path must be a regular file.');
+  if (stat.nlink > 1) throw invalid(options, 'Hard-linked state files are not permitted.');
+  if (stat.nlink < 1) throw new DurableStateReadRace(raceMessage);
+  if (stat.size > options.maxBytes) throw invalid(options, 'State file exceeds the bounded size.');
+}
+
+function assertStableRegular(stat       , options                     )       {
+  if (stat.isSymbolicLink() || !stat.isFile()) throw invalid(options, 'State path must be a regular file, not a link or special file.');
+  if (stat.nlink !== 1) throw invalid(options, 'Hard-linked state files are not permitted.');
+  if (stat.size > options.maxBytes) throw invalid(options, 'State file exceeds the bounded size.');
+}
+
+function sameFile(left       , right       )          {
+  // Node 22 on Windows can report dev=0 for path stat/lstat while the same
+  // file opened by handle reports the NT volume serial as dev. The file index
+  // (ino) remains stable across both views, so use that as the fail-closed
+  // identity on Windows and keep the POSIX dev+ino pair elsewhere.
+  if (process.platform === 'win32') return left.ino !== 0 && right.ino !== 0 && left.ino === right.ino;
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+async function syncDirectory(directory        )                {
+  const handle = await fs.open(directory, 'r');
+  try { await handle.sync(); } finally { await handle.close(); }
+}
+
+function validateOptions(options                     )       {
+  if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 1 || !options.errorCode || !options.invalidMessage) {
+    throw new OperatorError('DURABLE_STATE_CONFIGURATION_INVALID', 'Durable-state file options are invalid.');
+  }
+}
+
+function invalid(options                     , detail        )                {
+  return new OperatorError(options.errorCode, `${options.invalidMessage} ${detail}`);
+}

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

@@ -0,0 +1,20 @@
+export class OperatorError extends Error {
+  code        ;
+  retryable         ;
+  details                          ;
+
+  constructor(code        , message        , options                                                             = {}) {
+    super(message);
+    this.name = 'OperatorError';
+    this.code = code;
+    this.retryable = options.retryable ?? false;
+    this.details = options.details;
+  }
+}
+
+export class PolicyError extends OperatorError {
+  constructor(code        , message        , details                          ) {
+    super(code, message, { retryable: false, details });
+    this.name = 'PolicyError';
+  }
+}

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

@@ -0,0 +1,9 @@
+                                                           
+
+export function evidence(kind        , status                , message        , data                          )           {
+  return { kind, status, message, ...(data === undefined ? {} : { data }), timestamp: new Date().toISOString() };
+}
+
+export function verdict(items            )                              {
+  return items.some((item) => item.status === 'fail') ? 'NOT_VERIFIED' : 'VERIFIED';
+}

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

@@ -0,0 +1,17 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './evidence.js';
+export * from './provenance.js';
+export * from './policy.js';
+export * from './router.js';
+export * from './runtime.js';
+export * from './task.js';
+export * from './task-store.js';
+export * from './task-orchestrator.js';
+export * from './audit.js';
+export * from './device-identity.js';
+export * from './device-registry.js';
+export * from './session-token.js';
+export * from './relay-client.js';
+export * from './device-routing.js';
+export * from './account-device-registry.js';