ntntlang · joshcramer · Mar 9, 2026 · Mar 8, 2026 · Mar 8, 2026 · Mar 8, 2026
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -29,6 +29,32 @@ ntnt test server.tnt --get /health --post /users --body 'name=Alice'
 
 ---
 
+## Type Safety Modes (v0.4.0+)
+
+Two independent axes for type control:
+
+**Runtime (`NTNT_TYPE_MODE`):** Controls behavior on type mismatches at runtime.
+- `strict` — crash on mismatch (use for auth/payment apps)
+- `warn` — log `[WARN]` and continue **(default)**
+- `forgiving` — silent degradation
+
+**Lint (`NTNT_LINT_MODE`):** Controls annotation requirements.
+- `default` — only check annotated code **(default)**
+- `warn` — also warn about missing annotations (`--warn-untyped`)
+- `strict` — missing annotations are errors (`--strict`)
+
+```bash
+# Recommended for production apps with auth:
+NTNT_TYPE_MODE=strict NTNT_LINT_MODE=strict ntnt run server.tnt
+
+# Development:
+NTNT_TYPE_MODE=warn ntnt run server.tnt
+```
+
+`NTNT_STRICT` is deprecated — use `NTNT_LINT_MODE=strict`.
+
+---
+
 ## Intent-Driven Development (IDD)
 
 IDD is **the core workflow** for NTNT development. You capture user requirements as executable specifications, then implement code that satisfies them.

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -49,6 +49,32 @@ ntnt test server.tnt --get /health --post /users --body 'name=Alice'
 
 ---
 
+## Type Safety Modes (v0.4.0+)
+
+Two independent axes for type control:
+
+**Runtime (`NTNT_TYPE_MODE`):** Controls behavior on type mismatches at runtime.
+- `strict` — crash on mismatch (use for auth/payment apps)
+- `warn` — log `[WARN]` and continue **(default)**
+- `forgiving` — silent degradation
+
+**Lint (`NTNT_LINT_MODE`):** Controls annotation requirements.
+- `default` — only check annotated code **(default)**
+- `warn` — also warn about missing annotations (`--warn-untyped`)
+- `strict` — missing annotations are errors (`--strict`)
+
+```bash
+# Recommended for production apps with auth:
+NTNT_TYPE_MODE=strict NTNT_LINT_MODE=strict ntnt run server.tnt
+
+# Development:
+NTNT_TYPE_MODE=warn ntnt run server.tnt
+```
+
+`NTNT_STRICT` is deprecated — use `NTNT_LINT_MODE=strict`.
+
+---
+
 ## Intent-Driven Development (IDD)
 
 IDD is **the core workflow** for NTNT development. You capture user requirements as executable specifications, then implement code that satisfies them.

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "ntnt"
-version = "0.3.17"
+version = "0.4.0"
 edition = "2021"
 authors = ["NTNT Language Team"]
 description = "NTNT (Intent) - A programming language designed for AI-driven development"

diff --git a/docs/AI_AGENT_GUIDE.md b/docs/AI_AGENT_GUIDE.md
@@ -22,6 +22,32 @@ ntnt test server.tnt --get /health --post /users --body 'name=Alice'
 
 ---
 
+## Type Safety Modes (v0.4.0+)
+
+Two independent axes for type control:
+
+**Runtime (`NTNT_TYPE_MODE`):** Controls behavior on type mismatches at runtime.
+- `strict` — crash on mismatch (use for auth/payment apps)
+- `warn` — log `[WARN]` and continue **(default)**
+- `forgiving` — silent degradation
+
+**Lint (`NTNT_LINT_MODE`):** Controls annotation requirements.
+- `default` — only check annotated code **(default)**
+- `warn` — also warn about missing annotations (`--warn-untyped`)
+- `strict` — missing annotations are errors (`--strict`)
+
+```bash
+# Recommended for production apps with auth:
+NTNT_TYPE_MODE=strict NTNT_LINT_MODE=strict ntnt run server.tnt
+
+# Development:
+NTNT_TYPE_MODE=warn ntnt run server.tnt
+```
+
+`NTNT_STRICT` is deprecated — use `NTNT_LINT_MODE=strict`.
+
+---
+
 ## Intent-Driven Development (IDD)
 
 IDD is **the core workflow** for NTNT development. You capture user requirements as executable specifications, then implement code that satisfies them.

diff --git a/docs/IAL_REFERENCE.md b/docs/IAL_REFERENCE.md
@@ -2,7 +2,7 @@
 
 > **Auto-generated from [ial.toml](ial.toml)** - Do not edit directly.
 >
