mcard-js 2.1.16 → 2.1.19

package/README.md

@@ -607,17 +607,26 @@ To run integration tests against a live Ollama instance:
     npx vitest tests/rag/Integration.test.ts
     ```
 
-## Version 2.1.16 Release Notes (December 15, 2025)
-> UPTV Protocol Alignment & Loader Fixes
+## Version 2.1.16 Release Notes (December 16, 2025)
+> Feature Parity, Refactoring, and UPTV Alignment
+
+### 🏗️ Code Refactoring & Cleanup
+*   **Binary Detector Parity**: Refactored `BinaryDetector.ts` to expose `detectFromBytes` and match Python's logic structure, ensuring consistent file signatures detection.
+*   **FileSystemUtils Optimization**: `detectContentType` in `FileSystemUtils` now delegates to the central `ContentTypeInterpreter`, removing code duplication and ensuring consistent MIME type detection across the loader.
+*   **Handle Validation**: Relaxed validation to allow colons (`:`), supporting URI-like handles (e.g., `vcard://auth/1`) used in the UPTV architecture.
+
+### 🎭 Feature Parity
+*   **Petri Net Metadata**: The CLM Runner now attaches `petriNet` metadata (pcardHash, vcardHash, handle) to execution results, matching the Python implementation.
+*   **VCard Standardization**:
+    -   Aligned field names (`success` instead of `verified`, `token` types).
+    -   Handles now default to `vcard://` namespace.
+*   **Global Time**: `GTime` now consistently uses UTC with `Z` suffix, ensuring hash consistency between runtimes.
 
 ### 📜 Unifying Protocol of Truth Verification (UPTV)
 *   **Documentation Overhaul**: Updated PTR, CLM, and PCard documentation to align with the **Categorical Petri Net** architecture of UPTV.
 *   **CLM Triad**: Explicitly defined the Abstract ($A$) × Concrete ($C$) × Balanced ($B$) structure as the core verification unit.
 *   **Petri Net Mapping**: Clarified roles: Handle (Place), PCard (Transport/Function), VCard (Token/Evidence).
-
-### 🐛 Loader Persistence Fixes
-*   **Recursive Loading**: Fixed database corruption (`SQLITE_CORRUPT`) issues when recursively loading large directory trees in Node.js.
-*   **Consistency**: Synchronized filtering logic (ignoring `_` prefix and `config.yaml`) between Python and JavaScript CLM runners.
+*   **Loader Persistence**: Fixed database corruption issues during recursive loading.
 
 ---
 

package/dist/model/MCard.d.ts

