refactor: consolidate meshObject reference handling behind a single meshRef helper

[grubmeshi]

Consolidates the provider's reference-schema handling so every meshObject reference is built the same way, and brings the last outlier (building_block_definition_version_ref) in line by giving it a kind.

What changed

• One builder, two constructors. meshRefByUuid / meshRefByName take a meshRefOptions struct with just two behaviour flags — Output and OptionalComputed; the zero value is a required input. This replaces the previous meshRef(kind, refId, desc, ...opts) signature and its asOutput() / required() / optionalComputed() / requiredId() functional options. Every call site is repointed.
• Input identifiers are unknown-tolerant. They stay Optional+Computed with an AlsoRequires guard rather than Required. A plain Required cannot be used: a ref placed in a set (e.g. mandatory_building_block_refs) collapses to a wholly-unknown element at plan — Terraform hashes set elements by whole value — and Required then fails with "Missing Configuration for Required Attribute". The guard enforces presence while tolerating an identifier that resolves after apply (a computed .ref, a random suffix, …). This is documented inline in schema_utils.go.
• Output refs keep kind known at plan time. A new refOutputKind plan modifier fills a still-unknown output block with its constant kind and an unknown identifier, instead of planning the whole object as "known after apply". Verified by a PreApply plan check in TestAccWorkspace. Data sources have no plan-modifier hook, so this is resource-only; data-source refs resolve kind at their plan-time read.
• building_block_definition_version_ref gains a kind (computed, always meshBuildingBlockDefinitionVersion) across all schema sites and the definition's version_latest / version_latest_release / versions outputs, so the version ref carries a kind like every other reference. The client struct gains a Kind field; Read/Create force the fixed discriminator so it round-trips even if the backend omits it.

Deliberately left bespoke

• target_ref (discriminated uuid-or-name) and building_block_definition_version_ref (extra content_hash on the v3 path) carry extra fields, so they stay bespoke — the latter now simply also carries a kind.

User-facing impact (see CHANGELOG under pending v0.23.3)

• building_block_definition_version_ref now carries kind (FEATURES).
• meshstack_platform / meshstack_landingzone: project_role_ref in role mappings now has an optional kind (defaulting) instead of read-only and no longer requires a known-literal identifier, so a referenced resource's computed ref can be assigned (FIXES) — the same handling other refs already had.
• Remaining doc changes are identifier-description wording only.

Validation

• go build, task lint (0 issues), task generate (docs regenerated), unit tests (./client/, ./internal/provider/ mock mode) all pass.
• Rebased onto origin/main.
• Acceptance suite not re-run in this iteration (needs a local backend).

🤖 Generated with Claude Code

[github-actions]

📊 Test Coverage

Scope	Coverage
Unit tests (mock client)	75.2%
Combined (unit + acceptance)	80.7% — ✅ acceptance passed

Uncovered functions (combined run)

github.com/meshcloud/terraform-provider-meshstack/client/api_key_permissions.go:225:							AllApiKeyPermissions					0.0%
github.com/meshcloud/terraform-provider-meshstack/client/buildingblock.go:97:								Delete							0.0%
github.com/meshcloud/terraform-provider-meshstack/client/client.go:48:									NewApiTokenAuthorization				0.0%
github.com/meshcloud/terraform-provider-meshstack/client/internal/logging.go:27:							Debug							0.0%
github.com/meshcloud/terraform-provider-meshstack/client/internal/logging.go:31:							Info							0.0%
github.com/meshcloud/terraform-provider-meshstack/client/internal/logging.go:35:							Warn							0.0%
github.com/meshcloud/terraform-provider-meshstack/client/internal/retry.go:228:								Close							0.0%
github.com/meshcloud/terraform-provider-meshstack/client/internal/retry.go:249:								Write							0.0%
github.com/meshcloud/terraform-provider-meshstack/client/project_group_binding.go:27:							Read							0.0%
github.com/meshcloud/terraform-provider-meshstack/client/project_group_binding.go:31:							Create							0.0%

Combined with go tool covdata merge over the unit and acceptance coverage data. The acceptance suite runs ./internal/provider against the live backend; coverage is attributed across all packages (-coverpkg=./...).

[Copilot]

Pull request overview

This PR refactors the Terraform provider’s meshObject reference schema handling to consistently generate { kind, <uuid|name> } reference blocks via a single helper (meshRefByUuid / meshRefByName), and aligns the last outlier reference (building_block_definition_version_ref) by adding a kind discriminator throughout resources, data sources, and docs.

Changes:

• Consolidated reference attribute schema construction behind meshRefByUuid / meshRefByName with a small meshRefOptions config surface (including a resource-only plan modifier to keep output kind known at plan time).
• Added kind to building_block_definition_version_ref (and propagated it through building block resources/data sources and building block definition version outputs).
• Updated acceptance/unit tests and regenerated docs to reflect the unified reference semantics and new kind fields.