-> Last updated: v0.3.17
+> Last updated: v0.4.0
 
 IAL is a term rewriting engine that translates natural language assertions into executable tests
 

diff --git a/docs/RUNTIME_REFERENCE.md b/docs/RUNTIME_REFERENCE.md
@@ -2,7 +2,7 @@
 
 > **Auto-generated from [runtime.toml](runtime.toml)** - Do not edit directly.
 >
-> Last updated: v0.3.17
+> Last updated: v0.4.0
 
 Runtime configuration, environment variables, and CLI commands for NTNT
 
@@ -25,9 +25,11 @@ Environment variables that control NTNT runtime behavior
 |----------|--------|---------|-------------|
 | `NTNT_ALLOW_PRIVATE_IPS` | `true` | unset (disabled — private IPs blocked) | Allow `fetch()` to connect to private/internal IP ranges (10.x, 172.16-31.x, 192.168.x, 127.x). Required for Docker inter-container communication (e.g., calling a sidecar at 172.19.0.1). Disabled by default to prevent SSRF attacks. |
 | `NTNT_ENV` | `development`, `production`, `prod` | development (when unset) | Controls runtime mode. Production mode disables hot-reload for better performance. |
+| `NTNT_LINT_MODE` | `default`, `warn`, `strict` | default | Controls lint strictness for type annotations. `default`: only check annotated code. `warn`: also warn about missing annotations (non-fatal). `strict`: missing annotations are errors. CLI flags (`--strict`, `--warn-untyped`) override this. |
 | `NTNT_MAX_RECURSION` | integer | 256 | Maximum recursion depth for function calls. Prevents stack overflow from runaway recursion. |
-| `NTNT_STRICT` | `1`, `true` | unset (disabled) | Enable strict type checking. For `ntnt run`, blocks execution if type errors are found. For `ntnt lint`, warns about untyped function signatures. Also configurable via `ntnt lint --strict` or `ntnt.toml` config. |
+| `NTNT_STRICT` | `1`, `true` | unset (disabled) | **Deprecated — use `NTNT_LINT_MODE=strict` instead.** Enable strict type checking. Still works but emits a deprecation warning. |
 | `NTNT_TIMEOUT` | integer (seconds) | 30 | Request timeout for HTTP server in seconds. |
