test: cover numeric function subtraction returns

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+### Validate numeric function subtraction returns
+
+- Added focused positive typecheck coverage proving that a typed function can return a numeric subtraction expression after `CHECK TYPE` establishes its parameter type.
+- Wired the fixture into the standalone typecheck validator and `claro validate`.
+
 ### Validate division return diagnostics
 
 - Added focused `claro typecheck` coverage proving that a typed function returning `amount / "oops"` identifies division, the required `NUMBER` operands, and the offending `TEXT` value.

docs/ADVANCED_STATIC_TYPING.md

@@ -85,6 +85,17 @@ END
 
 This valid division case is included in the focused typecheck validation matrix beside the diagnostic for using a TEXT operand in division.
 
+Subtraction follows the same rule:
+
+```claro
+TEACH difference amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount - 2
+END
+```
+
+The focused validator checks this positive function case as well as the matching subtraction diagnostic for a TEXT operand.
+
 The same protection applies to object methods. A checked NUMBER parameter can be divided by a number and returned as NUMBER:
 
 ```claro

docs/CURRENT_STATUS.md

@@ -60,7 +60,7 @@ Ready now:
 
 Still needed:
 - Keep the focused typecheck validator's fixture list complete as new positive and negative examples are added. `claro validate` now executes the complete focused fixture matrix as well, so release validation cannot silently omit a listed typecheck example.
-- The expression checker now carries a known TEXT operand through all arithmetic operators so object-field and typed-function-return diagnostics do not hide addition, subtraction, multiplication, or division mistakes; focused numeric-subtraction, numeric-division, and numeric-multiplication positives plus text-operand addition, subtraction, multiplication, and division negatives protect this behavior. Typed-function return diagnostics now also have focused division coverage. Text concatenation into a TEXT field has focused positive fixtures for both operand orders, including concatenation of two TEXT object fields. Each numeric operator names the text operand and explains that it needs NUMBER values.
+- The expression checker now carries a known TEXT operand through all arithmetic operators so object-field and typed-function-return diagnostics do not hide addition, subtraction, multiplication, or division mistakes; focused numeric-subtraction, numeric-division, and numeric-multiplication positives plus text-operand addition, subtraction, multiplication, and division negatives protect this behavior. Typed-function return diagnostics now have focused subtraction and division positives alongside multiplication coverage. Text concatenation into a TEXT field has focused positive fixtures for both operand orders, including concatenation of two TEXT object fields. Each numeric operator names the text operand and explains that it needs NUMBER values.
 - Method return validation now has focused positive subtraction and division fixtures alongside the existing arithmetic return coverage, including a compatibility `TAKES` / `LEARNED` division case, so checked NUMBER method parameters and numeric subtraction or division remain accepted by the release validator in both method spellings.
 - richer typed function signatures and return values beyond the focused simple function/method `RETURNS TYPE` check
 - type checking through branches and loops

docs/ROADMAP.md

@@ -36,7 +36,7 @@ See `CURRENT_STATUS.md` for the detailed feature matrix.
 3b. Keep package security validation in Forgejo/Gitea CI so unsafe names, exact manifest-version/name/version/checksum mismatches, missing manifests, duplicate project manifest versions and packages, duplicate lock packages, duplicate package manifest names, versions, and checksums, and lockfile errors remain release blockers.
 4. Add small examples for each foundation feature before adding bigger syntax. The object-field foundation now includes positive and negative validation for field expressions such as `SET player.score player.name`, `SET player.score player.score + 1`, `SET player.name player.score + 1`, explicitly typed field assignments, explicit typed assignments to undeclared fields, simple and chained aliases such as `SET alias player`, `SET backup alias`, followed by `SET backup.score ...` or `CHECK TYPE backup.score IS ...`, chained aliases in object-method calls through both modern `DO` and compatibility `CALL ... WITH` forms (including a dedicated positive modern `DO` fixture), and arithmetic/text expression mismatches; typed containers also accept a map with nested type metadata when it is added to a `LIST OF MAP`; broader alias/control-flow checking remains planned.
 5. Keep the focused typecheck validator complete: every `typecheck_*.claro` fixture, including positive fixtures, is now exercised by both the standalone diagnostic validator and `claro validate`.
-6. Continue narrowing expression diagnostics: known TEXT operands now remain visible through arithmetic, with focused numeric-subtraction, numeric-division, and numeric-multiplication positives plus text-operand addition, subtraction, multiplication, and division coverage. Text concatenation into TEXT fields is covered in both operand orders, including field-to-field concatenation. Each numeric operator gives specific guidance naming the text operand. `CHECK TYPE` also rejects misspelled expected type names before comparing values.
+6. Continue narrowing expression diagnostics: known TEXT operands now remain visible through arithmetic, with focused numeric-subtraction, numeric-division, and numeric-multiplication positives plus text-operand addition, subtraction, multiplication, and division coverage. Typed function returns now include positive subtraction and division examples alongside multiplication. Text concatenation into TEXT fields is covered in both operand orders, including field-to-field concatenation. Each numeric operator names the text operand and explains that it needs NUMBER values. `CHECK TYPE` also rejects misspelled expected type names.
 - Keep typed method return examples balanced: numeric subtraction and division now have dedicated positive method fixtures in the focused validator, including a compatibility `TAKES` / `LEARNED` division case, alongside the existing method return mismatch diagnostics.
 - Keep IDE metadata aligned with the current beginner syntax: typed-language keywords such as `RETURNS`, `CHECK`, and `TYPE` are now included in the metadata used by editor helpers.
 - Keep compatibility-call coverage aligned with modern calls: empty `CALL object.method WITH` forms now have a focused missing-argument diagnostic fixture alongside the modern `DO object.method` case.

tests/typecheck_function_return_subtraction_good.claro

@@ -0,0 +1,6 @@
+TEACH difference amount RETURNS NUMBER
+    CHECK TYPE amount IS NUMBER
+    RETURN amount - 2
+END
+
+DO difference 5

tools/validate_typecheck_diagnostics.py

@@ -271,6 +271,7 @@ EXPECTED_OK = [
     "tests/typecheck_function_return_expression_good.claro",
     "tests/typecheck_function_return_multiplication_good.claro",
     "tests/typecheck_function_return_division_good.claro",
+    "tests/typecheck_function_return_subtraction_good.claro",
     "tests/typecheck_function_unknown_return_expression_good.claro",
     "tests/typecheck_function_branch_complete_good.claro",
     "tests/typecheck_function_nested_branch_complete_good.claro",