@@ -1,6 +1,26 @@
 import { DOTSMetadata } from '../types/dots';
 /**
- * MCard - Content-addressable data container
+ * MCard - Content-addressable data container (The Monad)
+ *
+ * ## Category Theory Role: MONAD
+ *
+ * MCard is the **Monad** in the MVP Cards categorical hierarchy:
+ * - **MCard (Monad)**: Data container with `unit` (create) and `bind` (chain)
+ * - **PCard (Functor)**: Pure transformation, `fmap` over MCard content
+ * - **VCard (Applicative)**: Context-aware application with pre-conditions
+ *
+ * ## Scale-Free Monadic Infrastructure: Spinoza-Leibniz Synthesis
+ *
+ * MCard implements the dual philosophical foundation:
+ *
+ * | Philosopher | Contribution | MCard Implementation |
+ * |-------------|--------------|---------------------|
+ * | **Spinoza** | One Substance (Deus sive Natura) | Fixed 3-field schema (Terminal Object) |
+ * | **Leibniz** | Infinite Monads (Pre-Established Harmony) | Infinite content-addressed entries |
+ * | **Both** | No windows / Internal causation | Content-addressing (same hash = same truth) |
+ *
+ * This enables **Experimental-Operational Symmetry (EOS)**: same behavior from
+ * a single user's PKC (100MB) to a planetary LLM registry (1PB).
  *
  * ## DOTS Vocabulary Role: CARRIER
  *
@@ -9,40 +29,48 @@ import { DOTSMetadata } from '../types/dots';
  * - Hash-links between MCards are **Morphisms** in Car(S)
  * - The Carrier is the category of all actual data/systems
  *
- * ## EOS Role: Invariant Content (Galois Root)
+ * ## Petri Net Role: TOKEN CONTENT
  *
- * MCard provides the **Invariant Substrate** in Experimental-Operational Symmetry:
- * - `Hash(Content)` is a **pure function** with no side effects
- * - Same content in Dev = Same hash in Prod (environment-invariant)
- * - This is the "Joint Reality" P(H,E) = P(E,H) in Bayesian terms
+ * In the Categorical Petri Net model:
+ * - **MCard content** is what tokens carry
+ * - **VCard** is the token type (Applicative wrapper)
+ * - **PCard** is the transition that transforms tokens
  *
  * ## MVP Cards Architecture: Data Plane
  *
  * ```
  * ┌───────────────────────────────────────────────────────┐
  * │               APPLICATION PLANE (VCard)               │
- * │     Value Exchange / AuthN/AuthZ / Sovereign Memory   │
+ * │     Petri Net Token / AuthN/AuthZ / Side Effects      │
  * └─────────────────────────┬─────────────────────────────┘
- *                           │ (Policy Triggers)
+ *                           │ (Pre-Condition Check)
  * ┌─────────────────────────▼─────────────────────────────┐
  * │                CONTROL PLANE (PCard)                  │
- * │   Polynomial Functor Composition / Monadic Execution  │
+ * │   Petri Net Transition / CLM Logic / Pure Function    │
  * └─────────────────────────┬─────────────────────────────┘
- *                           │ (Hash References)
+ *                           │ (Content Transformation)
  * ┌─────────────────────────▼─────────────────────────────┐
  * │                 DATA PLANE (MCard) ◀── YOU ARE HERE   │
- * │   Immutable, Content-Addressable Storage / Monad      │
+ * │   Monad / Content-Addressable / Scale-Free Substrate  │
  * └───────────────────────────────────────────────────────┘
  * ```
  *
- * ## The Empty Schema Principle
+ * ## The Empty Schema Principle (Kenosis)
  *
- * MCard embodies the Empty Schema Principle from the Wordless Book:
+ * MCard embodies the Empty Schema Principle:
  * - Schema contains NO domain-specific terms (only hash, content, g_time)
  * - Domain customization happens via data (INSERT), not schema changes
  * - Universal applicability: same structure for ANY domain
+ * - This emptiness enables universality (Kenosis in code)
+ *
+ * ## Three Tables as Irreducible Semiotic Triad
  *
- * ## Functional Requirements (from design docs)
+ * The MCard infrastructure uses three tables (Peirce's semiotics):
+ * - `card` (Object/Referent): what the content means
+ * - `handle_registry` (Representamen/Sign): which concept is named
+ * - `handle_history` (Interpretant): how understanding evolved
+ *
+ * ## Functional Requirements
  *
  * | ID | Requirement | Implementation |
  * |----|-------------|----------------|
@@ -50,17 +78,14 @@ import { DOTSMetadata } from '../types/dots';
  * | M-2 | CRD-only (no UPDATE) | Immutable class, `readonly` fields |
  * | M-3 | Include g_time for ordering | `this.g_time` field |
  * | M-4 | Human-readable content | `getContentAsText()` method |
+ * | MONAD-1 | Unit (pure) operation | `MCard.create(content)` |
+ * | MONAD-2 | Bind (chain) operation | `MCard.bind(f)` via hash reference |
  * | EOS-M1 | Hash is pure function | No side effects in hash computation |
  * | EOS-M2 | Content is immutable | All fields are `readonly` |
  *
  * @see {@link DOTSRole.CARRIER} for DOTS vocabulary definition
  * @see {@link EOSRole.INVARIANT_CONTENT} for EOS role definition
- * @see docs/WorkingNotes/Permanent/Projects/PKC Kernel/MCard.md for full specification
- *
- * Each MCard has:
- * - content: Raw bytes (Uint8Array)
- * - hash: SHA-256 cryptographic hash (the Carrier Object identity)
- * - g_time: Global timestamp with algorithm identifier
+ * @see docs/MCard_Impl.md for full implementation specification
  */
 export declare class MCard {
     readonly content: Uint8Array;

package/dist/model/MCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MCard.d.ts","sourceRoot":"","sources":["../../src/model/MCard.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgC,YAAY,EAA2B,MAAM,eAAe,CAAC;AAEpG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,qBAAa,KAAK;IACd,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,SAAS,aAAa,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;IAQlH;;OAEG;WACU,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,aAAa,GAAE,MAAiB,GAAG,OAAO,CAAC,KAAK,CAAC;IAoBnG;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK;IAMzE;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACH,UAAU,IAAI,UAAU;IAIxB;;OAEG;IACH,QAAQ,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE;IAUxG;;;;;;;;;;;;;;;;;;;OAmBG;IACH,eAAe,CAAC,SAAS,GAAE,MAAM,EAAO,EAAE,SAAS,GAAE,MAAM,EAAO,GAAG,YAAY;CAGpF"}
+{"version":3,"file":"MCard.d.ts","sourceRoot":"","sources":["../../src/model/MCard.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgC,YAAY,EAA2B,MAAM,eAAe,CAAC;AAEpG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,qBAAa,KAAK;IACd,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,SAAS,aAAa,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;IAQlH;;OAEG;WACU,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,aAAa,GAAE,MAAiB,GAAG,OAAO,CAAC,KAAK,CAAC;IAoBnG;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK;IAMzE;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACH,UAAU,IAAI,UAAU;IAIxB;;OAEG;IACH,QAAQ,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE;IAUxG;;;;;;;;;;;;;;;;;;;OAmBG;IACH,eAAe,CAAC,SAAS,GAAE,MAAM,EAAO,EAAE,SAAS,GAAE,MAAM,EAAO,GAAG,YAAY;CAGpF"}

package/dist/model/MCard.js

@@ -3,7 +3,27 @@ import { GTime } from './GTime';
 import { ContentTypeInterpreter } from './detectors/ContentTypeInterpreter';
 import { createMCardDOTSMetadata } from '../types/dots';
 /**
- * MCard - Content-addressable data container
+ * MCard - Content-addressable data container (The Monad)
+ *
+ * ## Category Theory Role: MONAD
+ *
+ * MCard is the **Monad** in the MVP Cards categorical hierarchy:
+ * - **MCard (Monad)**: Data container with `unit` (create) and `bind` (chain)
+ * - **PCard (Functor)**: Pure transformation, `fmap` over MCard content
+ * - **VCard (Applicative)**: Context-aware application with pre-conditions
+ *
+ * ## Scale-Free Monadic Infrastructure: Spinoza-Leibniz Synthesis
+ *
+ * MCard implements the dual philosophical foundation:
+ *
+ * | Philosopher | Contribution | MCard Implementation |
+ * |-------------|--------------|---------------------|
+ * | **Spinoza** | One Substance (Deus sive Natura) | Fixed 3-field schema (Terminal Object) |
+ * | **Leibniz** | Infinite Monads (Pre-Established Harmony) | Infinite content-addressed entries |
+ * | **Both** | No windows / Internal causation | Content-addressing (same hash = same truth) |
+ *
+ * This enables **Experimental-Operational Symmetry (EOS)**: same behavior from
+ * a single user's PKC (100MB) to a planetary LLM registry (1PB).
  *
  * ## DOTS Vocabulary Role: CARRIER
  *
@@ -12,40 +32,48 @@ import { createMCardDOTSMetadata } from '../types/dots';
  * - Hash-links between MCards are **Morphisms** in Car(S)
  * - The Carrier is the category of all actual data/systems
  *
- * ## EOS Role: Invariant Content (Galois Root)
+ * ## Petri Net Role: TOKEN CONTENT
  *
- * MCard provides the **Invariant Substrate** in Experimental-Operational Symmetry:
- * - `Hash(Content)` is a **pure function** with no side effects
- * - Same content in Dev = Same hash in Prod (environment-invariant)
- * - This is the "Joint Reality" P(H,E) = P(E,H) in Bayesian terms
+ * In the Categorical Petri Net model:
+ * - **MCard content** is what tokens carry
+ * - **VCard** is the token type (Applicative wrapper)
+ * - **PCard** is the transition that transforms tokens
  *
  * ## MVP Cards Architecture: Data Plane
  *
  * ```
  * ┌───────────────────────────────────────────────────────┐
  * │               APPLICATION PLANE (VCard)               │
- * │     Value Exchange / AuthN/AuthZ / Sovereign Memory   │
+ * │     Petri Net Token / AuthN/AuthZ / Side Effects      │
  * └─────────────────────────┬─────────────────────────────┘
- *                           │ (Policy Triggers)
+ *                           │ (Pre-Condition Check)
  * ┌─────────────────────────▼─────────────────────────────┐
  * │                CONTROL PLANE (PCard)                  │
- * │   Polynomial Functor Composition / Monadic Execution  │
+ * │   Petri Net Transition / CLM Logic / Pure Function    │
  * └─────────────────────────┬─────────────────────────────┘
- *                           │ (Hash References)
+ *                           │ (Content Transformation)
  * ┌─────────────────────────▼─────────────────────────────┐
  * │                 DATA PLANE (MCard) ◀── YOU ARE HERE   │
- * │   Immutable, Content-Addressable Storage / Monad      │
+ * │   Monad / Content-Addressable / Scale-Free Substrate  │
  * └───────────────────────────────────────────────────────┘
  * ```
  *
- * ## The Empty Schema Principle
+ * ## The Empty Schema Principle (Kenosis)
  *
- * MCard embodies the Empty Schema Principle from the Wordless Book:
+ * MCard embodies the Empty Schema Principle:
  * - Schema contains NO domain-specific terms (only hash, content, g_time)
  * - Domain customization happens via data (INSERT), not schema changes
  * - Universal applicability: same structure for ANY domain
+ * - This emptiness enables universality (Kenosis in code)
+ *
+ * ## Three Tables as Irreducible Semiotic Triad
  *
- * ## Functional Requirements (from design docs)
+ * The MCard infrastructure uses three tables (Peirce's semiotics):
+ * - `card` (Object/Referent): what the content means
+ * - `handle_registry` (Representamen/Sign): which concept is named
+ * - `handle_history` (Interpretant): how understanding evolved
+ *
+ * ## Functional Requirements
  *
  * | ID | Requirement | Implementation |
  * |----|-------------|----------------|
@@ -53,17 +81,14 @@ import { createMCardDOTSMetadata } from '../types/dots';
  * | M-2 | CRD-only (no UPDATE) | Immutable class, `readonly` fields |
  * | M-3 | Include g_time for ordering | `this.g_time` field |
  * | M-4 | Human-readable content | `getContentAsText()` method |
+ * | MONAD-1 | Unit (pure) operation | `MCard.create(content)` |
+ * | MONAD-2 | Bind (chain) operation | `MCard.bind(f)` via hash reference |
  * | EOS-M1 | Hash is pure function | No side effects in hash computation |
  * | EOS-M2 | Content is immutable | All fields are `readonly` |
  *
  * @see {@link DOTSRole.CARRIER} for DOTS vocabulary definition
  * @see {@link EOSRole.INVARIANT_CONTENT} for EOS role definition
- * @see docs/WorkingNotes/Permanent/Projects/PKC Kernel/MCard.md for full specification
- *
- * Each MCard has:
- * - content: Raw bytes (Uint8Array)
- * - hash: SHA-256 cryptographic hash (the Carrier Object identity)
- * - g_time: Global timestamp with algorithm identifier
+ * @see docs/MCard_Impl.md for full implementation specification
  */
 export class MCard {
     content;

package/dist/model/MCard.js.map

@@ -1 +1 @@
-{"version":3,"file":"MCard.js","sourceRoot":"","sources":["../../src/model/MCard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"MCard.js","sourceRoot":"","sources":["../../src/model/MCard.ts"],"names":[],"mappings":"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"}

package/dist/model/PCard.d.ts

@@ -1,13 +1,85 @@
 /**
- * PCard Model (Control Plane) - Implementation of LENS/CHART.
+ * PCard Model (Control Plane) - Petri Net TRANSITION
  *
- * This module defines the PCard, which represents the execution unit in the DOTS framework.
- * PCards are MCards that contain a valid CLM (Cubical Logic Model) specification.
+ * This module defines PCard, the execution unit in the MVP Cards architecture.
+ * PCards are MCards containing a valid CLM (Cubical Logic Model) specification.
+ *
+ * ## Category Theory Role: FUNCTOR
+ *
+ * PCard is the **Functor** in the MVP Cards 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
+ *
+ * A PCard (Transition) fires when all input VCards (Tokens) are present:
+ *
+ * ```
+ * M' = M - •t + t•
+ * ```
+ *
+ * Where:
+ * - M = Current marking (token distribution)
+ * - •t = Pre-set (input VCards required)
+ * - t• = Post-set (output VCards produced)
+ *
+ * ### Handle Naming Convention for CLM Execution
+ *
+ * ```
+ * clm://{module}/{function}/spec      # PCard (Transition definition)
+ * clm://{module}/{function}/input     # Input VCard (Precondition)
+ * clm://{module}/{function}/output    # Output VCard (Postcondition)
+ * clm://{module}/{function}/balanced  # Balanced Expectations history
+ * ```
+ *
+ * ## 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 (tracked in handle_history)
+ *
+ * ## 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';
 /**
- * PCard - The Control Plane unit (Lens + Chart)
+ * 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).
@@ -35,16 +107,83 @@ export declare class PCard extends MCard {
      */
     get clm(): any;
     /**
-     * Get the Abstract Specification section
+     * 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
+     * Get the Concrete Implementation section (Legacy)
      */
     get concreteImpl(): any;
     /**
-     * Get the Balanced Expectations (tests) section
+     * Get the Balanced Expectations (tests) section (Legacy)
      */
     get balancedExpectations(): 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

package/dist/model/PCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PCard.d.ts","sourceRoot":"","sources":["../../src/model/PCard.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAIhC,OAAO,EAAE,YAAY,EAA2B,MAAM,eAAe,CAAC;AAEtE;;;;;GAKG;AACH,qBAAa,KAAM,SAAQ,KAAK;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAM;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IAEjC,SAAS,aACL,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,GAAG,EACd,MAAM,EAAE,OAAO;IAOnB;;;;;;OAMG;WACU,MAAM,CACf,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,aAAa,GAAE,MAAiB,EAChC,MAAM,GAAE,OAAc,GACvB,OAAO,CAAC,KAAK,CAAC;IA+BjB;;;;OAIG;IACH,eAAe,IAAI,YAAY;IA0B/B;;OAEG;IACH,IAAI,GAAG,IAAI,GAAG,CAEb;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,GAAG,CAEtB;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,GAAG,CAEtB;IAED;;OAEG;IACH,IAAI,oBAAoB,IAAI,GAAG,CAE9B;CACJ"}
+{"version":3,"file":"PCard.d.ts","sourceRoot":"","sources":["../../src/model/PCard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAIhC,OAAO,EAAE,YAAY,EAA2B,MAAM,eAAe,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,IAAI,EAAE,cAAc,GAAG,eAAe,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC5D,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;;;;GAKG;AACH,qBAAa,KAAM,SAAQ,KAAK;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAM;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IAEjC,SAAS,aACL,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,GAAG,EACd,MAAM,EAAE,OAAO;IAOnB;;;;;;OAMG;WACU,MAAM,CACf,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,aAAa,GAAE,MAAiB,EAChC,MAAM,GAAE,OAAc,GACvB,OAAO,CAAC,KAAK,CAAC;IA+BjB;;;;OAIG;IACH,eAAe,IAAI,YAAY;IA0B/B;;OAEG;IACH,IAAI,GAAG,IAAI,GAAG,CAEb;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,GAAG,CAElB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,GAAG,CAElB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,GAAG,CAElB;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,GAAG,CAEtB;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,GAAG,CAEtB;IAED;;OAEG;IACH,IAAI,oBAAoB,IAAI,GAAG,CAE9B;IAMD;;;;;;;OAOG;IACH,iBAAiB,IAAI,aAAa,EAAE;IAuCpC;;;;;;OAMG;IACH,mBAAmB,IAAI,eAAe,EAAE;IAqCxC;;;;OAIG;IACH,mBAAmB,IAAI,MAAM;IAU7B;;;;;;OAMG;IACH,iBAAiB,IAAI,MAAM;IAK3B;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE;IAoBtF;;;;OAIG;IACH,UAAU,IAAI,MAAM;IAMpB;;;;OAIG;IACH,cAAc,IAAI,OAAO;CAI5B"}