mcard-js 2.1.47 → 2.1.49

package/dist/index.js

@@ -1,15 +1,15 @@
 import {
   FileIO_exports,
   Loader_exports
-} from "./chunk-MECEQNTO.js";
+} from "./chunk-VYDZR4ZD.js";
 import {
   LLMRuntime,
   chatMonad,
   promptMonad
-} from "./chunk-UEXPSC52.js";
+} from "./chunk-KVZYFZJ5.js";
 import {
   LLMConfig
-} from "./chunk-4OAJAFFP.js";
+} from "./chunk-OUW2SUGM.js";
 import {
   NETWORK_DEFAULT_HOST,
   PROCESS_TERMINATE_WAIT_MS,
@@ -61,12 +61,14 @@ import {
   storeTerm,
   termExists,
   termToMCard
-} from "./chunk-76T7FWZ6.js";
+} from "./chunk-QKH3N62B.js";
 import {
   ErrorCodes,
   FaroSidecar,
   LensProtocol,
   MCardStore,
+  PostconditionViolation,
+  PreconditionViolation,
   Reader,
   ServiceWorkerPTR,
   State,
@@ -75,10 +77,10 @@ import {
   Writer,
   computeHash,
   validationRegistry
-} from "./chunk-SP4YPKPR.js";
+} from "./chunk-XJZOEM5F.js";
 import {
   IndexedDBEngine
-} from "./chunk-GQZKMXGA.js";
+} from "./chunk-NGTY4P6A.js";
 import {
   IO
 } from "./chunk-MPMRBT5R.js";
@@ -87,11 +89,11 @@ import {
 } from "./chunk-2KADE3SE.js";
 import {
   SqliteNodeEngine
-} from "./chunk-AOTXYFW2.js";
+} from "./chunk-Z7EFXSTO.js";
 import {
   SqliteWasmEngine
-} from "./chunk-UFSXA5QB.js";
-import "./chunk-FPW33LMV.js";
+} from "./chunk-7AXRV7NS.js";
+import "./chunk-HIVVDGE5.js";
 import "./chunk-3EIBJPNF.js";
 import {
   ContentHandle,
@@ -106,21 +108,21 @@ import {
 import {
   CardCollection,
   Maybe
-} from "./chunk-Q7EHSN3K.js";
+} from "./chunk-QPVEUPMU.js";
 import {
   DEFAULT_CLM_TIMEOUT_MS,
   DEFAULT_SANDBOX_TIMEOUT_MS
-} from "./chunk-J3IDWMDN.js";
+} from "./chunk-3FFEA2XK.js";
 import {
   ContentTypeInterpreter,
   MCard,
   createPCardDOTSMetadata,
   createVCardDOTSMetadata
-} from "./chunk-2NFGZ6PA.js";
+} from "./chunk-GGQCF7ZK.js";
 import {
   GTime,
   HashValidator
-} from "./chunk-7NKII2JA.js";
+} from "./chunk-ASW6AOA7.js";
 import {
   __export
 } from "./chunk-PNKVD2UK.js";
