TDLN — Truth-Determining Language Normalizer

A protocol that turns human intentions into verifiable, executable policies — and proves every transformation along the way.

TDLN solves a fundamental problem in computing: the gap between what we mean and what machines do. Traditional systems lose the original intent in layers of compilation, configuration, and execution. TDLN preserves it.

What makes TDLN different:

• Deterministic translation: Same intention → same execution, every time
• Cryptographic proof: Every step from idea to implementation is verified
• Fractal structure: Policies compose like building blocks, infinitely
• Cost revolution: A complex silicon chip's logic fits in 50KB of text
• Universal auditability: Hash-based verification, not trust-based

---

🎯 What Is TDLN?

Imagine if every business rule, security policy, or decision logic could be:

• Written once in a format that never ambiguates
• Verified cryptographically so tampering is impossible
• Executed anywhere — software, hardware, distributed systems
• Audited completely with perfect historical record
• Composed infinitely like LEGO blocks

That's TDLN.

The Core Invention

At its heart, TDLN introduces the SemanticUnit — a fractal data structure where:

• Each level carries its own hash (cryptographic fingerprint)
• Policies compose into graphs of decisions
• The same text file can become software, hardware, or formal proof
• Nothing is lost in translation; everything is traceable

Real-world impact:

• A 200-million-gate chip can be specified in 50KB of text
• 7x better energy efficiency than general-purpose processors
• 20,000x cost reduction (text file vs fabricated silicon)
• Infinite prototyping before committing to hardware

This isn't incremental improvement. It's an exponential jump in how we think about computation.

---

🏗️ Estrutura do Repositório

TDLN/
├── tdln_core/                    # ⭐ Core protocol (Rust)
│   ├── src/lib.rs                # SemanticUnit, PolicyBit, Expression
│   └── Cargo.toml
│
├── tdln_runtime/                 # CPU evaluator/interpreter
│   ├── src/lib.rs                # Runtime para execução de políticas
│   └── Cargo.toml
│
├── specs/                        # Especificações canônicas
│   └── tdln-core-v2.0.schema.json
│
├── docs/                         # Documentação completa
│   ├── TDLN_FORMAT.md            # Especificação do formato .tdln
│   ├── ARCHITECTURE.md           # Arquitetura do sistema
│   ├── QUICKSTART.md             # Tutorial rápido
│   └── API_REFERENCE.md          # Referência de tipos
│
├── examples/                     # Exemplos de uso
│   ├── .tdln files               # Arquivos de política
│   └── 01_chip/                  # Uso: compilação para hardware
│   └── 02_translator/            # Uso: tradutor LN → TDLN
│   └── 03_validator/             # Uso: validação de políticas
│
└── Cargo.toml                    # Workspace Rust

---

🔥 How It Works

TDLN operates on three levels:

1. The Format (.tdln files)

A .tdln file is a structured JSON document representing a Semantic Unit — a complete, self-contained policy graph:

{
  "tdln_spec_version": "2.0.0",
  "node_type": "semantic_unit",
  "id": "su_550e8400-e29b-41d4-a716-446655440000",
  "hash": "blake3_f4a8b2c1d3e5...",
  
  "policies": [
    {
      "node_type": "policy_bit",
      "condition": {
        "type": "binary",
        "operator": "EQ",
        "left": {"type": "context_ref", "path": ["user", "role"]},
        "right": {"type": "literal", "value": "admin"}
      }
    }
  ]
}

Key properties:

• Fractal: Every node (SemanticUnit → PolicyBit → Expression) has node_type, id, hash
• Deterministic: Same semantic meaning → same canonical hash
• Composable: Policies combine in serial, parallel, or conditional graphs
• Verifiable: Cryptographic hashes ensure integrity

2. The Protocol

TDLN provides the translation layer between human intent and machine execution:

Natural Language → TDLN Core → Executable Format
    "Premium users can..."  →  .tdln file  →  Python/Metal/Verilog

Every transformation carries a cryptographic proof:

• Source text hash
• Translation steps
• Canonical output hash
• Optional digital signature

This creates an unbroken chain of custody from idea to implementation.

3. The Ecosystem

TDLN is infrastructure. Others build on it:

• TDLN-Chip: Compiles policies to hardware (GPU/FPGA/ASIC)
• Translators: Convert natural language to .tdln
• Validators: Prove policy correctness
• Auditors: Track all decisions to their source
• Your application: Any system needing deterministic rules

---

🚀 Why This Matters

The Old Way

1. Write business rules in English
2. Developer interprets and codes them
3. Code gets compiled, optimized, obfuscated
4. Deploy to production
5. Original intent is lost
6. Auditing requires reverse-engineering
7. Changes risk breaking everything

The TDLN Way

1. Write rules in .tdln format (or have LLM generate them)
2. Validate against schema automatically
3. Compile to any target (software/hardware)
4. Original intent preserved in hash
5. Auditing is reading the .tdln file
6. Changes are deterministic updates
7. Old versions remain valid and verifiable

Result: Faster iteration, perfect auditability, zero ambiguity.

---

🚀 Quick Start

1. Build o core TDLN

cd TDLN
cargo build --release

2. Usar o core em seu projeto

# Cargo.toml
[dependencies]
tdln_core = { path = "../TDLN/tdln_core" }
tdln_runtime = { path = "../TDLN/tdln_runtime" }

