Feature/strict context audit

.cursorrules

@@ -6,7 +6,7 @@ When modifying or generating code for this repository, you MUST adhere to the fo
 - **Never** use `save_entity_graph_from()`, `save_entity_with_comment()`, or any other repository-level methods directly on a `Repository` or `ResolvedRepository` instance to persist entities.
 - **Why?** Saving via the repository graph API (e.g., `save_entity_graph_from`) executes a full entity graph replacement. If child relations (like execution logs) are not explicitly loaded and re-attached to the graph, the framework will implicitly delete the missing records in the database.
 
-## 2. Use the Entity API (NTTAPI) Exclusively
+## 2. Use the Entity API Exclusively
 - Always perform state transitions or updates directly on the domain entity object itself, and call the generated `.save(&ctx).await` method on the entity.
 - Example:
   ```rust
@@ -18,3 +18,39 @@ When modifying or generating code for this repository, you MUST adhere to the fo
 
 ## 3. Explicit Deletion Only
 - Data MUST NOT be deleted implicitly. Unless there is an explicit deletion command or `.mark_as_delete()` is explicitly called on an entity, no command should delete any data.
+
+## 4. ABSOLUTE BAN ON `T::` TOOLS
+- Inside the application layer, you are strictly forbidden from calling any stateless utility from the `teaql_tool::T` facade directly.
+- All side effects (network, file) and all stateful computations (time, formatting, ID generation) MUST go through the user context (`ctx`).
+
+## 5. MANDATORY BUSINESS INTENT (`.comment()`)
+- Every single tool call must be appended with `.comment("English intent description")`. If you do not provide this, the result is encapsulated in a `MustComment<T>` wrapper and cannot be used, leading to compile errors.
+
+**Correct Examples:**
+```rust
+// Pure computation with Context Timezone and intent explanation
+let deadline = ctx.time().today().add_days(7).comment("Calculate 7-day grace period for payment");
+
+// IO Operation with Audit intent
+let data = ctx.file().read(path).comment("Load tenant specific configuration file").await?;
+```
+
+```rust
+let now = T::time().today(); // ERROR: Banned usage, no timezone!
+let id = T::id().uuid(); // ERROR: Cannot extract string without .comment()!
+let data = std::fs::read(path); // ERROR: Banned IO library!
+```
+
+## 6. ZERO-CODE LOGGING & DEBUGGING (ENVIRONMENT VARIABLES)
+- Do **NOT** insert `println!`, `tracing::info!`, or manually write custom log messages in the application layer code to debug data/SQL issues.
+- When you need to investigate SQL execution, entity changes, or tool calls during `cargo run` or `cargo test`, you MUST use the built-in 7 `TEAQL_` environment variables:
+  - `TEAQL_AUDIT`: Controls entity data change logs (`_silent`, `_summary`, `_full`).
+  - `TEAQL_SQL`: Controls SQL query logs (`_silent`, `_summary`, `_full`).
+  - `TEAQL_SQL_TABLES`: Filters SQL logs to specific tables (e.g., `task,task_status`).
+  - `TEAQL_TOOL`: Controls `ctx` tool usage logs (`_silent`, `_summary`, `_full`).
+  - `TEAQL_TOOL_FOCUS`: Filters tool logs to specific modules (e.g., `http,file`).
+  - `TEAQL_SINK`: Output destination (`_stdout`, `_file`, `_both`).
+  - `TEAQL_SCHEMA`: Controls schema migration (`_verify` [default], `_dryrun`, `_execute`). **Tests modifying schema MUST use `TEAQL_SCHEMA=_execute`.**
+- Example: If you want to see all SQL generated for the `task` table during a test, run:
+  `TEAQL_SCHEMA=_execute TEAQL_SQL=_full TEAQL_SQL_TABLES=task cargo test -- --nocapture`
+- The system enforces a strict whitelist. An invalid env var name (like `TEAQL_SQLL`) or invalid value will immediately panic and halt the process.

Cargo.toml

@@ -15,12 +15,13 @@ serde_json = "1"
 tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
 
 # TeaQL runtime packages
-teaql-core = "2.0.0"
-teaql-runtime = "2.0.0"
-teaql-macros = "2.0.0"
-teaql-sql = "2.0.0"
-teaql-provider-rusqlite = "2.0.0"
-teaql-data-service = "2.0.0"
+teaql-core = "2.0.1"
+teaql-runtime = "2.0.1"
+teaql-macros = "2.0.1"
+teaql-sql = "2.0.1"
+teaql-provider-rusqlite = "2.0.1"
+teaql-data-service = "2.0.1"
+teaql-tool-core = { path = "../teaql-rust-utils/teaql-tool-core" }
 
 # Our generated TeaQL domain logic library
 robot-kanban = { package = "robot-kanban-service", path = "./generate-lib/lib" }
@@ -33,9 +34,3 @@ codegen-units = 1
 panic = "abort"
 strip = true
 
-[patch.crates-io]
-teaql-core = { path = "../teaql-rs/teaql-core" }
-teaql-runtime = { path = "../teaql-rs/teaql-runtime" }
-teaql-sql = { path = "../teaql-rs/teaql-sql" }
-teaql-provider-rusqlite = { path = "../teaql-rs/teaql-provider-rusqlite" }
-teaql-data-service = { path = "../teaql-rs/teaql-data-service" }

README.md

@@ -126,6 +126,32 @@ TeaQL propagates comments through nested queries, facets, and aggregates, so eve
 
 ---
 
+## Zero-Code Logging & Debugging
+
+TeaQL provides 7 environment variables to control the runtime behavior, schema migrations, and logging outputs—without modifying a single line of code. All builtin values are prefixed with an underscore (`_`) to avoid collisions with your entity names.
+
+| Environment Variable | Description | Default | Allowed Values |
+|---|---|---|---|
+| `TEAQL_AUDIT` | Entity data change logs | `_full` | `_silent`, `_summary`, `_full` |
+| `TEAQL_SQL` | SQL query logs | `_silent` | `_silent`, `_summary`, `_full` |
+| `TEAQL_SQL_TABLES` | Filter SQL logs to specific tables | (All tables) | `task,task_status`, etc. |
+| `TEAQL_TOOL` | `ctx` tool usage logs (HTTP, File, etc.) | `_silent` | `_silent`, `_summary`, `_full` |
+| `TEAQL_TOOL_FOCUS` | Filter tool logs to specific modules | (All modules) | `http,money`, etc. |
+| `TEAQL_SINK` | Output destination | `_both` | `_stdout`, `_file`, `_both` |
+| `TEAQL_SCHEMA` | Schema migration & verification mode | **`_verify`** | `_verify`, `_dryrun`, `_execute` |
+
+**Development / AI Assistant Debugging:**
+To run tests and see exactly what SQL statements are generated for a specific table:
+```bash
+# Auto-apply schema changes, log all SQL for the 'task' table
+TEAQL_SCHEMA=_execute TEAQL_SQL=_full TEAQL_SQL_TABLES=task cargo test -- --nocapture
+```
+
+**Production Safety:**
+The system enforces a strict whitelist. If you provide an unknown environment variable (e.g., `TEAQL_SQLL`) or an invalid value, the application will panic immediately at startup and refuse to run. The default `TEAQL_SCHEMA=_verify` ensures that the app will not blindly modify your production schema.
+
+---
+
 ## What Is TeaQL?
 
 TeaQL applications are composed of three layers.