[Toyenzo]

Description

calm validate now checks each node interface that has a definition-url. It loads the schema at that URL and validates the interface config against it. Before this change, a config could leave out a property that the definition requires and validation still passed (the example in the issue).

The new check is a SEMANTIC rule beside the controls rule and works the same way. It loads the schema through the SchemaDirectory and checks the config with AJV. Each error is reported at the path of the config property, e.g. /nodes/0/interfaces/0/config/prop2. The rule runs on detailed sub-architectures too, because node-details validation runs the full engine again on each one.

One decision for review: if the definition cannot be loaded or compiled, the result is a warning (interface-definition-unresolved), not an error. Controls give an error for this. But interface definitions are often hosted somewhere else (the beginner tutorial uses calm-hub.example.com), and before this change those architectures passed. An error would make them fail with no change to the document. I can change it to an error if you prefer.

The beginner interfaces tutorial said that validation "does not yet ensure" definitions are followed. That sentence is updated, and so is the validation technical spec.

Closes #1994

AI-assisted: drafted with Claude Code; reviewed and tested by me.

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🎨 Code style/formatting changes
• ♻️ Refactoring (no functional changes)
• ⚡ Performance improvements
• ✅ Test additions or updates
• 🔧 Chore (maintenance, dependencies, CI, etc.)

Affected Components

• CLI (cli/)
• Schema (calm/)
• CALM AI (calm-ai/)
• CALM Hub (calm-hub/)
• CALM Hub UI (calm-hub-ui/)
• CALM Server (calm-server/)
• CALM Widgets (calm-widgets/)
• Documentation (docs/)
• Shared (shared/)
• VS Code Extension (calm-plugins/vscode/)
• Dependencies
• CI/CD

Commit Message Format ✅

Testing

• I have tested my changes locally

• I have added/updated unit tests

• All existing tests pass

• New e2e spec (validate-interfaces.e2e.spec.ts) runs the real validate() with the issue's example: a definition that requires prop1 (string) and prop2 (integer). Before the change, 3 of its 4 tests failed (missing property, wrong type and unloadable definition were all silent). After the change, all 4 pass.

• New unit tests cover these cases: a loader that throws, a definition that does not compile, interface types with no definition-url (skipped), an architecture that cannot be parsed, and the index path when the node has more than one interface. The rule wiring is tested in rules.spec.ts.

• npm run build:cli passes. npm run lint gives 0 errors (the 8 warnings are in calm-hub-ui and were there before).

• npm test --workspace shared: 1492 passed, 4 skipped, 5 failed. All 5 failures were timeouts on a heavily loaded machine (load average about 15). They are in the logger barrel, mermaid export, the docusaurus peer-dependency install, a network hook and the cyclic node-details e2e. The logger and node-details specs pass when run alone.

• npm test --workspace cli: 975 passed. The only failures were hook timeouts. When run alone with longer hook timeouts, cli.spec and document-loader-config.spec pass (117 tests) and the packed-CLI cli.e2e.spec passes 59/59.

Checklist

• My commits follow the conventional commit format
• I have updated documentation if necessary
• I have added tests for my changes (if applicable)
• My changes follow the project's coding standards

🤖 Generated with Claude Code