feature - support generic decorator factories (#640)

[dannymeijer]

Summary

This PR extends the v0.3 user-defined decorator surface so decorator factories can be generic over the decorated function type. Libraries can now write one registration-style helper such as registered[F](...) -> ((F) -> F), rely on inference from the decorated function, or provide an explicit decorator factory type argument like @registered[(str) -> ColumnExpr](...). The change also preserves concrete decorated source signatures through checked API metadata and imports, which unblocks catalog/decorator authoring without signature-specific factory helpers.

Type of change

• Bug fix
• New feature
• Refactor / maintenance
• Documentation
• CI / tooling
• RFC (adds/updates docs/RFCs/*)

Area(s)

Select the primary areas touched (used for review routing; labels are managed separately):

• Incan Language (syntax/semantics)
• Compiler (frontend/backend/codegen)
• Tooling (CLI/formatter/test runner)
• Editor integration (LSP/VS Code extension)
• Runtime / Core crates (stdlib/core/derive)
• Documentation

Key details

• User-facing behavior: Decorator factories support explicit call-site type arguments and can infer the decorated callable type when returning ((F) -> F). Checked API metadata continues to expose the concrete decorated function signature.
• Decorator contract: User-defined decorators are callable-to-callable transforms. The typechecker now rejects decorators whose application result is not callable, and the language reference includes a Python migration note mapping Callable[[A, B], R] to (A, B) -> R.
• Internals: The decorator AST now carries factory type arguments through parsing, formatting, typechecking, lowering, and bridge rejection where the public vocab bridge cannot represent them. Closure expressions gained contextual typing against expected function shapes so generic identity-style factories typecheck cleanly. Decorator application lowering now separates the factory-call span from the synthetic callable-application span so monomorph metadata is not applied twice.
• Formatter/parser compatibility: Closure parameters are formatted with the untyped closure syntax the parser accepts today, avoiding formatter output such as (func: _) => func.
• Generated docs: The decorator-factory reference prose now lives in the generated reference source, and feature inventory metadata is registry-backed.
• Risks: This touches decorator parsing/typechecking/lowering and generated Rust emission. Existing compiler-owned decorators should keep their behavior, but decorator factory edge cases are the main regression surface.

Testing / verification

• make test / cargo test
• make examples (if relevant)
• incan fmt --check . (if relevant)
• Manual verification described below

Manual verification notes:

• cargo test -p incan_syntax test_parse_decorator_factory_with_explicit_type_args
• cargo test test_format_source_preserves_untyped_closure_params
• cargo test test_user_defined_decorator_rejects_non_callable_and_factory_result
• cargo test decorator_factory
• cargo test -p incan_core
• cargo run -p incan_core --bin generate_lang_reference
• target/debug/incan fmt /private/tmp/incan640debug/src/registry.incn
• target/debug/incan tools metadata api /private/tmp/incan640debug/src/registry.incn --format json
• make fmt
• make pre-commit passed, including fmt-check, rustdoc, 2449 nextest tests, clippy, cargo-deny, and smoke-test-fast
• git diff --check origin/release/v0.3..HEAD

Docs impact

• No docs changes needed
• Docs updated
• Docs follow Divio intent (tutorial/how-to/reference/explanation) where applicable

If docs updated:

• Link(s): workspaces/docs-site/docs/language/reference/language.md, workspaces/docs-site/docs/language/reference/feature_inventory.md, workspaces/docs-site/docs/release_notes/0_3.md, workspaces/docs-site/docs/RFCs/closed/implemented/036_user_defined_decorators.md

Checklist

• I kept public docs user-focused and moved internals to contributing docs when appropriate
• I avoided duplicating canonical install/run instructions in multiple places
• I added/updated tests where it materially reduces regressions

Closes #640