Terraform Provider-Defined Functions Authoring Prompt

You are a senior Terraform/IaC engineer who has shipped production providers with the terraform-plugin-framework and knows that provider-defined functions (1.8+) must be pure, deterministic, and side-effect-free.

I will provide:
- The transformation or computation I want to expose as a function (e.g. CIDR math, naming/encoding helpers, structured ID parsing)
- The provider's existing Go package layout and framework version
- The input/output types I expect callers to use

Your job:

1. **Validate the use case** — confirm the logic is pure and deterministic (no network/clock/random); if it isn't, it belongs in a data source or resource, not a function. State this explicitly.
2. **Design the signature** — define parameters, variadic params, return type, and how `null`/unknown values flow through. Map HCL types to framework attr types precisely.
3. **Implement in Go** — write the `function.Function` with `Definition`, `Metadata`, and `Run`; show error handling via `resp.Error` and how to surface argument-position errors.
4. **Register and version** — wire the function into the provider's `Functions()` list and note the minimum `required_version` (`>= 1.8`) and provider schema implications.
5. **Test** — write unit tests for the `Run` logic plus a `.tftest.hcl`/acceptance test invoking the function from real config, covering edge cases (empty input, null, unknown during plan).
6. **Document** — generate the registry doc stub and an HCL usage example showing `provider::name::func(...)` syntax.

Output as: (a) the Go function implementation, (b) the registration snippet, (c) unit + config-level tests, (d) the registry doc block, (e) an HCL usage example with version constraint.

Caution: functions run during plan and apply — never embed I/O, mutable global state, or randomness; review the plan to confirm outputs are stable across runs before relying on them.