v0.4.0: Type Safety Modes — Two Axes of Type Control (DD-009)

.github/copilot-instructions.md

@@ -1,6 +1,6 @@
 <!-- NTNT coding guide sections are sourced from docs/AI_AGENT_GUIDE.md -->
 <!-- To update NTNT coding instructions, edit AI_AGENT_GUIDE.md and copy to all agent files -->
-<!-- Last synced: 2026-03-08 -->
+<!-- Last synced: 2026-03-09 -->
 
 # NTNT Language - GitHub Copilot Instructions
 
@@ -29,6 +29,40 @@ 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
+```
+
+**Type syntax (v0.4.0+):**
+- Optional shorthand: `fn find(id: Int) -> User?` (equivalent to `Optional<User>`)
+- Type aliases: `type UserId = Int`, `type Handler = (Request) -> Response`
+- Array types: `fn sum(nums: [Int]) -> Int`
+- Generics: `fn identity<T>(x: T) -> T` — type checker infers concrete types from call args
+
+**Error messages** include file:line, source snippets, expected/got context, and fix hints.
+
+`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.

CLAUDE.md

@@ -1,6 +1,6 @@
 <!-- NTNT coding guide sections are sourced from docs/AI_AGENT_GUIDE.md -->
 <!-- To update NTNT coding instructions, edit AI_AGENT_GUIDE.md and copy to all agent files -->
-<!-- Last synced: 2026-03-08 -->
+<!-- Last synced: 2026-03-09 -->
 
 # NTNT Language - Claude Code Instructions
 
@@ -49,6 +49,40 @@ 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
+```
+
+**Type syntax (v0.4.0+):**
+- Optional shorthand: `fn find(id: Int) -> User?` (equivalent to `Optional<User>`)
+- Type aliases: `type UserId = Int`, `type Handler = (Request) -> Response`
+- Array types: `fn sum(nums: [Int]) -> Int`
+- Generics: `fn identity<T>(x: T) -> T` — type checker infers concrete types from call args
+
+**Error messages** include file:line, source snippets, expected/got context, and fix hints.
+
+`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.

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"

README.md

@@ -110,7 +110,7 @@ NTNT explores a different approach. Requirements are executable specifications w
 | **Intent-Driven Development** | Write requirements in `.intent` files. Link code with `@implements`. Run `ntnt intent check` to verify. Full traceability from requirement to implementation. |
 | **Design by Contract** | `requires` and `ensures` built into function syntax. In HTTP routes, contract violations return 400/500 automatically. |
 | **Agent-Native Tooling** | `ntnt inspect` outputs JSON describing every function, route, and contract. `ntnt validate` returns machine-readable errors. |
-| **Gradual Type System** | Optional type annotations with inference. Types catch structural errors at lint time; contracts catch semantic errors. Strict mode for full enforcement. |
+| **Gradual Type System** | Optional type annotations with inference, generics (`fn identity<T>(x: T) -> T`), type aliases (`type Handler = (Request) -> Response`), and `T?` shorthand. Two independent axes: **lint mode** (`--warn-untyped` / `--strict`) controls static analysis depth; **runtime mode** (`NTNT_TYPE_MODE=strict\|warn\|forgiving`) controls what happens on type mismatches. |
 | **Batteries Included** | HTTP servers, PostgreSQL, SQLite, JSON, CSV, file I/O, crypto, concurrency - all in the standard library. No package manager needed. |
 | **Hot Reload** | HTTP servers reload automatically when you save. Edit code, refresh browser, see changes. |
 
@@ -160,7 +160,8 @@ fn withdraw(amount: Int) -> Int
 ```bash
 ntnt run <file>              # Run a .tnt file
 ntnt lint <file>             # Check for errors
-ntnt lint --strict <file>    # Check with strict type warnings
+ntnt lint --warn-untyped <f> # Warn on missing type annotations
+ntnt lint --strict <file>    # Require type annotations (errors)
 ntnt validate <file>         # Validate with JSON output
 ntnt test <file> --get /     # Quick HTTP endpoint testing
 ntnt intent check <file>     # Verify code matches intent

docs/AI_AGENT_GUIDE.md

@@ -22,6 +22,40 @@ 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
+```
+
+**Type syntax (v0.4.0+):**
+- Optional shorthand: `fn find(id: Int) -> User?` (equivalent to `Optional<User>`)
+- Type aliases: `type UserId = Int`, `type Handler = (Request) -> Response`
+- Array types: `fn sum(nums: [Int]) -> Int`
+- Generics: `fn identity<T>(x: T) -> T` — type checker infers concrete types from call args
+
+**Error messages** include file:line, source snippets, expected/got context, and fix hints.
+
+`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.

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
 

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

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
 

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
 
@@ -279,6 +279,36 @@ Syntax: `let x: Type = value`
 
 Optional type annotations on variables
 
+### OPTIONAL SHORTHAND
+
+Syntax: `T?`
+
+Shorthand for Optional<T> in type annotations
+
+### TYPE ALIAS
+
+Syntax: `type Name = Type`
+
+Type alias declaration
+
+### FUNCTION TYPE
+
+Syntax: `(ParamTypes) -> ReturnType`
+
+Function type annotation for parameters and type aliases
+
+### ARRAY TYPE
+
+Syntax: `[ElementType]`
+
+Array type annotation
+
+### GENERICS
+
+Syntax: `fn name<T>(param: T) -> T { }`
+
+Generic type parameters on functions
+
 ---
 
 ## Imports