{"id":50757640,"url":"https://github.com/yumin-chen/cml","last_synced_at":"2026-06-11T06:32:12.593Z","repository":{"id":333479162,"uuid":"1137472491","full_name":"yumin-chen/cml","owner":"yumin-chen","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-19T18:37:36.000Z","size":67,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-19T19:26:24.364Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yumin-chen.png","metadata":{"files":{"readme":"ReadMe.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-19T12:14:39.000Z","updated_at":"2026-01-19T18:37:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yumin-chen/cml","commit_stats":null,"previous_names":["yumin-chen/cml"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/yumin-chen/cml","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yumin-chen%2Fcml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yumin-chen%2Fcml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yumin-chen%2Fcml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yumin-chen%2Fcml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yumin-chen","download_url":"https://codeload.github.com/yumin-chen/cml/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yumin-chen%2Fcml/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34186385,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-11T06:32:12.480Z","updated_at":"2026-06-11T06:32:12.571Z","avatar_url":"https://github.com/yumin-chen.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"---\nVersion: 0.0.2\nDate: 2025-01-20\nKeywords:\n  - Meta-Programming\n  - Canonical Serialisation\n  - Rust ADT\n  - Triple Projection\n---\n\n# CML\n\n\u003e The missing *Code-as-Data* framework designed for multi-stage meta-programming that treats *\"Code\"* as immutable, structurally typed, content-addressed, and context-dependent values.\n\n**CML (Computation Modelling Language)** is a component-driven meta-programming code-as-data markup language that declaratively states what the modelled computation does. \n\nSyntactically, CML is a subset and an extension of [XML (Extensible Markup Language)](https://en.wikipedia.org/wiki/XML) as its cannonical syntax serialisation format. However, a valid CML document can be carried in various formats of code artefacts, such as: `.cml` or `.xml` or `.html` or `.md` or `.mdx` or `.tsx` or `.ts` or `.jsx` or `.js`, because any CML document can be defined by the dynamic runtime meta component that \"compiles\" (or executes/evaluates) to a static `CmlElement`. The same \u003cCmlElement\u003e represented in XML can be stored in a Markdown document with YAML frontmatter metadata, or as an MDX document to have JS-in-CML, or as an JSX document to do CML-in-JS, or just pure vanila JavaScript/TypeScript but you use a helper function to `createElement`.\n\nSound familiar? This gives us the entire component-centric development ecosystem. We can take advantage of frameworks like Panda.js for static analysis and our CmlElement actually becomes the meta-language.\n\nIf you want a more technical definition: CML is  a closed, deterministic algebra for representing executable semantics as pure data. Unlike traditional languages that store logic as text, CML stores logic as a Merkle-DAG and state as a Ledger of Ref-Transitions. \n\nThis ensures that:\n- **Logic is immutable and verifiable** (content-addressed Merkle-DAG)\n- **System remains dynamic and collaborative** (Git-like ref namespace)\n- **Truth is distributed** (no central authority required)\n- **State is reconcilable** (Desired vs Observed feedback loop)\n\n## The 4-Layer MOF Stack: Multi-Stage Programming Framework\n\nCML extends the standard Meta-Object Facility (MOF) to account for decentralised state management:\n\n| Layer | Domain | Responsibility | Stability |\n|-------|--------|----------------|-----------|\n| **M3** | **Meta** | PKL Schemas defining the rules of CML | Constant |\n| **M2** | **Language** | Component Definitions (e.g., MathOp, Unit) | Versioned |\n| **M1** | **Logic** | The Merkle-DAG of specific logic instances | Immutable (CID) |\n| **M4** | **State** | The Git-Ref namespace mapping Names to CIDs | Fluid (DID) |\n\n### Storage \u0026 Data Rendering: Triple-Projection Strategy\n\nCML uses a **Triple-Projection strategy** to ensure interoperability across human, machine, and database environments:\n\n#### M1 Blob Store (Merkle-DAG)\n- **Format**: `pklbinary` (deterministic MessagePack)\n- **Indexing**: BLAKE3 Content-Identifier (CID)\n- **Invariant**: Only `@Semantic` children are hashed. Metadata (M4) is excluded to maintain CID stability\n\n#### M4 Relational Layer (PostgreSQL/SQLite)\n- **Ref Table**: Maps `did + ref_path` to `target_cid`\n- **Assertion Log**: An append-only table of signed transitions (the COB ledger)\n- **Interop**: Uses BYTEA for Postgres and BLOB for SQLite to store M1 payloads\n\n#### Recursive Identity Calculation\nEvery CML node's identity is calculated as:\n\n```\nCID = BLAKE3(type.cid + children.cids)\n```\n\nIf the node is a `CmlPrimitiveNode` (Leaf), the recursion terminates by hashing the raw value.\n\n### The Reconciliation Engine: Dynamic Reality Management\n\nCML manages \"Dynamic Reality\" through a **Desired vs. Observed feedback loop**:\n\n#### State Definitions\n- **Desired State**: The \"Intent\" authored by a user/controller, stored in `refs/cml/desired/`\n- **Observed State**: The \"Reality\" witnessed by an M0 agent, stored in `refs/cml/observed/`\n- **Status/Delta**: The computed difference between Intent and Reality\n\n#### The Reconciliation Node\nA specialised M₁ node that takes two M₄ pointers as input:\n\n```\nStatus = Logic(DesiredRef, ObservedRef)\n```\n\nThis enables continuous reconciliation between intended state and actual system state.\n\n### Git Interoperability: The Social Layer\n\nCML uses the **Git refs/ namespace** as a decentralised symbol table:\n\n- **Namespace**: `refs/cml/`\n- **Heads**: `heads/main` points to the latest root CmlManifest\n- **COBs**: `cobs/{uuid}` tracks the head of collaborative objects (issues, PRs, state logs)\n\nThis enables decentralised collaboration without requiring central coordination.\n\n### Semantic Promotion: M2 Layer Responsibility\n\nThe M2 layer (PKL) is responsible for \"promoting\" XML attributes into Merkle child nodes:\n\n**Input**: `\u003cLiteral value=\"10\" author=\"Alice\" /\u003e`\n- **M1 Process**: `value` is wrapped in a `CmlPrimitiveNode` and hashed\n- **M4 Process**: `author` is written to the SQL `m4_assertions` table\n\nThis ensures clean separation between semantic content (hashed) and metadata (not hashed).\n\n### M1: Logic Layer - The Merkle-DAG\n\n- **Entity**: **Specific computational trees and expressions**\n- **Role**: Pure mathematical logic - the actual computational meaning\n- **Identification**: CID (Content Identifier / Hash)\n- **Storage**: Immutable Merkle-DAG with content-addressed identity\n- **Key Insight**: CML artifacts are pure data that model computation but don't execute themselves\n\n### M4: State Layer - The Git-Ref Namespace\n\n- **Entity**: Named References, Assertions, COB State\n- **Role**: Maps names to CIDs, enabling mutable references to immutable logic\n- **Identification**: DID + RefName (e.g., `alice/repo/issues/1/status`)\n- **Storage**: Relational database with append-only assertion log\n- **Key Insight**: Provides collaborative state management without contaminating algebraic truth\n\n## Strategic Road Map\n\n### Phase 1: PKL Foundation\n- Finalise PKL M₃ base classes and `@Semantic` annotation\n- Implement semantic promotion for XML attributes\n\n### Phase 2: Storage Layer\n- Build the SqlRenderer for Postgres/SQLite binary interoperability\n- Implement M1 blob store with BLAKE3 indexing\n\n### Phase 3: State Management\n- Implement the Git Ref-Watcher to sync M₄ state into the relational database\n- Build reconciliation engine for Desired vs Observed state\n\n### Phase 4: Analysis \u0026 Tooling\n- Develop the Panda.js Static Analysis suite for \"Delta\" detection across repositories\n- Build collaborative development tools\n\n## � Why the Hermetic Seal at M3 is Critical\n\n**M3 Reflexivity Maintains Algebraic Purity:**\n- **The Theory**: M3 describes itself using its own rules - the structural \"ladder\" stops here\n- **The Seal**: M3 is the highest layer that deals with pure computation - no social concerns\n- **The Benefit**: Any machine running the same M1 CID gets identical results, regardless of social context\n\n**M4+ Handles Social Coordination:**\n- **M4 (CML-COB)**: Manages collaborative operations without polluting algebraic truth\n- **M5 (User Node)**: Provides actor identity for signing operations\n- **The Separation**: Social concerns never leak into the pure mathematical layers\n\n## 🚫 Why We Must Maintain the Seal\n\nViolating the hermetic seal creates \"Invariant Collapse\":\n\n1. **Algebraic Contamination**: If social concerns leak into M1-M3, mathematical truth becomes context-dependent\n2. **CID Instability**: If M1 artifacts contain social metadata, identical logic produces different CIDs\n3. **Reproducibility Loss**: If M3 rules depend on social context, the same code behaves differently across systems\n\n## 📐 The Boundary: Algebraic vs Social Truth\n\n| Property | Localised (M1-M3) | Social (M4-M5) |\n|----------|-------------------|----------------|\n| **Identity** | CID (Hash of the code) | DID (Identity of the actor) |\n| **Stability** | Immutable (Algebraic) | Mutable (Historical/Versioned) |\n| **Context** | \"What is the result of 1+1?\" | \"Who says 1+1 should be the rule?\" |\n| **Storage** | Content-Addressed Blobs | Collaborative Object (COB) Logs |\n| **Truth Type** | Mathematical/Universal | Social/Contextual |\n\n## Complete System: Pure + Social\n\nWith the hermetic seal properly maintained:\n\n- **Pure Algebraic Truth (M1-M3)**: Universal, immutable, context-free mathematical logic\n- **Social Coordination (M4-M5)**: Collaborative processes, governance, and actor identity\n- **The Bridge**: M4 carries pure M1 logic into social contexts without contamination\n\n### 🔒 M3: Meta-CML (The \"Physics\" - Hermetic Seal)\n- **Entity**: The CmlComponent Base Class / Rust enum system\n- **Role**: Self-describing rules that define component structure - the \"physics\" of modeling\n- **Identification**: FQN (Fully Qualified Name) of the Meta-type  \n- **Why the seal?** M3 is the highest layer dealing with pure computation - no social concerns\n- **Example**: The Rust `CmlNode` enum defining universal component rules\n\n### 🔒 M2: CML Metamodel (The \"Grammar\" - Pure Algebraic)\n- **Entity**: Specific CML node type definitions (e.g., Unit, BinOp, Literal)\n- **Role**: The Language Dictionary - defines semantics of mathematical operations\n- **Identification**: The TagType name\n- **Why pure?** Mathematical operations have universal meaning regardless of social context\n- **Example**: The definition of what a `BinOp` is and how it behaves mathematically\n\n### 🔒 M1: CML Artifacts (The \"Frozen Snapshot\" - **WHERE CML LIVES**)\n- **Entity**: **Your specific, content-addressed logic values**\n- **Role**: Pure mathematical logic - the actual computational meaning you wrote\n- **Identification**: CID (Content Identifier / Hash)\n- **Why frozen?** Mathematical truth is immutable - 2+2=4 regardless of who says it\n- **Key Insight**: Every CML artifact at M1 is pure algebraic truth with no social metadata\n- **Example**: `\u003cUnit name=\"AddTen\"\u003e...\u003c/Unit\u003e` with CID `b3a123...`\n\n### M0: Runtime (The \"Event\" - Pure Execution)\n- **Entity**: TruffleNode instances, interpreters, compilers\n- **Role**: Physical execution of mathematical operations\n- **Identification**: Memory Address / Pointer\n- **Why separate?** Execution tools (M0) operate on pure mathematical logic (M1) without contaminating it\n\n## The \"Self/This\" Problem and M4 Solution\n\n### The Problem\nTraditional systems cannot represent collaborative, dynamic references within immutable mathematical structures:\n- A CID cannot point to \"the current price\" (mutable)\n- A CID can only point to a specific observation of a price (immutable)\n\n### The M4 Solution: Named References\nM4 provides a **registry** that maps named references to current CIDs:\n\n```\nRef:CurrentPrice → CID_987\nRef:UserStatus → CID_abc\nRef:IssueTitle → CID_def\n```\n\nWhen CML logic contains `self.amount`, the system:\n1. **M1**: Recognizes this as a `CmlReferenceNode` (syntactically complete)\n2. **M4**: Looks up `Lookup(Subject: M4_CONTEXT_SELF, Path: [\"amount\"])` \n3. **Resolution**: Returns the current CID that the named reference points to\n4. **M0**: Executes the resolved mathematical logic\n\n### COB (Collaborative Object) Implementation\nFor collaborative objects like Issues or Tasks:\n- **M1**: Contains the computational logic (empty for pure data objects)\n- **M4**: Contains the assertion log with operations like `SET_TITLE`, `UPDATE_STATUS`\n- **Resolution**: System reduces M4 log to find latest state and returns corresponding M1 node\n\n## M4 SQL Schema for Named References\n\n```sql\n-- M4: Named reference registry (Git-like refs)\nCREATE TABLE m4_refs (\n    did TEXT NOT NULL,             -- Decentralised identifier\n    ref_path TEXT NOT NULL,        -- e.g., 'desired/tax-rate'\n    target_cid TEXT NOT NULL,      -- Points to current M1 state\n    seq_number BIGINT NOT NULL,    -- Incremental version for COB ordering\n    PRIMARY KEY (did, ref_path)\n);\n\n-- M1: Pure mathematical logic storage\nCREATE TABLE m1_blobs (\n    cid TEXT PRIMARY KEY,\n    node_type TEXT NOT NULL,\n    data BYTEA NOT NULL,           -- pklbinary (MessagePack) representation\n    created_at TIMESTAMP DEFAULT NOW()\n);\n\n-- M4: Assertion log for collaborative objects (COB ledger)\nCREATE TABLE m4_assertions (\n    id SERIAL PRIMARY KEY,\n    did TEXT NOT NULL,             -- Who made the assertion\n    ref_path TEXT NOT NULL,        -- What reference was updated\n    operation TEXT NOT NULL,       -- SET, UPDATE, DELETE, etc.\n    payload_cid TEXT NOT NULL,     -- References m1_blobs.cid\n    created_at TIMESTAMP DEFAULT NOW(),\n    seq_number BIGINT NOT NULL,\n    FOREIGN KEY (payload_cid) REFERENCES m1_blobs(cid)\n);\n```\n\n### CmlReferenceNode Support\n\nThe system supports CmlReferenceNode as a \"Variable\" that the M0 Runtime fills in by looking at the M4 state:\n\n```rust\n#[derive(Debug, Clone, PartialEq, Serialise, Deserialise)]\npub enum CmlNode {\n    // ... other variants\n    Reference {\n        subject: String,    // M4_CONTEXT_SELF or specific DID\n        path: Vec\u003cString\u003e,  // [\"amount\"], [\"status\"], etc.\n    },\n}\n\n// M4 Resolution Logic\nimpl CmlNode {\n    pub fn resolve_reference(\u0026self, m4_context: \u0026M4Context) -\u003e Result\u003cCID, ReferenceError\u003e {\n        match self {\n            CmlNode::Reference { subject, path } =\u003e {\n                let ref_path = format!(\"{}/{}\", subject, path.join(\"/\"));\n                m4_context.lookup_ref(\u0026ref_path)\n            },\n            _ =\u003e Err(ReferenceError::NotAReference)\n        }\n    }\n}\n```\n\n### The \"Self/This\" Problem Solution\n\nWhen CML logic contains `self.amount`, the system:\n\n1. **M1**: Recognizes this as a `CmlReferenceNode` (syntactically complete)\n2. **M4**: Looks up `Lookup(Subject: M4_CONTEXT_SELF, Path: [\"amount\"])` \n3. **Resolution**: Returns the current CID that the named reference points to\n4. **M0**: Executes the resolved mathematical logic\n\n### COB (Collaborative Object) Implementation\n\nFor collaborative objects like Issues or Tasks:\n\n- **M1**: Contains the computational logic (empty for pure data objects)\n- **M4**: Contains the assertion log with operations like `SET_TITLE`, `UPDATE_STATUS`\n- **Resolution**: System reduces M4 log to find latest state and returns corresponding M1 node\n\nExample COB workflow:\n1. Look up the DID of the Issue\n2. Fetch the M4 Assertion Log (the COB)\n3. Reduce the log to find the latest SET_TITLE operation\n4. Return the M1 Leaf Node contained in that operation\n\n## 🔑 Why M1 is the \"CID Layer\"\n\nM1 is the layer where **Content Addressing (CID) becomes the primary citisen**.\n\n- **At M3/M2**: You are defining the shape of the language\n- **At M1**: You are using that shape to create a specific **Value**\n- **CID Assignment**: Because every CML artifact at M1 is a pure value, it gets a CID\n- **Immutability**: If you change a single character, you create a **new** M1 artifact with a different CID\n\n## 📂 The Distinction: M1 (Fact) vs. M4 (Assertion)\n\n| Layer | What Lives Here | Example |\n|-------|----------------|---------|\n| **M1 (The Artifact)** | `CID_Alpha` — \"A function that adds 1.\" | Timeless, Anonymous, Absolute |\n| **M4 (The Assertion)** | `DID_Alice` says \"This CID_Alpha is version 1.0 of my math library.\" | Social context, authorship, versioning |\n\n**The M1 layer is \"Blind\"** - it doesn't know who created it or why. It only knows its own algebraic truth. This makes CML artifacts perfectly interoperable without the \"baggage\" of social context.\n\n## 🧬 How CML \"Operates\" at M1\n\nBecause CML artifacts are at M1, they are **Homoiconic** (Code is Data):\n\n- **Your program**: A Tree of CIDs\n- **A \"Compiler\"**: Just another M1 artifact that takes a CML Tree as input\n- **Self-describing**: The compiler logic is also at M1, making the entire system reflexive\n\n## The Complete System: Static + Dynamic\n\n**CID + DID = Complete System**\n\n- **CID (M1-M3)**: Universal Truth - \"This logic is always this logic\"\n- **DID/Ref (M4)**: Situational Truth - \"This is what Alice currently thinks the status is\"\n\nBy separating them, CML builds a system that is:\n- **As stable as a mathematical proof** (M1-M3)\n- **As dynamic as a Git repository** (M4)\n\n### Practical Example: Collaborative Tax Calculator\n\n**M3 (Physics)**: Universal rules ensure all tax calculations follow component structure rules\n**M2 (Biology)**: The `Multiply` operation has universal mathematical meaning  \n**M1 (Anatomy)**: The logic `Amount * 0.21` produces `CID_b3a123...`\n**M4 (Memory)**: `Ref:TaxRate → CID_b3a123...` allows collaborative updates to tax logic\n**M0 (Event)**: Any CPU executing the resolved CID produces identical results\n\n**Key Insight**: By separating static mathematical truth (CID) from dynamic collaborative state (DID/Ref), the system ensures computation is universal while enabling practical collaboration.\n\n## Summary Mapping Table\n\n| Layer | Name | Identity | Primary Key | Responsibility |\n|-------|------|----------|-------------|----------------|\n| **M4** | **CML State** | **DID + RefName** | **Named Refs** | Memory: Named references to current CIDs |\n| **M3** | **Meta-CML** | **Code/Schema** | **Reflexive Rules** | Physics: Universal component structure rules |\n| **M2** | **CML Schema** | **CID** | **Component Definitions** | Biology: Mathematical operation definitions |\n| **M1** | **CML Logic** | **CID** | **Specific Trees** | Anatomy: Immutable computational expressions |\n| **M0** | **Runtime** | **Pointer** | **Execution** | Event: CPU executing the resolved mathematics |\n\n## 2. Ontological Commitments\n\n### 2.1 What CML Is\n\n**CML operates as a 4-layer dynamic MOF architecture that bridges static mathematical truth with collaborative state:**\n\n#### M4 — CML State (The \"Memory\")\n- **The Causal Layer**: Named references and collaborative assertions\n- **Dynamic State**: Git-like refs that point to current CIDs\n- **Artifact**: Named reference registry with DID-based ownership\n- **Role**: Bridges static CIDs with mutable collaborative state\n\n#### M3 — Meta-CML (The \"Physics\")\n- **The Reflexive Meta-Metamodel**: Defines \"What is a Component?\" using itself\n- **Structural Rules**: Universal component structure rules\n- **Artifact**: PKL-based self-describing meta-metamodel\n- **Role**: Language of Languages - defines the \"physics\" of modeling\n\n#### M2 — CML Schema (The \"Biology\")\n- **Component Definitions**: The standard library of component types\n- **Mathematical Operations**: Defines the semantics of specific operations\n- **Artifacts**: `Unit`, `BinOp`, `Literal`, `Var`, `Invoke` definitions\n- **Role**: The vocabulary that validates MDX tags and defines execution semantics\n\n#### M1 — CML Artifacts (The \"Identity\")\n- **Algebraic Identity**: The immutable, \"cold\" representation of logic\n- **Pure Values**: CML artifacts are values, not processes - they don't \"run\"\n- **Unique Identity**: Each instance has a specific CID (Content Identifier)\n- **Role**: Stable \"truth\" of the program structure - **this is where CML lives**\n- **Key Insight**: The separation between representation (M1 values) and realisation (M0 execution)\n\n#### M0 — TruffleNode (The \"Execution\")\n- **Physical Execution**: The \"hot\" object living in GraalVM/JVM heap\n- **Runtime Optimisation**: JIT-compiled code and type-profiled data\n- **Machine Identity**: Memory address / pointer in running system\n- **Role**: High-performance CPU reduction of the computation\n\nCML represents:\n\n- functions (as M2 tagType definitions, M1 instances)\n- control flow (as component compositions)\n- expressions (as nested CmlComponent structures)\n- types (as classification systems)\n- constraints (as logical restrictions)\n\nAs **values** with **content-addressed identity**.\n\n## 📂 The \"MDX Sandwich\" Across the Stack\n\nAn MDX file in the system is actually a \"Multi-Layer Object.\" When you save a `.mdx` file, you are saving data across three MOF layers simultaneously:\n\n| Part of the File | MOF Layer | Identifier | Role |\n|------------------|-----------|------------|------|\n| **YAML Frontmatter** | M4 (Subjective) | DID | Context: Author, Date, Social Tags |\n| **XML `\u003cBody\u003e`** | **M1 (Model)** | **CID** | **The CML Artifact: The Merkle-DAG logic** |\n| **Imported Tags** | M2 (Metamodel) | Type FQN | Grammar: The definitions of the tags used |\n\n### 🎨 Usage: Building the AST with TSX\n\nBecause we use the createElement signature, you can use TSX (TypeScript JSX) to write CML:\n\n```typescript\n/** @jsx createElement */\n\nconst MyComputation = (\n  \u003cUnit name=\"Global_Calc\" author=\"did:key:alice\"\u003e\n    \u003cPrimitiveValue value={100} /\u003e\n    {/* This Ref node has a CID based on the string \"TAX_RATE\",\n         but its value is resolved via the M4 Repo lookup */}\n    \u003cNamedRef name=\"TAX_RATE\" /\u003e\n  \u003c/Unit\u003e\n);\n\nconsole.log(MyComputation.cid); // Deterministic M1 Identity\n```\n\n### 📝 Key Implementation Notes\n\n- **Stable Ordering**: Children are hashed in the order provided (CML is often non-commutative)\n- **Referential Stability**: Identical trees produce identical CIDs, enabling structural deduplication\n- **Truffle-Ready**: Output serializes directly to pklbinary format with pre-calculated CIDs\n\n## 🔑 Key Insight: CML is a \"Model of Computation,\" Not a \"Mechanism of Execution\"\n\nIn traditional programming (C++, Java), an executable is a file where the meaning of the code and the instructions for the CPU are smashed together into a single blob of binary.\n\n**In CML, we decouple them.** CML artifacts are pure data that model computation - they don't execute themselves.\n\n### The M0/M1 Separation\n\n| Component | Layer | Nature | Analogy |\n|-----------|-------|--------|---------|\n| **CML Node** | M1 | A static, immutable Merkle-tree (CID) | A blueprint for a car |\n| **Interpreter** | M0 | A live process that \"reads\" the tree | A person following the blueprint to build/move the car |\n| **Compiler** | M0 | A process that \"translates\" the tree into Machine Code | A factory that turns the blueprint into a finished physical car |\n\n### The CML Runtime Interpreter (M0)\n\nThe Interpreter is a **Universal Reader** - a program (likely written in Go, Rust, or Zig) that performs a Tree-Walk:\n\n1. **Input**: A CID (the \"entry point\" of the M1 model)\n2. **Process**: \n   - Resolve the CID to its CML Value\n   - Look at the nodeType (M2)\n   - Perform the logic associated with that type (e.g., if BinOp(ADD), find the children and add them)\n3. **Lifecycle**: Lives as a running process in memory with \"State\" that is not part of CML (clock time, stack pointer)\n\n### The CML Static Compiler (M0)\n\nThe Compiler is a **Translator** - it doesn't \"run\" the logic; it transforms the Merkle-DAG into CPU-specific format:\n\n1. **Input**: A CID\n2. **Process**: Traverses the M1 graph and emits machine instructions that represent the same algebraic truth\n3. **Output**: A non-CML artifact (an .exe or .wasm file)\n\n## 🛡️ \"CML is not executable\" — Clarifying the Paradox\n\nWhen we say \"CML is not executable,\" we mean **the data structure itself has no agency**:\n\n1. **Safety**: A CML file sitting on your disk can never \"harm\" your computer because it's just a value (like a JSON file). It only \"does\" something when an Interpreter decides to process it.\n\n2. **Portability**: Because CML is just a model of computation, you can write one Interpreter in Python and another in Rust. They will both produce the exact same result because the M1 Value is the single source of truth.\n\n**Example**: Think of an SVG file. Is an SVG \"executable\"? No. It's just a text file (M1). But when a Browser (M0 Interpreter) reads that text, it \"executes\" the drawing commands to show you a picture. **CML is like \"SVG for Logic.\"**\n\n## 🧠 Why \"Computation Modeling Language\" Makes Sense\n\nThe computation is executable in principle, but the artifact is pure data:\n\n- **Logic (M1)**: `f(x) = x + 1` (This is a static fact)\n- **Computation (M0)**: The CPU actually flipping bits to turn 5 into 6\n\nBy keeping the \"Model\" (M1) separate from the \"Execution\" (M0), you gain **Merkle-Stability**:\n- You can sign the model\n- Cache it  \n- Verify it across a network\n- All without ever needing to run it\n\nYou only \"Realise\" the computation at the last possible second.\n\n## 🌟 Summary: The \"Living\" System\n\n- **CML (M1)**: The \"Spirit\" / The Logic (Immutable CID)\n- **Interpreter/Compiler (M0)**: The \"Body\" / The Physicality (Transient Process)\n\n### 2.2 CML in the MDX Ecosystem\n\n**CmlComponent** is the M3-level formalisation of MDX Component concept, designed for content-addressed, computational environments:\n\n#### The Three Sectors of CmlComponent\n\n1. **Hashed Body (Children)**: Core identity - if children change, CID changes\n2. **Non-Hashed Metadata (Props/Attributes)**: XML attributes and YAML frontmatter excluded from CID\n3. **tagType (FQN)**: Fully-qualified name ensuring type identity uniqueness\n\n#### Strategic Ontology Mapping\n\n| Concept | MDX Equivalent | CML/MOF Positioning | Role |\n|---------|----------------|-------------------|------|\n| **CmlComponent** | React.Component base | M3 (Meta-CML) | Defines the \"Rules\" (Hashed vs. Non-Hashed) |\n| **tagType** | A specific .jsx file | M2 (CML Core) | Defines a specific \"Symbol\" (Unit, Literal) |\n| **XML Tag** | `\u003cMyComp /\u003e` | M1 (Artifact) | The specific \"Logic\" with a unique CID |\n\n---\n\n### 2.2 What CML Is Not\n\nCML does **not** represent:\n\n- runtime state or execution semantics\n- threads\n- memory\n- IO\n- system calls\n- time\n- authorship\n- mutation of reality\n\nThose belong to **M0** or **M4**.\n\n---\n\n## 3. Core Design Rules\n\n### Rule 1 — Value Semantics Only\n\nEvery CML node is a **value**.\nNodes do not “run”, “execute”, or “happen”.\n\n---\n\n### Rule 2 — Closed Algebra\n\nOnly the node kinds defined in this specification are valid.\nNo user-defined node kinds are allowed at M3.\n\n---\n\n### Rule 3 — Structural Determinism\n\nTwo CML documents with identical structure and content **must** serialise to the same canonical form and produce the same CID.\n\n---\n\n### Rule 4 — No Identity, No Time\n\nCML nodes do not contain:\n\n- timestamps\n- authors\n- environment references\n- mutable identifiers\n\n---\n\n## 4. Document Structure\n\n```xml\n\u003cCML version=\"0.1\"\u003e\n  \u003cUnit\u003e...\u003c/Unit\u003e\n\u003c/CML\u003e\n```\n\nA CML document contains **one or more `Unit` nodes**.\n\n---\n\n## 5. The Closed Algebra of Nodes\n\nThe following node kinds constitute the **complete M3 algebra**.\n\n---\n\n## 6. Unit\n\n### Definition\n\nA `Unit` represents a callable computational value.\n\n### Properties\n\n* name\n* parameters\n* return type\n* body\n\n### Semantics\n\nA `Unit` denotes a **pure mapping** from inputs to output.\n\n### XML Form\n\n```xml\n\u003cUnit name=\"add\"\u003e\n  \u003cParams\u003e\n    \u003cBinding name=\"a\" type=\"Int32\"/\u003e\n    \u003cBinding name=\"b\" type=\"Int32\"/\u003e\n  \u003c/Params\u003e\n  \u003cReturns type=\"Int32\"/\u003e\n  \u003cBlock\u003e...\u003c/Block\u003e\n\u003c/Unit\u003e\n```\n\n---\n\n## 7. Block\n\n### Definition\n\nA `Block` is an ordered list of statements.\n\n### Properties\n\n* sequence of statements\n\n### Semantics\n\nA block denotes **sequential composition**.\n\n### XML Form\n\n```xml\n\u003cBlock\u003e\n  \u003cBinding name=\"x\" type=\"Int32\"/\u003e\n  \u003cReturn\u003e\n    \u003cVar name=\"x\"/\u003e\n  \u003c/Return\u003e\n\u003c/Block\u003e\n```\n\n---\n\n## 8. Expression (Abstract)\n\n### Definition\n\nAn `Expression` denotes a value.\n\n### Semantics\n\nExpressions are **side-effect-free** and **total**.\n\n### Subtypes\n\n* Literal\n* Var\n* Call\n* BinOp\n* Match\n\n---\n\n## 9. Call\n\n### Definition\n\nA `Call` represents function application.\n\n### Properties\n\n* target\n* arguments\n\n### Semantics\n\nA call denotes **evaluation of a Unit value**.\n\n### XML Form\n\n```xml\n\u003cCall target=\"add\"\u003e\n  \u003cArg\u003e\u003cVar name=\"a\"/\u003e\u003c/Arg\u003e\n  \u003cArg\u003e\u003cVar name=\"b\"/\u003e\u003c/Arg\u003e\n\u003c/Call\u003e\n```\n\n---\n\n## 10. Loop\n\n### Definition\n\nA `Loop` represents bounded or unbounded iteration.\n\n### Properties\n\n* kind\n* condition or iterator\n* body\n\n### Semantics\n\nA loop denotes **recursive structural repetition**, not runtime looping.\n\n### XML Form\n\n```xml\n\u003cLoop kind=\"while\"\u003e\n  \u003cCondition\u003e\n    \u003cBinOp op=\"\u003c\"\u003e\n      \u003cVar name=\"i\"/\u003e\n      \u003cLiteral type=\"Int32\" value=\"10\"/\u003e\n    \u003c/BinOp\u003e\n  \u003c/Condition\u003e\n  \u003cBlock\u003e...\u003c/Block\u003e\n\u003c/Loop\u003e\n```\n\n---\n\n## 11. Match\n\n### Definition\n\nA `Match` represents structural branching.\n\n### Properties\n\n* value\n* arms\n\n### Semantics\n\nA match denotes **pattern-based selection**.\n\n### XML Form\n\n```xml\n\u003cMatch\u003e\n  \u003cValue\u003e\u003cVar name=\"x\"/\u003e\u003c/Value\u003e\n  \u003cArm\u003e\n    \u003cPattern type=\"Literal\" value=\"0\"/\u003e\n    \u003cBlock\u003e...\u003c/Block\u003e\n  \u003c/Arm\u003e\n\u003c/Match\u003e\n```\n\n---\n\n## 12. Type\n\n### Definition\n\nA `Type` is a value describing a classification of values.\n\n### Semantics\n\nTypes are **descriptive**, not enforced at runtime.\n\n### Subtypes\n\n* PrimitiveType\n* CompositeType\n* FunctionType\n* ArrayType\n* ReferenceType\n\n### XML Form\n\n```xml\n\u003cType kind=\"Primitive\" name=\"Int32\"/\u003e\n```\n\n---\n\n## 13. Constraint\n\n### Definition\n\nA `Constraint` restricts type parameters.\n\n### Semantics\n\nConstraints are **logical predicates**, not runtime checks.\n\n### XML Form\n\n```xml\n\u003cConstraint kind=\"Trait\" target=\"Comparable\"/\u003e\n```\n\n---\n\n## 14. Canonical Serialisation\n\nCML nodes are serialisable into a canonical form (e.g., canonical XML, length-prefixed binary, or JSON-LD), from which content identifiers (CIDs) are derived.\n\nCanonicalisation rules:\n\n1. Node type name\n2. Attributes sorted lexicographically\n3. Children serialised in declaration order\n4. No insignificant whitespace\n\nExample canonical form:\n\n```\nUnit(name=add,params=[Int32,Int32],returns=Int32,body=...)\n```\n\n---\n\n## 15. Hashing and Identity\n\nEach node has:\n\n* no intrinsic identity\n* identity = hash(canonical form)\n\nHashes are:\n\n* deterministic\n* content-derived\n* immutable\n\n---\n\n## 16. Interpretation Boundary\n\nCML **does not execute itself**.\n\nExecution requires:\n\n* an interpreter\n* a compiler\n* a runtime\n\nThose are **outside CML**.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyumin-chen%2Fcml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyumin-chen%2Fcml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyumin-chen%2Fcml/lists"}