feat: support newer provider plugin-protocol features via targetVersions (RFC-04)

[so0k]

Implements RFC-04 — provider feature availability: support the newer provider plugin-protocol capability families with targetVersions-aware codegen and synth-time validation. Proposal, dataset, sweep tooling and interactive report live in open-constructs/cdktn-planning → RFCS/04-provider-feature-availability/ (only the merged matrix is vendored here, matching the function-availability split).

Builds directly on the #269 foundation (targetVersions + ValidateFeatureTargetSupport) and the #268 usage-registry pattern.

Guiding decision

Generate the full surface the schema offers; narrow per project at synth time via targetVersions. Generation-time filtering would fork the generated API by project configuration — impossible for prebuilt providers and hostile to caching. Constraints baked into the validations are the per-product >= ranges from the sweep dataset.

Review guide (one commit per RFC rollout item)

1. chore: vendor provider-feature availability matrix — dataset digest + README only, no behavior change.
2. feat(lib): TerraformEphemeralResource — new public base class synthesizing to the top-level ephemeral key (JSON + HCL renderer), refs as ephemeral.<type>.<id>.<attr>, no provisioners/connection/import/move. Constructor registers the target-version validation unconditionally (new API surface — only fires on use, no feature flag per RFC). Internal providerFeatureConstraints map sourced from the vendored matrix.
3. feat(provider-generator): acquire newer provider-protocol schema sections (Phase 0, a bugfix on its own) — commons types for functions / ephemeral_resource_schemas / resource_identity_schemas / write_only; sanitizer walks ephemeral schemas; fetched schemas stamped with the fetching CLI; cache key now includes CLI product+minor (a schema fetched once with an old CLI no longer poisons every later generation); fetch-time warning when the fetching binary structurally cannot emit sections the targets admit.
4. feat(provider-generator): generate ephemeral resource bindings — third schema family mirroring the data_ pipeline (EphemeralRandomPassword in ephemeral-random-password/), config extends TerraformEphemeralMetaArguments, no generateConfigForImport. Zero churn in existing snapshots (ephemeral models append after resources/data sources; class-name dedup is order-dependent).
5. feat(provider-generator): generate provider-defined function bindings — TimeProviderFunctions.rfc3339Parse(ts) → ${provider::time::rfc3339_parse(...)}; namespace defaults to the registry short name with a providerLocalName override (local names change the namespace, aliases don't). Runtime flows through one public jsii chokepoint (TerraformProviderFunction.invoke) feeding a usage registry; TerraformStack validates usage against terraform >=1.8.0 / opentofu >=1.7.0 — note the deliberate asymmetry: OpenTofu language support (1.7.0) predates its schema emission (1.8.0), so generation and validation use different boundaries.
6. feat(provider-generator): deprecate write-only attribute getters, validate usage — providers never persist write-only values (every read is null by protocol contract), so the state-backed getter is a trap: emitted @deprecated now, removal rides the next prebuilt major (JSII-breaking otherwise). Setting one (setter or constructor config) registers usage via a new protected TerraformResource.registerProviderFeatureUsage hook — generated code reaches the validation machinery only by extending base classes.
7. feat(cli): thread targetVersions into cdktn get — GetOptions.targetVersions → ConstructsMaker → readSchema, driving the Phase 0 fetch-time warning; constraints.json gains diagnostic stamps (targetVersions, fetching cli) without affecting the filterAlreadyGenerated staleness logic (targets don't change codegen output, so they must not force regeneration).

Test coverage

• Generator: snapshot tests against real terraform providers schema -json fragments from the sweep (random ephemeral, time functions incl. object returns, vault *_wo), plus a synthetic fixture for variadic/reserved-name mapping branches. Zero churn in pre-existing snapshots.
• Core: validation matrices mirroring validations.test.ts (admit/exclude per product, hint text, the OpenTofu 1.7.0 asymmetry, registry resets).
• Schema: emission-gap logic matrix, cache-key suffix behavior, sanitizer walk over ephemeral schemas; CLI stamps in network snapshots are stubbed (environment-dependent).

Known/deferred

• matchers.test.ts › toPlanSuccessfully fails in this environment before and after these changes (downloads the real docker provider; verified pre-existing via stash on the unmodified tree).
• Deferred per RFC Phase 4: resource identity consumption (schema plumbing already carried), list resources / actions / state stores (Terraform-only today; re-evaluate on Support 'query' CLI and provider 'list' resources as in Terraform 1.14 opentofu/opentofu#3787).
• Follow-ups tracked as issues: Nested write-only attributes don't register targetVersions feature usage #308 (nested write-only registration), In-repo consistency check for the provider-feature availability matrix and its hand-maintained maps #309 (matrix drift check / in-repo tooling), hcl2cdk: convert top-level ephemeral {} blocks #310 (hcl2cdk ephemeral conversion), Edge-provider schema: cross-language compile coverage for ephemeral resources, provider functions, write-only attributes #311 (edge-provider schema cross-language coverage), Integration test: ephemeral resources end-to-end, gated on Terraform >= 1.10 #312 (ephemeral integration test gated on TF >= 1.10), fix(lib): HCL synth corrupts or drops core blocks (terraform{} extras, top-level overrides, lifecycle conditions) #313 (pre-existing HCL renderer defects), lib: add addProviderMeta() helper for terraform { provider_meta } blocks (value stays any) #304 (first-class provider_meta; feat(lib): first-class provider_meta support (aws user_agent module attribution) #314 closed as its duplicate), Remove write-only attribute getters at the next prebuilt-provider major (deprecated in #296) #316 (remove the deprecated write-only getters at the next prebuilt-provider major — the Phase 3 end state). New this round: provider-generator: structural typing for object-shaped provider-function parameters and returns #336 (structural typing for object-shaped function params/returns), CI: thin-slice runtime coverage for newer-protocol features on current stable Terraform AND OpenTofu #337 (runtime CI thin slice on terraform 1.15.x + opentofu 1.12.x — CI's Terraform ceiling is 1.6.5, so the new schema sections are covered by fixture unit tests, the edge-provider compile slice below, and the external demo harness until CI: thin-slice runtime coverage for newer-protocol features on current stable Terraform AND OpenTofu #337 lands).

Review findings addressed (from the demo-harness verification comment)

• Fixed — targetVersions validation bypass: CdktfConfig.targetVersions (the runGetInDir path) now validates via commons validateTargetVersions (warn + ignore), and the emission-gap check treats invalid ranges as not-wanted instead of throwing — a malformed range previously crashed cdktn get via semver.intersects.
• Fixed — ephemeral lifecycle narrowed: new TerraformEphemeralResourceLifecycle (precondition/postcondition only) replaces the full managed-resource lifecycle on the ephemeral API, before it ships as jsii surface.
• Fixed (docs) — provider-fn self-reference cycle: generated provider-function JSDoc and TerraformProviderFunction.invoke now warn against calling a provider's functions inside that same provider's configuration block.
• Documented — ephemeral × write-only: registration deliberately skips ephemeral resources — write-only is a state concept, ephemeral resources have no state, and no schema in the sweep (incl. vault's 16 ephemeral resources) combines the two.
• Follow-up — nested write-only registration (Nested write-only attributes don't register targetVersions feature usage #308): write_only inside nested blocks gets the deprecated getter but skips usage registration; deep config scanning deserves its own PR (a miss degrades to the plan-time error, not silent breakage).
• Pre-existing / by design: the AWS barrel-import OOM predates this PR (lazy-index is the existing mitigation); Fn.ephemeralasnull + sensitive on outputs is Terraform semantics (docs candidate); list resources / actions / resource identity codegen is the RFC Phase 4 deferral noted above.

Second review round addressed

• Fixed — cross-App usage-registry leak: App construction now resets both usage registries (a new App = a new synthesis session). Within an App the process-global registry is by design — every stack resolves the same targetVersions from App context — but usage no longer leaks into later, unrelated Apps in the same process (the reviewer's jest scenario). Regression tests cover the exact sequence; the flag-gated Fn registry had the same latent leak and is reset too.
• Fixed — emission-gap warning on cache hits: the warning moved from readProviderSchema into readSchema, running for cached and fresh schemas using the cli_name/cli_version stamps the schema carries. Regression test: two readSchema calls against a cache dir → one producer call, two warnings.
• Docs — matrix as source of truth: both hand-maintained maps now name features-matrix.json as their source and cross-reference each other; automated drift check tracked in In-repo consistency check for the provider-feature availability matrix and its hand-maintained maps #309.

Third review round addressed (cfncompat/awscc demo findings)

• Fixed — dynamic-typed provider-function returns coerced to string: generated wrappers for dynamic/object/map return types no longer wrap in Token.asString(...); they return the raw invoke() IResolvable, which Tokenization.isResolvable() recognizes — struct-typed attribute assignments (OutputReference.internalValue) no longer vanish silently from synth output.
• Fixed — invoke() dropped literal null positional arguments: arguments are now validated per position (variadic flattening stays in the generated wrappers where the signature is known), and a latent third bug this exposed was fixed too: FunctionCall rendered args via Array.prototype.join, which collapses null entries to empty strings — resolved null/undefined now render as the Terraform null keyword. Regression tests pin the exact provider::cfncompat::condition_if(true, null, {"a" = 1}) rendering.

Fourth review round addressed (jsteinich's CHANGES_REQUESTED)

Seven commits on top of the reviewed head, one per finding group (inline replies on each thread carry the details):

1. Schema fidelity — FunctionParameter gains is_nullable, FunctionSignature gains deprecation_message, and both drop description_kind (verified against internal/command/jsonfunction/{function,parameter}.go and the OpenTofu equivalent: that field does not exist on function JSON; allow_null_value/allow_unknown_values are protocol-only names — the old comment was wrong). OpenTofu emits no deprecation_message at all (divergence, documented).
2. Recursive, honest type mapping — collections recurse (list(number) → number[] via Token.asNumberList, set(bool) param → Array<boolean | IResolvable>, nested compose); object/map/dynamic returns are declared IResolvable instead of any (property access on a token is now a compile error); is_nullable consumed (trailing → jsii-optional, mid-position → any, variadic → any[], docstrings say T | null); deprecation_message → @deprecated; name collisions hard-fail generation with an actionable error. Structural helpers for object shapes: provider-generator: structural typing for object-shaped provider-function parameters and returns #336.
3. App-owned usage registries — recording moved to token-resolve time keyed by the resolving stack's node.root (WeakMaps); the App-constructor resets and the "pathological" disclaimer are gone; the interleaved-App false negative is structurally impossible and pinned by regression tests for both registries.
4. Functions move onto the provider class — time.functions.rfc3339Parse(ts) via a memoized getter fed by this.terraformResourceType (the exact required_providers key, so the namespace is correct by construction); the static class and providerLocalName parameter are gone, mooting the providerAlias naming question. Per-method self-reference JSDoc dropped (kept once on invoke; docs PR: docs(concepts): provider-defined functions + caveats cdk-terrain-docs#29).
5. Cleanups — registerProviderFeatureUsage moved to TerraformElement (ephemeral resources reuse it); enum casts replaced by a membership guard + direct ProviderFeature indexing; hints get their own map instead of runtime label-mangling (messages byte-identical); write-only registration treats explicit null as omission (!= null, both constructor and setter paths, four pinned tests).
6. Demo-validation fixes — exercising the generated bindings in a real app (demo PR) caught three bugs snapshots couldn't: the sibling import needed /index under nodenext; the wrapper constructor's TS parameter property is rejected by Node's native type-stripping (jsii accepts it — Node is the stricter consumer); variadic rest params need Array<T> for union element types.
7. Edge-provider compile coverage (closes Edge-provider schema: cross-language compile coverage for ephemeral resources, provider functions, write-only attributes #311) — the edge schema now carries nine functions (one per generator branch, incl. all three nullability shapes and deprecation), an ephemeral resource, and a write_only attribute; its bindings ride the existing postbuild jsii + pacmak flow for all five languages and the test/<lang>/edge native-compile suites, independent of CI's Terraform version.

External validation (full matrix in the demo PR): terraform 1.15.7 and opentofu 1.12.3 generate byte-identical bindings modulo registry-host doc links; schema cache keys per CLI product+minor; omitted/explicit/mid-position nullable args all render the bare null keyword in position; generated bindings pass tsc + jsii + pacmak; the targetVersions validation error was demonstrated live through the resolve-time registry.

Resolves Terraform CDK issues

• COMPONENT: Support Terraform ephemeral resources hashicorp/terraform-cdk#3886
• provider-generator: Add support for provider functions hashicorp/terraform-cdk#3686

🤖 Generated with Claude Code

[sakul-learning]

Draft PR #296 review notes / verification results

I built and published a small reusable demo harness against this PR head so the new provider-protocol features can be exercised with real generated AWS bindings:

https://github.com/sakul-learning/cdktn-provider-features-demo

PR head used for the run: 78299b4b9ece16c45ab26a0cd28dec08e8ba57e9.

Verification performed

Using the PR-head packages directly, not npmjs:

• pnpm run assert:prhead-deps confirms cdktn resolves from the PR-head worktree and the CLI comes from the PR-head cdktn-cli bundle.
• Terraform 1.15.7:
  • captured AWS provider schema
  • generated AWS bindings
  • ran schema inspection and generated-feature assertions
  • ran pnpm exec tsc --noEmit
  • ran pnpm run synth:all
  • ran pnpm run plan:all
• OpenTofu 1.12.3:
  • reused the Terraform-generated bindings
  • ran generated-feature assertions
  • ran pnpm exec tsc --noEmit
  • ran pnpm run synth:all
  • ran pnpm run plan:all

The AWS provider schema from Terraform 1.15.7 exposed:

• provider functions: 4
• ephemeral resources: 10
• list resources: 153
• provider actions: 11
• resource identities: 437

Generated bindings confirmed:

• provider functions: yes
• ephemeral resources: yes
• list resources: no first-class generated bindings observed
• provider actions: no first-class generated bindings observed
• resource identities: no first-class generated bindings observed

OpenTofu 1.12.3 successfully planned the examples with the Terraform-generated bindings. A separate OpenTofu schema probe exposed provider functions, ephemeral resources, and resource identities, but reported list_resource_schemas: 0 and action_schemas: 0, so Terraform 1.15.7 is the better generator binary for this comprehensive AWS capability test.

UX / integration notes from the demo

These are non-blocking, but important feedback from trying to use the generated bindings in a real app:

• I switched the examples from the AWS barrel import (./.gen/providers/aws) to direct generated-module imports (provider, provider-functions, and the specific ephemeral resource module). The barrel import path pulled in thousands of generated AWS classes and hit the Node/TypeScript OOM path during synth.
• After that import change, I had to replace the remaining namespace-style references (provider.*, providerFunctions.*, and ephemeral...*) with direct class references like AwsProvider, AwsProviderFunctions, and EphemeralAwsSecretsmanagerRandomPassword.
• The ephemeral output needs both Fn.ephemeralasnull(...) and sensitive: true so Terraform and OpenTofu accept the plan. Without ephemeralasnull, the ephemeral value is used in a non-ephemeral context; without sensitive, the output still fails because it is derived from secret ephemeral data.
• I removed a trial use of AwsProviderFunctions.userAgent(...) inside AwsProvider configuration after OpenTofu reported a provider self-reference/cycle. The mistaken assumption was that provider-defined functions behave like pure static helpers that are safe to use while configuring that same provider. The generated call is still a provider-namespaced function (provider::aws::user_agent), so putting it inside the aws provider block asks Terraform/OpenTofu to evaluate an AWS provider function while the AWS provider is still being configured. The demo now exercises provider functions in outputs instead, after provider configuration exists.

Non-blocking findings / suggested follow-ups

• targetVersions validation bypass in cdktn get path
  targetVersions is validated in parseConfig (packages/@cdktn/commons/src/config.ts), but cdktn get appears to use CdktfConfig.read() plus the raw targetVersions getter (packages/@cdktn/cli-core/src/lib/cdktf-config.ts, then passed through in packages/@cdktn/cli-core/src/lib/get.ts). That path appears to bypass the parseConfig validator, so malformed targetVersions can reach generation.

• Ephemeral resources expose too much lifecycle surface
  TerraformEphemeralMetaArguments currently exposes lifecycle?: TerraformResourceLifecycle. Terraform ephemeral blocks only support lifecycle precondition / postcondition; they do not support the full managed-resource lifecycle surface such as ignore_changes, replace_triggered_by, create_before_destroy, etc. I’d introduce a narrowed lifecycle type for ephemeral resources, e.g. only precondition and postcondition, and use that in TerraformEphemeralMetaArguments.

• Nested write-only attributes do not register feature usage
  The constructor-time write-only registration only iterates top-level assignable attributes in resource.configStruct.assignableAttributes. Provider schemas can put write_only inside nested blocks, not only on top-level resource config attributes, so nested write-only usage can skip registerProviderFeatureUsage("writeOnlyAttributes").

• Generated ephemeral resources skip write-only feature usage registration
  The generator currently limits write-only registration to classes whose parent is TerraformResource; generated ephemeral resources do not get that registration path. Maybe current provider schemas do not combine ephemeral resources with write-only attributes, but since this PR is adding generalized newer-protocol support, I’d either cover the ephemeral path or explicitly document/filter why that combination cannot happen.

Overall: the core provider-function and ephemeral-resource generated bindings worked in real synth/plan flows for Terraform and OpenTofu once the UX issues above were accounted for. The largest current generated-coverage gap is that Terraform exposes AWS list resources, actions, and resource identities, but I did not see first-class generated bindings for those schema sections yet.

[so0k]

deliberately not exposed there because the combination doesn't occur - verified empirically across every provider in the 1.15.6 sweep dump — zero ephemeral attributes carry write_only.

[vincenthsh]

While extending cdktn-provider-features-demo to port real aws-cdk-lib L2 construct logic onto generated awscc bindings + the cfncompat provider's intrinsic-function polyfills, I hit two cdktn-side bugs (not cfncompat bugs) worth flagging here. Full context/examples: examples/l2-kinesis-stream, README "UX notes" section.

1. Provider-function bindings that return a documented "dynamic" type are force-coerced to string, silently dropping struct-typed results

Some provider::*::* functions (e.g. cfncompat's condition_if, matching Fn::If) are documented as returning a dynamic type — either branch of Fn::If can be a string or an object. But the generated TS wrapper unconditionally routes the result through Token.asString(...):

public static conditionIf(condition: any, valueIfTrue: any, valueIfFalse: any, providerLocalName?: string): any {
  return cdktn.Token.asString(cdktn.TerraformProviderFunction.invoke(providerLocalName ?? "cfncompat", "condition_if", [condition, valueIfTrue, valueIfFalse])) as any;
}

That's fine for the common string-return case, but breaks when the result is assigned to a struct-typed resource attribute: Tokenization.isResolvable() doesn't recognize a Token.asString-wrapped value, so the struct's generated setter (e.g. KinesisStreamStreamEncryptionOutputReference.set internalValue) treats it as a plain object with no known keys and the whole attribute silently disappears from synth output — no warning, no error.

Repro:

new KinesisStream(this, "stream", {
  streamEncryption: CfncompatProviderFunctions.conditionIf(
    someCondition, {}, { encryptionType: "KMS", keyId: "alias/aws/kinesis" },
  ),
});

terraform plan shows no stream_encryption key at all in the planned resource.

Workaround: call cdktn.TerraformProviderFunction.invoke("cfncompat", "condition_if", [...]) directly, bypassing the generated wrapper — its return type (IResolvable, no Token.asString) is handled correctly by struct setters.

Suggested fix: only wrap a provider function's result in Token.asString(...) when its schema-declared return type is actually string-shaped; leave functions documented/typed as dynamic (condition_if, find_in_map, select, ...) as a raw IResolvable.

2. TerraformProviderFunction.invoke(...) silently drops literal null positional arguments from any call

TerraformProviderFunction.invoke's runtime validates its whole args array with a single variadic(anyValue) validator — the same one used for genuinely variadic argument lists (e.g. condition_and/condition_or's conditions). variadic's underlying listOf() unconditionally filters out null/undefined entries, which is correct for a variadic list, but wrong for a fixed-arity call: passing null for one positional argument (e.g. condition_if(condition, value_if_true, value_if_false)'s value_if_true) drops it from the argument list entirely instead of preserving its slot.

Repro:

TerraformProviderFunction.invoke("cfncompat", "condition_if", [someCondition, null, { a: 1 }])

terraform plan fails:

Error: Not enough function arguments
while calling provider::cfncompat::condition_if(condition, value_if_true, value_if_false)
Function "provider::cfncompat::condition_if" expects 3 argument(s). Missing value for "value_if_false".

(Terraform actually complains about the third argument going missing, since null — meant for the second slot — got filtered and everything shifted.)

Workaround: avoid passing null; substitute an empty struct ({}) or other schema-appropriate sentinel where possible. Not a great substitute for CloudFormation's Aws.NO_VALUE (property omission) semantics, but the closest expressible result today.

Suggested fix: TerraformProviderFunction.invoke should validate fixed-arity provider functions per-position (preserving null/undefined in their slot) rather than treating the whole args array as one variadic list; the "flatten variadic trailing args" behavior should only apply when a function is genuinely variadic.

[jsteinich]

Similar to the parameters case, this isn't that useful to consumers.

[so0k]

Returns are honest as of 80945aa: list/set(string|number) unwrap via Token.asList/asNumberList; everything that can't go through a lossless Token helper (object/map/dynamic/other collections) is declared cdktn.IResolvable instead of any — so property access on a token (result.hours) is now a compile error instead of a silent undefined. This also surfaced in the demo migration, where the stricter types caught two real call sites.

[jsteinich]

We do have some token supported map types which could be supported similar to the list types

[jsteinich]

Could be useful to add a return type to the documentation similar to what is being done for the parameter types.

[so0k]

You're right, we under-used our own toolbox — 08433c6 wires map(string|number|bool) returns through Token.asStringMap/asNumberMap/asBooleanMap (and map(*) through asAnyMap), so typed map results now feed typed map parameters directly. Composition pinned by test.

[so0k]

Added in 08433c6 — every generated method now carries @returns {<type>}.

[sakul-learning]

I found two remaining correctness gaps at 58cd428338d826cb7425bbf9320252599d762306.

1. provider-functions/index.ts: sanitized function names can collide with generated wrapper members

packages/@cdktn/provider-generator/src/get/generator/models/provider-function-model.ts rejects two provider function names that sanitize to the same method name, but it does not reserve names already emitted by packages/@cdktn/provider-generator/src/get/generator/emitter/provider-functions-emitter.ts on the generated <Provider>ProviderFunctions class: constructor and the private providerLocalName field.

For a schema whose functions map contains constructor, sanitizeMethodName() leaves the name unchanged and ProviderFunctionsEmitter.emitMethod() emits a second constructor:

export class ExampleProviderFunctions {
  private readonly providerLocalName: string;

  constructor(providerLocalName: string) {
    this.providerLocalName = providerLocalName;
  }

  public constructor(...): SomeType {
    // ...
  }
}

TypeScript parses the second declaration as another constructor, not an ordinary method; its return type and implementation shape are invalid. A provider_local_name function instead sanitizes to providerLocalName and emits a method with the same name as the wrapper's private readonly providerLocalName field. Schemas containing either name therefore produce invalid TypeScript rather than the generator diagnostic that assertNoMethodNameCollisions() provides for function-to-function collisions.

Could buildProviderFunctionsModel() reject Terraform function names that sanitize to the wrapper's currently emitted reserved names—at least constructor and providerLocalName—and report both the provider and original Terraform function name? Generator tests/fixtures for each name should assert generation fails before output is written.

2. attributes-emitter.ts / terraform-element.ts: clearing a write-only value does not clear its target-version validation

The generated setter in packages/@cdktn/provider-generator/src/get/generator/emitter/attributes-emitter.ts now avoids registering WRITE_ONLY_ATTRIBUTES when its incoming value is null or undefined; the generated constructor applies the analogous guard. However, after a non-null constructor value or setter call registers the feature, packages/cdktn/src/terraform-element.ts retains both the feature in _registeredProviderFeatures and its ValidateFeatureTargetSupport validation for the lifetime of the element.

Assigning null later does not undo that registration, and a generated reset...() method only clears the stored attribute value. Thus, with targetVersions below the write-only floor (Terraform/OpenTofu <1.11.0), synthesis still fails even after the configured write-only value has been cleared—where null is treated as Terraform omission and reset stores undefined.

For example:

resource.secretWo = "temporary"; // installs write-only target validation
resource.secretWo = null;        // Terraform treats the final null as omission
// or: resource.resetSecretWo()

app.synth(); // still rejects an older target

The same stale validation remains when construction begins with a non-null optional write-only value and the generated reset method is called before app.synth().

Could registration be reconciled from current values at validation/synthesis time, or otherwise be removed when no write-only attribute on that resource remains configured? An optional write-only attribute fixture is needed because the current required secret_key_wo fixture cannot generate a reset method. Generated-binding/runtime tests should cover:

• non-null setter value → null before synth;
• non-null setter value → reset before synth;
• non-null constructor value → reset before synth;
• in each case, the synthesized attribute state and the absence of write-only target validation for an older targetVersions range.

Current coverage establishes the initial null/undefined guards and repeated-registration deduplication, but it does not cover clearing a previously registered write-only value.

[so0k]

Both findings addressed and pushed (58cd42833..60d933cc6) — thanks, these were sharp catches.

1. Wrapper-member collisions → 045ecb2f1. buildProviderFunctionsModel now rejects any function whose sanitized method name lands on a member the emitter itself puts on the wrapper class (constructor, providerLocalName), with the actionable error you asked for (provider + original Terraform name + generated identifier), thrown at the model level so it fires before any output is written. Both names are pinned by tests. One deliberate scoping note (documented in the assertion): parameter names are not checked against providerLocalName — parameters live in method scope and merely shadow the field, so there's no invalid output to abort over.

2. Sticky write-only validation → 60d933cc6. We went further than reconciling at validation time: registration now happens at token-resolve time, mirroring the function-usage registry this PR already uses. Generated synthesizeAttributes()/synthesizeHclAttributes() wrap write-only values in a transparent markWriteOnlyAttribute() IResolvable that defers to the real resolver and registers usage only when the resolved result is non-null; undefined/null pass through unwrapped so omission filtering is untouched, and the mutation-time guards in the generated constructor/setters are deleted entirely. Validation describes what renders — structurally, not by bookkeeping.

Your full matrix is pinned in packages/cdktn/test/write-only.test.ts (plus the generator fixture gained the optional write-only attribute so the reset path exists): setter→null, setter→reset, and constructor→reset all synth cleanly on <1.11 targets with the attribute absent from output; a value present at synth still fails; re-set after clear re-arms; and — the case that motivated going resolve-time — a Lazy/IResolvable producer resolving to undefined registers nothing, while the same producer resolving to a value does. Dual resolve passes (preparing + final) dedup to a single validation, relying on the same prepareStack-before-validations ordering invariant the function registry documents and tests.

[eduardomourar]

Just an idea. Maybe use the JSDoc @experimental tag where applicable. That way we can introduce breaking changes while developing the functionality to its production-ready API.

[so0k]

Round 6 (private delta review): validation lifecycle now has explicit epoch semantics — 📝 release-notes material below

Two commits (60d933cc6..0eb1a1a4f) resolving the three lifecycle/HCL findings against the resolve-time write-only design:

fc5cd9dd3 — HCL renderer omits orphaned attribute descriptors. A token resolving to undefined in HCL mode left a metadata-only {isBlock, type, storageClassType} shell that rendered as a bogus fuzzy-JSON assignment. renderAttributes() now recognizes and omits that shape (unambiguous — only value can ever be token-typed in a generated descriptor). This fixes the general pre-existing HCL hole (#313 family), not just write-only markers; explicit null keeps rendering as a null assignment.

0eb1a1a4f — usage represents the current synthesis pass, everywhere. Feature registrations are now mode-tagged (structural — e.g. ephemeral resources, never reset — vs resolve-discovered — write-only, deactivated each preparing resolve and re-armed only when a real value renders), and both function-usage registries adopt the same per-session epoch. Every validation-enabled entry point now establishes the discovery prepare: App.synth() (as before), StackSynthesizer.synthesize() via the new optional ISynthesisSession.stacksPrepared flag, and Testing.synth/synthHcl. Pinned regressions: old-target failures surface through all entry points (write-only and gated functions); synth-fail → reset → re-synth passes; Lazy flipping value→undefined across passes passes; multi-stack sibling usage survives; structural registrations survive epochs.

📝 For the release notes (behavior change in Testing)

Testing.synth(stack, true) and Testing.synthHcl(stack, true) now run the preparing resolve before validations. Previously these entry points validated before any resolve pass, so validations could not see late-bound usage (write-only values behind tokens, Fn.*/provider-function calls) — they silently passed configurations the same stack would fail under app.synth(). Consumers who worked around this with custom prepare wrappers in their testing harnesses can delete them: validations now see exactly what the pass renders, and only that (usage is per-synthesis, so cleared attributes and removed function calls no longer trip stale validations on re-synth). No backend is injected by this change — Testing runs only the discovery half of prepareStack(), so existing snapshots are unaffected.

Suites at 0eb1a1a4f: cdktn core 516/517 (sole failure remains the pre-existing docker toPlanSuccessfully), provider-generator 99/99 with 101 snapshots, git diff --check clean on branch-touched files.

[sakul-learning]

Re-evaluated at 0eb1a1a4f780f3b008aa02f9e2cccb87688a9320: the remaining concerns I found are confined to HCL synthesis/validation. I found no unresolved blocker in the default JSON synthesis path or in this PR's provider-protocol feature behavior. From this review, I consider PR #296 unblocked / approved; the items below are HCL follow-ups, not requested changes to this PR. The pre-existing HCL renderer defects remain tracked in #313.

For the HCL follow-up, two behaviors should be retained explicitly:

1. This PR introduces a new HCL-only drop risk in packages/cdktn/src/hcl/render.ts: isOrphanedAttributeDescriptor() omits any object passed through renderAttributes() that lacks own value/dynamic keys and has own isBlock, type, and storageClassType keys. The predicate does not require an exact own-key set or a private descriptor marker. Consequently, a legitimate custom synthesizeHclAttributes() value with those metadata-like keys plus application fields can be omitted wholesale rather than rendered. This is a PR-introduced HCL-only regression, not one of fix(lib): HCL synth corrupts or drops core blocks (terraform{} extras, top-level overrides, lifecycle conditions) #313's pre-existing defects. A follow-up should use a non-colliding descriptor marker (or an equivalent internal representation) and pin a regression case for a custom object with those keys plus user data.

2. This PR's HCL validation discovery still resolves the JSON representation: TerraformStack._runPreparingResolve() resolves toTerraform() even when Testing.synthHcl(..., true) or an HCL StackSynthesizer will emit toHclTerraform(). Thus, when JSON and HCL representations differ, target-feature validation can report JSON-only usage that HCL does not render, or miss HCL-only usage that it does render. The underlying JSON/HCL synthesis divergence predates feat: support newer provider plugin-protocol features via targetVersions (RFC-04) #296 and is exemplified by #313; the PR-introduced worsening is that the new resolve-time validation lifecycle uses the JSON-only discovery pass for validation-enabled HCL synthesis. A follow-up should make discovery renderer-aware and test both JSON-only and HCL-only feature values.

These are concrete HCL follow-up acceptance cases, but I am not requesting changes to #296 for them. At this head, the configured validation test, cdktn build, and full cdktn test target all passed locally (40 focused tests; 42 suites / 517 full tests).

[jsteinich]

Other places in the codebase use Array<boolean | cdktn.IResolvable> | cdktn.IResolvable which allows for the entire list to be a token.

[so0k]

Adopted in 08433c6 — list/set(bool) is now Array<boolean | cdktn.IResolvable> | cdktn.IResolvable, and the same whole-collection union applies to nested collections and the any[] fallback (each branch now cites its attribute-type-model counterpart). string[]/number[] stay plain, matching resource inputs (encoded list tokens already satisfy them). This is also what makes function-result → function-parameter composition typecheck — pinned by composition tests (set(bool) result into set(bool) param).

[jsteinich]

Perhaps distinguish between list and set in the doc string

[so0k]

Done in 08433c6 — set-typed params/returns are labeled [set] in the docstring so the unordered/deduped semantics are visible.

[jsteinich]

This check isn't really accurate for what compatible types are actually generated as in other parts of the codebase for nested collection types. Perhaps there's a simple way to tie into the normal generation.

[so0k]

Agreed the heuristic was wrong — replaced in 08433c6 with explicit per-branch mappings, each commented with the attribute-type-model.ts branch it mirrors (nested collections follow the non-simple-element rule: string[][] | cdktn.IResolvable). We mirrored rather than physically reused: the resource machinery is entangled with struct/storage-class generation that function expressions don't have, but the type matrix is now convention-identical and tested as such.

[jsteinich]

Is this actually true? Optional vs nullable can be different concepts. I'm used to this being true for actually optional parameters, but not true for nullable parameters, but different languages could have different rules.
Just want to double check as this is complexity that would be nice if we didn't need it.

[so0k]

Fair question — verified against jsii's model rather than assumed: Java and C# cannot omit parameters (jsii TypeScript-restrictions doc), so a jsii-optional parameter there is satisfied by passing null (cf. the @nullable discussion aws/aws-cdk#6026) — i.e. optional≈nullable is exactly jsii's cross-language behavior. TS/Python omit; Java/C# pass null; both render the Terraform null keyword positionally (pinned by test in 08433c6). The trailing param additionally accepts Token.nullValue() now, so the two concepts also converge in the typed API.

[jsteinich]

This is pretty painful from a useability perspective.

[so0k]

Fixed in 08433c6 — mid-position nullables are no longer any: they're T | cdktn.IResolvable, with Token.nullValue() as the explicit-null spelling (it resolves to the bare null keyword — proving that surfaced two pre-existing expression-rendering bugs, fixed in a2ea87a: a resolvable resolving to null rendered as "" and a resolvable resolving to a raw array rendered via Array.toString).

[jsteinich]

Errors for these two cases is probably fine to start with, but has the potential to become a challenge to support long term. Perhaps a follow-up issue to dedupe them.

[so0k]

Agreed — tracked as a follow-up in #340 (deterministic dedupe strategy to replace the hard-fail long-term, plus evaluating jsii's per-language reserved-word lists). Meanwhile the prebuilt sweep below shows no real provider can currently trip the errors.

[jsteinich]

I was thinking of the jsii reserved list, but I'm not sure we actually use that anywhere now that I look for it.

[jsteinich]

I was thinking the functions themselves would be available rather than a separate class access.
The updated approach does eliminate the need for the extra parameter, but it still obscures them a bit. Perhaps that is ok for the reduced name collision risk.

The name collision generation failure is still not ideal, but might be ok for now (should at least check pre-built providers)

[jsteinich]

We should consider just defining the type and only instantiating it if a registration is necessary. I would expect most elements to not actually use this which means we could save a decent amount of memory in a large stack.

[so0k]

I was thinking the functions themselves would be available rather than a separate class access.
The updated approach does eliminate the need for the extra parameter, but it still obscures them a bit. Perhaps that is ok for the reduced name collision risk.

The name collision generation failure is still not ideal, but might be ok for now (should at least check pre-built providers)

Agree we should do a data-sweep across pre-built provider schema if any function names post normalization cause collisions and will produce errors when this is merged. There's also grafana and mongodb providers requested to be added to pre-built providers so we could at least include those in our local datasweep assuming we will eventually (preferably sooner than later) add them to the pre-built list as well.

Ref:

• New Pre-built Provider Request: MongoDB Atlas cdktn-io/cdktn-repository-manager#27
• New Pre-built Provider Request: grafana cdktn-io/cdktn-repository-manager#20

[so0k]

Done in a2ea87a — the map is allocated on first registration; elements that never register (the vast majority) no longer pay for it.

[so0k]

open-constructs/cdktn-planning#3

[jsteinich]

This has gone through a couple iterations, but ultimately, it still seems like this isn't place in the correct scope for its actual usage.

[so0k]

Third time was the charm — you were right that the scope was still wrong, and it was more than hygiene: targetVersions can be overridden per stack, so root-keyed usage let a stack targeting old versions fail on a sibling's rendered function. As of a2ea87a the state lives on the TerraformStack itself (the construct whose constructor registers the validations and whose context resolves targetVersions): recorded via context.scope at resolve time, cleared by the stack's own preparing resolve, read by the stack's own validations. The module-global registry file is deleted outright, along with every session-level reset — per-stack epochs need no coordination. Sibling-stacks-with-different-targetVersions tests pin the fix, including the shared-token-attributed-to-both case.