mcard-js 2.1.47 → 2.1.49

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { S as StorageEngine, M as MCard } from './AbstractSqlEngine-BSfp8S_Y.cjs';
-export { P as Page } from './AbstractSqlEngine-BSfp8S_Y.cjs';
+import { S as StorageEngine, M as MCard, D as DOTSMetadata } from './AbstractSqlEngine-DKka6XjT.cjs';
+export { P as Page } from './AbstractSqlEngine-DKka6XjT.cjs';
 import { CardCollection, Either, IO, Maybe } from './index.browser.cjs';
-export { ALGORITHM_HIERARCHY, ContentHandle, ContentTypeInterpreter, EVENT_CONSTANTS, ErrorCodes, ExecutionResult, FaroSidecar, FaroSidecarConfig, GTime, HandleValidationError, HashValidator, IndexedDBEngine, JsonRpcRequest, JsonRpcResponse, LensProtocol, LivenessMetric, MCardStore, PolynomialTerm, PrimeHash, Reader, SafetyViolation, ServiceWorkerPTR, State, ValidationRegistry, VerificationStatus, Writer, computeHash, validateHandle, validationRegistry } from './index.browser.cjs';
+export { ALGORITHM_HIERARCHY, ContentHandle, ContentTypeInterpreter, EVENT_CONSTANTS, ErrorCodes, ExecutionResult, FaroSidecar, FaroSidecarConfig, GTime, HandleValidationError, HashValidator, IndexedDBEngine, JsonRpcRequest, JsonRpcResponse, LensProtocol, LivenessMetric, MCardStore, PolynomialTerm, PostconditionViolation, PreconditionViolation, PrimeHash, Reader, SafetyViolation, ServiceWorkerPTR, State, ValidationRegistry, VerificationStatus, Writer, computeHash, validateHandle, validationRegistry } from './index.browser.cjs';
 export { SqliteWasmEngine } from './storage/SqliteWasmEngine.cjs';
 export { SqliteNodeEngine } from './storage/SqliteNodeEngine.cjs';
 import '@grafana/faro-web-sdk';
@@ -898,6 +898,725 @@ declare namespace index {
   export { type index_AbsTerm as AbsTerm, type index_AppTerm as AppTerm, type index_LambdaConfig as LambdaConfig, type index_LambdaOperation as LambdaOperation, index_LambdaRuntime as LambdaRuntime, type index_LambdaRuntimeResult as LambdaRuntimeResult, type index_LambdaTerm as LambdaTerm, type index_NormalizationResult as NormalizationResult, type index_ReductionStrategy as ReductionStrategy, type index_VarTerm as VarTerm, index_alphaEquivalent as alphaEquivalent, index_alphaNormalize as alphaNormalize, index_alphaRename as alphaRename, index_betaReduce as betaReduce, index_boundVariables as boundVariables, index_deserializeTerm as deserializeTerm, index_difference as difference, index_etaEquivalent as etaEquivalent, index_etaExpand as etaExpand, index_etaNormalize as etaNormalize, index_etaReduce as etaReduce, index_etaReduceE as etaReduceE, index_findEtaRedexes as findEtaRedexes, index_findInnermostRedex as findInnermostRedex, index_findLeftmostRedex as findLeftmostRedex, index_freeVariables as freeVariables, index_generateFresh as generateFresh, index_generateFreshFor as generateFreshFor, index_hasNormalForm as hasNormalForm, index_intersection as intersection, index_isAbs as isAbs, index_isApp as isApp, index_isClosed as isClosed, index_isEtaRedex as isEtaRedex, index_isFreeIn as isFreeIn, index_isNormalForm as isNormalForm, index_isRedex as isRedex, index_isVar as isVar, index_loadTerm as loadTerm, index_mcardToTerm as mcardToTerm, index_mkAbs as mkAbs, index_mkApp as mkApp, index_mkVar as mkVar, index_normalize as normalize, index_parseLambdaExpression as parseLambdaExpression, index_prettyPrintDeep as prettyPrintDeep, index_prettyPrintShallow as prettyPrintShallow, index_reduceStep as reduceStep, index_serializeTerm as serializeTerm, index_storeTerm as storeTerm, index_termExists as termExists, index_termToMCard as termToMCard };
 }
 
