# star-ga/mind-spec architecture

> Architecture diagram of the GitHub repository star-ga/mind-spec, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/star-ga/mind-spec
- Repository: https://github.com/star-ga/mind-spec

## Overview

This repository’s product is the normative MIND language specification, not a compiler implementation. Its main user workflow is to consult the language and type rules, follow the defined IR and runtime contracts, and use the standard-library and evidence documents to understand supported capabilities and guarantees. The graph also shows the small sampled Core IR prototype as a supporting internal layer. Most source excerpts are documentation; links between specification areas follow the README’s organization, and the prototype links are limited to calls visible in sampled code.

Main entry points: [`spec/v1.0/ir.md`](https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/ir.md) (Core IR), [`spec/v1.0/language.md`](https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/language.md) (Surface language), [`tools/core_ir/language.py`](https://github.com/star-ga/mind-spec/blob/main/tools/core_ir/language.py) (Expression entry), [`spec/v1.0/stdlib.md`](https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/stdlib.md) (Standard library)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language specification"]
  node_language["Surface language<br/>[language.md]"]
  node_lexical["Lexical rules<br/>[lexical.md]"]
  node_types["Types and shapes<br/>[types.md]"]
end

subgraph group_execution["Execution contracts"]
  node_ir["Core IR<br/>[ir.md]"]
  node_autodiff["Static autodiff<br/>[autodiff.md]"]
  node_runtime["Runtime interface<br/>[runtime.md]"]
  node_lowering["MLIR lowering<br/>[mlir-lowering.md]"]
end

subgraph group_evidence["Libraries and evidence"]
  node_stdlib["Standard library<br/>[stdlib.md]"]
  node_determinism["Determinism<br/>[determinism.md]"]
  node_stability["IR stability<br/>[ir-stability.md]"]
  node_artifact["Model artifacts<br/>[model-artifact.md]"]
  node_security["Security profile<br/>[security.md]"]
end

subgraph group_prototype["IR prototype"]
  node_prototype_entry["Expression entry<br/>[language.py]"]
  node_prototype_types["Type validation<br/>[type_system.py]"]
  node_prototype_ir["IR builder<br/>[core_ir.py]"]
end

node_reader(("Language reader"))

node_reader -->|"consults"| node_language
node_reader -->|"consults"| node_stdlib
node_language -->|"specifies syntax"| node_lexical
node_language -->|"uses type rules"| node_types
node_language -->|"defines representation"| node_ir
node_ir -->|"supports transforms"| node_autodiff
node_ir -->|"defines interface"| node_runtime
node_ir -->|"describes lowering"| node_lowering
node_stdlib -->|"specifies library use"| node_runtime
node_stability -->|"constrains format"| node_ir
node_artifact -->|"anchors evidence"| node_stability
node_security -->|"specifies trust"| node_artifact
node_determinism -->|"states guarantees"| node_reader
node_prototype_entry -->|"validates program"| node_prototype_types
node_prototype_entry -->|"emits operations"| node_prototype_ir
node_prototype_types -->|"materializes inputs"| node_prototype_ir

click node_language "https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/language.md"
click node_lexical "https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/lexical.md"
click node_types "https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/types.md"
click node_ir "https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/ir.md"
click node_autodiff "https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/autodiff.md"
click node_runtime "https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/runtime.md"
click node_lowering "https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/mlir-lowering.md"
click node_stdlib "https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/stdlib.md"
click node_determinism "https://github.com/star-ga/mind-spec/blob/main/determinism.md"
click node_stability "https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/ir-stability.md"
click node_artifact "https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/model-artifact.md"
click node_security "https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/security.md"
click node_prototype_entry "https://github.com/star-ga/mind-spec/blob/main/tools/core_ir/language.py"
click node_prototype_types "https://github.com/star-ga/mind-spec/blob/main/tools/core_ir/type_system.py"
click node_prototype_ir "https://github.com/star-ga/mind-spec/blob/main/tools/core_ir/core_ir.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_language,node_lexical,node_types toneBlue
class node_ir,node_autodiff,node_runtime,node_lowering toneAmber
class node_stdlib,node_determinism,node_stability,node_artifact,node_security toneMint
class node_prototype_entry,node_prototype_types,node_prototype_ir toneRose
class node_reader toneIndigo
```

## Components

### Language specification

- [Surface language](https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/language.md): `spec/v1.0/language.md`
- [Lexical rules](https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/lexical.md): `spec/v1.0/lexical.md`
- [Types and shapes](https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/types.md): `spec/v1.0/types.md`

### Execution contracts

- [Core IR](https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/ir.md): `spec/v1.0/ir.md`
- [Static autodiff](https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/autodiff.md): `spec/v1.0/autodiff.md`
- [Runtime interface](https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/runtime.md): `spec/v1.0/runtime.md`
- [MLIR lowering](https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/mlir-lowering.md): `spec/v1.0/mlir-lowering.md`

### Libraries and evidence

- [Standard library](https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/stdlib.md): `spec/v1.0/stdlib.md`
- [Determinism](https://github.com/star-ga/mind-spec/blob/main/determinism.md): `determinism.md`
- [IR stability](https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/ir-stability.md): `spec/v1.0/ir-stability.md`
- [Model artifacts](https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/model-artifact.md): `spec/v1.0/model-artifact.md`
- [Security profile](https://github.com/star-ga/mind-spec/blob/main/spec/v1.0/security.md): `spec/v1.0/security.md`

### IR prototype

- [Expression entry](https://github.com/star-ga/mind-spec/blob/main/tools/core_ir/language.py): `tools/core_ir/language.py`
- [Type validation](https://github.com/star-ga/mind-spec/blob/main/tools/core_ir/type_system.py): `tools/core_ir/type_system.py`
- [IR builder](https://github.com/star-ga/mind-spec/blob/main/tools/core_ir/core_ir.py): `tools/core_ir/core_ir.py`

### Other components

- **Language reader**

## Connections

- Language reader → Surface language: consults
- Language reader → Standard library: consults
- Surface language → Lexical rules: specifies syntax
- Surface language → Types and shapes: uses type rules
- Surface language → Core IR: defines representation
- Core IR → Static autodiff: supports transforms
- Core IR → Runtime interface: defines interface
- Core IR → MLIR lowering: describes lowering
- Standard library → Runtime interface: specifies library use
- IR stability → Core IR: constrains format
- Model artifacts → IR stability: anchors evidence
- Security profile → Model artifacts: specifies trust
- Determinism → Language reader: states guarantees
- Expression entry → Type validation: validates program
- Expression entry → IR builder: emits operations
- Type validation → IR builder: materializes inputs