mcard-js 2.1.48 → 2.1.49

package/dist/AbstractSqlEngine-DKka6XjT.d.cts

@@ -0,0 +1,451 @@
+/**
+ * DOTS Vocabulary Types
+ *
+ * From the Double Operadic Theory of Systems (DOTS), this module provides
+ * a minimal, domain-independent vocabulary for describing compositional systems.
+ *
+ * The MVP Cards architecture maps directly to DOTS:
+ * - MCard → Carrier (the actual data/systems)
+ * - PCard → Lens (tight) + Chart (loose)
+ * - VCard → Arena + Action
+ *
+ * Reference: docs/WorkingNotes/Hub/Theory/Integration/DOTS Vocabulary as Efficient Representation for ABC Curriculum.md
+ */
+/**
+ * DOTS Role enumeration
+ *
+ * These nine terms (seven structural + Action + Unit) form a complete,
+ * compositional language for describing any system, interface, or interaction.
+ */
+declare enum DOTSRole {
+    /**
+     * CARRIER - Category Car(S) of all actual data/systems
+     *
+     * MCard is the Carrier. Each MCard is an Object in the Carrier category;
+     * each hash-link is a Morphism in Car(S).
+     *
+     * Polynomial Form: Objects = MCards, Morphisms = hash references
+     */
+    CARRIER = "Carrier",
+    /**
+     * LENS - Tight morphism (structure-preserving interface map)
+     *
+     * PCard's abstract_spec ↔ concrete_impl relationship is a Lens.
+     * Ensures type safety: Abstract types match Concrete types.
+     *
+     * Lens = (get, put) pair with coherence laws
+     */
+    LENS = "Lens",
+    /**
+     * CHART - Loose morphism (behavioral interaction pattern)
+     *
+     * PCard's balanced_expectations (tests) describe the wiring.
+     * Enables flexibility: same Abstract spec via different Concrete implementations.
+     *
+     * Chart = horizontal morphism in Target double category
+     */
+    CHART = "Chart",
+    /**
+     * ARENA - Interface type (what can interact)
+     *
+     * VCard is the Arena. It defines the subject_did, capabilities[],
+     * and ExternalRef[]. An Arena is a pair of sets (Inputs, Outputs).
+     *
+     * Arena = (I, O) → Polynomial functor P(X) = Σ_{i∈I} X^{O(i)}
+     */
+    ARENA = "Arena",
+    /**
+     * ACTION - Module structure where interactions act on systems
+     *
+     * VCard enables Action: interactions (Charts/PCards) act on
+     * systems (MCards/Carrier) to produce new systems.
+     * The VCard authorization gate is the mechanism of this action.
+     *
+     * Action = Loose(I) ⊛ Car(S) → Car(S)
+     */
+    ACTION = "Action",
+    /**
+     * TARGET - Double category I of all interfaces and interactions
+     *
+     * The CLM design space. Contains all possible Arenas (objects),
+     * Lenses (tight morphisms), and Charts (loose morphisms).
+     */
+    TARGET = "Target",
+    /**
+     * TIGHT - Vertical composition direction (strict)
+     *
+     * Prerequisites chains. Cannot skip foundational concepts.
+     * Ensures type safety across compositions.
+     *
+     * Vertical = mandatory sequential dependency
+     */
+    TIGHT = "Tight",
+    /**
+     * LOOSE - Horizontal composition direction (flexible)
+     *
+     * Same concept via different interaction patterns.
+     * Enables behavioral flexibility while preserving semantics.
+     *
+     * Horizontal = parallel/interchangeable alternatives
+     */
+    LOOSE = "Loose",
+    /**
+     * UNIT - Identity object for parallel composition
+     *
+     * Empty MCard / Root Namespace. The neutral element.
+     * For any system S: Unit ⊗ S ≅ S
+     */
+    UNIT = "Unit"
+}
+/**
+ * EOS (Experimental-Operational Symmetry) Role
+ *
+ * Each MVP Card type enforces a specific dimension of symmetry
+ * to ensure environment-invariant correctness.
+ */
+declare enum EOSRole {
+    /**
+     * INVARIANT_CONTENT - The Galois Root
+     *
+     * MCard: Hash(Content) is a pure function.
+     * Same content in Dev = Same hash in Prod.
+     * Environment-invariant identity.
+     */
+    INVARIANT_CONTENT = "InvariantContent",
+    /**
+     * GENERATIVE_LENS - Controlled Symmetry Breaking 1
+     *
+     * PCard: Pure function f(x)=y.
+     * Invariant in definition, variant only in input.
+     * The logic is environment-invariant.
+     */
+    GENERATIVE_LENS = "GenerativeLens",
+    /**
+     * SOVEREIGN_DECISION - Controlled Symmetry Breaking 2
+     *
+     * VCard: The Gap Junction.
+     * Breaks symmetry by introducing Authority.
+     * Decisional reality creation.
+     */
+    SOVEREIGN_DECISION = "SovereignDecision"
+}
+/**
+ * Card Plane in the MVP Cards architecture
+ *
+ * Maps to SDN (Software-Defined Networking) plane separation:
+ * Data Plane → Control Plane → Application Plane
+ */
+declare enum CardPlane {
+    /**
+     * DATA_PLANE - MCard
+     *
+     * Immutable, content-addressable storage.
+     * The monadic foundation that wraps effects.
+     * CRD-only operations (Create, Retrieve, Delete).
+     */
+    DATA = "Data",
+    /**
+     * CONTROL_PLANE - PCard
+     *
+     * Polynomial functor composition.
+     * Monadic execution via PTR.
+     * Policy and logic gating.
+     */
+    CONTROL = "Control",
+    /**
+     * APPLICATION_PLANE - VCard
+     *
+     * Value exchange and authentication.
+     * Side effect management (IO Monad).
+     * Sovereign memory and authorization.
+     */
+    APPLICATION = "Application"
+}
+/**
+ * Polynomial Functor Type
+ *
+ * The mathematical foundation for DOTS.
+ * Every DOTS component is a polynomial functor of the form:
+ * P(X) = Σ_{i∈I} X^{O(i)}
+ */
+interface PolynomialFunctor {
+    /** Positions (I) - input types, system states */
+    positions: string[];
+    /** Directions O(i) - output types per position */
+    directions: Record<string, string[]>;
+}
+/**
+ * DOTS metadata that can be attached to any card type
+ */
+interface DOTSMetadata {
+    /** Primary DOTS role (Carrier, Lens, Chart, Arena, Action) */
+    role: DOTSRole;
+    /** EOS symmetry role */
+    eosRole?: EOSRole;
+    /** Card plane (Data, Control, Application) */
+    plane: CardPlane;
+    /** Polynomial functor representation (optional) */
+    polynomial?: PolynomialFunctor;
+    /** Tight morphism references (prerequisite hashes) */
+    tightRefs?: string[];
+    /** Loose morphism references (alternative implementation hashes) */
+    looseRefs?: string[];
+}
+
+/**
+ * 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
+ *
+ * MCard is the **Carrier** in the Double Operadic Theory of Systems (DOTS).
+ * - Each MCard is an **Object** in the Carrier category Car(S)
+ * - Hash-links between MCards are **Morphisms** in Car(S)
+ * - The Carrier is the category of all actual data/systems
+ *
+ * ## Petri Net Role: TOKEN CONTENT
+ *
+ * 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)               │
+ * │     Petri Net Token / AuthN/AuthZ / Side Effects      │
+ * └─────────────────────────┬─────────────────────────────┘
+ *                           │ (Pre-Condition Check)
+ * ┌─────────────────────────▼─────────────────────────────┐
+ * │                CONTROL PLANE (PCard)                  │
+ * │   Petri Net Transition / CLM Logic / Pure Function    │
+ * └─────────────────────────┬─────────────────────────────┘
+ *                           │ (Content Transformation)
+ * ┌─────────────────────────▼─────────────────────────────┐
+ * │                 DATA PLANE (MCard) ◀── YOU ARE HERE   │
+ * │   Monad / Content-Addressable / Scale-Free Substrate  │
+ * └───────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ## The Empty Schema Principle (Kenosis)
+ *
+ * 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
+ *
+ * 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 |
+ * |----|-------------|----------------|
+ * | M-1 | Content-addressable via hash | `this.hash = SHA-256(content)` |
+ * | 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/MCard_Impl.md for full implementation specification
+ */
+declare class MCard {
+    readonly content: Uint8Array;
+    readonly hash: string;
+    readonly g_time: string;
+    readonly contentType: string;
+    readonly hashFunction: string;
+    protected constructor(content: Uint8Array, hash: string, g_time: string, contentType: string, hashFunction: string);
+    /**
+     * Create a new MCard from content
+     */
+    static create(content: string | Uint8Array, hashAlgorithm?: string): Promise<MCard>;
+    /**
+     * Create an MCard from existing data (e.g., from database)
+     */
+    static fromData(content: Uint8Array, hash: string, g_time: string): MCard;
+    /**
+     * Get content as text (UTF-8 decoded)
+     */
+    getContentAsText(): string;
+    /**
+     * Get content as raw bytes
+     */
+    getContent(): Uint8Array;
+    /**
+     * Convert to plain object
+     */
+    toObject(): {
+        hash: string;
+        content: string;
+        g_time: string;
+        contentType: string;
+        hashFunction: string;
+    };
+    /**
+     * Get DOTS vocabulary metadata for this MCard
+     *
+     * Returns the DOTS role information that positions this MCard
+     * in the Double Operadic Theory of Systems framework.
+     *
+     * MCard is always a CARRIER object in the Data Plane.
+     *
+     * @param tightRefs - Optional array of prerequisite MCard hashes (vertical composition)
+     * @param looseRefs - Optional array of alternative MCard hashes (horizontal composition)
+     * @returns DOTSMetadata describing this card's role in the compositional system
+     *
+     * @example
+     * ```typescript
+     * const card = await MCard.create('Hello World');
+     * const meta = card.getDOTSMetadata();
+     * console.log(meta.role);  // 'Carrier'
+     * console.log(meta.plane); // 'Data'
+     * ```
+     */
+    getDOTSMetadata(tightRefs?: string[], looseRefs?: string[]): DOTSMetadata;
+}
+
+/**
+ * Page - Pagination container for query results
+ */
+interface Page<T> {
+    items: T[];
+    totalItems: number;
+    pageNumber: number;
+    pageSize: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrevious: boolean;
+}
+/**
+ * StorageEngine - Abstract interface for storage backends
+ *
+ * Implementations: IndexedDBEngine, SqliteWasmEngine
+ */
+interface StorageEngine {
+    add(card: MCard): Promise<string>;
+    get(hash: string): Promise<MCard | null>;
+    delete(hash: string): Promise<void>;
+    searchByHash(hashPrefix: string): Promise<MCard[]>;
+    getPage(pageNumber: number, pageSize: number): Promise<Page<MCard>>;
+    search(query: string, pageNumber: number, pageSize: number): Promise<Page<MCard>>;
+    getAll(): Promise<MCard[]>;
+    count(): Promise<number>;
+    clear(): Promise<void>;
+    registerHandle(handle: string, hash: string): Promise<void>;
+    resolveHandle(handle: string): Promise<string | null>;
+    getByHandle(handle: string): Promise<MCard | null>;
+    updateHandle(handle: string, newHash: string): Promise<string>;
+    getHandleHistory(handle: string): Promise<{
+        previousHash: string;
+        changedAt: string;
+    }[]>;
+    pruneHandleHistory?(handle: string, options: {
+        olderThan?: string;
+        deleteAll?: boolean;
+    }): Promise<number>;
+    /** List all registered handles with their current hashes. */
+    getAllHandles(): Promise<{
+        handle: string;
+        hash: string;
+    }[]>;
+    /** Remove a handle and all its history entries. Does NOT delete the underlying card(s). */
+    removeHandle(handle: string): Promise<void>;
+    /** Rename a handle: update the handle key in registry and all history entries atomically. */
+    renameHandle(oldHandle: string, newHandle: string): Promise<void>;
+    /** Delete a single history entry by handle + previousHash, stitching the chain. */
+    deleteHistoryEntry(handle: string, previousHash: string): Promise<void>;
+}
+
+/**
+ * AbstractSqlEngine — Base class for SQL-backed StorageEngine implementations.
+ *
+ * Provides concrete implementations of all handle operations (register, resolve,
+ * update, rename, prune, delete history, etc.) using two abstract primitives
+ * that each SQL engine must implement:
+ *
+ *   - queryRows(sql, ...params)  — Run a SELECT and return row objects
+ *   - execSql(sql, ...params)    — Run a write statement and return rows-changed
+ *
+ * Card operations (add, get, delete, getPage, search, etc.) remain abstract
+ * because they involve engine-specific row ↔ MCard conversion logic.
+ */
+
+declare abstract class AbstractSqlEngine implements StorageEngine {
+    /** Run a SELECT query and return row objects. */
+    protected abstract queryRows(sql: string, ...params: unknown[]): Promise<Record<string, unknown>[]>;
+    /** Run a write statement (INSERT/UPDATE/DELETE) and return rows-changed count. */
+    protected abstract execSql(sql: string, ...params: unknown[]): Promise<number>;
+    /** Convert a row object into an MCard. Engine-specific because of content types. */
+    protected abstract rowToCard(row: Record<string, unknown>): MCard;
+    /**
+     * SQL expression for casting content to text in search queries.
+     * Override in subclasses: SQLite uses 'TEXT', DuckDB uses 'VARCHAR'.
+     */
+    protected get castContentAs(): string;
+    /**
+     * Add a card. Default uses INSERT OR REPLACE (SQLite).
+     * DuckDB overrides with DELETE + INSERT.
+     */
+    add(card: MCard): Promise<string>;
+    get(hash: string): Promise<MCard | null>;
+    delete(hash: string): Promise<void>;
+    getPage(pageNumber?: number, pageSize?: number): Promise<Page<MCard>>;
+    count(): Promise<number>;
+    searchByHash(hashPrefix: string): Promise<MCard[]>;
+    search(queryStr: string, pageNumber?: number, pageSize?: number): Promise<Page<MCard>>;
+    getAll(): Promise<MCard[]>;
+    clear(): Promise<void>;
+    registerHandle(handle: string, hash: string): Promise<void>;
+    resolveHandle(handle: string): Promise<string | null>;
+    getByHandle(handle: string): Promise<MCard | null>;
+    updateHandle(handle: string, newHash: string): Promise<string>;
+    getHandleHistory(handle: string): Promise<{
+        previousHash: string;
+        changedAt: string;
+    }[]>;
+    pruneHandleHistory(handle: string, options?: {
+        olderThan?: string;
+        deleteAll?: boolean;
+    }): Promise<number>;
+    getAllHandles(): Promise<{
+        handle: string;
+        hash: string;
+    }[]>;
+    removeHandle(handle: string): Promise<void>;
+    renameHandle(oldHandle: string, newHandle: string): Promise<void>;
+    deleteHistoryEntry(handle: string, previousHash: string): Promise<void>;
+}
+
+export { AbstractSqlEngine as A, type DOTSMetadata as D, MCard as M, type Page as P, type StorageEngine as S };