@@ -161,7 +163,7 @@ var ENGINE_INFO = {
 async function createEngine(type, options = {}) {
   switch (type) {
     case "indexeddb" /* INDEXED_DB */: {
-      const { IndexedDBEngine: IndexedDBEngine2 } = await import("./IndexedDBEngine-SYJHHDQM.js");
+      const { IndexedDBEngine: IndexedDBEngine2 } = await import("./IndexedDBEngine-BWXAB46W.js");
       const engine = new IndexedDBEngine2();
       await engine.init();
       return engine;
@@ -410,12 +412,12 @@ var SandboxWorker = class {
    * Send request and wait for response
    */
   sendRequest(request) {
-    return new Promise((resolve4, reject) => {
+    return new Promise((resolve5, 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: resolve4, reject, timeout });
+      this.pendingRequests.set(request.id, { resolve: resolve5, reject, timeout });
       this.worker.postMessage(request);
     });
   }
@@ -516,67 +518,9 @@ __export(lambda_exports, {
   termToMCard: () => termToMCard
 });
 
-// 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
-import * as path5 from "path";
-import * as yaml2 from "yaml";
+// src/ptr/node/PTREngine.ts
+import * as path6 from "path";
+import * as yaml3 from "yaml";
 
 // src/model/PCard.ts
 import { parse } from "yaml";
@@ -771,8 +715,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$)
@@ -799,8 +743,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$)
@@ -826,8 +770,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
@@ -1031,6 +975,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
@@ -1421,6 +1429,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;
@@ -1442,6 +1571,68 @@ var VCardSimulation = class {
   }
 };
 
+// src/ptr/node/clm/runner.ts
+import * as path5 from "path";
+import * as yaml2 from "yaml";
+
+// 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",
@@ -1557,8 +1748,8 @@ async function runVersionExamples(examples) {
 }
 async function executeVersionSingle(handle, versions) {
   const { SqliteNodeEngine: SqliteNodeEngine2 } = await import("./storage/SqliteNodeEngine.js");
-  const { CardCollection: CardCollection2 } = await import("./CardCollection-QY5VDVEL.js");
-  const { MCard: MCard2 } = await import("./MCard-XHG3BZC7.js");
+  const { CardCollection: CardCollection2 } = await import("./CardCollection-ZQ3G3Q3A.js");
+  const { MCard: MCard2 } = await import("./MCard-RHTWJPHJ.js");
   const engine = await SqliteNodeEngine2.create(":memory:");
   const collection = new CardCollection2(engine);
   try {
@@ -1618,8 +1809,8 @@ async function runPruneExamples(examples) {
 }
 async function executePruneSingle(handle, versions, pruneType, olderThanSeconds) {
   const { SqliteNodeEngine: SqliteNodeEngine2 } = await import("./storage/SqliteNodeEngine.js");
-  const { CardCollection: CardCollection2 } = await import("./CardCollection-QY5VDVEL.js");
-  const { MCard: MCard2 } = await import("./MCard-XHG3BZC7.js");
+  const { CardCollection: CardCollection2 } = await import("./CardCollection-ZQ3G3Q3A.js");
+  const { MCard: MCard2 } = await import("./MCard-RHTWJPHJ.js");
   const engine = await SqliteNodeEngine2.create(":memory:");
   const collection = new CardCollection2(engine);
   try {
@@ -1788,7 +1979,7 @@ setInterval(() => {}, 1000);
       });
       child.unref();
       fs.writeFileSync(pidFile, String(child.pid));
-      await new Promise((resolve4) => setTimeout(resolve4, STATIC_SERVER_START_WAIT_MS));
+      await new Promise((resolve5) => setTimeout(resolve5, STATIC_SERVER_START_WAIT_MS));
       if (isPortInUse(port)) {
         return {
           success: true,
@@ -1841,10 +2032,10 @@ setInterval(() => {}, 1000);
     }
     try {
       process.kill(pid, "SIGTERM");
-      await new Promise((resolve4) => setTimeout(resolve4, PROCESS_TERMINATE_WAIT_MS));
+      await new Promise((resolve5) => setTimeout(resolve5, PROCESS_TERMINATE_WAIT_MS));
       if (isPortInUse(port)) {
         process.kill(pid, "SIGKILL");
-        await new Promise((resolve4) => setTimeout(resolve4, PROCESS_TERMINATE_WAIT_MS));
+        await new Promise((resolve5) => setTimeout(resolve5, PROCESS_TERMINATE_WAIT_MS));
       }
       if (fs.existsSync(pidFile)) {
         fs.unlinkSync(pidFile);
@@ -1986,7 +2177,7 @@ Process exited with code ${code}
       } catch {
       }
       fs2.writeFileSync(pidFile, String(child.pid));
-      await new Promise((resolve4) => setTimeout(resolve4, WEBSOCKET_SERVER_START_WAIT_MS));
+      await new Promise((resolve5) => setTimeout(resolve5, WEBSOCKET_SERVER_START_WAIT_MS));
       if (isPortInUse2(port)) {
         console.log(`[WebSocket Server] Successfully started on port ${port}`);
         return {
@@ -2050,10 +2241,10 @@ Process exited with code ${code}
     }
     try {
       process.kill(pid, "SIGTERM");
-      await new Promise((resolve4) => setTimeout(resolve4, PROCESS_TERMINATE_WAIT_MS));
+      await new Promise((resolve5) => setTimeout(resolve5, PROCESS_TERMINATE_WAIT_MS));
       if (isPortInUse2(port)) {
         process.kill(pid, "SIGKILL");
-        await new Promise((resolve4) => setTimeout(resolve4, PROCESS_TERMINATE_WAIT_MS));
+        await new Promise((resolve5) => setTimeout(resolve5, PROCESS_TERMINATE_WAIT_MS));
       }
       if (fs2.existsSync(pidFile)) {
         fs2.unlinkSync(pidFile);
@@ -2382,10 +2573,12 @@ var CLMRunner = class _CLMRunner {
   loader;
   timeout;
   collection;
-  constructor(basePath = process.cwd(), timeout = DEFAULT_CLM_TIMEOUT_MS, collection) {
+  privateCollection;
+  constructor(basePath = process.cwd(), timeout = DEFAULT_CLM_TIMEOUT_MS, collection, privateCollection) {
     this.loader = new CLMLoader(basePath);
     this.timeout = timeout;
     this.collection = collection;
+    this.privateCollection = privateCollection;
   }
   /**
    * Run a CLM directly from a file path.
@@ -2496,7 +2689,8 @@ var CLMRunner = class _CLMRunner {
           previousVCard,
           result.success
         );
-        await this.collection.add(vcard);
+        const storageTarget = this.privateCollection || this.collection;
+        await storageTarget.add(vcard);
         result.petriNet = {
           pcardHash: pcard.hash,
           vcardHash: vcard.hash,
@@ -2771,6 +2965,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(path6.dirname(filePath));
+    const clm = loader.load(filePath);
+    const chapterDir = path6.dirname(path6.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}`);
+    }
+  }
+};
 export {
   ALGORITHM_HIERARCHY,
   CLMRunner,
@@ -2798,6 +3236,9 @@ export {
   MCard,
   MCardStore,
   Maybe,
+  PTREngine,
+  PostconditionViolation,
+  PreconditionViolation,
   Reader,
   SandboxWorker,
   ServiceWorkerPTR,