**Source code should be a structured database of logic, not a text file of syntax.**
Whetstone is a Universal Logic Database that stores code as a semantic graph (AST), with traditional programming languages serving as **projections** of that canonical representation. This enables lossless transpilation, massively parallel development (human and AI agents), and complete separation of intent from implementation.
---
## Core Philosophy
### The Problem: Text Blindness
Current software engineering couples **Intent** (what we want to happen) with **Implementation** (how the machine does it) through language-specific syntax. This creates:
- Lock-in to specific languages and ecosystems
- Loss of semantic information during translation
- Inability to express cross-cutting concerns (ownership, risk, optimization hints)
- Barriers to parallel development by multiple agents
### The Solution: Projectional Editing
Move the "Source of Truth" from text files to a **Logical Graph Database**:
| Text-Based | Graph-Based (Whetstone) |
|------------|-------------------------|
| Linear | Structural |
| Ambiguous | Explicit |
| Syntax-heavy | Meaning-heavy |
| Language-specific | Universal |
---
## Architecture: The Three Layers
### Layer 1: The Logic Database (Definition)
A schema of pure logical concepts stored in a graph/tree database (JetBrains MPS).
**Core Principle:** This layer must be a **superset** of all target languages. It must express concepts like memory ownership (Rust-style) even when targeting languages that don't require them (Python).
- Hypergraph relationships (nodes participate in multiple relationships)
### Layer 2: Semantic Generators (Bridge)
Generators that translate the Logic Database into idiomatic text for specific runtimes.
**Example - SharedMemoryBlock concept:**
```
Generator A (Python): x = [1, 2, 3] # Note: Shared usage implied
Generator B (Rust): let x = Arc::new(Mutex::new(vec![1, 2, 3]));
Generator C (Verilog): reg [31:0] memory [0:2];
```
### Layer 3: Runtime (Metal)
Standard toolchains (GCC, LLVM, Python interpreter) compile/execute the generated code. Whetstone does not replace compilers; it feeds them optimized, correct input.
---
## SemAnno: Universal Semantic Annotation Schema
Six annotation systems provide metadata for agents (human and AI):
### 1. Complexity & Intelligence ("Rank" System)
Defines who/what is qualified to modify a node.
| Annotation | Type | Purpose |
|------------|------|---------|
| `@complexity-score` | int | Derived from cyclomatic complexity, nesting, mutation |
- In foreign language: renders as comment with semantic hint
**Long-term Vision:** These annotations enable future semantic equivalence detection. When the system understands that `@lru_cache` and a C++ `std::map`-based cache serve the same purpose ("memoization"), it can generate idiomatic implementations in either direction rather than just commenting.
Memory management is decoupled from logic as a first-class AST field. The canonical annotation system (defined in `annotations/Memory strategy.md`) uses distinct annotation families, each targeting a specific memory paradigm:
In `@Deallocate(Explicit)` mode, the AST requires an explicit **Deallocation Time Field**. If empty, the editor flags it as a "Missing Intent" error. This makes it impossible to forget a deallocation point.
### Lossless Projection Logic
When the transpiler encounters a memory annotation that the target language cannot express natively (see `annotations/Memory strategy.md` Section 3):
- **High-Level → Low-Level** (e.g., Python → C): `@Reclaim(Tracing)` → inject `INC_REF`/`DEC_REF` shim with `free()` on zero
- **Low-Level → High-Level** (e.g., C → Java): `@Deallocate(Explicit)` → wrap in `try-with-resources` or `Cleaner` API
- **Strict → Permissive** (e.g., Rust → Python): `@Owner(Single)` → preserve in AST metadata, no enforcement in generated code
Parse old Fortran/COBOL → Logic Database → Generate modern C++/Rust/Julia
### Cross-Platform Logic
Write business logic once → Generate Kotlin (Android), Swift (iOS), Rust (backend)
### Agentic Coding
Agents manipulate Graph Nodes directly (no syntax errors from text generation)
### Parallel Development
Multiple developers/agents work on same codebase with explicit conflict boundaries
---
## Technical Principles
### Behavior Over Implementation
A node's primary definition is its **Behavioral Contract** (e.g., "Sort this collection") rather than implementation (e.g., "Quicksort with pointer increments").
### Substrate-Agnostic Core Nodes
Core AST nodes must not assume specific memory models or hardware constraints.
- **Bad:** LoopNode requires a "Pointer" field
- **Good:** LoopNode requires an "IteratorIntent" - realization is metadata
### The Semantic Boundary
Strict boundary between **What** (Logic) and **How** (Execution Strategy). Future capabilities are implemented by adding Strategy Engines to existing nodes, not re-architecting nodes.
### Strictest Common Denominator
The Logic Database enforces strict rules by default (explicit ownership), while Generators can "relax" rules for permissive languages or "poly-fill" rules for strict languages.
---
## The C Primitives Substrate (Long-term Vision)
All high-level language features ultimately resolve to C-level primitives:
Level 2: Semantic Intent "memoize", "parameterize by type", "scope-bound cleanup"
│
▼
Level 1: C Primitives pointers, structs, malloc/free, function calls
```
**End State:** Languages become pure *syntactic projections* over C primitives + semantic annotations. This enables true lossless transpilation because the canonical form captures both the intent (semantic annotations) and the implementation (C primitives).
---
## Implementation Platform
**JetBrains MPS (Meta Programming System)**
- Projectional editor (edit AST directly, not text)
