mcard-js/dist/ptr/Bridgelet.d.ts

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

/**
 * Bridgelet Universal Vehicle - Cross-Language Execution Abstraction
 *
 * The Bridgelet provides a universal interface for executing CLM logic across
 * different language runtimes, enabling polyglot composition of PCards.
 *
 * ## Conceptual Foundation
 *
 * Bridgelet = Universal Vehicle for Cross-Language Execution
 *
 * Just as a physical bridge connects two lands, a Bridgelet connects two
 * language runtimes, enabling data and control flow across the boundary.
 *
 * ## Architecture
 *
 * ```
 * ┌─────────────────────────────────────────────────────────────────────┐
 * │                        Bridgelet Interface                          │
 * │  invoke(pcard_hash, input_vcard) → output_vcard                    │
 * └───────────────────────────┬─────────────────────────────────────────┘
 *                             │
 *         ┌───────────────────┼───────────────────────┐
 *         ▼                   ▼                       ▼
 *     ┌────────┐         ┌────────┐             ┌────────┐
 *     │  JS    │         │ Python │             │ WASM   │
 *     │Runtime │         │(HTTP)  │             │Runtime │
 *     └────────┘         └────────┘             └────────┘
 * ```
 *
 * ## Protocol
 *
 * 1. Serialize input VCard to content-addressable format (MCard)
 * 2. Invoke target runtime with PCard hash and input MCard hash
 * 3. Receive output MCard hash
 * 4. Deserialize output MCard to VCard
 *
 * All data crosses the bridge as immutable MCards (content-addressed),
 * ensuring EOS (Experimental-Operational Symmetry).
 *
 * @see CLM_MCard_REPL_Implementation.md §10: Bridgelet Universal Vehicle
 * @see PTR_MCard_CLM_Recent_Developments_Jan2026.md §5.3: Polyglot Execution
 */
/**
 * Supported runtime types for Bridgelet execution
 */
export declare enum RuntimeType {
    JAVASCRIPT = "javascript",
    TYPESCRIPT = "typescript",
    PYTHON = "python",
    WASM = "wasm",
    LEAN = "lean",
    UNKNOWN = "unknown"
}
/**
 * Represents a cross-runtime invocation request.
 *
 * All data is represented by content hashes (MCard references),
 * ensuring immutability and EOS compliance.
 */
export interface BridgeletInvocation {
    /** PCard to execute (content hash) */
    pcardHash: string;
    /** Input VCard (content hash) */
    inputVCardHash: string;
    /** Target runtime */
    targetRuntime: RuntimeType;
    /** Execution context (serializable parameters) */
    context: Record<string, any>;
    /** Trace ID for observability */
    traceId: string;
}
/**
 * Result of a Bridgelet invocation.
 *
 * Contains the output VCard hash and execution metadata.
 */
export interface BridgeletResult {
    /** Success status */
    success: boolean;
    /** Output VCard (content hash) */
    outputVCardHash?: string;
    /** Error message if failed */
    error?: string;
    /** Execution time in milliseconds */
    executionTimeMs: number;
    /** Runtime that executed the PCard */
    executedBy: RuntimeType;
    /** Additional metadata */
    metadata: Record<string, any>;
}
/**
 * Abstract interface for runtime-specific Bridgelet adapters.
 *
 * Each adapter implements the protocol for a specific runtime,
 * handling serialization, invocation, and deserialization.
 */
export interface BridgeletAdapter {
    /** Get the runtime type this adapter supports */
    getRuntimeType(): RuntimeType;
    /** Check if this runtime is available for execution */
    isAvailable(): boolean;
    /** Invoke a PCard in this runtime */
    invoke(invocation: BridgeletInvocation): Promise<BridgeletResult>;
}
/**
 * JavaScript/TypeScript Bridgelet adapter.
 *
 * Executes PCards using the local JavaScript CLM runner.
 */
export declare class JavaScriptBridgeletAdapter implements BridgeletAdapter {
    private collection;
    constructor(collection?: any);
    getRuntimeType(): RuntimeType;
    isAvailable(): boolean;
    invoke(invocation: BridgeletInvocation): Promise<BridgeletResult>;
}
/**
 * Universal Vehicle for Cross-Language Execution.
 *
 * The Bridgelet manages a registry of runtime adapters and routes
 * PCard execution requests to the appropriate runtime based on
 * the PCard's declared runtime requirement.
 *
 * ## Usage
 *
 * ```typescript
 * const bridgelet = new Bridgelet(collection);
 * bridgelet.registerAdapter(new JavaScriptBridgeletAdapter());
 * bridgelet.registerAdapter(new PythonHTTPBridgeletAdapter('http://localhost:8000'));
 *
 * const result = await bridgelet.invoke({
 *     pcardHash: "abc123",
 *     inputVCardHash: "def456",
 *     context: { param: "value" }
 * });
 * ```
 *
 * ## Cross-Language Composition
 *
 * The Bridgelet enables polyglot PCard composition:
 *
 * ```typescript
 * jsPCard.andThen(pythonPCard).andThen(wasmPCard)
 * ```
 *
 * Each transition crosses a runtime bridge, with data flowing
 * as content-addressed MCards.
 */
export declare class Bridgelet {
    private collection;
    private adapters;
    private traceCounter;
    constructor(collection?: any);
    /**
     * Register a runtime adapter
     */
    registerAdapter(adapter: BridgeletAdapter): void;
    /**
     * Get list of available runtimes
     */
    getAvailableRuntimes(): RuntimeType[];
    /**
     * Generate a unique trace ID for observability
     */
    private generateTraceId;
    /**
     * Detect the required runtime for a PCard
     */
    private detectRuntime;
    /**
     * Invoke a PCard across the appropriate runtime bridge
     */
    invoke(options: {
        pcardHash: string;
        inputVCardHash: string;
        context?: Record<string, any>;
        targetRuntime?: RuntimeType;
    }): Promise<BridgeletResult>;
}
//# sourceMappingURL=Bridgelet.d.ts.map