mcard-js 2.1.49 → 2.1.51

package/dist/NetworkRuntime-KR2QITXV.js

@@ -0,0 +1,987 @@
+import {
+  HTTP_DEFAULT_BACKOFF,
+  HTTP_DEFAULT_BASE_DELAY_MS,
+  HTTP_DEFAULT_CACHE_TTL_SECONDS,
+  HTTP_DEFAULT_MAX_ATTEMPTS,
+  HTTP_DEFAULT_MAX_DELAY_MS,
+  HTTP_DEFAULT_TIMEOUT_MS,
+  NETWORK_DEFAULT_LISTEN_PORT,
+  NETWORK_DEFAULT_ORCHESTRATOR_SLEEP_MS,
+  RATE_LIMIT_DEFAULT_MAX_BURST,
+  RATE_LIMIT_DEFAULT_TOKENS_PER_SECOND,
+  RATE_LIMIT_WAIT_INTERVAL_MS
+} from "./chunk-FSDRDWOP.js";
+import {
+  MCard
+} from "./chunk-GGQCF7ZK.js";
+import "./chunk-ASW6AOA7.js";
+import "./chunk-PNKVD2UK.js";
+
+// src/ptr/node/NetworkRuntime.ts
+import * as http from "http";
+
+// src/ptr/node/network/NetworkSecurity.ts
+var NetworkSecurity = class {
+  config;
+  constructor(config) {
+    this.config = config || this.loadSecurityConfigFromEnv();
+  }
+  /**
+   * Load security configuration from environment variables
+   */
+  loadSecurityConfigFromEnv() {
+    const parseList = (value) => {
+      if (!value) return void 0;
+      return value.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    };
+    return {
+      allowed_domains: parseList(process.env.CLM_ALLOWED_DOMAINS),
+      blocked_domains: parseList(process.env.CLM_BLOCKED_DOMAINS),
+      allowed_protocols: parseList(process.env.CLM_ALLOWED_PROTOCOLS),
+      block_private_ips: process.env.CLM_BLOCK_PRIVATE_IPS === "true",
+      block_localhost: process.env.CLM_BLOCK_LOCALHOST === "true"
+    };
+  }
+  /**
+   * Validate URL against security policy
+   * Throws SecurityViolationError if URL is not allowed
+   */
+  validateUrl(urlString) {
+    let url;
+    try {
+      url = new URL(urlString);
+    } catch {
+      throw this.createSecurityError("DOMAIN_BLOCKED", `Invalid URL: ${urlString}`, urlString);
+    }
+    const hostname = url.hostname.toLowerCase();
+    const protocol = url.protocol.replace(":", "");
+    if (this.config.blocked_domains) {
+      for (const pattern of this.config.blocked_domains) {
+        if (this.matchDomainPattern(hostname, pattern)) {
+          throw this.createSecurityError(
+            "DOMAIN_BLOCKED",
+            `Domain '${hostname}' is blocked by security policy`,
+            urlString
+          );
+        }
+      }
+    }
+    if (this.config.allowed_domains && this.config.allowed_domains.length > 0) {
+      const isAllowed = this.config.allowed_domains.some(
+        (pattern) => this.matchDomainPattern(hostname, pattern)
+      );
+      if (!isAllowed) {
+        throw this.createSecurityError(
+          "DOMAIN_NOT_ALLOWED",
+          `Domain '${hostname}' is not in the allowed list`,
+          urlString
+        );
+      }
+    }
+    if (this.config.allowed_protocols && this.config.allowed_protocols.length > 0) {
+      if (!this.config.allowed_protocols.includes(protocol)) {
+        throw this.createSecurityError(
+          "PROTOCOL_NOT_ALLOWED",
+          `Protocol '${protocol}' is not allowed. Allowed: ${this.config.allowed_protocols.join(", ")}`,
+          urlString
+        );
+      }
+    }
+    if (this.config.block_localhost) {
+      if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1") {
+        throw this.createSecurityError(
+          "LOCALHOST_BLOCKED",
+          "Localhost access is blocked by security policy",
+          urlString
+        );
+      }
+    }
+    if (this.config.block_private_ips) {
+      if (this.isPrivateIP(hostname)) {
+        throw this.createSecurityError(
+          "PRIVATE_IP_BLOCKED",
+          `Private IP '${hostname}' is blocked by security policy`,
+          urlString
+        );
+      }
+    }
+  }
+  /**
+   * Match hostname against domain pattern (supports wildcards like *.example.com)
+   */
+  matchDomainPattern(hostname, pattern) {
+    const patternLower = pattern.toLowerCase();
+    if (patternLower.startsWith("*.")) {
+      const suffix = patternLower.slice(1);
+      return hostname.endsWith(suffix) || hostname === patternLower.slice(2);
+    }
+    return hostname === patternLower;
+  }
+  /**
+   * Check if hostname is a private IP address
+   */
+  isPrivateIP(hostname) {
+    const privatePatterns = [
+      /^10\.\d+\.\d+\.\d+$/,
+      // 10.x.x.x
+      /^192\.168\.\d+\.\d+$/,
+      // 192.168.x.x
+      /^172\.(1[6-9]|2\d|3[01])\.\d+\.\d+$/,
+      // 172.16-31.x.x
+      /^169\.254\.\d+\.\d+$/,
+      // Link-local
+      /^fc00:/i,
+      // IPv6 private
+      /^fd00:/i
+      // IPv6 private
+    ];
+    return privatePatterns.some((pattern) => pattern.test(hostname));
+  }
+  createSecurityError(code, message, url) {
+    const error = new Error(message);
+    error.securityViolation = { code, message, url };
+    return error;
+  }
+};
+
+// src/ptr/node/network/MCardSerialization.ts
+var MCardSerialization = class {
+  /**
+   * Serialize an MCard to a JSON-safe payload for network transfer
+   */
+  static serialize(card) {
+    return {
+      hash: card.hash,
+      content: Buffer.from(card.content).toString("base64"),
+      g_time: card.g_time,
+      contentType: card.contentType,
+      hashFunction: card.hashFunction
+    };
+  }
+  /**
+   * Deserialize a JSON payload back to an MCard
+   * Uses fromData if hash/g_time provided (preserves identity)
+   * Otherwise creates new MCard (generates new hash/g_time)
+   */
+  static async deserialize(json) {
+    if (!json.content) {
+      throw new Error("Missing content in MCard payload");
+    }
+    const content = Buffer.from(json.content, "base64");
+    if (json.hash && json.g_time) {
+      return MCard.fromData(content, json.hash, json.g_time);
+    }
+    return MCard.create(content);
+  }
+  /**
+   * Verify hash matches content (optional strict mode)
+   */
+  static verifyHash(card, expectedHash) {
+    if (card.hash !== expectedHash) {
+      console.warn(`[Network] Hash mismatch. Expected: ${expectedHash}, Got: ${card.hash}`);
+      return false;
+    }
+    return true;
+  }
+};
+
+// src/ptr/node/network/NetworkInfrastructure.ts
+var RateLimiter = class {
+  limits;
+  defaultLimit;
+  constructor(tokensPerSecond = RATE_LIMIT_DEFAULT_TOKENS_PER_SECOND, maxBurst = RATE_LIMIT_DEFAULT_MAX_BURST) {
+    this.limits = /* @__PURE__ */ new Map();
+    this.defaultLimit = { tokensPerSecond, maxBurst };
+  }
+  /**
+   * Check if request allowed. Consumes a token if allowed.
+   */
+  check(domain) {
+    const now = Date.now();
+    const bucket = this.limits.get(domain) || {
+      tokens: this.defaultLimit.maxBurst,
+      lastRefill: now
+    };
+    const elapsed = (now - bucket.lastRefill) / 1e3;
+    const refill = elapsed * this.defaultLimit.tokensPerSecond;
+    bucket.tokens = Math.min(this.defaultLimit.maxBurst, bucket.tokens + refill);
+    bucket.lastRefill = now;
+    if (bucket.tokens >= 1) {
+      bucket.tokens -= 1;
+      this.limits.set(domain, bucket);
+      return true;
+    }
+    this.limits.set(domain, bucket);
+    return false;
+  }
+  /**
+   * Wait until rate limit allows request
+   */
+  async waitFor(domain) {
+    while (!this.check(domain)) {
+      await new Promise((resolve) => setTimeout(resolve, RATE_LIMIT_WAIT_INTERVAL_MS));
+    }
+  }
+};
+var NetworkCache = class {
+  memoryCache;
+  collection;
+  constructor(collection) {
+    this.memoryCache = /* @__PURE__ */ new Map();
+    this.collection = collection;
+  }
+  /**
+   * Generate cache key from request config
+   */
+  static generateKey(method, url, body) {
+    const keyData = `${method}:${url}:${body || ""}`;
+    let hash = 0;
+    for (let i = 0; i < keyData.length; i++) {
+      const char = keyData.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash = hash & hash;
+    }
+    return `cache_${Math.abs(hash).toString(36)}`;
+  }
+  /**
+   * Get cached response if valid
+   */
+  get(cacheKey) {
+    const cached = this.memoryCache.get(cacheKey);
+    if (cached && cached.expiresAt > Date.now()) {
+      return { ...cached.response, timing: { ...cached.response.timing, total: 0 } };
+    }
+    if (cached) {
+      this.memoryCache.delete(cacheKey);
+    }
+    return null;
+  }
+  /**
+   * Cache a response with TTL
+   */
+  async set(cacheKey, response, ttlSeconds, persist = false) {
+    this.memoryCache.set(cacheKey, {
+      response,
+      expiresAt: Date.now() + ttlSeconds * 1e3
+    });
+    if (persist && this.collection) {
+      const cacheEntry = {
+        key: cacheKey,
+        response,
+        expiresAt: Date.now() + ttlSeconds * 1e3,
+        cachedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      const card = await MCard.create(JSON.stringify(cacheEntry));
+      await this.collection.add(card);
+    }
+  }
+};
+var RetryUtils = class {
+  static calculateBackoffDelay(attempt, strategy, baseDelay, maxDelay) {
+    let delay;
+    switch (strategy) {
+      case "exponential":
+        delay = baseDelay * Math.pow(2, attempt - 1);
+        break;
+      case "linear":
+        delay = baseDelay * attempt;
+        break;
+      case "constant":
+      default:
+        delay = baseDelay;
+    }
+    const jitter = delay * 0.1 * (Math.random() * 2 - 1);
+    delay = Math.round(delay + jitter);
+    return maxDelay ? Math.min(delay, maxDelay) : delay;
+  }
+  static shouldRetryStatus(status, retryOn) {
+    const defaultRetryStatuses = [408, 429, 500, 502, 503, 504];
+    const retryStatuses = retryOn || defaultRetryStatuses;
+    return retryStatuses.includes(status);
+  }
+};
+
+// src/ptr/node/network/HttpClient.ts
+var HttpClient = class {
+  rateLimiter;
+  cache;
+  constructor(rateLimiter, cache) {
+    this.rateLimiter = rateLimiter;
+    this.cache = cache;
+  }
+  async request(url, method, headers, body, config) {
+    const startTime = Date.now();
+    const fetchUrl = new URL(url);
+    const cacheConfig = config.cache;
+    const cacheKey = NetworkCache.generateKey(method, fetchUrl.toString(), typeof body === "string" ? body : void 0);
+    if (cacheConfig?.enabled && method === "GET") {
+      const cachedResponse = this.cache.get(cacheKey);
+      if (cachedResponse) {
+        console.log(`[Network] Cache hit for ${url}`);
+        return { ...cachedResponse, cached: true };
+      }
+    }
+    const domain = fetchUrl.hostname;
+    await this.rateLimiter.waitFor(domain);
+    const retryConfig = config.retry || {
+      max_attempts: HTTP_DEFAULT_MAX_ATTEMPTS,
+      backoff: HTTP_DEFAULT_BACKOFF,
+      base_delay: HTTP_DEFAULT_BASE_DELAY_MS,
+      max_delay: HTTP_DEFAULT_MAX_DELAY_MS
+    };
+    let lastError = null;
+    let lastStatus = null;
+    let retriesAttempted = 0;
+    for (let attempt = 1; attempt <= retryConfig.max_attempts; attempt++) {
+      const timeout = config.timeout || HTTP_DEFAULT_TIMEOUT_MS;
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+      try {
+        const ttfbStart = Date.now();
+        const response = await fetch(fetchUrl.toString(), {
+          method,
+          headers,
+          body,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok && RetryUtils.shouldRetryStatus(response.status, retryConfig.retry_on)) {
+          lastStatus = response.status;
+          if (attempt < retryConfig.max_attempts) {
+            retriesAttempted++;
+            const delay = RetryUtils.calculateBackoffDelay(
+              attempt,
+              retryConfig.backoff,
+              retryConfig.base_delay,
+              retryConfig.max_delay
+            );
+            console.log(`[Network] Retry ${attempt}/${retryConfig.max_attempts} for ${url} (status: ${response.status}, delay: ${delay}ms)`);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            continue;
+          }
+        }
+        const ttfbTime = Date.now() - ttfbStart;
+        let responseBody;
+        const responseType = config.responseType || "json";
+        if (responseType === "json") {
+          try {
+            responseBody = await response.json();
+          } catch {
+            responseBody = await response.text();
+          }
+        } else if (responseType === "text") {
+          responseBody = await response.text();
+        } else if (responseType === "binary") {
+          const arrayBuffer = await response.arrayBuffer();
+          responseBody = Buffer.from(arrayBuffer).toString("base64");
+        } else {
+          responseBody = await response.text();
+        }
+        const totalTime = Date.now() - startTime;
+        let mcard_hash;
+        try {
+          const bodyStr = typeof responseBody === "string" ? responseBody : JSON.stringify(responseBody);
+          const responseCard = await MCard.create(bodyStr);
+          mcard_hash = responseCard.hash;
+        } catch {
+        }
+        const timing = {
+          dns: 0,
+          connect: 0,
+          ttfb: ttfbTime,
+          total: totalTime
+        };
+        const result = {
+          success: true,
+          status: response.status,
+          headers: Object.fromEntries(response.headers.entries()),
+          body: responseBody,
+          timing,
+          mcard_hash
+        };
+        if (cacheConfig?.enabled && method === "GET" && response.ok) {
+          await this.cache.set(
+            cacheKey,
+            result,
+            cacheConfig.ttl ?? HTTP_DEFAULT_CACHE_TTL_SECONDS,
+            cacheConfig.storage === "mcard"
+          );
+        }
+        return result;
+      } catch (error) {
+        clearTimeout(timeoutId);
+        lastError = error;
+        if (attempt < retryConfig.max_attempts) {
+          retriesAttempted++;
+          const delay = RetryUtils.calculateBackoffDelay(
+            attempt,
+            retryConfig.backoff,
+            retryConfig.base_delay,
+            retryConfig.max_delay
+          );
+          console.log(`[Network] Retry ${attempt}/${retryConfig.max_attempts} for ${url} (error: ${lastError.message}, delay: ${delay}ms)`);
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          continue;
+        }
+      }
+    }
+    const err = lastError;
+    return {
+      success: false,
+      error: {
+        code: err?.name === "AbortError" ? "TIMEOUT" : "HTTP_ERROR",
+        message: err?.message || "Request failed after retries",
+        status: lastStatus,
+        retries_attempted: retriesAttempted
+      }
+    };
+  }
+};
+
+// src/ptr/node/NetworkRuntime.ts
+var NetworkRuntime = class {
+  collection;
+  security;
+  cache;
+  rateLimiter;
+  httpClient;
+  constructor(collection) {
+    this.collection = collection;
+    this.security = new NetworkSecurity();
+    this.cache = new NetworkCache(collection);
+    this.rateLimiter = new RateLimiter();
+    this.httpClient = new HttpClient(this.rateLimiter, this.cache);
+  }
+  async execute(_code, context, config, _chapterDir) {
+    const builtin = config.builtin;
+    const builtinConfig = config.config ?? {};
+    if (!builtin) {
+      throw new Error('NetworkRuntime requires "builtin" to be defined in config.');
+    }
+    switch (builtin) {
+      case "http_request":
+        return this.handleHttpRequest(builtinConfig, context);
+      case "http_get":
+        return this.handleHttpGet(builtinConfig, context);
+      case "http_post":
+        return this.handleHttpPost(builtinConfig, context);
+      case "load_url":
+        return this.handleLoadUrl(builtinConfig, context);
+      case "mcard_send":
+        return this.handleMCardSend(builtinConfig, context);
+      case "listen_http":
+        return this.handleListenHttp(builtinConfig, context);
+      case "mcard_sync":
+        return this.handleMCardSync(builtinConfig, context);
+      case "listen_sync":
+        return this.handleListenSync(builtinConfig, context);
+      case "webrtc_connect":
+      case "webrtc_listen":
+        console.warn(`[Network] WebRTC builtin ${builtin} mocked in TS runtime.`);
+        return { success: true, connection_id: "mock_conn_" + Date.now(), mock: true };
+      case "mcard_read":
+        return this.handleMCardRead(builtinConfig, context);
+      case "run_command":
+        return this.handleRunCommand(builtinConfig, context);
+      case "clm_orchestrator":
+        return this.handleOrchestrator(builtinConfig, context);
+      case "session_record":
+      case "signaling_server":
+        throw new Error(`Builtin ${builtin} removed (Kenotic Principle).`);
+      default:
+        throw new Error(`Unknown network builtin: ${builtin}`);
+    }
+  }
+  async handleHttpGet(config, context) {
+    return this.handleHttpRequest({ ...config, method: "GET" }, context);
+  }
+  async handleHttpPost(config, context) {
+    const params = { ...config, method: "POST" };
+    if (config.json) {
+      params.headers = { ...params.headers, "Content-Type": "application/json" };
+      params.body = JSON.stringify(config.json);
+    }
+    return this.handleHttpRequest(params, context);
+  }
+  async handleHttpRequest(config, context) {
+    const url = this.interpolate(config.url ?? "", context);
+    this.security.validateUrl(url);
+    const method = config.method || "GET";
+    const headers = this.interpolateHeaders(config.headers || {}, context);
+    let body = config.body;
+    if (typeof body === "string") {
+      body = this.interpolate(body, context);
+    } else if (typeof body === "object" && body !== null) {
+      body = JSON.stringify(body);
+    }
+    const fetchUrl = new URL(url);
+    if (config.query_params) {
+      for (const [key, value] of Object.entries(config.query_params)) {
+        fetchUrl.searchParams.append(key, this.interpolate(String(value), context));
+      }
+    }
+    return this.httpClient.request(
+      fetchUrl.toString(),
+      method,
+      headers,
+      body,
+      {
+        retry: config.retry,
+        cache: config.cache,
+        timeout: typeof config.timeout === "number" ? config.timeout : config.timeout?.total,
+        responseType: config.response_type
+      }
+    );
+  }
+  async handleLoadUrl(config, context) {
+    const url = this.interpolate(config.url, context);
+    this.security.validateUrl(url);
+    try {
+      const res = await fetch(url);
+      const text = await res.text();
+      return {
+        url,
+        content: text,
+        status: res.status,
+        headers: Object.fromEntries(res.headers.entries())
+      };
+    } catch (e) {
+      return { success: false, error: String(e) };
+    }
+  }
+  async handleMCardSend(config, context) {
+    if (!this.collection) {
+      throw new Error("MCard Send requires a CardCollection.");
+    }
+    const hash = this.interpolate(config.hash, context);
+    const url = this.interpolate(config.url, context);
+    const card = await this.collection.get(hash);
+    if (!card) {
+      return { success: false, error: `MCard not found: ${hash}` };
+    }
+    const payload = MCardSerialization.serialize(card);
+    return this.handleHttpPost({
+      url,
+      json: payload,
+      headers: config.headers
+    }, context);
+  }
+  async handleListenHttp(config, context) {
+    const port = Number(this.interpolate(String(config.port || NETWORK_DEFAULT_LISTEN_PORT), context));
+    const path = this.interpolate(config.path || "/mcard", context);
+    return new Promise((resolve, reject) => {
+      const server = http.createServer(async (req, res) => {
+        if (req.method === "POST" && req.url === path) {
+          const bodyChunks = [];
+          req.on("data", (chunk) => bodyChunks.push(chunk));
+          req.on("end", async () => {
+            try {
+              const body = Buffer.concat(bodyChunks).toString();
+              const json = JSON.parse(body);
+              const card = await MCardSerialization.deserialize(json);
+              if (json.hash) {
+                MCardSerialization.verifyHash(card, json.hash);
+              }
+              if (this.collection) {
+                await this.collection.add(card);
+              }
+              res.writeHead(200, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ success: true, hash: card.hash }));
+            } catch (e) {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ success: false, error: String(e) }));
+            }
+          });
+        } else {
+          res.writeHead(404);
+          res.end();
+        }
+      });
+      server.listen(port, () => {
+        console.info(`[Network] Listening on port ${port} at ${path}`);
+        resolve({
+          success: true,
+          message: `Server started on port ${port}`
+        });
+      });
+      server.on("error", (err) => {
+        reject(err);
+      });
+    });
+  }
+  async handleMCardSync(config, context) {
+    if (!this.collection) {
+      throw new Error("MCard Sync requires a CardCollection.");
+    }
+    const mode = this.interpolate(config.mode || "pull", context);
+    const urlParams = this.interpolate(config.url ?? "", context);
+    const url = urlParams.endsWith("/") ? urlParams.slice(0, -1) : urlParams;
+    const localCards = await this.collection.getAllMCardsRaw();
+    const localHashes = new Set(localCards.map((c) => c.hash));
+    const manifestRes = await this.handleHttpRequest({
+      url: `${url}/manifest`,
+      method: "GET"
+    }, context);
+    const manifestResult = manifestRes;
+    if (!manifestResult.success) {
+      const errorMessage = typeof manifestResult.error === "string" ? manifestResult.error : manifestResult.error?.message;
+      throw new Error(`Failed to fetch remote manifest: ${errorMessage}`);
+    }
+    const remoteHashes = new Set(manifestResult.body ?? []);
+    const stats = {
+      mode,
+      local_total: localHashes.size,
+      remote_total: remoteHashes.size,
+      synced: 0,
+      pushed: 0,
+      pulled: 0
+    };
+    const pushCards = async () => {
+      const toSend = [];
+      for (const card of localCards) {
+        if (!remoteHashes.has(card.hash)) {
+          toSend.push(card);
+        }
+      }
+      if (toSend.length > 0) {
+        const payload = {
+          cards: toSend.map((card) => MCardSerialization.serialize(card))
+        };
+        const pushRes = await this.handleHttpPost({
+          url: `${url}/batch`,
+          json: payload,
+          headers: config.headers
+        }, context);
+        const pushResult = pushRes;
+        if (!pushResult.success) {
+          const errorMessage = typeof pushResult.error === "string" ? pushResult.error : pushResult.error?.message;
+          throw new Error(`Failed to push batch: ${errorMessage}`);
+        }
+        return toSend.length;
+      }
+      return 0;
+    };
+    const pullCards = async () => {
+      const neededHashes = [];
+      for (const h of remoteHashes) {
+        if (!localHashes.has(h)) {
+          neededHashes.push(h);
+        }
+      }
+      if (neededHashes.length > 0) {
+        const fetchRes = await this.handleHttpPost({
+          url: `${url}/get`,
+          json: { hashes: neededHashes },
+          headers: config.headers
+        }, context);
+        const fetchResult = fetchRes;
+        if (!fetchResult.success) {
+          const errorMessage = typeof fetchResult.error === "string" ? fetchResult.error : fetchResult.error?.message;
+          throw new Error(`Failed to pull batch: ${errorMessage}`);
+        }
+        const receivedCards = fetchResult.body?.cards ?? [];
+        for (const json of receivedCards) {
+          const card = await MCardSerialization.deserialize(json);
+          await this.collection.add(card);
+        }
+        return receivedCards.length;
+      }
+      return 0;
+    };
+    if (mode === "push") {
+      stats.pushed = await pushCards();
+      stats.synced = stats.pushed;
+    } else if (mode === "pull") {
+      stats.pulled = await pullCards();
+      stats.synced = stats.pulled;
+    } else if (mode === "both" || mode === "bidirectional") {
+      const pushed = await pushCards();
+      const pulled = await pullCards();
+      stats.synced = pushed + pulled;
+      stats.pushed = pushed;
+      stats.pulled = pulled;
+    }
+    return { success: true, stats };
+  }
+  // ============ WebRTC Implementation ============
+  async handleListenSync(config, context) {
+    if (!this.collection) {
+      throw new Error("Listen Sync requires a CardCollection.");
+    }
+    const port = Number(this.interpolate(String(config.port || NETWORK_DEFAULT_LISTEN_PORT), context));
+    const basePath = this.interpolate(config.base_path || "/sync", context);
+    return new Promise((resolve, reject) => {
+      const server = http.createServer(async (req, res) => {
+        const url = req.url || "";
+        const readBody = async () => {
+          return new Promise((res2, rej) => {
+            const chunks = [];
+            req.on("data", (c) => chunks.push(c));
+            req.on("end", () => {
+              try {
+                const str = Buffer.concat(chunks).toString();
+                res2(JSON.parse(str || "{}"));
+              } catch (e) {
+                rej(e);
+              }
+            });
+            req.on("error", rej);
+          });
+        };
+        try {
+          if (req.method === "GET" && url === `${basePath}/manifest`) {
+            const all = await this.collection.getAllMCardsRaw();
+            const hashes = all.map((c) => c.hash);
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(hashes));
+            return;
+          }
+          if (req.method === "POST" && url === `${basePath}/batch`) {
+            const json = await readBody();
+            const cards = Array.isArray(json.cards) ? json.cards : [];
+            let added = 0;
+            for (const cJson of cards) {
+              const card = await MCardSerialization.deserialize(cJson);
+              await this.collection.add(card);
+              added++;
+            }
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ success: true, added }));
+            return;
+          }
+          if (req.method === "POST" && url === `${basePath}/get`) {
+            const json = await readBody();
+            const requestedHashes = Array.isArray(json.hashes) ? json.hashes : [];
+            const foundCards = [];
+            for (const h of requestedHashes) {
+              const card = await this.collection.get(h);
+              if (card) {
+                foundCards.push(MCardSerialization.serialize(card));
+              }
+            }
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ success: true, cards: foundCards }));
+            return;
+          }
+          res.writeHead(404);
+          res.end();
+        } catch (e) {
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ success: false, error: String(e) }));
+        }
+      });
+      server.listen(port, () => {
+        console.log(`[Network] Sync listening on port ${port} at ${basePath}`);
+        resolve({
+          success: true,
+          message: `Sync Server started on port ${port}`,
+          port,
+          basePath
+        });
+      });
+      server.on("error", (err) => {
+        reject(err);
+      });
+    });
+  }
+  interpolate(text, context) {
+    if (!text || typeof text !== "string") return text;
+    return text.replace(/\$\{([^}]+)\}/g, (_, path) => {
+      const keys = path.split(".");
+      let val = context;
+      for (const key of keys) {
+        if (val && typeof val === "object" && key in val) {
+          val = val[key];
+        } else {
+          return "";
+        }
+      }
+      return String(val);
+    });
+  }
+  interpolateHeaders(headers, context) {
+    const result = {};
+    for (const [key, val] of Object.entries(headers)) {
+      result[key] = this.interpolate(val, context);
+    }
+    return result;
+  }
+  async handleMCardRead(config, context) {
+    if (!this.collection) {
+      throw new Error("MCard Read requires a CardCollection.");
+    }
+    const hash = this.interpolate(config.hash, context);
+    if (!hash) throw new Error("Hash is required for mcard_read");
+    const card = await this.collection.get(hash);
+    if (!card) return { success: false, error: "MCard not found", hash };
+    let content = card.getContentAsText();
+    if (config.parse_json !== false) {
+      try {
+        if (typeof content === "string") {
+          content = JSON.parse(content);
+        }
+      } catch (e) {
+      }
+    }
+    return {
+      success: true,
+      hash,
+      content,
+      g_time: card.g_time
+    };
+  }
+  async handleOrchestrator(config, context) {
+    const steps = config.steps || [];
+    const state = {};
+    let allSuccess = true;
+    console.log(`[NetworkRuntime] Starting Orchestration with ${steps.length} steps.`);
+    for (const step of steps) {
+      const stepName = step.name || step.action;
+      console.log(`[Orchestrator] Step: ${stepName}`);
+      try {
+        if (step.action === "start_process") {
+          const cmd = this.interpolate(step.command ?? "", context);
+          const { spawn } = await import("child_process");
+          const parts = cmd.split(" ");
+          const env = { ...process.env, ...step.env || {} };
+          const proc = spawn(parts[0], parts.slice(1), {
+            detached: true,
+            stdio: "inherit",
+            cwd: process.cwd(),
+            env
+          });
+          proc.unref();
+          if (step.id_key && proc.pid !== void 0) {
+            state[step.id_key] = proc.pid;
+            console.log(`[Orchestrator] Process started (PID: ${proc.pid}) stored in '${step.id_key}'`);
+          } else {
+            console.log(`[Orchestrator] Process started (PID: ${proc.pid})`);
+          }
+          if (step.wait_after) {
+            await new Promise((r) => setTimeout(r, step.wait_after));
+          }
+        } else if (step.action === "run_clm") {
+          if (!context.runCLM) throw new Error("runCLM capability not available in context");
+          const file = step.file;
+          if (!file) {
+            throw new Error("run_clm step requires file");
+          }
+          const input = step.input || {};
+          console.log(`[Orchestrator] Running CLM: ${file}`);
+          const res = await context.runCLM(file, input);
+          if (!res.success) {
+            console.error(`[Orchestrator] CLM Failed: ${file}`, res.error);
+            if (!step.continue_on_error) {
+              allSuccess = false;
+              break;
+            }
+          } else {
+            console.log(`[Orchestrator] CLM Passed: ${file}`);
+          }
+        } else if (step.action === "run_clm_background") {
+          const file = step.file;
+          if (!file) {
+            throw new Error("run_clm_background step requires file");
+          }
+          const filter = file.replace(/\.(yaml|yml|clm)$/i, "");
+          const cmd = `npx tsx examples/run-all-clms.ts ${filter}`;
+          const { spawn } = await import("child_process");
+          const parts = cmd.split(" ");
+          const env = { ...process.env, ...step.env || {} };
+          const proc = spawn(parts[0], parts.slice(1), {
+            detached: true,
+            stdio: "inherit",
+            cwd: process.cwd(),
+            env
+          });
+          proc.unref();
+          if (step.id_key && proc.pid !== void 0) {
+            state[step.id_key] = proc.pid;
+            console.log(`[Orchestrator] Background CLM started (PID: ${proc.pid}) stored in '${step.id_key}'`);
+          }
+          if (step.wait_after) {
+            await new Promise((r) => setTimeout(r, step.wait_after));
+          }
+        } else if (step.action === "stop_process") {
+          const key = step.pid_key;
+          if (!key) {
+            console.warn("[Orchestrator] stop_process missing pid_key");
+            continue;
+          }
+          const pid = state[key];
+          if (typeof pid === "number") {
+            try {
+              context.process?.kill(pid);
+              console.log(`[Orchestrator] Stopped process ${pid} (${key})`);
+            } catch (e) {
+              console.warn(`[Orchestrator] Failed to stop process ${pid}: ${e}`);
+            }
+          } else {
+            console.warn(`[Orchestrator] No PID found for key '${key}'`);
+          }
+        } else if (step.action === "sleep") {
+          const ms = step.ms || NETWORK_DEFAULT_ORCHESTRATOR_SLEEP_MS;
+          await new Promise((r) => setTimeout(r, ms));
+        } else if (step.action === "start_signaling_server") {
+          throw new Error(`Builtin signaling server removed (Kenotic Principle).`);
+        } else if (step.action === "stop_signaling_server") {
+          throw new Error(`Builtin signaling server removed (Kenotic Principle).`);
+        }
+      } catch (e) {
+        console.error(`[Orchestrator] Step '${stepName}' caused error:`, e);
+        allSuccess = false;
+        if (!step.continue_on_error) break;
+      }
+    }
+    return {
+      success: allSuccess,
+      state
+    };
+  }
+  async handleRunCommand(config, context) {
+    const command = this.interpolate(config.command, context);
+    console.log(`[NetworkRuntime] Executing command: ${command}`);
+    const { exec, spawn } = await import("child_process");
+    if (config.background) {
+      const parts = command.split(" ");
+      const cmd = parts[0];
+      const args = parts.slice(1);
+      if (!cmd) {
+        throw new Error("Command is required");
+      }
+      const subprocess = spawn(cmd, args, {
+        detached: true,
+        stdio: "ignore"
+      });
+      subprocess.unref();
+      console.log(`[NetworkRuntime] Started background process with PID: ${subprocess.pid}`);
+      return {
+        success: true,
+        pid: subprocess.pid,
+        message: "Background process started"
+      };
+    }
+    return new Promise((resolve, reject) => {
+      exec(command, (error, stdout, stderr) => {
+        if (error) {
+          console.error(`[NetworkRuntime] Command failed: ${error.message}`);
+          return resolve({
+            success: false,
+            error: error.message,
+            stderr
+          });
+        }
+        console.log(`[NetworkRuntime] Command output:
+${stdout}`);
+        resolve({
+          success: true,
+          stdout,
+          stderr
+        });
+      });
+    });
+  }
+};
+export {
+  NetworkRuntime
+};