+/**
+ * PCard Model (Control Plane) - Petri Net TRANSITION
+ *
+ * This module defines PCard, the execution unit in the MVP Cards architecture.
+ * PCards are MCards containing a valid CLM (Cubical Logic Model) specification.
+ *
+ * ## Categorical Foundation: STRONG PROFUNCTOR
+ *
+ * PCard implements the Strong Profunctor pattern from category theory:
+ *
+ *     P: A^op × B → Set
+ *
+ * Where:
+ *   - A^op denotes contravariance in input types (accepts MORE general)
+ *   - B denotes covariance in output types (produces MORE specific)
+ *   - Set is the category of sets (our value space)
+ *
+ * The "Strong" property means PCard supports:
+ *   - first:  P(A, B) → P(C × A, C × B)  (threading context through)
+ *   - second: P(A, B) → P(A × C, B × C)  (preserving additional structure)
+ *
+ * ## Composition via Coend
+ *
+ * Two PCards compose via the Coend (categorical integral):
+ *
+ *     (P ⨾ Q)(A, C) = ∫ᴮ P(A, B) × Q(B, C)
+ *
+ * Where:
+ *   - ∫ᴮ is the Coend over the intermediate type B
+ *   - P(A, B) is the first PCard (input A, output B)
+ *   - Q(B, C) is the second PCard (input B, output C)
+ *   - Result is a new PCard from A to C
+ *
+ * The `andThen()` method implements this Coend composition.
+ *
+ * ## SMC Structure (Symmetric Monoidal Category)
+ *
+ * PCard composition forms a Symmetric Monoidal Category:
+ *   - **Identity**: The "pass-through" PCard
+ *   - **Composition**: Sequential chaining via `andThen()` (;)
+ *   - **Tensor Product**: Parallel composition via `andAlso()` (⊗)
+ *   - **Symmetry**: Port swapping via `swap()` (σ)
+ *
+ * ## Functor Role in MVP Cards Hierarchy
+ *
+ * PCard is the **Functor** in the categorical hierarchy:
+ *   - **MCard (Monad)**: Data container
+ *   - **PCard (Functor)**: Pure transformation `fmap :: (a -> b) -> F a -> F b`
+ *   - **VCard (Applicative)**: Context-aware application
+ *
+ * ## Petri Net Role: TRANSITION
+ *
+ * In the Categorical Petri Net model, PCard is the **Transition**:
+ *   - Consumes input VCards (Tokens) from input Places
+ *   - Executes CLM logic (Abstract → Concrete transformation)
+ *   - Produces output VCards (Tokens) for output Places
+ *
+ * ### The Firing Rule
+ *
+ *     M' = M - •t + t•
+ *
+ * Where:
+ *   - M = Current marking (token distribution)
+ *   - •t = Pre-set (input VCards required)
+ *   - t• = Post-set (output VCards produced)
+ *
+ * ## CLM Triad: Abstract, Concrete, Balanced
+ *
+ * PCard content encodes the three dimensions:
+ *   - **Abstract (A)**: WHY - Specification, intent, type signature
+ *   - **Concrete (C)**: HOW - Implementation, runtime logic
+ *   - **Balanced (B)**: WHAT - Tests, verification expectations
+ *
+ * ## DOTS Vocabulary Role: LENS + CHART
+ *
+ *   - **Lens**: Tight morphism (Abstract ↔ Concrete coherence)
+ *   - **Chart**: Loose morphism (Balanced expectations wiring)
+ *
+ * @see docs/PCard_Impl.md for full implementation specification
+ */
+
+type ClmObject = Record<string, unknown>;
+/**
+ * Input VCard reference for Petri Net pre-condition
+ */
+interface InputVCardRef {
+    /** Handle name (Place) where precondition VCard must exist */
+    handle: string;
+    /** Expected VCard hash (optional, for strict matching) */
+    expectedHash?: string;
+    /** Purpose of this precondition (e.g., 'authenticate', 'authorize') */
+    purpose?: string;
+}
+/**
+ * Output VCard specification for Petri Net post-condition
+ */
+interface OutputVCardSpec {
+    /** Handle name (Place) where output VCard will be deposited */
+    handle: string;
+    /** Type of VCard to generate */
+    type: 'verification' | 'authorization' | 'audit' | 'result';
+    /** Additional metadata to include in the VCard */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * PCard - The Control Plane unit (Petri Net Transition)
+ *
+ * A PCard is an MCard whose content is a valid CLM specification.
+ * It represents a transformation (Lens) with a specific interaction pattern (Chart).
+ */
+declare class PCard extends MCard {
+    private readonly parsedClm;
+    private readonly isLens;
+    protected constructor(content: Uint8Array, hash: string, g_time: string, contentType: string, hashFunction: string, parsedClm: ClmObject, isLens: boolean);
+    /**
+     * Create a new PCard from CLM content
+     *
+     * @param content - The CLM YAML string or bytes
+     * @param hashAlgorithm - Hash algorithm to use
+     * @param isLens - Whether this acts primarily as a Lens (default true)
+     */
+    static create(content: string | Uint8Array, hashAlgorithm?: string, isLens?: boolean): Promise<PCard>;
+    /**
+     * Get DOTS vocabulary metadata for this PCard
+     *
+     * Automatically extracts dependencies from the CLM structure if available.
+     */
+    getDOTSMetadata(): DOTSMetadata;
+    /**
+     * Get the parsed CLM object
+     */
+    get clm(): ClmObject;
+    private getSection;
+    /**
+     * Get the Abstract Specification section (UPTV Role: Abstract)
+     */
+    get abstract(): unknown;
+    /**
+     * Get the Concrete Implementation section (UPTV Role: Concrete)
+     */
+    get concrete(): unknown;
+    /**
+     * Get the Balanced Expectations (tests) section (UPTV Role: Balanced)
+     */
+    get balanced(): unknown;
+    /**
+     * Get the Abstract Specification section (Legacy)
+     */
+    get abstractSpec(): unknown;
+    /**
+     * Get the Concrete Implementation section (Legacy)
+     */
+    get concreteImpl(): unknown;
+    /**
+     * Get the Balanced Expectations (tests) section (Legacy)
+     */
+    get balancedExpectations(): unknown;
+    /**
+     * Sequential Composition via Coend (P ⨾ Q)
+     *
+     * Implements profunctor composition using the Coend formula:
+     *
+     *     (P ⨾ Q)(A, C) = ∫ᴮ P(A, B) × Q(B, C)
+     *
+     * Where:
+     *   - this is P: A → B
+     *   - otherPCard is Q: B → C
+     *   - Result is P ⨾ Q: A → C
+     *
+     * The Coend (∫ᴮ) "integrates out" the intermediate type B by:
+     * 1. Matching P's output type with Q's input type
+     * 2. Creating a chain where P's result feeds into Q
+     * 3. The composition is associative: (P ⨾ Q) ⨾ R = P ⨾ (Q ⨾ R)
+     *
+     * In PTR execution:
+     *   - P is executed first (prep → exec → post)
+     *   - P's output VCard becomes Q's input VCard
+     *   - Q is executed second
+     *   - Final result is Q's output VCard
+     *
+     * Note: Named 'andThen' to avoid conflict with Promise.then (Thenable).
+     *
+     * @param otherPCard - The PCard to execute after this one (Q in P ⨾ Q)
+     * @returns A new PCard representing the composed profunctor (P ⨾ Q)
+     */
+    andThen(otherPCard: PCard): Promise<PCard>;
+    /**
+     * Tensor Product ($A \otimes B$)
+     *
+     * Runs this PCard and otherPCard in parallel.
+     */
+    andAlso(otherPCard: PCard): Promise<PCard>;
+    /**
+     * Symmetry ($\sigma$)
+     *
+     * Swaps the input/output ports of a tensor product.
+     */
+    swap(): Promise<PCard>;
+    /**
+     * Run the Balanced Expectations (Proof)
+     */
+    verify(): Record<string, unknown>;
+    /**
+     * Run with instrumentation (eBPF/Tracing)
+     */
+    profile(): Record<string, unknown>;
+    /**
+     * Run in Operative mode (Step-by-step)
+     */
+    debug(): Record<string, unknown>;
+    /**
+     * Return documentation/explanation
+     */
+    explain(): Record<string, unknown>;
+    /**
+     * Get input VCard references (Pre-set: •t)
+     *
+     * These represent the preconditions that must be satisfied before
+     * this PCard (Transition) can fire.
+     *
+     * @returns Array of input VCard references from CLM specification
+     */
+    getInputVCardRefs(): InputVCardRef[];
+    /**
+     * Get output VCard specifications (Post-set: t•)
+     *
+     * These define what VCards (Tokens) this PCard produces when fired.
+     *
+     * @returns Array of output VCard specifications
+     */
+    getOutputVCardSpecs(): OutputVCardSpec[];
+    /**
+     * Get the canonical handle for this PCard (Transition)
+     *
+     * @returns Handle string in form `clm://{module}/{function}/spec`
+     */
+    getTransitionHandle(): string;
+    /**
+     * Get the balanced expectations handle for this PCard
+     *
+     * This is where verification history is tracked in handle_history.
+     *
+     * @returns Handle string for balanced expectations
+     */
+    getBalancedHandle(): string;
+    /**
+     * Check if this PCard (Transition) can fire given the available VCards
+     *
+     * A transition can fire when all input VCards (preconditions) are present.
+     *
+     * @param availableVCards - Map of handle → VCard hash
+     * @returns Object with canFire boolean and missing preconditions
+     */
+    canFire(availableVCards: Map<string, string>): {
+        canFire: boolean;
+        missing: string[];
+    };
+    /**
+     * Get the runtime required for this PCard
+     *
+     * @returns Runtime name (e.g., 'javascript', 'python', 'lean')
+     */
+    getRuntime(): string;
+    /**
+     * Check if this is a multi-runtime PCard
+     *
+     * @returns True if this PCard supports multiple runtimes
+     */
+    isMultiRuntime(): boolean;
+    /**
+     * 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(): {
+        conditions: unknown[];
+        classified: {
+            type: string;
+            condition: unknown;
+        }[];
+    };
+    /**
+     * 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(): {
+        conditions: unknown[];
+        classified: {
+            type: string;
+            condition: unknown;
+        }[];
+    };
+    /**
+     * Classify a condition by its type (function, schema, capability, declarative).
+     *
+     * @param condition - The condition to classify
+     * @returns Object with type and the original condition
+     */
+    private classifyCondition;
+}
+
+/**
+ * VCard Model (Application Plane) - Petri Net TOKEN / PRE-CONDITION CARRIER
+ *
+ * This module defines VCard, the sovereign decision layer in the MVP Cards architecture.
+ * VCard is the Applicative that manages all side effects and authorization.
+ *
+ * ## Category Theory Role: APPLICATIVE
+ *
+ * VCard is the **Applicative** in the MVP Cards categorical hierarchy:
+ * - **MCard (Monad)**: Data container with unit and bind
+ * - **PCard (Functor)**: Pure transformation
+ * - **VCard (Applicative)**: Context-aware application `<*> :: F (a -> b) -> F a -> F b`
+ *
+ * The Applicative nature means VCard can encode **static pre-conditions**:
+ * the authorization graph is known ahead of time, while actual execution
+ * depends on runtime results.
+ *
+ * ## Petri Net Role: TOKEN + PRE-CONDITION
+ *
+ * In the Categorical Petri Net model, VCard serves dual roles:
+ *
+ * ### As Token
+ * - VCard is the **Token** that resides in Places (Handles)
+ * - Tokens enable Transitions (PCards) to fire
+ * - Token movement represents verification cascade
+ *
+ * ### As Pre-Condition (Firing Guard)
+ * A Petri Net transition fires when all input VCards exist:
+ *
+ * ```
+ * M' = M - •t + t•
+ * ```
+ *
+ * VCard as Input Arc encodes:
+ * - **Input Place**: Handle pointing to required VCard
+ * - **Token in Place**: VCard content in `card` table
+ * - **Arc Guard**: VCard's Applicative authorization check
+ * - **Token "Consumption"**: Recording `previous_hash` in new VCard
+ *
+ * ### Hash as Token AND Certificate (Dual Role)
+ *
+ * | Role | Function | Implementation |
+ * |------|----------|----------------|
+ * | **Token** | Triggers firing (enables transitions) | `handle_registry.current_hash IS NOT NULL` |
+ * | **Certificate** | Proves correctness after verification | VCard content witnesses Hoare Triple |
+ *
+ * ```
+ * {h_pre} PCard {h_post}
+ * ```
+ *
+ * Where:
+ * - h_pre = hash of input VCard (precondition satisfied)
+ * - PCard = CLM specification (transformation logic)
+ * - h_post = hash of output VCard (postcondition witnessed)
+ *
+ * ## Cascade Pattern: Propagating Verification
+ *
+ * VCards enable **verification cascades** across the network:
+ *
+ * ```
+ * T1 → V1 → T2 → V2 → T3 → ... → Vn
+ * ```
+ *
+ * Each VerificationVCard (Vi) serves as:
+ * 1. **Post-condition** of transition Ti (what it produces)
+ * 2. **Pre-condition** of transition Ti+1 (what enables next step)
+ *
+ * ## DOTS Vocabulary Role: ARENA + ACTION
+ *
+ * VCard is both:
+ * - **Arena**: Interface type defining what can interact (subject_did, capabilities, external_refs)
+ * - **Action**: Morphism where interactions (PCards) act on systems (MCards)
+ *
+ * ## The Four Roles:
+ * 1. Identity & Credential Container (The "Who")
+ * 2. Verification Hub (The "Rules")
+ * 3. Side Effect Manager (The "Bridge")
+ * 4. Input/Output Gatekeeper (The "Gate")
+ *
+ * ## VCard as Egress Gate: The Sovereign Boundary
+ *
+ * When a VerificationVCard is produced, it may also serve as **egress authorization**:
+ *
+ * | Egress Role | VCard Content | Enables |
+ * |-------------|--------------|---------|
+ * | Export Authorization | `egress_capability: { destination_did, scope }` | Sharing to specific PKCs |
+ * | Cross-PKC Transition | `transferable: true` | Token moves to destination's Petri Net |
+ * | Federation Trigger | Signed VCard bundle | Downstream PKC's transitions enabled |
+ *
+ * @see docs/VCard_Impl.md for full implementation specification
+ */
+
+/**
+ * Scope of a capability token.
+ */
+declare enum CapabilityScope {
+    READ = "read",
+    WRITE = "write",
+    EXECUTE = "execute",
+    ADMIN = "admin",
+    DELEGATE = "delegate"
+}
+/**
+ * Direction of gatekeeper authorization.
+ */
+declare enum GatekeeperDirection {
+    INGRESS = "ingress",
+    EGRESS = "egress"
+}
+/**
+ * A capability token defining authorized actions.
+ */
+interface Capability {
+    capabilityId: string;
+    actorDid: string;
+    scope: CapabilityScope;
+    resourcePattern: string;
+    expiresAt?: Date;
+    constraints?: Record<string, unknown>;
+    transferable: boolean;
+}
+/**
+ * A verified external reference managed by VCard.
+ */
+interface ExternalRef {
+    uri: string;
+    contentHash: string;
+    status: 'verified' | 'pending' | 'stale' | 'invalid';
+    signature?: string;
+    lastVerified?: Date;
+    qosMetrics?: Record<string, unknown>;
+}
+type ParsedVCardContent = Record<string, unknown>;
+type SimulationLogEntry = {
+    timestamp: Date;
+    effectType: string;
+    details: unknown;
+    simulated: true;
+};
+/**
+ * An ingress or egress gatekeeper event.
+ */
+interface GatekeeperEvent {
+    direction: GatekeeperDirection;
+    timestamp: Date;
+    sourceDid?: string;
+    destinationDid?: string;
+    contentHash: string;
+    authorized: boolean;
+    capabilityUsed?: string;
+    signature?: string;
+}
+/**
+ * VCard - The Application Plane unit (Petri Net Token)
+ *
+ * Implements the Empty Schema Principle: VCard IS an MCard.
+ * This class provides a view and runtime state management over the immutable content.
+ *
+ * In Petri Net terms:
+ * - VCard is a **Token** that resides in a **Place** (Handle)
+ * - VCard enables **Transitions** (PCards) to fire when present
+ * - VCard serves as both **Pre-condition** (what enables) and **Post-condition** (what is produced)
+ */
+declare class VCard extends MCard {
+    private _subjectDid;
+    private _controllerPubkeys;
+    private _capabilities;
+    private _externalRefs;
+    private _exportManifest;
+    private _gatekeeperLog;
+    private _pcardRefsHashes;
+    protected constructor(content: Uint8Array, hash: string, g_time: string, contentType: string, hashFunction: string, initialData: ParsedVCardContent);
+    private _initializeMutableState;
+    /**
+     * Create a new VCard from parameters.
+     * Follows strict UPTV structure { vcard: { ... } }.
+     */
+    static createVCard(subjectDid: string, controllerPubkeys: string[], capabilities?: Capability[], externalRefs?: ExternalRef[], hashAlgorithm?: string): Promise<VCard>;
+    /**
+     * Create a VCard wrapper from an existing MCard.
+     */
+    static fromMCard(card: MCard): Promise<VCard>;
+    getDOTSMetadata(): DOTSMetadata;
+    get subjectDid(): string;
+    get controllerPubkeys(): string[];
+    get capabilities(): Capability[];
+    get externalRefs(): ExternalRef[];
+    addCapability(capability: Capability): void;
+    getValidCapabilities(): Capability[];
+    hasCapability(scope: CapabilityScope, resourceHash: string): boolean;
+    addPCardReference(pcardHash: string): void;
+    getPCardReferences(): string[];
+    addExternalRef(ref: ExternalRef): void;
+    getExternalRefsByStatus(status: ExternalRef['status']): ExternalRef[];
+    verifyExternalRef(uri: string, newHash: string): boolean;
+    authorizeIngress(sourceDid: string, contentHash: string, capabilityId?: string): boolean;
+    registerForEgress(contentHash: string): boolean;
+    authorizeEgress(destinationDid: string, contentHash: string, capabilityId?: string): boolean;
+    private _logEgress;
+    getGatekeeperLog(direction?: GatekeeperDirection): GatekeeperEvent[];
+    getExportManifest(): string[];
+    simulateMode(): VCardSimulation;
+    /**
+     * Get the handle where this VCard token currently resides
+     *
+     * In Petri Net terms, this is the "Place" where the token is located.
+     *
+     * @returns Handle string if available in content, or hash-based handle
+     */
+    getTokenHandle(): string;
+    /**
+     * Check if this VCard is a VerificationVCard (result of PCard execution)
+     *
+     * VerificationVCards are produced by PCard transitions and contain
+     * execution results with provenance chain.
+     *
+     * @returns True if this is a verification token
+     */
+    isVerificationVCard(): boolean;
+    /**
+     * Get the previous hash in the provenance chain
+     *
+     * In Petri Net terms, this links to the input VCard that was "consumed"
+     * when the transition fired to produce this VCard.
+     *
+     * @returns Previous VCard hash if this is part of a verification cascade
+     */
+    getPreviousHash(): string | undefined;
+    /**
+     * Get the PCard hash that produced this VCard (if verification)
+     *
+     * This links the output token to the transition that created it.
+     *
+     * @returns PCard hash that produced this VCard
+     */
+    getSourcePCardHash(): string | undefined;
+    /**
+     * Create a VerificationVCard from PCard execution result
+     *
+     * This is the factory method for producing output tokens in the Petri Net.
+     *
+     * @param pcard - The PCard (Transition) that executed
+     * @param result - Execution result
+     * @param previousVCard - Input VCard (pre-condition) if any
+     * @param success - Whether execution succeeded
+     * @returns New VerificationVCard
+     */
+    static createVerificationVCard(pcard: {
+        hash: string;
+        getTransitionHandle?: () => string;
+        getBalancedHandle?: () => string;
+    }, result: unknown, previousVCard?: VCard, success?: boolean, hashAlgorithm?: string): Promise<VCard>;
+    /**
+     * Check if this VCard enables a specific PCard to fire
+     *
+     * @param requiredHandle - The handle where a precondition VCard must exist
+     * @returns True if this VCard satisfies that precondition
+     */
+    enablesTransition(requiredHandle: string): boolean;
+    /**
+     * 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 witnessPrecondition(inputMCard: MCard, hashAlgorithm?: string): Promise<VCard>;
+    /**
+     * 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 witnessPostcondition(output: unknown, pcardHash?: string, hashAlgorithm?: string): Promise<VCard>;
+    /**
+     * 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 sandwich(vPre: VCard, vPost: VCard, pcardHash?: string, hashAlgorithm?: string): Promise<VCard>;
+}
+/**
+ * Simulation context for VCard (EOS Compliance).
+ */
+declare class VCardSimulation {
+    private vcard;
+    private log;
+    constructor(vcard: VCard);
+    logEffect(effectType: string, details: unknown): void;
+    getSimulationLog(): SimulationLogEntry[];
+}
+
+/**
+ * PTREngine — The Polynomial Type Runtime Engine (Arrow Interface)
+ *
+ * This is the canonical execution primitive for the MVP Cards architecture.
+ * It implements the formal Arrow interface mandated by the design documents:
+ *
+ *   - arr:     Lift a pure function into a PTR-managed Arrow (PCard)
+ *   - compose: Sequential composition (>>>)
+ *   - first:   Operate on first element of a product, preserving second
+ *
+ * The `runWithSandwich()` method is the core Arrow evaluation function,
+ * implementing the VCard Sandwich lifecycle:
+ *
+ *     V_pre → PCard(Evaluation Map) → V_post → Sandwich(V_pre, V_post)
+ *
+ * Mirrors Python: mcard.ptr.core.engine.PTREngine
+ *
+ * Usage:
+ *     import { PTREngine } from './PTREngine.js';
+ *     const engine = new PTREngine(collection);
+ *     const [output, sandwich] = await engine.runWithSandwich(pcardHash, inputHash);
+ *
+ * @module PTREngine
+ */
+
+type PreCheck = (input: MCard) => boolean;
+type PostCheck = (output: unknown) => boolean;
+/**
+ * PTREngine — The formal Arrow execution engine.
+ *
+ * Replaces ad-hoc CLMRunner execution paths with a formal
+ * VCard Sandwich lifecycle. Every PCard execution generates
+ * (V_pre, V_post) boundary proofs.
+ */
+declare class PTREngine {
+    private collection;
+    private executionLog;
+    private 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?: CardCollection, executionLogCollection?: CardCollection, options?: {
+        basePath?: string;
+        timeout?: number;
+    });
+    /**
+     * 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
+     */
+    runWithSandwich(pcardHash: string, inputHash: string, preCheck?: PreCheck, postCheck?: PostCheck): Promise<[unknown, VCard]>;
+    /**
+     * 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
+     */
+    runFile(filePath: string, context?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * 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)
+     */
+    arr(func: (input: string) => string, name?: string): Promise<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)
+     */
+    compose(pcardAHash: string, pcardBHash: string): Promise<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)
+     */
+    first(pcardHash: string): Promise<PCard>;
+    private recordToExecutionLog;
+}
+
 /**
  * Type definitions for CLM (Cubical Logic Model) execution.
  */
