update docs for compile chain

docs/c-modules.md

@@ -52,10 +52,13 @@ Where:
 Examples:
 - `mypackage/math.c` -> `js_mypackage_math_use`
 - `gitea.pockle.world/john/lib/render.c` -> `js_gitea_pockle_world_john_lib_render_use`
+- `mypackage/internal/helpers.c` -> `js_mypackage_internal_helpers_use`
 - `mypackage/game.ce` (AOT actor) -> `js_mypackage_game_program`
 
 Actor files (`.ce`) use the `_program` suffix instead of `_use`.
 
+Internal modules (in `internal/` subdirectories) follow the same convention — the `internal` directory name becomes part of the symbol. For example, `internal/os.c` in the core package has the symbol `js_core_internal_os_use`.
+
 **Note:** Having both a `.cm` and `.c` file with the same stem at the same scope is a build error.
 
 ## Required Headers

docs/compiler-tools.md

@@ -72,6 +72,7 @@ cell streamline --stats <file.ce|file.cm>        # summary stats per function
 cell streamline --ir <file.ce|file.cm>           # human-readable IR
 cell streamline --check <file.ce|file.cm>        # warnings only
 cell streamline --types <file.ce|file.cm>        # IR with type annotations
+cell streamline --diagnose <file.ce|file.cm>     # compile-time diagnostics
 ```
 
 | Flag | Description |
@@ -81,6 +82,7 @@ cell streamline --types <file.ce|file.cm>        # IR with type annotations
 | `--ir` | Human-readable canonical IR (same format as `ir_report.ce`) |
 | `--check` | Warnings only (e.g. `nr_slots > 200` approaching 255 limit) |
 | `--types` | Optimized IR with inferred type annotations per slot |
+| `--diagnose` | Run compile-time diagnostics (type errors and warnings) |
 
 Flags can be combined.
 

docs/nota.md

@@ -5,7 +5,7 @@ weight: 85
 type: "docs"
 ---
 
-Nota is a binary message format developed for use in the Procession Protocol. It provides a compact, JSON-like encoding that supports blobs, text, arrays, records, numbers, and symbols.
+Nota is a binary message format developed for use in the Procession Protocol. It provides a compact, JSON-like encoding that supports blobs, text, arrays, records, numbers, and symbols. Nota is an internal module: `use('internal/nota')`.
 
 Nota stands for Network Object Transfer Arrangement.
 

docs/shop.md

@@ -230,4 +230,4 @@ If `shop.toml` is missing or has no `[policy]` section, all methods are enabled
 | `internal/os.c` | OS intrinsics: dylib ops, internal symbol lookup, embedded modules |
 | `package.cm` | Package directory detection, alias resolution, file listing |
 | `link.cm` | Development link management (link.toml read/write) |
-| `boot/*.cm.mcode` | Pre-compiled pipeline seeds (tokenize, parse, fold, mcode, bootstrap) |
+| `boot/*.cm.mcode` | Pre-compiled pipeline seeds (tokenize, parse, fold, mcode, streamline, bootstrap) |

docs/spec/pipeline.md

@@ -69,6 +69,7 @@ Optimizes the Mcode IR through a series of independent passes. Operates per-func
 6. **Move elimination**: Removes self-moves (`move a, a`).
 7. **Unreachable elimination**: Nops dead code after `return` until the next label.
 8. **Dead jump elimination**: Removes jumps to the immediately following label.
+9. **Compile-time diagnostics** (optional): When `_warn` is set on the mcode input, emits errors for provably wrong operations (storing named property on array, invoking null, etc.) and warnings for suspicious patterns (named property access on array/text). The engine aborts compilation if any error-severity diagnostics are emitted.
 
 See [Streamline Optimizer](streamline.md) for detailed pass descriptions.
 
@@ -134,6 +135,7 @@ Seeds are used during cold start (empty cache) to compile the pipeline modules f
 | `mcode.ce --pretty` | Print raw Mcode IR before streamlining |
 | `streamline.ce --types` | Print streamlined IR with type annotations |
 | `streamline.ce --stats` | Print IR after streamlining with before/after stats |
+| `streamline.ce --diagnose` | Print compile-time diagnostics (type errors and warnings) |
 
 ## Test Files
 
@@ -146,3 +148,4 @@ Seeds are used during cold start (empty cache) to compile the pipeline modules f
 | `qbe_test.ce` | End-to-end QBE IL generation |
 | `test_intrinsics.cm` | Inlined intrinsic opcodes (is_array, length, push, etc.) |
 | `test_backward.cm` | Backward type propagation for parameters |
+| `tests/compile.cm` | Compile-time diagnostics (type errors and warnings) |

docs/spec/streamline.md

@@ -178,6 +178,36 @@ Removes `jump L` instructions where `L` is the immediately following label (skip
 
 **Nop prefix:** `_nop_dj_`
 
+### 9. diagnose_function (compile-time diagnostics)
+
+Optional pass that runs when `_warn` is set on the mcode input. Performs a forward type-tracking scan and emits diagnostics for provably wrong operations. Diagnostics are collected in `ir._diagnostics` as `{severity, file, line, col, message}` records.
+
+This pass does not modify instructions — it only emits diagnostics.
+
+**Errors** (compilation is aborted):
+
+| Pattern | Message |
+|---------|---------|
+| `store_field` on T_ARRAY | storing named property on array |
+| `store_index` on T_RECORD | storing numeric index on record |
+| `store_field` / `store_index` on T_TEXT | storing property/index on text |
+| `push` on T_TEXT / T_RECORD | push on text/record |
+| `invoke` on T_NULL / T_INT / T_FLOAT / T_NUM / T_TEXT / T_BOOL / T_ARRAY | invoking null/number/text/bool/array |
+| arity mismatch (module imports only) | function expects N arguments, got M |
+
+**Warnings** (compilation continues):
+
+| Pattern | Message |
+|---------|---------|
+| `load_field` on T_ARRAY | named property access on array |
+| `load_field` on T_TEXT | named property access on text |
+| `load_dynamic` with T_TEXT key on T_RECORD | text key on record |
+| `load_dynamic` with T_RECORD / T_ARRAY / T_BOOL / T_NULL key on T_RECORD | record/array/bool/null key on record |
+
+The engine (`internal/engine.cm`) prints all diagnostics and aborts compilation if any have severity `"error"`. Warnings are printed but do not block compilation.
+
+**Nop prefix:** none (diagnostics only, does not modify instructions)
+
 ## Pass Composition
 
 All passes run in sequence in `optimize_function`:
@@ -191,6 +221,7 @@ simplify_booleans
 eliminate_moves
 eliminate_unreachable
 eliminate_dead_jumps
+diagnose_function        → optional, when _warn is set
 ```
 
 Each pass is independent and can be commented out for testing or benchmarking.

docs/testing.md

@@ -192,6 +192,36 @@ Failures saved to tests/fuzz_failures/
 
 Saved failure files are valid `.cm` modules that can be run directly or added to the test suite.
 
+## Compile-Time Diagnostics Tests
+
+The `tests/compile.cm` test suite verifies that the type checker catches provably wrong operations at compile time. It works by compiling source snippets through the pipeline with `_warn` enabled and checking that the expected diagnostics are emitted.
+
+```javascript
+var shop = use('internal/shop')
+var streamline = use('streamline')
+
+function get_diagnostics(src) {
+  fd.slurpwrite(tmpfile, stone(blob(src)))
+  var compiled = shop.mcode_file(tmpfile)
+  compiled._warn = true
+  var optimized = streamline(compiled)
+  if (optimized._diagnostics == null) return []
+  return optimized._diagnostics
+}
+```
+
+The suite covers:
+- **Store errors**: storing named property on array, numeric index on record, property/index on text, push on text/record
+- **Invoke errors**: invoking null, number, text
+- **Warnings**: named property access on array/text, record key on record
+- **Clean code**: valid operations produce no diagnostics
+
+Run the compile diagnostics tests with:
+
+```bash
+pit test compile
+```
+
 ## Test File Organization
 
 Tests live in the `tests/` directory of a package:

docs/wota.md

@@ -5,7 +5,7 @@ weight: 86
 type: "docs"
 ---
 
-Wota is a binary message format for local inter-process communication. It is similar to Nota but works at word granularity (64-bit words) rather than byte granularity. Wota arrangements are less compact than Nota but faster to arrange and consume.
+Wota is a binary message format for local inter-process communication. It is similar to Nota but works at word granularity (64-bit words) rather than byte granularity. Wota arrangements are less compact than Nota but faster to arrange and consume. Wota is an internal module: `use('internal/wota')`.
 
 Wota stands for Word Object Transfer Arrangement.