+| `NTNT_TYPE_MODE` | `strict`, `warn`, `forgiving` | warn | Controls runtime behavior for type mismatches. `strict`: type mismatches crash (fail-closed, recommended for auth/payments). `warn`: log `[WARN]` and continue (default). `forgiving`: silent degradation (pre-v0.4 behavior). See [Type Safety Modes](#type-safety-modes). |
 
 ### Examples
 
@@ -38,15 +40,97 @@ NTNT_ALLOW_PRIVATE_IPS=true ntnt run server.tnt
 # Controls runtime mode
 NTNT_ENV=production ntnt run server.tnt
 
+# Controls lint strictness for type annotations
+NTNT_LINT_MODE=strict ntnt lint server.tnt
+
 # Maximum recursion depth for function calls
 NTNT_MAX_RECURSION=512 ntnt run server.tnt
 
-# Enable strict type checking
+# **Deprecated — use `NTNT_LINT_MODE=strict` instead.** Enable strict type checking
 NTNT_STRICT=1 ntnt run server.tnt
 
 # Request timeout for HTTP server in seconds.
 NTNT_TIMEOUT=60 ntnt run server.tnt
 
+# Controls runtime behavior for type mismatches
+NTNT_TYPE_MODE=strict ntnt run server.tnt
+
+```
+
+---
+
+## Type Safety Modes
+
+ntnt provides two independent axes for type control, configured via environment variables.
+
+### Axis 1: Runtime Type Mode (`NTNT_TYPE_MODE`)
+
+Controls what happens when types mismatch at runtime (e.g., bad data from a database, wrong API response type).
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `strict` | Type mismatches crash the request (fail-closed) | Apps with auth, payments, safety-critical logic |
+| `warn` | Log `[WARN]` to stderr and continue **(default)** | Production apps with log monitoring |
+| `forgiving` | Silent degradation, no warnings | Content sites where uptime > correctness |
+
+```bash
+# Crash on type mismatches (safest)
+NTNT_TYPE_MODE=strict ntnt run server.tnt
+
+# Log warnings and continue (default)
+NTNT_TYPE_MODE=warn ntnt run server.tnt
+
+# Silent degradation (pre-v0.4 behavior)
+NTNT_TYPE_MODE=forgiving ntnt run server.tnt
+```
+
+**Affected operations:** index (`[]`) type mismatch, `for..in` on non-collections, field access on wrong types, template expression errors. Warnings are deduplicated per evaluation context — the same mismatch won't spam 50 times in a loop.
+
+**Security note:** Apps with authentication, authorization, or financial logic should use `strict`. Forgiving mode is fail-open — a type mismatch on a permission check can silently bypass it.
+
+### Axis 2: Lint Mode (`NTNT_LINT_MODE`)
+
+Controls how the linter treats missing type annotations.
+
+| Mode | Behavior | CI Exit Code |
+|------|----------|--------------|
+| `default` | Only report errors in annotated code | 0 (if no type conflicts) |
+| `warn` | Also warn about missing annotations | 0 (warnings are non-fatal) |
+| `strict` | Missing annotations are errors | Non-zero on missing annotations |
+
+```bash
+# Default: only check annotated code
+ntnt lint app.tnt
+
+# Warn about missing annotations (non-fatal)
+ntnt lint --warn-untyped app.tnt
+NTNT_LINT_MODE=warn ntnt lint app.tnt
+
+# Require all annotations (CI-safe)
+ntnt lint --strict app.tnt
+NTNT_LINT_MODE=strict ntnt lint app.tnt
+```
+
+### Precedence
+
+```
+CLI flag > Environment variable > ntnt.toml > built-in default
+```
+
+### Docker Configuration
+
+```yaml
+# SaaS app with auth + payments
+environment:
+  - NTNT_TYPE_MODE=strict
+  - NTNT_LINT_MODE=strict
+  - NTNT_ENV=production
+
+# Content site / blog
+environment:
+  - NTNT_TYPE_MODE=warn
+  - NTNT_LINT_MODE=default
+  - NTNT_ENV=production
 ```
 
 ---
@@ -198,7 +282,8 @@ Check source file(s) for syntax errors and common mistakes
 |--------|------|---------|-------------|
 | `--quiet`, `-q` | flag | - | Show only errors, not warnings or suggestions |
 | `--fix` | flag | - | Output auto-fix suggestions as JSON patch |
-| `--strict` | flag | - | Warn about untyped function parameters and missing return types (also: NTNT_STRICT=1 or ntnt.toml) |
+| `--warn-untyped` | flag | - | Enable strict typechecker warnings without failing the build: warns on missing type annotations and other strict-mode issues (e.g., Float→Int precision-loss, complex interpolation). Exit code remains 0. Also: `NTNT_LINT_MODE=warn`. |
+| `--strict` | flag | - | Require type annotations on all functions — missing annotations are errors (non-zero exit). Also: `NTNT_LINT_MODE=strict`. Replaces deprecated `NTNT_STRICT`. |
 
 **Example:**
 ```bash

diff --git a/docs/STDLIB_REFERENCE.md b/docs/STDLIB_REFERENCE.md
@@ -2,7 +2,7 @@
 
 > **Auto-generated from source code doc comments** - Do not edit directly.
 >
-> Last updated: v0.3.17
+> Last updated: v0.4.0
 
 ## Table of Contents
 

diff --git a/docs/SYNTAX_REFERENCE.md b/docs/SYNTAX_REFERENCE.md
@@ -2,7 +2,7 @@
 
 > **Auto-generated from [syntax.toml](syntax.toml)** - Do not edit directly.
 >
-> Last updated: v0.3.17
+> Last updated: v0.4.0
 
 ## Table of Contents
 

diff --git a/docs/runtime.toml b/docs/runtime.toml
@@ -41,13 +41,104 @@ description = "Maximum recursion depth for function calls. Prevents stack overfl
 example = "NTNT_MAX_RECURSION=512 ntnt run server.tnt"
 affects = ["runtime"]
 
+[env_vars.NTNT_TYPE_MODE]
+values = ["strict", "warn", "forgiving"]
+default = "warn"
+description = "Controls runtime behavior for type mismatches. `strict`: type mismatches crash (fail-closed, recommended for auth/payments). `warn`: log `[WARN]` and continue (default). `forgiving`: silent degradation (pre-v0.4 behavior). See [Type Safety Modes](#type-safety-modes)."
+example = "NTNT_TYPE_MODE=strict ntnt run server.tnt"
+affects = ["type-checking", "runtime"]
+
+[env_vars.NTNT_LINT_MODE]
+values = ["default", "warn", "strict"]
+default = "default"
+description = "Controls lint strictness for type annotations. `default`: only check annotated code. `warn`: also warn about missing annotations (non-fatal). `strict`: missing annotations are errors. CLI flags (`--strict`, `--warn-untyped`) override this."
+example = "NTNT_LINT_MODE=strict ntnt lint server.tnt"
+affects = ["lint", "type-checking"]
+
 [env_vars.NTNT_STRICT]
 values = ["1", "true"]
 default = "unset (disabled)"
-description = "Enable strict type checking. For `ntnt run`, blocks execution if type errors are found. For `ntnt lint`, warns about untyped function signatures. Also configurable via `ntnt lint --strict` or `ntnt.toml` config."
+description = "**Deprecated — use `NTNT_LINT_MODE=strict` instead.** Enable strict type checking. Still works but emits a deprecation warning."
 example = "NTNT_STRICT=1 ntnt run server.tnt"
 affects = ["type-checking", "lint"]
 
+# =============================================================================
+# TYPE SAFETY MODES (DD-009)
+# =============================================================================
+
+[type_safety_modes]
+content = """ntnt provides two independent axes for type control, configured via environment variables.
+
+### Axis 1: Runtime Type Mode (`NTNT_TYPE_MODE`)
+
+Controls what happens when types mismatch at runtime (e.g., bad data from a database, wrong API response type).
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `strict` | Type mismatches crash the request (fail-closed) | Apps with auth, payments, safety-critical logic |
+| `warn` | Log `[WARN]` to stderr and continue **(default)** | Production apps with log monitoring |
+| `forgiving` | Silent degradation, no warnings | Content sites where uptime > correctness |
+
+```bash
+# Crash on type mismatches (safest)
+NTNT_TYPE_MODE=strict ntnt run server.tnt
+
+# Log warnings and continue (default)
+NTNT_TYPE_MODE=warn ntnt run server.tnt
+
+# Silent degradation (pre-v0.4 behavior)
+NTNT_TYPE_MODE=forgiving ntnt run server.tnt
+```
+
+**Affected operations:** index (`[]`) type mismatch, `for..in` on non-collections, field access on wrong types, template expression errors. Warnings are deduplicated per evaluation context — the same mismatch won't spam 50 times in a loop.
+
+**Security note:** Apps with authentication, authorization, or financial logic should use `strict`. Forgiving mode is fail-open — a type mismatch on a permission check can silently bypass it.
+
+### Axis 2: Lint Mode (`NTNT_LINT_MODE`)
+
+Controls how the linter treats missing type annotations.
+
+| Mode | Behavior | CI Exit Code |
+|------|----------|--------------|
+| `default` | Only report errors in annotated code | 0 (if no type conflicts) |
+| `warn` | Also warn about missing annotations | 0 (warnings are non-fatal) |
+| `strict` | Missing annotations are errors | Non-zero on missing annotations |
+
+```bash
+# Default: only check annotated code
+ntnt lint app.tnt
+
+# Warn about missing annotations (non-fatal)
+ntnt lint --warn-untyped app.tnt
+NTNT_LINT_MODE=warn ntnt lint app.tnt
+
+# Require all annotations (CI-safe)
+ntnt lint --strict app.tnt
+NTNT_LINT_MODE=strict ntnt lint app.tnt
+```
+
+### Precedence
+
+```
+CLI flag > Environment variable > ntnt.toml > built-in default
+```
+
+### Docker Configuration
+
+```yaml
+# SaaS app with auth + payments
+environment:
+  - NTNT_TYPE_MODE=strict
+  - NTNT_LINT_MODE=strict
+  - NTNT_ENV=production
+
+# Content site / blog
+environment:
+  - NTNT_TYPE_MODE=warn
+  - NTNT_LINT_MODE=default
+  - NTNT_ENV=production
+```"""
+
 # =============================================================================
 # HOT-RELOAD
 # =============================================================================
@@ -174,7 +265,8 @@ description = "Check source file(s) for syntax errors and common mistakes"
 options = [
     { name = "--quiet", short = "-q", type = "flag", description = "Show only errors, not warnings or suggestions" },
     { name = "--fix", short = "", type = "flag", description = "Output auto-fix suggestions as JSON patch" },
-    { name = "--strict", short = "", type = "flag", description = "Warn about untyped function parameters and missing return types (also: NTNT_STRICT=1 or ntnt.toml)" }
+    { name = "--warn-untyped", short = "", type = "flag", description = "Enable strict typechecker warnings without failing the build: warns on missing type annotations and other strict-mode issues (e.g., Float→Int precision-loss, complex interpolation). Exit code remains 0. Also: `NTNT_LINT_MODE=warn`." },
+    { name = "--strict", short = "", type = "flag", description = "Require type annotations on all functions — missing annotations are errors (non-zero exit). Also: `NTNT_LINT_MODE=strict`. Replaces deprecated `NTNT_STRICT`." }
 ]
 example = "ntnt lint server.tnt"