@@ -1089,7 +1808,8 @@ declare class CLMRunner {
     private loader;
     private timeout;
     private collection?;
-    constructor(basePath?: string, timeout?: number, collection?: CardCollection);
+    private privateCollection?;
+    constructor(basePath?: string, timeout?: number, collection?: CardCollection, privateCollection?: CardCollection);
     /**
      * Run a CLM directly from a file path.
      */
@@ -1153,4 +1873,4 @@ declare class CLMRunner {
     private buildRunCLM;
 }
 
-export { CLMRunner, CardCollection, type CreateEngineOptions, ENGINE_INFO, Either, type EngineEnvironment, type EngineInfo, EngineType, FileIO, IO, LLMConfig, LLMRuntime, index as Lambda, LambdaRuntime, Loader, MCard, Maybe, SandboxWorker, StorageEngine, chatMonad, createEngine, getAvailableEngines, getEngineInfo, getEnginesByEnvironment, promptMonad };
+export { CLMRunner, CardCollection, type CreateEngineOptions, ENGINE_INFO, Either, type EngineEnvironment, type EngineInfo, EngineType, FileIO, IO, LLMConfig, LLMRuntime, index as Lambda, LambdaRuntime, Loader, MCard, Maybe, PTREngine, SandboxWorker, StorageEngine, chatMonad, createEngine, getAvailableEngines, getEngineInfo, getEnginesByEnvironment, promptMonad };