mcard-js/dist/model/PCard.d.ts

MCard - Content-addressable storage with cryptographic hashing, handle resolution, and vector search for Node.js and browsers

/**
 * 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
 */
import { MCard } from './MCard';
import { DOTSMetadata } from '../types/dots';
/**
 * Input VCard reference for Petri Net pre-condition
 */
export 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
 */
export 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).
 */
export 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: any, 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(): any;
    private getSection;
    /**
     * Get the Abstract Specification section (UPTV Role: Abstract)
     */
    get abstract(): any;
    /**
     * Get the Concrete Implementation section (UPTV Role: Concrete)
     */
    get concrete(): any;
    /**
     * Get the Balanced Expectations (tests) section (UPTV Role: Balanced)
     */
    get balanced(): any;
    /**
     * Get the Abstract Specification section (Legacy)
     */
    get abstractSpec(): any;
    /**
     * Get the Concrete Implementation section (Legacy)
     */
    get concreteImpl(): any;
    /**
     * Get the Balanced Expectations (tests) section (Legacy)
     */
    get balancedExpectations(): any;
    /**
     * 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, any>;
    /**
     * Run with instrumentation (eBPF/Tracing)
     */
    profile(): Record<string, any>;
    /**
     * Run in Operative mode (Step-by-step)
     */
    debug(): Record<string, any>;
    /**
     * Return documentation/explanation
     */
    explain(): Record<string, any>;
    /**
     * 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;
}
//# sourceMappingURL=PCard.d.ts.map