feat(provider-fn): enforce declarative signatures on provider functions

[raphaelvigee]

Context

Provider-exposed functions (heph.<provider>.<fn>, added in #656d9ab) advertised only a name + handler. Args and the return were untyped htvalue::Value, the Starlark bridge installed every function with param_spec: for_arguments() / return_type: Ty::any(), and each handler hand-rolled its own validation. A typo, wrong type, or bad arity slipped past the engine.

Change

Add a declarative signature to ProviderFunctionDef — typed positional + named params (required/optional + default) and a typed return — and enforce it (hard-fail).

• src/htvalue/signature.rs (new): ParamType (reuses htvalue::Value kinds — String/Bool/Int/Uint/Float/Null/List/Map), Param, FnSignature with validate_args/validate_return (errors name the function + offending param) and render().
• Registry carries the signature (RegisteredFn). The bridge validates args and the return value around every call — the canonical guard, and the only one that checks the return at runtime.
• build_globals drives Starlark's native param_spec/return_type from the signature, so BUILD-time also gets arity/type errors + typing/docs. Both layers enforce.
• pluginfs glob/join/dir/base declare signatures; join now takes one list[string] (was variadic); redundant hand-rolled checks dropped.
• inspect functions prints the rendered signature, e.g. heph.fs.glob(pattern: string) -> list[string].

Scope

Provider functions only — not target, not driver config.

Test plan

• cargo build + cargo clippy --all-targets -- -D warnings clean; cargo fmt applied.
• Full lib suite: 943 passed, 0 failed.
• New: 9 validator unit tests (htvalue/signature.rs) + 6 e2e BUILD-eval tests (missing required, wrong type, too-many-positional, unknown kwarg, join requires-list, join accepts-list).

🤖 Generated with Claude Code

[raphaelvigee]

remove heph. prefix

[raphaelvigee]

@claude