# MCard Type System: Types as Primitive Functions
In the MCard Agentic OS, the type system is structurally integrated with the Kenotic conversational grammar defined in `governance/clm_reserved_words.yaml`.
**The Paradigm:** Every type is a reserved word, and every reserved word is a primitive function.
A primitive function evaluates deterministically to a static state (a number or an MCard) that requires no further evaluation. By declaring a type within a CLM manifest, you are explicitly revealing its functionality and binding it to the structural transition matrix governed by the OS.
### Function-Number Duality
All data in CLM falls into exactly two categories:
- **Number (MCard)**: A static, content-addressed data image. It has a `hash`, `content`, and `g_time`. It requires no further evaluation.
- **Function (PCard)**: A causal relation that transforms inputs to outputs. It contains `abstract_spec`, `concrete_impl`, and `balanced_exp`.
The Root Type (`meta/type.yaml`) is the universal classifier that determines which category a given payload belongs to.
### Inspiration: Cubical Type Theory & The Dependency Lattice
Partially inspired by **Cubical Type Theory**, this language enforces a strict rule: **Every type must be explicitly defined.**
If a type has not been defined first in the vocabulary (by having an explicit `.yaml` definition in the `types/` directory), it is inadmissible at the syntactical level.
This strict requirement creates a fully traceable **Lattice of Dependency** (rather than just a simple tree). Much like the dependency management structure of a `make` program, the evaluator explicitly checks these dependencies to reach any given state. Because every execution trace is bounded by `pre` and `post` conditions (where the `post` condition serves as the top/bottom of the finalized judgment), the OS can guarantee that every reachable state is permanently captured within this formal lattice.
## The 4-Tier Universe Hierarchy
Types are organized into **universe levels** to prevent Girard's paradox. A type at level $N$ can only reference types at level $N-1$ or below.
### Level 0: `/primitives` (Terminal States)
Static values that resolve immediately. These map to `valid_types` and `categorical_types` in the governance dictionary.
- `string.yaml`, `integer.yaml`, `float.yaml`, `boolean.yaml`
- `list.yaml`, `map.yaml`
- `blob.yaml`
### Level 1: `/meta` (Ontological Roots)
The foundational reserved words defining the Triad and the grammar of the OS. Their fields reference Level 0 primitives.
- `type.yaml`: The universal namespace classification anchor.
- `clm.yaml`: The overall grammar matrix ($A \times C \times B$).
- `mcard.yaml`: The static state function (The Monad / Number).
- `pcard.yaml`: The transition function (The active bridge / Function).
- `vcard.yaml`: The verification function (The Boolean Lean bound).
### Level 2: `/runtime` (Execution Mechanics)
Types defining operational verbs and actor models. Their fields reference Level 0 and Level 1 types.
- `clmEval.yaml`: The shell meta-evaluator trigger.
- `evaluate.yaml`: The action verb executing the PTR loop.
- `agent.yaml`: The identity representation (EOA/CA) required for VCard verification.
### Level 3: `/governance` (Policy Constraints)
Governance types that enforce integrity, authorization, and telemetry rules across Level 0–2 types.
- `verify_authorization.yaml`, `general_file_integrity.yaml`, etc.
## Type Manifest Schema
Every type manifest MUST include a `schema` section declaring the structural contract. This enables runtime type validation via `validate_type()`.
```yaml
# Example: types/meta/mcard.yaml (target structure)
clm:
abstract_spec:
context: "..."
goal: "..."
success_criteria:
- "..."
concrete_impl:
runtime: system
operation: type_validator_mcard
schema:
required_fields:
- name: "hash"
type: "string"
description: "SHA-256 content address"
- name: "content"
type: "blob"
description: "The payload content"
- name: "g_time"
type: "string"
description: "Generalized timestamp"
process:
type: shell
script: |
type_validator_mcard() { ... }
balanced_exp:
tested_cases: [...]
```
## Baldwin Operators as Type-Level Manipulators
The type lattice is not static — it evolves through six **Baldwin Modularity Operators** that manipulate the namespace structure of CLM types. These operators serve as the **elementary arithmetic of the function space**, operating directly on the polynomial $P(X) = \sum A_i X^{C_i}$ that every CLM represents:
| `split` | Decompose a CLM type into A/C/B sub-types | Factoring ($\div$) |
| `exclude` | Remove a field from a type manifest | Subtraction ($-$) |
| `substitute` | Swap the `concrete_impl` of a type | Substitution ($=$) |
| `augment` | Add fields or test cases to a type | Addition ($+$) |
| `invert` | Promote a nested value to `success_criteria` | Inversion ($^{-1}$) |
| `port` | Migrate a type to a new runtime environment | Translation ($\rightarrow$) |
Each operator maps to a CLM dimension ($A$/$C$/$B$) and a Reverse Trivium learning phase, making the type system simultaneously a **naming structure** (namespace), a **mathematical structure** (polynomial), and a **pedagogical structure** (Trivium). Evidence is tracked through `handle_history` — any type mutation produces an audit trail.
## `lattice/`: the runtime contract, ratchets, and conformance vectors
`types/lattice/` holds the data the three runtimes must agree on. Generators in `tools/types/` project it into each kernel, and guards in `tools/guards/` hold the tree to it. Since Sprints `592..601` it is also where contract-owned values are authored.
| `runtime_contract.json` | The runtime contract (`INV-489`): environment variables, the Tri-DB, the canonical DDL statements projected from `schema/mcard_schema.sql`, URI schemes, hash algorithms, exit codes, SQLite result codes, typed `parameters` with refinement bounds, route-handle outcomes, application `configuration`, `vocabulary`, and `signature_defaults`. `tools/types/sync_runtime_contract.py --write` projects it; `--check` fails on drift. |
| `dispatch_catalog.json`, `dispatch_catalog.schema.json` | One canonical id (`clm.<area>.<name>`) per production operation, with module paths and operation names as aliases, verification policy, and pre and post gates (`INV-600`). `tools/types/sync_dispatch_catalog.py` projects it. |
| `dispatch_surface_inventory.json` | Which runtimes implement each catalog id, and the binding file in each. |
| `execution_receipt.schema.json` | The execution receipt, including the optional `parameter_context_hash` (`INV-597`) and `dispatch_catalog_hash` (`INV-600`) fields, omitted when unset so earlier receipt hashes do not move. |
| `parameter_boundary.json` | The only kernel modules allowed to read the process environment directly (`INV-596`). |
| `kenotic_seed.json` | At most twelve reasoned bootstrap values the kernel may hold before its contract loads (`INV-592`). |
| `kenotic_deny_list.json` | Domain nouns (model ids, provider URLs, ports) that must not appear in kernel production code, with reasoned exceptions (`INV-598`). |
| `literal_ledger.json`, `literal_ledger_floor.json`, `literal_ledger_targets.json`, `literal_ledger_reconciliation.json` | The literal inventory, its shrink-only per-runtime, per-class floor, the graduation targets the floor must meet, and the reasons for divergence from the reference counts (`INV-592`, `INV-601`). |
| `golden_hash_vectors.json` | Frozen content hashes for the canonical fixtures in every algorithm and runtime (`INV-592`). |
| `canonical_ddl_exceptions.json` | Production files still allowed to declare a canonical Triad table by hand; currently empty (`INV-594`). |
| `consumer_compat_0_0_21.json` | The `0.0.21` deprecation window: deprecated aliases, retired exports, and environment alias splits, each with `remove_in` (`INV-593`, `INV-599`, `INV-600`). |
| `bench_contract_baseline.json`, `bundle_size_baseline.json`, `storage_concurrency_baseline.json` | Performance baselines for `make bench-contract`, the TypeScript bundle size, and `make bench-storage-concurrency`. |
| `vectors/parameter_context_precedence.json` | `ParameterContext` precedence and MISU bottom-narrowing cases replayed in all three runtimes (`INV-596`). |
| `vectors/param_roundtrip.json` | Each contract parameter reified as a `PrimitivePCard` `TokenMCard`, with the canonical bytes and BLAKE3 digest every runtime must reproduce (`INV-597`). |
| `vectors/dispatch_witness/` | Per-operation witness vectors: identical exit codes, output digests, and errors across Python, Rust, and TypeScript (`INV-600`). |
| `vectors/env_alias_vectors.json` | Canonical-first environment resolution and one-version alias diagnostics (`INV-593`). |
`kernel/clm_rust_core/types/` is the crate's packaged copy of this directory, refreshed by the packaging step (`rsync -aL --delete types/ kernel/clm_rust_core/types/` in `tools/make/packaging.mk`); the generators keep `lattice/runtime_contract.json`, its `vectors/`, and `lattice/dispatch_catalog.json` mirrored on every `--write`, and the crate compiles the dispatch catalog in with `include_str!`.
## Engineering Roadmap
| Type manifests declared | ✅ Done | All 15 types have YAML manifests |
| Schema formalization | ✅ Sprint 4 | Machine-readable `schema.required_fields` added |
| Type registry | ✅ Sprint 4 | Auto-discover and resolve types at runtime |
| Baldwin operators | ✅ Sprint 8 | Six modular operators for type-level manipulation |
| Script hardening | ✅ Sprint 9 | Shared utilities, shellcheck-clean, clm_log, grammar guards |
| Content type manifests | 🔜 Sprint 10 | `types/content/` — MIME types as first-class type entries |
| Content interpreter | 🔜 Sprint 10 | Registry-driven detection, validation, structured detectors |
| Lattice enforcement | 🔮 Sprint 11 | DAG validator for universe stratification |
| Multi-modal types | 🔮 Sprint 12 | `audio`, `video`, `3d_model` content type manifests |