mcard-js 2.1.48 → 2.1.49

package/dist/index.cjs

@@ -455,6 +455,8 @@ var init_app_config = __esm({
         default_ws_host: "127.0.0.1",
         default_ws_port: 5321,
         default_api_port: 5320,
+        default_python_api_port: 28302,
+        default_js_api_port: 28303,
         default_server_host: "0.0.0.0",
         cors_origins: [
           "http://localhost:3000",
@@ -484,7 +486,8 @@ var init_app_config = __esm({
         default_server_memory_db: "servermemory.db",
         default_mcard_db: "mcard.db",
         default_server_log_db: "server_log.db",
-        default_push_subscriptions_file: "subscriptions.json"
+        default_push_subscriptions_file: "subscriptions.json",
+        default_vcard_db_path: "data/vcard.db"
       },
       services: {
         default_ollama_base_url: "http://localhost:11434",
@@ -524,7 +527,7 @@ var init_app_config = __esm({
 });
 
 // src/config/constants.ts
-var network, identity, services, web, DEFAULT_PAGE_SIZE, MAX_FILE_SIZE, READ_TIMEOUT_MS, KNOWN_TYPE_SIZE_LIMIT, BINARY_CHECK_SAMPLE_SIZE, CONTENT_DETECTION_SAMPLE_SIZE, DEFAULT_MAX_PROBLEM_BYTES, INDEXEDDB_DEFAULT_DB_NAME, INDEXEDDB_DEFAULT_DB_VERSION, SQLITE_BUSY_TIMEOUT_MS, DEFAULT_IDENTITY_PROVIDER, DEFAULT_IDENTITY_SPACE_PATH, DEFAULT_API_PORT, DEFAULT_WS_PORT, DEFAULT_WS_HOST, DEFAULT_SERVER_HOST, CORS_ORIGINS, getEnvUrl, API_KEY_HEADER_NAME, DEFAULT_OLLAMA_BASE_URL, DEFAULT_OTLP_ENDPOINT, DEFAULT_VLLM_BASE_URL, DEFAULT_LMSTUDIO_BASE_URL, DEFAULT_SQLJS_WASM_URL, DEFAULT_SANDBOX_TIMEOUT_MS, DEFAULT_CLM_TIMEOUT_MS, DEFAULT_VM_EXECUTION_TIMEOUT_MS, LLM_DEFAULT_TIMEOUT_SECS, LLM_DEFAULT_RETRY_COUNT, LLM_DEFAULT_RETRY_DELAY_SECS;
+var network, identity, services, web, DEFAULT_PAGE_SIZE, MAX_FILE_SIZE, READ_TIMEOUT_MS, KNOWN_TYPE_SIZE_LIMIT, BINARY_CHECK_SAMPLE_SIZE, CONTENT_DETECTION_SAMPLE_SIZE, DEFAULT_MAX_PROBLEM_BYTES, INDEXEDDB_DEFAULT_DB_NAME, INDEXEDDB_DEFAULT_DB_VERSION, SQLITE_BUSY_TIMEOUT_MS, DEFAULT_IDENTITY_PROVIDER, DEFAULT_IDENTITY_SPACE_PATH, DEFAULT_API_PORT, DEFAULT_PYTHON_API_PORT, DEFAULT_JS_API_PORT, DEFAULT_VCARD_DB_PATH, DEFAULT_WS_PORT, DEFAULT_WS_HOST, DEFAULT_SERVER_HOST, CORS_ORIGINS, getEnvUrl, API_KEY_HEADER_NAME, DEFAULT_OLLAMA_BASE_URL, DEFAULT_OTLP_ENDPOINT, DEFAULT_VLLM_BASE_URL, DEFAULT_LMSTUDIO_BASE_URL, DEFAULT_SQLJS_WASM_URL, DEFAULT_SANDBOX_TIMEOUT_MS, DEFAULT_CLM_TIMEOUT_MS, DEFAULT_VM_EXECUTION_TIMEOUT_MS, LLM_DEFAULT_TIMEOUT_SECS, LLM_DEFAULT_RETRY_COUNT, LLM_DEFAULT_RETRY_DELAY_SECS;
 var init_constants = __esm({
   "src/config/constants.ts"() {
     "use strict";
@@ -546,6 +549,9 @@ var init_constants = __esm({
     DEFAULT_IDENTITY_PROVIDER = String(identity.provider ?? "sqlite");
     DEFAULT_IDENTITY_SPACE_PATH = String(identity.space_path ?? "./data/IDENTITY_SPACE.db");
     DEFAULT_API_PORT = Number(network.default_api_port ?? 5320);
+    DEFAULT_PYTHON_API_PORT = Number(network.default_python_api_port ?? 28302);
+    DEFAULT_JS_API_PORT = Number(network.default_js_api_port ?? 28303);
+    DEFAULT_VCARD_DB_PATH = String(app_config_default.storage?.default_vcard_db_path ?? "./data/vcard.db");
     DEFAULT_WS_PORT = Number(network.default_ws_port ?? 5321);
     DEFAULT_WS_HOST = String(network.default_ws_host ?? "127.0.0.1");
     DEFAULT_SERVER_HOST = String(network.default_server_host ?? "0.0.0.0");
@@ -2855,7 +2861,7 @@ var init_OllamaProvider = __esm({
           },
           timeout: this.timeout
         };
-        return new Promise((resolve10) => {
+        return new Promise((resolve11) => {
           let payload;
           if (data) {
             payload = JSON.stringify(data);
@@ -2870,33 +2876,33 @@ var init_OllamaProvider = __esm({
               if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
                 try {
                   if (body.includes("\n") && !body.trim().startsWith("{")) {
-                    resolve10(Either.right(JSON.parse(body)));
+                    resolve11(Either.right(JSON.parse(body)));
                   } else {
-                    resolve10(Either.right(JSON.parse(body)));
+                    resolve11(Either.right(JSON.parse(body)));
                   }
                 } catch (e) {
                   const lines = body.trim().split("\n").filter((l) => l);
                   if (lines.length > 0) {
                     try {
-                      resolve10(Either.right(JSON.parse(lines[lines.length - 1])));
+                      resolve11(Either.right(JSON.parse(lines[lines.length - 1])));
                     } catch (parseErr) {
-                      resolve10(Either.left(`Ollama response parse error: ${parseErr}`));
+                      resolve11(Either.left(`Ollama response parse error: ${parseErr}`));
                     }
                   } else {
-                    resolve10(Either.left(`Ollama response parse error: ${e}`));
+                    resolve11(Either.left(`Ollama response parse error: ${e}`));
                   }
                 }
               } else {
-                resolve10(Either.left(`Ollama HTTP error ${res.statusCode}: ${body}`));
+                resolve11(Either.left(`Ollama HTTP error ${res.statusCode}: ${body}`));
               }
             });
           });
           req.on("error", (e) => {
-            resolve10(Either.left(`Ollama connection error: ${e.message}`));
+            resolve11(Either.left(`Ollama connection error: ${e.message}`));
           });
           req.on("timeout", () => {
             req.destroy();
-            resolve10(Either.left(`Ollama request timed out after ${this.timeout}ms`));
+            resolve11(Either.left(`Ollama request timed out after ${this.timeout}ms`));
           });
           if (payload) {
             req.write(payload);
@@ -3168,26 +3174,26 @@ var init_MLCLLMProvider = __esm({
           headers: options.headers || {},
           timeout: this.timeout
         };
-        return new Promise((resolve10) => {
+        return new Promise((resolve11) => {
           const req = client.request(url, reqOptions, (res) => {
             let body = "";
             res.on("data", (chunk) => body += chunk);
             res.on("end", () => {
               if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
                 try {
-                  resolve10(Either.right(JSON.parse(body)));
+                  resolve11(Either.right(JSON.parse(body)));
                 } catch (e) {
-                  resolve10(Either.left(`Parse error: ${e}`));
+                  resolve11(Either.left(`Parse error: ${e}`));
                 }
               } else {
-                resolve10(Either.left(`HTTP Error ${res.statusCode}: ${body}`));
+                resolve11(Either.left(`HTTP Error ${res.statusCode}: ${body}`));
               }
             });
           });
-          req.on("error", (e) => resolve10(Either.left(e.message)));
+          req.on("error", (e) => resolve11(Either.left(e.message)));
           req.on("timeout", () => {
             req.destroy();
-            resolve10(Either.left("Request timed out"));
+            resolve11(Either.left("Request timed out"));
           });
           if (options.body) {
             req.write(options.body);
@@ -4092,7 +4098,7 @@ function normalize(collection, termHash, strategy = "normal", maxSteps = 1e3, ma
     const startTime = Date.now();
     let current = termHash;
     let steps = 0;
-    const path15 = [termHash];
+    const path16 = [termHash];
     while (steps < maxSteps) {
       if (maxTimeMs !== void 0 && Date.now() - startTime > maxTimeMs) {
         return Either.left(
@@ -4104,11 +4110,11 @@ function normalize(collection, termHash, strategy = "normal", maxSteps = 1e3, ma
         return Either.right({
           normalForm: current,
           steps,
-          reductionPath: path15
+          reductionPath: path16
         });
       }
       current = stepResult.value;
-      path15.push(current);
+      path16.push(current);
       steps++;
       if (onStep) {
         await onStep(steps, current);
@@ -4690,7 +4696,7 @@ var init_wasm = __esm({
       async execute(wasmPath, context, config, chapterDir) {
         const fullPath = path7.resolve(chapterDir, wasmPath);
         const contextStr = typeof context === "string" ? context : JSON.stringify(context ?? {});
-        return new Promise((resolve10, reject) => {
+        return new Promise((resolve11, reject) => {
           const proc = child_process3.spawn("wasmtime", [fullPath, contextStr]);
           proc.stdin.end();
           let stdout = "";
@@ -4713,16 +4719,16 @@ var init_wasm = __esm({
             }
             const out = stdout.trim();
             if (!out) {
-              return resolve10(void 0);
+              return resolve11(void 0);
             }
             const numeric = out.trim();
             if (numeric && !Number.isNaN(Number(numeric))) {
-              return resolve10(Number(numeric));
+              return resolve11(Number(numeric));
             }
             try {
-              return resolve10(JSON.parse(out));
+              return resolve11(JSON.parse(out));
             } catch {
-              return resolve10(out);
+              return resolve11(out);
             }
           });
         });
@@ -5092,14 +5098,14 @@ var init_P2PChatSession = __esm({
 
 // src/ptr/node/SignalingServer.ts
 function killProcessOnPort(port) {
-  return new Promise((resolve10) => {
+  return new Promise((resolve11) => {
     (0, import_child_process.exec)(`lsof -ti:${port} | xargs kill -9 2>/dev/null`, (error) => {
       if (error) {
         Logger2.info(`No existing process on port ${port} to kill`);
       } else {
         Logger2.info(`Killed existing process on port ${port}`);
       }
-      setTimeout(resolve10, NETWORK_SIGNALING_PORT_RELEASE_WAIT_MS);
+      setTimeout(resolve11, NETWORK_SIGNALING_PORT_RELEASE_WAIT_MS);
     });
   });
 }
@@ -5119,8 +5125,8 @@ async function createSignalingServer(config = {}) {
       return;
     }
     const url = new URL(req.url || "/", `http://${req.headers.host}`);
-    const path15 = url.pathname;
-    if (req.method === "GET" && path15 === "/health") {
+    const path16 = url.pathname;
+    if (req.method === "GET" && path16 === "/health") {
       res.writeHead(200, { "Content-Type": "application/json" });
       res.end(JSON.stringify({
         status: "ok",
@@ -5129,7 +5135,7 @@ async function createSignalingServer(config = {}) {
       }));
       return;
     }
-    if (req.method === "GET" && path15 === "/signal") {
+    if (req.method === "GET" && path16 === "/signal") {
       const peerId = url.searchParams.get("peer_id");
       if (!peerId) {
         res.writeHead(400);
@@ -5162,7 +5168,7 @@ async function createSignalingServer(config = {}) {
       });
       return;
     }
-    if (req.method === "POST" && path15 === "/signal") {
+    if (req.method === "POST" && path16 === "/signal") {
       let body = "";
       req.on("data", (chunk) => body += chunk);
       req.on("end", () => {
@@ -5202,7 +5208,7 @@ async function createSignalingServer(config = {}) {
   for (let attempt = 0; attempt < maxTries; attempt++) {
     const port = startPort + attempt;
     try {
-      await new Promise((resolve10, reject) => {
+      await new Promise((resolve11, reject) => {
         server.once("error", (err) => {
           if (err.code === "EADDRINUSE") {
             reject(err);
@@ -5212,7 +5218,7 @@ async function createSignalingServer(config = {}) {
         });
         server.listen(port, () => {
           server.removeAllListeners("error");
-          resolve10();
+          resolve11();
         });
       });
       Logger2.info(`Server running on port ${port}`);
@@ -5228,11 +5234,11 @@ async function createSignalingServer(config = {}) {
         Logger2.info(`Port ${port} in use, trying to kill existing process...`);
         await killProcessOnPort(port);
         try {
-          await new Promise((resolve10, reject) => {
+          await new Promise((resolve11, reject) => {
             server.once("error", reject);
             server.listen(port, () => {
               server.removeAllListeners("error");
-              resolve10();
+              resolve11();
             });
           });
           Logger2.info(`Server running on port ${port} (after kill)`);
@@ -5493,7 +5499,7 @@ var init_NetworkInfrastructure = __esm({
        */
       async waitFor(domain) {
         while (!this.check(domain)) {
-          await new Promise((resolve10) => setTimeout(resolve10, RATE_LIMIT_WAIT_INTERVAL_MS));
+          await new Promise((resolve11) => setTimeout(resolve11, RATE_LIMIT_WAIT_INTERVAL_MS));
         }
       }
     };
@@ -5639,7 +5645,7 @@ var init_HttpClient = __esm({
                   retryConfig.max_delay
                 );
                 console.log(`[Network] Retry ${attempt}/${retryConfig.max_attempts} for ${url} (status: ${response.status}, delay: ${delay}ms)`);
-                await new Promise((resolve10) => setTimeout(resolve10, delay));
+                await new Promise((resolve11) => setTimeout(resolve11, delay));
                 continue;
               }
             }
@@ -5703,7 +5709,7 @@ var init_HttpClient = __esm({
                 retryConfig.max_delay
               );
               console.log(`[Network] Retry ${attempt}/${retryConfig.max_attempts} for ${url} (error: ${lastError.message}, delay: ${delay}ms)`);
-              await new Promise((resolve10) => setTimeout(resolve10, delay));
+              await new Promise((resolve11) => setTimeout(resolve11, delay));
               continue;
             }
           }
@@ -5873,10 +5879,10 @@ var init_NetworkRuntime = __esm({
       }
       async handleListenHttp(config, context) {
         const port = Number(this.interpolate(String(config.port || NETWORK_DEFAULT_LISTEN_PORT), context));
-        const path15 = this.interpolate(config.path || "/mcard", context);
-        return new Promise((resolve10, reject) => {
+        const path16 = this.interpolate(config.path || "/mcard", context);
+        return new Promise((resolve11, reject) => {
           const server = http3.createServer(async (req, res) => {
-            if (req.method === "POST" && req.url === path15) {
+            if (req.method === "POST" && req.url === path16) {
               const bodyChunks = [];
               req.on("data", (chunk) => bodyChunks.push(chunk));
               req.on("end", async () => {
@@ -5903,8 +5909,8 @@ var init_NetworkRuntime = __esm({
             }
           });
           server.listen(port, () => {
-            console.log(`[Network] Listening on port ${port} at ${path15}`);
-            resolve10({
+            console.info(`[Network] Listening on port ${port} at ${path16}`);
+            resolve11({
               success: true,
               message: `Server started on port ${port}`
             });
@@ -6032,9 +6038,9 @@ var init_NetworkRuntime = __esm({
         const myPeerId = config.peer_id ? this.interpolate(config.peer_id, context) : `peer_${Date.now()}`;
         const channelLabel = config.channel_label || "mcard-sync";
         if (signalingUrl === "mock://p2p") {
-          return new Promise((resolve10) => {
+          return new Promise((resolve11) => {
             setTimeout(() => {
-              resolve10({
+              resolve11({
                 success: true,
                 peer_id: myPeerId,
                 channel: channelLabel,
@@ -6044,12 +6050,12 @@ var init_NetworkRuntime = __esm({
             }, WEBRTC_DEFAULT_MOCK_DELAY_MS);
           });
         }
-        console.log(`[WebRTC] Connecting to ${targetPeerId} via ${signalingUrl} as ${myPeerId}`);
+        console.info(`[WebRTC] Connecting to ${targetPeerId} via ${signalingUrl} as ${myPeerId}`);
         const pc = new PeerConnection({
           iceServers: config.ice_servers || [{ urls: "stun:stun.l.google.com:19302" }]
         });
         const dc = pc.createDataChannel(channelLabel);
-        const connectionPromise = new Promise((resolve10, reject) => {
+        const connectionPromise = new Promise((resolve11, reject) => {
           const timeoutMs = config.timeout || WEBRTC_DEFAULT_TIMEOUT_MS;
           const timeoutId = setTimeout(() => {
             pc.close();
@@ -6057,12 +6063,12 @@ var init_NetworkRuntime = __esm({
           }, timeoutMs);
           dc.onopen = () => {
             clearTimeout(timeoutId);
-            console.log(`[WebRTC] Data channel '${channelLabel}' open`);
+            console.info(`[WebRTC] Data channel '${channelLabel}' open`);
             if (config.message) {
               const msg = typeof config.message === "string" ? this.interpolate(config.message, context) : JSON.stringify(config.message);
               dc.send(msg);
             }
-            resolve10({
+            resolve11({
               success: true,
               peer_id: myPeerId,
               channel: channelLabel,
@@ -6078,7 +6084,7 @@ var init_NetworkRuntime = __esm({
         });
         const offer = await pc.createOffer();
         await pc.setLocalDescription(offer);
-        console.log("[WebRTC] Local Offer created. SDP ready to send.");
+        console.info("[WebRTC] Local Offer created. SDP ready to send.");
         if (config.await_response !== false) {
           return connectionPromise;
         }
@@ -6129,7 +6135,7 @@ var init_NetworkRuntime = __esm({
                 await this.collection.add(card);
                 added++;
               }
-              console.log(`[WebRTC] Synced ${added} cards from peer.`);
+              console.info(`[WebRTC] Synced ${added} cards from peer.`);
             }
           } catch (e) {
             console.error("[WebRTC] Protocol error:", e);
@@ -6147,9 +6153,9 @@ var init_NetworkRuntime = __esm({
         const signalingUrl = this.interpolate(config.signaling_url ?? "", context);
         const myPeerId = config.peer_id ? this.interpolate(config.peer_id, context) : `listener_${Date.now()}`;
         if (signalingUrl === "mock://p2p") {
-          return new Promise((resolve10) => {
+          return new Promise((resolve11) => {
             setTimeout(() => {
-              resolve10({
+              resolve11({
                 success: true,
                 peer_id: myPeerId,
                 status: "listening",
@@ -6172,7 +6178,7 @@ var init_NetworkRuntime = __esm({
         }
         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((resolve10, reject) => {
+        return new Promise((resolve11, reject) => {
           const server = http3.createServer(async (req, res) => {
             const url = req.url || "";
             const readBody = async () => {
@@ -6234,7 +6240,7 @@ var init_NetworkRuntime = __esm({
           });
           server.listen(port, () => {
             console.log(`[Network] Sync listening on port ${port} at ${basePath}`);
-            resolve10({
+            resolve11({
               success: true,
               message: `Sync Server started on port ${port}`,
               port,
@@ -6248,8 +6254,8 @@ var init_NetworkRuntime = __esm({
       }
       interpolate(text, context) {
         if (!text || typeof text !== "string") return text;
-        return text.replace(/\$\{([^}]+)\}/g, (_, path15) => {
-          const keys = path15.split(".");
+        return text.replace(/\$\{([^}]+)\}/g, (_, path16) => {
+          const keys = path16.split(".");
           let val = context;
           for (const key of keys) {
             if (val && typeof val === "object" && key in val) {
@@ -6551,11 +6557,11 @@ var init_NetworkRuntime = __esm({
             message: "Background process started"
           };
         }
-        return new Promise((resolve10, reject) => {
+        return new Promise((resolve11, reject) => {
           exec3(command, (error, stdout, stderr) => {
             if (error) {
               console.error(`[NetworkRuntime] Command failed: ${error.message}`);
-              return resolve10({
+              return resolve11({
                 success: false,
                 error: error.message,
                 stderr
@@ -6563,7 +6569,7 @@ var init_NetworkRuntime = __esm({
             }
             console.log(`[NetworkRuntime] Command output:
 ${stdout}`);
-            resolve10({
+            resolve11({
               success: true,
               stdout,
               stderr
@@ -7553,6 +7559,9 @@ __export(index_exports, {
   MCard: () => MCard,
   MCardStore: () => MCardStore,
   Maybe: () => Maybe,
+  PTREngine: () => PTREngine,
+  PostconditionViolation: () => PostconditionViolation,
+  PreconditionViolation: () => PreconditionViolation,
   Reader: () => Reader,
   SandboxWorker: () => SandboxWorker,
   ServiceWorkerPTR: () => ServiceWorkerPTR,
@@ -8090,12 +8099,12 @@ var SandboxWorker = class {
    * Send request and wait for response
    */
   sendRequest(request) {
-    return new Promise((resolve10, reject) => {
+    return new Promise((resolve11, reject) => {
       const timeout = setTimeout(() => {
         this.pendingRequests.delete(request.id);
         reject(new Error(`Request ${request.id} timed out`));
       }, this.defaultTimeout);
-      this.pendingRequests.set(request.id, { resolve: resolve10, reject, timeout });
+      this.pendingRequests.set(request.id, { resolve: resolve11, reject, timeout });
       this.worker.postMessage(request);
     });
   }
@@ -8156,6 +8165,32 @@ var VerificationStatus = /* @__PURE__ */ ((VerificationStatus2) => {
   VerificationStatus2["SKIPPED"] = "skipped";
   return VerificationStatus2;
 })(VerificationStatus || {});
+var PreconditionViolation = class extends Error {
+  pcardHash;
+  inputHash;
+  detail;
+  constructor(pcardHash, inputHash, detail = "") {
+    const msg = `PreconditionViolation: PCard ${pcardHash.substring(0, 16)} rejected input ${inputHash.substring(0, 16)}${detail ? ` \u2014 ${detail}` : ""}`;
+    super(msg);
+    this.name = "PreconditionViolation";
+    this.pcardHash = pcardHash;
+    this.inputHash = inputHash;
+    this.detail = detail;
+  }
+};
+var PostconditionViolation = class extends Error {
+  pcardHash;
+  outputRepr;
+  detail;
+  constructor(pcardHash, outputRepr, detail = "") {
+    const msg = `PostconditionViolation: PCard ${pcardHash.substring(0, 16)} postcondition failed for output ${outputRepr.substring(0, 64)}${detail ? ` \u2014 ${detail}` : ""}`;
+    super(msg);
+    this.name = "PostconditionViolation";
+    this.pcardHash = pcardHash;
+    this.outputRepr = outputRepr;
+    this.detail = detail;
+  }
+};
 
 // src/ptr/browser/storage/MCardStore.ts
 var import_idb2 = require("idb");
@@ -8641,78 +8676,10 @@ init_LambdaRuntime();
 // src/index.ts
 init_LambdaRuntime();
 
-// src/ptr/node/clm/utils.ts
-function resultsEqual(a, b, tolerance = 1e-9) {
-  if (a === b) return true;
-  if (a == null || b == null) return false;
-  if (typeof a === "number" && typeof b === "number") {
-    if (Number.isNaN(a) && Number.isNaN(b)) return true;
-    if (!Number.isFinite(a) || !Number.isFinite(b)) return a === b;
-    return Math.abs(a - b) <= tolerance * Math.max(1, Math.abs(a), Math.abs(b));
-  }
-  if (Array.isArray(a) && Array.isArray(b)) {
-    if (a.length !== b.length) return false;
-    return a.every((val, i) => resultsEqual(val, b[i], tolerance));
-  }
-  if (typeof a === "object" && typeof b === "object") {
-    const keysA = Object.keys(a);
-    const keysB = Object.keys(b);
-    if (keysA.length !== keysB.length) return false;
-    return keysA.every(
-      (key) => keysB.includes(key) && resultsEqual(a[key], b[key], tolerance)
-    );
-  }
-  return a === b;
-}
-function asObject(input) {
-  return typeof input === "object" && input !== null ? input : {};
-}
-function buildBaseContext(clm, input) {
-  const inputObj = asObject(input);
-  return {
-    balanced: clm.clm.balanced,
-    input_arguments: clm.clm.concrete?.input_arguments,
-    output_arguments: clm.clm.concrete?.output_arguments,
-    params: inputObj,
-    ...inputObj
-  };
-}
-function buildExecutionResult(success, result, startTime, clm, error, boundary) {
-  return {
-    success,
-    result,
-    error,
-    executionTime: Date.now() - startTime,
-    clm: {
-      chapter: clm.chapter?.title || "Unknown",
-      concept: clm.clm.abstract?.concept || "Unknown",
-      manifestation: clm.clm.concrete?.manifestation || "Unknown",
-      boundary
-    }
-  };
-}
-function isRecursiveCLM(runtimeName) {
-  return runtimeName.endsWith(".clm") || runtimeName.endsWith(".yaml") || runtimeName.endsWith(".yml");
-}
-function isMultiRuntime(clm) {
-  const runtimesConfig = clm.clm?.concrete?.runtimes_config;
-  return Array.isArray(runtimesConfig) && runtimesConfig.length > 0;
-}
-
-// src/ptr/node/clm/runner.ts
-var path14 = __toESM(require("path"), 1);
-var yaml2 = __toESM(require("yaml"), 1);
-init_constants();
-
-// src/ptr/node/runtimes/index.ts
-init_base();
-init_javascript();
-init_python();
-init_binary();
-init_wasm();
-init_lean();
-init_loader();
-init_factory();
+// src/ptr/node/PTREngine.ts
+var path15 = __toESM(require("path"), 1);
+var yaml3 = __toESM(require("yaml"), 1);
+init_MCard();
 
 // src/model/PCard.ts
 var import_yaml = require("yaml");
@@ -8912,8 +8879,8 @@ var PCard = class _PCard extends MCard {
         }
       }
     };
-    const { stringify: stringify2 } = await import("yaml");
-    return _PCard.create(stringify2(newClm), this.hashFunction);
+    const { stringify: stringify3 } = await import("yaml");
+    return _PCard.create(stringify3(newClm), this.hashFunction);
   }
   /**
    * Tensor Product ($A \otimes B$)
@@ -8940,8 +8907,8 @@ var PCard = class _PCard extends MCard {
         }
       }
     };
-    const { stringify: stringify2 } = await import("yaml");
-    return _PCard.create(stringify2(newClm), this.hashFunction);
+    const { stringify: stringify3 } = await import("yaml");
+    return _PCard.create(stringify3(newClm), this.hashFunction);
   }
   /**
    * Symmetry ($\sigma$)
@@ -8967,8 +8934,8 @@ var PCard = class _PCard extends MCard {
         }
       }
     };
-    const { stringify: stringify2 } = await import("yaml");
-    return _PCard.create(stringify2(newClm), this.hashFunction);
+    const { stringify: stringify3 } = await import("yaml");
+    return _PCard.create(stringify3(newClm), this.hashFunction);
   }
   // =========================================================================
   // Universal Tooling Interface
@@ -9172,6 +9139,70 @@ var PCard = class _PCard extends MCard {
     const runtimesConfig = config?.runtimes_config;
     return Array.isArray(runtimesConfig) && runtimesConfig.length > 1;
   }
+  // =========================================================================
+  // VCard Sandwich Boundary Spec Accessors
+  // =========================================================================
+  // Mirrors Python: PCard.get_pre_vcard_spec(), PCard.get_post_vcard_spec()
+  // =========================================================================
+  /**
+   * Get precondition specification for VCard Sandwich evaluation.
+   *
+   * Extracts the precondition spec from abstract.preconditions,
+   * classifying each condition by type.
+   *
+   * @returns Object with conditions array and classified conditions
+   */
+  getPreVCardSpec() {
+    const abstractSpec = this.abstract;
+    const preconditions = abstractSpec?.preconditions || [];
+    return {
+      conditions: preconditions,
+      classified: preconditions.map((c) => this.classifyCondition(c))
+    };
+  }
+  /**
+   * Get postcondition specification for VCard Sandwich evaluation.
+   *
+   * Extracts the postcondition spec from abstract.postconditions,
+   * classifying each condition by type.
+   *
+   * @returns Object with conditions array and classified conditions
+   */
+  getPostVCardSpec() {
+    const abstractSpec = this.abstract;
+    const postconditions = abstractSpec?.postconditions || [];
+    return {
+      conditions: postconditions,
+      classified: postconditions.map((c) => this.classifyCondition(c))
+    };
+  }
+  /**
+   * Classify a condition by its type (function, schema, capability, declarative).
+   *
+   * @param condition - The condition to classify
+   * @returns Object with type and the original condition
+   */
+  classifyCondition(condition) {
+    if (typeof condition === "string") {
+      return { type: "declarative", condition };
+    }
+    if (typeof condition === "object" && condition !== null) {
+      const cond = condition;
+      if (typeof cond.function === "string" || typeof cond.callable === "string") {
+        return { type: "function", condition };
+      }
+      if (cond.schema || cond.json_schema) {
+        return { type: "schema", condition };
+      }
+      if (typeof cond.capability === "string") {
+        return { type: "capability", condition };
+      }
+      if (cond.description) {
+        return { type: "declarative", condition };
+      }
+    }
+    return { type: "unknown", condition };
+  }
 };
 
 // src/model/VCard.ts
@@ -9567,6 +9598,127 @@ var VCard = class _VCard extends MCard {
     const myHandle = this.getTokenHandle();
     return myHandle === requiredHandle;
   }
+  // =========================================================================
+  // VCard Sandwich — Arrow Boundary Evaluation Pattern
+  // =========================================================================
+  //
+  // These static methods implement the formal VCard Sandwich lifecycle:
+  //   V_pre → PCard(Evaluation Map) → V_post → Sandwich(V_pre, V_post)
+  //
+  // Mirrors Python: VCard.witness_precondition(), witness_postcondition(), sandwich()
+  // =========================================================================
+  /**
+   * Witness Precondition (V_pre) — creates a VCard that witnesses
+   * the input was accepted for evaluation.
+   *
+   * @param inputMCard - The input MCard being evaluated
+   * @param hashAlgorithm - Hash algorithm to use
+   * @returns VCard with type "precondition-witness"
+   */
+  static async witnessPrecondition(inputMCard, hashAlgorithm = "sha256") {
+    const structure = {
+      vcard: {
+        type: "precondition-witness",
+        identity: {
+          subject_did: "did:ptr:system",
+          controller_pubkeys: []
+        },
+        verification: {
+          input_hash: inputMCard.hash,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          witness_type: "precondition"
+        },
+        gatekeeper: { capabilities: [] },
+        external_refs: []
+      }
+    };
+    const contentString = JSON.stringify(structure, null, 2);
+    const bytes = new TextEncoder().encode(contentString);
+    const hash = await HashValidator.computeHash(bytes, hashAlgorithm);
+    const g_time = GTime.stampNow(hashAlgorithm);
+    const contentType = ContentTypeInterpreter.detect(bytes);
+    return new _VCard(bytes, hash, g_time, contentType, hashAlgorithm, structure);
+  }
+  /**
+   * Witness Postcondition (V_post) — creates a VCard that witnesses
+   * the output was produced by a PCard evaluation.
+   *
+   * @param output - The execution output
+   * @param pcardHash - Hash of the PCard that produced the output
+   * @param hashAlgorithm - Hash algorithm to use
+   * @returns VCard with type "postcondition-witness"
+   */
+  static async witnessPostcondition(output, pcardHash, hashAlgorithm = "sha256") {
+    let outputRepr;
+    try {
+      outputRepr = typeof output === "string" ? output : JSON.stringify(output);
+    } catch {
+      outputRepr = String(output);
+    }
+    const outputHash = await HashValidator.computeHash(
+      new TextEncoder().encode(outputRepr),
+      hashAlgorithm
+    );
+    const structure = {
+      vcard: {
+        type: "postcondition-witness",
+        identity: {
+          subject_did: "did:ptr:system",
+          controller_pubkeys: []
+        },
+        verification: {
+          output_hash: outputHash,
+          pcard_hash: pcardHash || null,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          witness_type: "postcondition"
+        },
+        gatekeeper: { capabilities: [] },
+        external_refs: []
+      }
+    };
+    const contentString = JSON.stringify(structure, null, 2);
+    const bytes = new TextEncoder().encode(contentString);
+    const hash = await HashValidator.computeHash(bytes, hashAlgorithm);
+    const g_time = GTime.stampNow(hashAlgorithm);
+    const contentType = ContentTypeInterpreter.detect(bytes);
+    return new _VCard(bytes, hash, g_time, contentType, hashAlgorithm, structure);
+  }
+  /**
+   * Create a Sandwich Proof — combines V_pre and V_post into a
+   * composite verification proof.
+   *
+   * @param vPre - Precondition witness VCard
+   * @param vPost - Postcondition witness VCard
+   * @param pcardHash - Hash of the PCard that was evaluated
+   * @param hashAlgorithm - Hash algorithm to use
+   * @returns VCard with type "verification-sandwich"
+   */
+  static async sandwich(vPre, vPost, pcardHash, hashAlgorithm = "sha256") {
+    const structure = {
+      vcard: {
+        type: "verification-sandwich",
+        identity: {
+          subject_did: "did:ptr:system",
+          controller_pubkeys: []
+        },
+        verification: {
+          v_pre_hash: vPre.hash,
+          v_post_hash: vPost.hash,
+          pcard_hash: pcardHash || null,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          witness_type: "sandwich"
+        },
+        gatekeeper: { capabilities: [] },
+        external_refs: []
+      }
+    };
+    const contentString = JSON.stringify(structure, null, 2);
+    const bytes = new TextEncoder().encode(contentString);
+    const hash = await HashValidator.computeHash(bytes, hashAlgorithm);
+    const g_time = GTime.stampNow(hashAlgorithm);
+    const contentType = ContentTypeInterpreter.detect(bytes);
+    return new _VCard(bytes, hash, g_time, contentType, hashAlgorithm, structure);
+  }
 };
 var VCardSimulation = class {
   vcard;
@@ -9588,6 +9740,79 @@ var VCardSimulation = class {
   }
 };
 
+// src/ptr/node/clm/runner.ts
+var path14 = __toESM(require("path"), 1);
+var yaml2 = __toESM(require("yaml"), 1);
+init_constants();
+
+// src/ptr/node/runtimes/index.ts
+init_base();
+init_javascript();
+init_python();
+init_binary();
+init_wasm();
+init_lean();
+init_loader();
+init_factory();
+
+// src/ptr/node/clm/utils.ts
+function resultsEqual(a, b, tolerance = 1e-9) {
+  if (a === b) return true;
+  if (a == null || b == null) return false;
+  if (typeof a === "number" && typeof b === "number") {
+    if (Number.isNaN(a) && Number.isNaN(b)) return true;
+    if (!Number.isFinite(a) || !Number.isFinite(b)) return a === b;
+    return Math.abs(a - b) <= tolerance * Math.max(1, Math.abs(a), Math.abs(b));
+  }
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((val, i) => resultsEqual(val, b[i], tolerance));
+  }
+  if (typeof a === "object" && typeof b === "object") {
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length) return false;
+    return keysA.every(
+      (key) => keysB.includes(key) && resultsEqual(a[key], b[key], tolerance)
+    );
+  }
+  return a === b;
+}
+function asObject(input) {
+  return typeof input === "object" && input !== null ? input : {};
+}
+function buildBaseContext(clm, input) {
+  const inputObj = asObject(input);
+  return {
+    balanced: clm.clm.balanced,
+    input_arguments: clm.clm.concrete?.input_arguments,
+    output_arguments: clm.clm.concrete?.output_arguments,
+    params: inputObj,
+    ...inputObj
+  };
+}
+function buildExecutionResult(success, result, startTime, clm, error, boundary) {
+  return {
+    success,
+    result,
+    error,
+    executionTime: Date.now() - startTime,
+    clm: {
+      chapter: clm.chapter?.title || "Unknown",
+      concept: clm.clm.abstract?.concept || "Unknown",
+      manifestation: clm.clm.concrete?.manifestation || "Unknown",
+      boundary
+    }
+  };
+}
+function isRecursiveCLM(runtimeName) {
+  return runtimeName.endsWith(".clm") || runtimeName.endsWith(".yaml") || runtimeName.endsWith(".yml");
+}
+function isMultiRuntime(clm) {
+  const runtimesConfig = clm.clm?.concrete?.runtimes_config;
+  return Array.isArray(runtimesConfig) && runtimesConfig.length > 0;
+}
+
 // src/ptr/node/core/operations/index.ts
 var NETWORK_BUILTINS = /* @__PURE__ */ new Set([
   "http_get",
@@ -9935,7 +10160,7 @@ setInterval(() => {}, 1000);
       });
       child.unref();
       fs8.writeFileSync(pidFile, String(child.pid));
-      await new Promise((resolve10) => setTimeout(resolve10, STATIC_SERVER_START_WAIT_MS));
+      await new Promise((resolve11) => setTimeout(resolve11, STATIC_SERVER_START_WAIT_MS));
       if (isPortInUse(port)) {
         return {
           success: true,
@@ -9988,10 +10213,10 @@ setInterval(() => {}, 1000);
     }
     try {
       process.kill(pid, "SIGTERM");
-      await new Promise((resolve10) => setTimeout(resolve10, PROCESS_TERMINATE_WAIT_MS));
+      await new Promise((resolve11) => setTimeout(resolve11, PROCESS_TERMINATE_WAIT_MS));
       if (isPortInUse(port)) {
         process.kill(pid, "SIGKILL");
-        await new Promise((resolve10) => setTimeout(resolve10, PROCESS_TERMINATE_WAIT_MS));
+        await new Promise((resolve11) => setTimeout(resolve11, PROCESS_TERMINATE_WAIT_MS));
       }
       if (fs8.existsSync(pidFile)) {
         fs8.unlinkSync(pidFile);
@@ -10134,7 +10359,7 @@ Process exited with code ${code}
       } catch {
       }
       fs9.writeFileSync(pidFile, String(child.pid));
-      await new Promise((resolve10) => setTimeout(resolve10, WEBSOCKET_SERVER_START_WAIT_MS));
+      await new Promise((resolve11) => setTimeout(resolve11, WEBSOCKET_SERVER_START_WAIT_MS));
       if (isPortInUse2(port)) {
         console.log(`[WebSocket Server] Successfully started on port ${port}`);
         return {
@@ -10198,10 +10423,10 @@ Process exited with code ${code}
     }
     try {
       process.kill(pid, "SIGTERM");
-      await new Promise((resolve10) => setTimeout(resolve10, PROCESS_TERMINATE_WAIT_MS));
+      await new Promise((resolve11) => setTimeout(resolve11, PROCESS_TERMINATE_WAIT_MS));
       if (isPortInUse2(port)) {
         process.kill(pid, "SIGKILL");
-        await new Promise((resolve10) => setTimeout(resolve10, PROCESS_TERMINATE_WAIT_MS));
+        await new Promise((resolve11) => setTimeout(resolve11, PROCESS_TERMINATE_WAIT_MS));
       }
       if (fs9.existsSync(pidFile)) {
         fs9.unlinkSync(pidFile);
@@ -10923,6 +11148,250 @@ var CLMRunner = class _CLMRunner {
   }
 };
 
+// src/ptr/node/PTREngine.ts
+var PTREngine = class {
+  collection;
+  executionLog;
+  runner;
+  /**
+   * Initialize PTREngine.
+   *
+   * @param storageCollection - MCard collection for long-term knowledge (mcard_collection.db)
+   * @param executionLogCollection - MCard collection for execution traces (execution_log.db).
+   *   If not provided, traces are written to storageCollection.
+   * @param options - Additional configuration
+   */
+  constructor(storageCollection, executionLogCollection, options) {
+    this.collection = storageCollection;
+    this.executionLog = executionLogCollection || this.collection;
+    this.runner = new CLMRunner(
+      options?.basePath || process.cwd(),
+      options?.timeout,
+      this.collection,
+      this.executionLog
+    );
+  }
+  // =========================================================================
+  // ARROW INTERFACE — The canonical PTR execution primitives
+  // =========================================================================
+  /**
+   * The Arrow execution primitive — the entire PTR in one method.
+   *
+   * Implements the VCard Sandwich lifecycle:
+   *     V_pre → PCard(Evaluation Map) → V_post
+   *
+   * @param pcardHash - Hash of the PCard to execute
+   * @param inputHash - Hash of the input MCard
+   * @param preCheck - Optional callable to validate preconditions on input
+   * @param postCheck - Optional callable to validate postconditions on output
+   * @returns Tuple of [execution_output, vcard_sandwich]
+   * @throws PreconditionViolation if preCheck returns false
+   * @throws PostconditionViolation if postCheck returns false
+   */
+  async runWithSandwich(pcardHash, inputHash, preCheck, postCheck) {
+    const pcard = await this.collection.get(pcardHash);
+    if (!pcard) throw new Error(`PCard not found: ${pcardHash}`);
+    const inputMCard = await this.collection.get(inputHash);
+    if (!inputMCard) throw new Error(`Input MCard not found: ${inputHash}`);
+    if (preCheck && !preCheck(inputMCard)) {
+      throw new PreconditionViolation(pcardHash, inputHash);
+    }
+    const vPre = await VCard.witnessPrecondition(inputMCard);
+    const pcardObj = await PCard.create(
+      new TextDecoder().decode(pcard.content)
+    );
+    const clmSpec = {
+      chapter: { id: "runtime", title: "Runtime Execution" },
+      clm: pcardObj.clm
+    };
+    const result = await this.runner.executeCLM(
+      clmSpec,
+      process.cwd(),
+      inputMCard.getContentAsText()
+    );
+    const output = result.result;
+    if (postCheck && !postCheck(output)) {
+      throw new PostconditionViolation(
+        pcardHash,
+        typeof output === "string" ? output.substring(0, 64) : JSON.stringify(output).substring(0, 64)
+      );
+    }
+    const vPost = await VCard.witnessPostcondition(output, pcardHash);
+    const sandwich = await VCard.sandwich(vPre, vPost, pcardHash);
+    await this.recordToExecutionLog(sandwich);
+    return [output, sandwich];
+  }
+  /**
+   * Execute a CLM specification from a YAML file.
+   *
+   * Absorbs CLMRunner.runFile(), routing all file-based execution
+   * through the formal PTREngine lifecycle with VCard Sandwich generation.
+   *
+   * @param filePath - Path to the YAML file
+   * @param context - Execution context (inputs)
+   * @returns Execution report with VCard Sandwich proof hashes
+   */
+  async runFile(filePath, context) {
+    const loader = new CLMLoader(path15.dirname(filePath));
+    const clm = loader.load(filePath);
+    const chapterDir = path15.dirname(path15.resolve(filePath));
+    const clmContent = yaml3.stringify(clm);
+    const pcard = await PCard.create(clmContent);
+    if (this.collection) {
+      await this.collection.add(pcard);
+    }
+    const inputMCard = await MCard.create(JSON.stringify(context || {}));
+    const vPre = await VCard.witnessPrecondition(inputMCard);
+    const result = await this.runner.executeCLM(clm, chapterDir, context || {});
+    const vPost = await VCard.witnessPostcondition(result.result, pcard.hash);
+    const sandwich = await VCard.sandwich(vPre, vPost, pcard.hash);
+    let eventRecordHash = null;
+    try {
+      if (this.executionLog) {
+        await this.executionLog.add(sandwich);
+        eventRecordHash = sandwich.hash;
+      }
+    } catch (e) {
+      console.warn(`[PTREngine] Failed to store VCard Sandwich: ${e}`);
+    }
+    return {
+      status: result.success ? "success" : "failure",
+      result: result.result,
+      error: result.error,
+      chapter_id: clm.chapter?.id,
+      chapter_title: clm.chapter?.title,
+      event_record_hash: eventRecordHash,
+      v_pre_hash: vPre.hash,
+      v_post_hash: vPost.hash,
+      sandwich_hash: sandwich.hash
+    };
+  }
+  /**
+   * Arrow `arr` — lift a pure function into a PCard.
+   *
+   * Creates a PCard whose Concrete implementation is the given function.
+   *
+   * @param func - A pure function from string to string
+   * @param name - Human-readable name for the PCard
+   * @returns The created PCard (stored in collection)
+   */
+  async arr(func, name = "lifted") {
+    const funcSource = func.toString();
+    const clmYaml = yaml3.stringify({
+      chapter: { id: `arr_${name}`, title: `Lifted: ${name}` },
+      clm: {
+        abstract: {
+          purpose: `Lifted pure function: ${name}`,
+          inputs: { input: "any" },
+          outputs: { result: "any" },
+          preconditions: [],
+          postconditions: []
+        },
+        concrete: {
+          runtime: "javascript",
+          operation: `lifted_${name}`,
+          code: funcSource
+        },
+        balanced: { test_cases: [], expectations: {} }
+      }
+    });
+    const pcard = await PCard.create(clmYaml);
+    if (this.collection) {
+      await this.collection.add(pcard);
+    }
+    return pcard;
+  }
+  /**
+   * Arrow `>>>` — sequential composition of two PCards.
+   *
+   * Creates a new PCard representing pcardA >>> pcardB,
+   * where the output of A feeds into the input of B.
+   *
+   * @param pcardAHash - Hash of the first PCard (executed first)
+   * @param pcardBHash - Hash of the second PCard (executed second)
+   * @returns The composed PCard (stored in collection)
+   */
+  async compose(pcardAHash, pcardBHash) {
+    const clmYaml = yaml3.stringify({
+      chapter: {
+        id: `compose_${pcardAHash.substring(0, 8)}_${pcardBHash.substring(0, 8)}`,
+        title: "Sequential Composition (Arrow >>>)"
+      },
+      clm: {
+        abstract: {
+          type: "sequential_composition",
+          purpose: `Compose ${pcardAHash.substring(0, 16)} >>> ${pcardBHash.substring(0, 16)}`,
+          inputs: { input: "any" },
+          outputs: { result: "any" },
+          preconditions: [],
+          postconditions: []
+        },
+        concrete: {
+          runtime: "ptr",
+          operation: "compose_sequential",
+          steps: [pcardAHash, pcardBHash]
+        },
+        balanced: { test_cases: [], expectations: {} }
+      }
+    });
+    const pcard = await PCard.create(clmYaml);
+    if (this.collection) {
+      await this.collection.add(pcard);
+    }
+    return pcard;
+  }
+  /**
+   * Arrow `first` — operate on first element of a product.
+   *
+   * Creates a new PCard that applies the original PCard to the
+   * first element of a (A, C) pair while preserving C.
+   *
+   * @param pcardHash - Hash of the PCard to lift
+   * @returns The first-lifted PCard (stored in collection)
+   */
+  async first(pcardHash) {
+    const clmYaml = yaml3.stringify({
+      chapter: {
+        id: `first_${pcardHash.substring(0, 8)}`,
+        title: "Arrow First (Product Preservation)"
+      },
+      clm: {
+        abstract: {
+          type: "arrow_first",
+          purpose: `Apply ${pcardHash.substring(0, 16)} to first element, preserve second`,
+          inputs: { pair: "(A, C)" },
+          outputs: { result: "(B, C)" },
+          preconditions: [],
+          postconditions: []
+        },
+        concrete: {
+          runtime: "ptr",
+          operation: "apply_first",
+          target: pcardHash
+        },
+        balanced: { test_cases: [], expectations: {} }
+      }
+    });
+    const pcard = await PCard.create(clmYaml);
+    if (this.collection) {
+      await this.collection.add(pcard);
+    }
+    return pcard;
+  }
+  // =========================================================================
+  // Private Helpers
+  // =========================================================================
+  async recordToExecutionLog(sandwich) {
+    try {
+      if (this.executionLog) {
+        await this.executionLog.add(sandwich);
+      }
+    } catch (e) {
+      console.warn(`[PTREngine] Failed to record to execution log: ${e}`);
+    }
+  }
+};
+
 // src/model/hash/algorithms/LocalSHA256.ts
 async function computeHash(content) {
   let contentStr;
@@ -11160,6 +11629,9 @@ var validationRegistry = new ValidationRegistry();
   MCard,
   MCardStore,
   Maybe,
+  PTREngine,
+  PostconditionViolation,
+  PreconditionViolation,
   Reader,
   SandboxWorker,
   ServiceWorkerPTR,