docs: document ephemeral resources, provider-defined functions, and write-only attributes (cdk-terrain#296)

[so0k]

Context

cdk-terrain#296 ("feat: support newer provider plugin-protocol features via targetVersions (RFC-04)", not yet merged) adds three entirely new public surfaces plus a CLI-side change, none of which currently have any documentation in this repo:

• TerraformEphemeralResource — new base class for Terraform's ephemeral resource type
• TerraformProviderFunction.invoke / generated <Provider>Functions bindings — provider-defined functions (provider::<name>::<function>(...))
• Deprecated write-only attribute getters + synth-time usage validation
• targetVersions now threads into cdktn get (fetch-time warning), not just diff/deploy/destroy

Confirmed via grep that ephemeral, write-only/write_only, and provider:: are not mentioned anywhere in content/ outside two "out of scope" limitation bullets that #296 will make incorrect (see below). This issue tracks writing that documentation once #296 merges.

content/api-reference/** is generated from source — do not hand-edit it for the new TerraformEphemeralResource/TerraformProviderFunction types; it will pick them up automatically. This issue is scoped to content/concepts/, content/create-and-deploy/, content/cli-reference/, and content/release/.

Related/style references already in the repo (use these as the pattern, not things that need changing themselves):

• content/release/function-availability.mdx and content/release/s3-native-locking.mdx — "What's New" page pattern (## What changed → ### <feature> subsections, feature-flag / migration callouts)
• content/concepts/mixins.mdx — concept-page pattern (## Define a mixin → worked examples → ## X vs. Y comparison → ## Related resources)
• Add: struct-typed values via Lazy producers / provider-function arguments need the resource's own xxxToTerraform mapper #26 already flags part of this ground (provider-function xxxToTerraform struct-argument gotcha) — coordinate with that issue rather than duplicating it.

Doc gaps to fill

1. New concept doc: Provider-Defined Functions

No conceptual page exists for provider::<name>::<function> today — content/concepts/functions.mdx explicitly scopes them out ("Provider-defined functions... are out of scope"). Add content/concepts/provider-functions.mdx (or a new section in functions.mdx) covering:

• What a provider-defined function is and when to reach for one instead of a resource/data source — link out to Terraform's provider-defined functions docs and the function-call syntax for what these are at the HCL level.
• Usage: generated <Provider>Functions.someFunction(...) bindings, namespace defaults to the registry short name with providerLocalName override.
• The self-reference cycle warning (don't call a provider's own functions inside that provider's config block) — already landed as JSDoc per the PR's review-findings section; surface it in prose too.
• The version-skew callout (see item 4 below) — this is the single most important thing to get right per the PR discussion.
• Cross-link with Add: struct-typed values via Lazy producers / provider-function arguments need the resource's own xxxToTerraform mapper #26's ask (the xxxToTerraform struct-argument gotcha for dynamic/object-typed function args).

2. New concept doc: Ephemeral Resources

Add content/concepts/ephemeral-resources.mdx (or a section in resources.mdx) covering:

• What ephemeral resources are and why they exist (values that are never persisted to state) — link out to Terraform's ephemeral resources docs.
• TerraformEphemeralResource base class: synthesizes to the top-level ephemeral key, referenced as ephemeral.<type>.<id>.<attr>.
• What's not available on ephemeral resources vs. normal resources: no provisioners, no connection block, no import/generateConfigForImport, no moveTo, and a narrowed TerraformEphemeralResourceLifecycle (precondition/postcondition only — no createBeforeDestroy/preventDestroy/etc.).
• A short worked example (e.g. EphemeralRandomPassword).

3. Write-only attributes section in the Resources concept doc

Add a section to content/concepts/resources.mdx (which currently has no mention of write-only attributes) covering:

• What a write-only attribute is and why the value is never in state — link out to Terraform's write-only arguments docs.
• The state-backed getter for these attributes is now @deprecated in generated code (reads always return null by protocol contract) — removal is planned for the next prebuilt-provider major, tracked in cdk-terrain#316.
• Setting a write-only attribute (constructor config or setter) registers synth-time usage validation via registerProviderFeatureUsage; note the known gap that nested/deep write-only attributes inside blocks don't yet register (cdk-terrain#308) and degrade to a plan-time error rather than silently breaking.
• Explicitly note ephemeral resources are exempt from write-only handling (write-only is a state concept; ephemeral resources have no state).

4. Document the OpenTofu provider-function version skew prominently

Per cdk-terrain#296 (comment), this is easy to misread and should be called out explicitly wherever provider-function version constraints are shown (the new concept doc from item 1, and any "what's new" release page):

OpenTofu provider-function language support starts at 1.7.0 (so synth-time targetVersions validation allows provider functions for opentofu >=1.7.0), but provider-function schema emission for binding generation only starts at OpenTofu 1.8.0. Users targeting OpenTofu 1.7.x can use provider functions, but must run cdktn get with tofu >=1.8.0 installed to actually generate the bindings.

Call this out as a deliberate asymmetry, not a bug — the PR author was explicit that a future maintainer should not "fix" this in the wrong direction.

5. Fix now-incorrect "provider functions are out of scope" bullets

Two existing docs currently say provider-defined function usage is not validated. #296 adds exactly that validation (TerraformStack checks provider-function usage against terraform >=1.8.0 / opentofu >=1.7.0). Update:

• content/concepts/functions.mdx — "Limitations" section, bullet on provider-defined functions being out of scope.
• content/release/function-availability.mdx — same bullet under "Limitations".

6. Document targetVersions now applying to cdktn get

content/create-and-deploy/configuration-file.mdx and content/cli-reference/commands.mdx currently document targetVersions/validateInstalledBinary as affecting diff, deploy, and destroy only. #296 threads targetVersions into cdktn get as well, producing a fetch-time warning when the fetching CLI binary structurally cannot emit the schema sections the declared targets admit (e.g. fetching with Terraform 1.7 while targeting terraform >=1.8.0 for provider functions). Add this behavior to both pages.

7. Consider a "What's New" release page for the whole RFC-04 feature set

Following the function-availability.mdx / s3-native-locking.mdx pattern, a single content/release/provider-feature-availability.mdx-style page introducing ephemeral resources, provider functions, and write-only attributes together (with the version-skew callout front and center) may read better than three disconnected concept-doc additions landing at once. Worth a judgment call when actually writing — could be either/or or both (concept docs for lasting reference + a release page for the version announcement).

Out of scope / explicitly not needed

• content/api-reference/** — generated, do not hand-edit.
• No change needed to content/concepts/mixins.mdx or content/release/s3-native-locking.mdx — referenced above only as style examples.

Won't start until

cdk-terrain#296 merges — the API surface (class names, method signatures, exact validation messages) may still shift during review. Re-check the current source once ready to write against it rather than the PR description.

[so0k]

Related: cdk-terrain#304 (first-class provider_meta support — noted in #296's "Known/deferred" list, with #314 closed as its duplicate).

Worth folding into item 4/5 above when writing this up: the provider_meta typing gap isn't OpenTofu-specific — it's the same class of generator/binary skew for both Terraform and OpenTofu. The provider generator will keep typing provider_meta as any until terraform providers schema -json (or tofu providers schema -json) actually includes that schema section, so the generator can type it properly. Until then, whichever binary the targetVersions-aware cdktn get run happens to use determines whether this stays untyped, independent of what the project's targetVersions declare for synth-time validation.

So when documenting the provider-function schema-emission skew (item 4), it's probably worth generalizing the framing slightly: the fetching binary's version determines what the generator can see and type (functions, ephemeral resources, provider_meta, write-only, etc.), while targetVersions only governs synth-time usage validation against the schema that was already generated. provider_meta is a good second example to cite alongside the OpenTofu 1.7/1.8 provider-function split, since it shows the same generator/binary coupling shows up on Terraform too, not just as an OpenTofu quirk.