use tdln_core::{SemanticUnit, PolicyBit, Expression};
use tdln_runtime::Evaluator;

// Criar uma política
let policy = PolicyBit {
    node_type: "policy_bit",
    id: "pb_admin_check",
    condition: Expression::Binary { /* ... */ }
};

// Avaliar
let evaluator = Evaluator::new();
let result = evaluator.evaluate(&policy, &context);

3. Validar um arquivo .tdln

# Validar contra schema
jsonschema -i arquivo.tdln specs/tdln-core-v2.0.schema.json

# Scripts utilitários
./scripts/validate-all.sh
./scripts/check-integrity.sh

---

📚 Documentação

Documento	Descrição
TDLN_FORMAT.md	Especificação completa do formato .tdln
README.examples.md	Guia dos exemplos incluídos
tdln-core-v2.0.schema.json	JSON Schema canônico

---

🔗 Ecossistema TDLN

TDLN é o protocolo fundacional. Dele derivam aplicações específicas:

Aplicações Oficiais

1. TDLN-Chip 🔩
   • Compila políticas TDLN para hardware
   • Backends: Metal (GPU), CUDA (NVIDIA), Verilog (FPGA/ASIC)
   • Usa: tdln_core + tdln_runtime deste repo

Use Cases

TDLN Protocol
    ├─→ TDLN-Chip        (compilar para hardware)
    ├─→ Tradutor LN      (natural language → .tdln)
    ├─→ Validador        (verificação formal)
    ├─→ Sistema Audit    (compliance/rastreabilidade)
    └─→ Seu projeto      (qualquer aplicação de políticas)

Ver exemplos em examples/ para cada use case.

---

📦 Exemplos Incluídos

Arquivos marcados como EXAMPLE ONLY:

1. examples/premium-user-access.tdln.json — Exemplo completo
2. examples/chip-minimal.tdln.json — Exemplo mínimo
3. grammar/ — Gramáticas de referência
4. policies/ — Política neutra de sandbox

⚠️ Importante: Não faça deploy de arquivos .example.* em produção!

---

�️ Roadmap

✅ v2.0 (Atual)

• Formato .tdln fractal (SemanticUnit)
• JSON Schema completo
• Exemplos de referência
• Documentação completa
• Scripts de validação

🔜 v2.1 (Próximo)

• Validador TDLN em Rust (standalone binary)
• VSCode extension (syntax highlighting)
• Python library (tdln-pure)
• GitHub Actions workflow para CI/CD
• Showcase com 10+ exemplos .tdln

🔮 v3.0 (Futuro)

• TDLN REPL (interpretador interativo)
• Visualizador de grafos (PolicyComposition)
• Ferramenta de diff semântico
• Certificação de conformidade (TDLN Compliant™)

---

🎨 Extensibilidade e Customização

TDLN é um protocolo extensível. Você pode customizar:

• ✅ Operadores customizados via SemanticOp::Custom(String)
• ✅ Metadados para qualquer finalidade
• ✅ Novos backends de compilação (WebGPU, Python, etc.)
• ✅ Novos tipos de units (via fork)
• ✅ Integrações com qualquer linguagem

Limites importantes:

• ❌ Não modifique estruturas core (quebra compatibilidade)
• ❌ Mantenha determinismo (hash consistente)
• ❌ Implemente todas políticas declaradas

➡️ Guia completo: CUSTOMIZATION.md
➡️ Exemplos categorizados: examples/

Categorias de exemplos:

1. 01_core_usage/ - Uso básico sem customização
2. 02_custom_operators/ - Operadores específicos (AudioFFT, etc.)
3. 03_custom_types/ - Extensões de tipos (via fork)
4. 04_custom_backends/ - Novos targets de compilação
5. 05_integrations/ - Python, JS, REST API, etc.

---

❓ FAQ

P: O que é TDLN Pure vs TDLN Chip?

TDLN Pure = Protocolo (formato .tdln, specs, docs)
TDLN Chip = Implementação (compila .tdln → Metal/CUDA/Verilog)

Analogia: Pure = MP3 spec, Chip = VLC player

P: Posso usar TDLN sem TDLN Chip?

Sim! TDLN Pure é independente. Use para:

• Auditoria de políticas
• Validação de workflows
• Documentação formal
• Análise semântica

P: Por que Blake3 e não SHA-256?

Blake3 é:

• 10x mais rápido que SHA-256
• Paralelizável (multi-core)
• Mesmo nível de segurança (256-bit)
• Mais moderno (2020 vs 2001)

P: O formato .tdln vai mudar?

Garantia de estabilidade:

• Versões 2.x são backward compatible
• Breaking changes só em versões major (3.0, 4.0, etc)
• Deprecações anunciadas com 6 meses de antecedência

P: Como contribuir?

Leia CONTRIBUTING.md. Em resumo:

1. Fork o repo
2. Crie branch (feat/minha-feature)
3. Siga convenções (JSON Schema, exemplos)
4. Abra Pull Request

---

📄 Licença

MIT License © 2025 LogLine Foundation

Ver LICENSE para detalhes completos.

---

📞 Suporte

• 📖 Docs: docs/TDLN_FORMAT.md
• 🐛 Issues: GitHub Issues
• 💬 Discussão: GitHub Discussions

---

TDLN — O protocolo fundacional para aplicação determinística de políticas. 🎯