Validate documented container and interface features

Docs/01-introduction/key-features.md

@@ -150,7 +150,7 @@ Features:
 - Methods (called "actions")
 - Inheritance with `extends`
 - Interfaces with `implements`
-- Events and event handlers
+- Events that an action can `trigger` (attaching handlers is not a shipped form yet)
 
 ## 7. Comprehensive Standard Library
 

Docs/reference/language-specification.md

@@ -199,12 +199,20 @@ end try
 ```
 create container <identifier> [extends <identifier>] [implements <identifier-list>]:
     [property <identifier>: <type>]*
-    [action <identifier> [with parameters <param-list>]:
+    [action <identifier> [needs <param>: <type>, ...]:
         <statements>
     end]*
 end
 ```
 
+**Interface Definition:**
+```
+create interface <identifier> [extends <identifier-list>]
+create interface <identifier> [extends <identifier-list>]:
+    [requires action <identifier> [needs <param>: <type>, ...] [: <type>]]*
+end
+```
+
 ### Expressions
 
 **Literals:** numbers, text, booleans, lists

Docs/reference/reserved-keywords.md

@@ -148,20 +148,20 @@ These keywords **MUST** always be reserved and **CANNOT** be used as variable na
 | `catch` | Error handler | `catch when error:` |
 | `check` | Start conditional | `check if x is greater than 5:` |
 | `constant` | Define constant property | `constant property max_size as 100` |
-| `container` | Define a class/container | `define container called Person:` |
+| `container` | Define a class/container | `create container Person:` |
 | `continue` | Skip to next iteration | `continue` |
 | `define` | Define action/container | `define action called test:` |
 | `display` | Output text | `display "Hello World"` |
 | `each` | For each loop | `for each item in list:` |
 | `end` | Close block | `end` |
 | `event` | Define an event | `event click` |
-| `extends` | Inheritance | `container Person extends Human:` |
+| `extends` | Inheritance | `create container Employee extends Person:` |
 | `finally` | Always-run cleanup clause on try | `finally:` |
 | `for` | For loop | `for each x in items:` |
 | `forever` | Infinite loop | `repeat forever:` |
 | `from` | Count loop start | `count from 1 to 10:` |
 | `if` | Conditional | `check if x is 5:` |
-| `implements` | Interface implementation | `container Dog implements Animal:` |
+| `implements` | Interface implementation | `create container Dog implements Animal:` |
 | `in` | For each collection | `for each item in list:` |
 | `interface` | Interface definition | `create interface Runnable:` |
 | `load` | Load module | `load module math` |
@@ -171,7 +171,7 @@ These keywords **MUST** always be reserved and **CANNOT** be used as variable na
 | `or` | Logical OR | `check if x is 5 or y is 10:` |
 | `otherwise` | Else clause | `otherwise:` |
 | `private` | Private visibility | `private property age` |
-| `property` | Container property | `property name as "default"` |
+| `property` | Container property | `property name: Text` |
 | `public` | Public visibility | `public property name` |
 | `push` | Add to list | `push with myList and item` |
 | `repeat` | Loop construct | `repeat 10 times:` |
@@ -579,7 +579,7 @@ Complete reference table of all 181 keywords.
 | `command` | Other | Process | ❌ | `execute command` |
 | `connections` | Other | Web/Network | ❌ | `network connections` |
 | `constant` | Structural | Declaration | ❌ | `constant property` |
-| `container` | Structural | OOP | ❌ | `define container` |
+| `container` | Structural | OOP | ❌ | `create container` |
 | `contains` | Contextual | Comparison | ✅ | `list contains item` |
 | `content` | Other | File I/O | ❌ | `file content` |
 | `continue` | Structural | Control Flow | ❌ | `continue loop` |

History/dev-diary/2026/2026-08-30-container-feature-validation.md

@@ -0,0 +1,73 @@
+# 2026-08-30 — Documented container and interface features, validated
+
+## What this is
+
+A pass over every user-facing container/interface claim — the containers
+guide, the language spec's `implements` list, keyword examples, and the
+key-features container bullet list — against the release binary.
+
+## What already worked
+
+The shipped `create container` / `create new` / `object.action()` /
+`object.property` surface ran as documented: typed properties, in-action
+mutation, parameterized and returning actions, `extends` with overrides,
+multi-level inheritance, `requires action` contracts (including parameters
+and interface `extends`), marker interfaces, inherited methods satisfying a
+contract, static members, property `defaults`, containers as action
+parameter types, and a container implementing more than one interface.
+
+Gated programs that already covered parts of this (`containers_comprehensive.wfl`,
+`containers/interface_contracts.wfl`, the four original docs examples, the
+interface Rust suite) still pass.
+
+## What did not match the docs
+
+**Interface return types were static-only.**
+`Docs/04-advanced-features/containers-oop.md` says a required return type is
+checked before the program runs. The type checker already reported
+`requires action get_area: Number` vs `action get_area: Text`, but the CLI
+treats type diagnostics as warnings and the runtime never compared return
+types. A container that failed the contract still defined and continued.
+
+Runtime conformance now stores each method and each `requires action` return
+type and rejects a concrete mismatch when the container definition runs —
+the same stop as a missing action or a wrong arity.
+
+**Keyword examples used a grammar that does not parse.**
+`define container called Person:` / `store pet as new Animal` was still the
+example in the reserved-keyword table and in
+`TestPrograms/docs_examples/keyword_reference/containers_examples.wfl`
+(CI-SKIP'd). Those now show `create container` / `create new`.
+
+**Event handlers were listed as a container feature.**
+`key-features.md` claimed "Events and event handlers." Declaring `event` and
+`trigger` inside a container works; `on <instance> <event>:` does not parse
+a handler body. The bullet now says handlers are not a shipped form.
+
+## Coverage added
+
+- `TestPrograms/containers/documented_features.wfl` — 14 `describe`/`expect`
+  cases covering the containers-guide surface plus multiple `implements`,
+  defaults, and static members.
+- `TestPrograms/error_examples/interface_return_type.wfl` and
+  `interface_static_action.wfl` — gated expected-failure programs.
+- `tests/interface_contract_test.rs` —
+  `container_with_incompatible_return_type_fails_at_runtime`.
+- Docs examples for inheritance, override, interface `extends`, marker
+  interfaces, and property access, registered in the docs-examples manifest.
+
+## TDD evidence
+
+Red: `wfl TestPrograms/error_examples/interface_return_type.wfl` exited 0
+and printed `unreachable: a return-type mismatch must fail` against the
+pre-change release binary; the new Rust test encodes that same program and
+requires a nonzero exit naming `get_area` and `return`.
+
+Green: after the runtime check, that program exits 1 with
+`action 'get_area' returns Text but the interface requires Number`, and the
+14 asserted documented-feature tests pass.
+
+Risk class **R3** (backward compatibility / public contract): a program that
+claimed `implements` with a concrete return-type mismatch used to run; it
+now stops at the container definition, matching the already-documented
+static rule.