Reviewed changes

Copilot reviewed 46 out of 46 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
internal/provider/workspace_resource.go	Switches workspace ref output to the unified meshRefByName helper.
internal/provider/workspace_resource_test.go	Adds plan checks asserting ref.kind known and ref.name unknown on create.
internal/provider/workspace_data_source.go	Switches workspace data source ref output to meshRefByName.
internal/provider/tenants_v4_data_source.go	Uses meshRefByUuid for tenant ref output within list items.
internal/provider/tenant_v4_resource.go	Uses meshRefByUuid for tenant resource ref output.
internal/provider/schema_utils.go	Introduces meshRefOptions, meshRefByUuid/meshRefByName, and refOutputKind plan modifier; removes legacy ref helpers.
internal/provider/platform_type_data_source.go	Uses meshRefByName for platform type ref output.
internal/provider/platform_resource.go	Uses meshRefByUuid for platform resource ref output.
internal/provider/platform_resource_schema_kubernetes.go	Updates project_role_ref schema to unified meshRefByName helper.
internal/provider/platform_resource_schema_gcp.go	Updates project_role_ref schema to unified meshRefByName helper.
internal/provider/platform_resource_schema_azure.go	Updates project_role_ref schema to unified meshRefByName helper.
internal/provider/platform_resource_schema_aws.go	Updates project_role_ref schema to unified meshRefByName helper (multiple sites).
internal/provider/platform_data_source.go	Converts multiple output refs (ref, location_ref, platform_type_ref, project_role_ref) to meshRefByUuid/meshRefByName.
internal/provider/landingzone_resource.go	Reuses meshRefByUuid attributes/validators for building block definition refs; updates project_role_ref schemas.
internal/provider/landingzone_data_source.go	Converts platform_ref output to meshRefByUuid.
internal/provider/integrations_data_source.go	Converts integration runner output refs to meshRefByUuid.
internal/provider/integration_resource_schema.go	Converts optional-computed runner refs and integration ref output to meshRefByUuid.
internal/provider/building_blocks_data_source.go	Adds kind to version ref list item model/schema and sets it during Read.
internal/provider/building_block_v2_resource.go	Adds kind attribute to version ref schema; forces discriminator during Create/State set.
internal/provider/building_block_v2_data_source.go	Adds computed kind field to version ref output and sets it during Read.
internal/provider/building_block_runner_resource.go	Converts runner ref output to meshRefByUuid.
internal/provider/building_block_resource.go	Adds kind attribute to version ref schema; forces discriminator during DTO mapping.
internal/provider/building_block_definitions_data_source.go	Converts definition ref output to meshRefByUuid.
internal/provider/building_block_definition_resource_test.go	Extends known-value assertions to include kind on version refs.
internal/provider/building_block_definition_resource_schema.go	Adds kind to version outputs; converts dependency refs and other refs to meshRefByUuid.
internal/provider/building_block_definition_resource_model.go	Adds kind field to version ref model and populates it when mapping client DTOs.
docs/resources/workspace.md	Updates generated docs for workspace ref wording.
docs/resources/tenant_v4.md	Updates generated docs for tenant ref UUID wording.
docs/resources/platform.md	Updates generated docs to reflect unified ref semantics in nested schemas and outputs.
docs/resources/landingzone.md	Updates generated docs to reflect unified ref semantics in nested schemas.
docs/resources/integration.md	Updates generated docs for runner refs and integration ref UUID wording.
docs/resources/building_block.md	Documents added kind on version ref.
docs/resources/building_block_v2.md	Documents added kind on version ref.
docs/resources/building_block_runner.md	Updates generated docs for runner ref UUID wording.
docs/resources/building_block_definition.md	Documents added kind on version outputs and updates ref wording.
docs/data-sources/workspace.md	Updates generated docs for workspace ref wording.
docs/data-sources/tenants.md	Updates generated docs for tenant ref wording.
docs/data-sources/platform.md	Updates generated docs for refs and nested role mappings.
docs/data-sources/platform_type.md	Updates generated docs for platform type ref wording.
docs/data-sources/landingzone.md	Updates generated docs for platform/role mapping refs.
docs/data-sources/integrations.md	Updates generated docs for runner refs.
docs/data-sources/building_blocks.md	Documents added kind on version ref entries.
docs/data-sources/building_block_v2.md	Documents added kind on version ref output.
docs/data-sources/building_block_definitions.md	Updates generated docs for building block definition ref wording.
client/building_block_v2.go	Adds Kind to the client DTO for building block definition version refs.
CHANGELOG.md	Adds feature/fix entries describing the new kind field and ref behavior improvements.