docs: point the hand-maintained constraint maps at the vendored matrix

providerFeatureConstraints (usage boundaries, packages/cdktn) and
SCHEMA_EMISSION_BOUNDARIES (fetching-CLI emission boundaries,
@cdktn/provider-schema) now name features-matrix.json as their source,
cross-reference each other, and spell out the deliberate OpenTofu
provider-functions exception (language support 1.7.0 vs schema emission
1.8.0). The matrix README gains an in-repo consumers section.

An automated drift check between the maps and the matrix is tracked in
#309. From PR #296 review.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: so0k

packages/@cdktn/provider-schema/src/emission-check.ts

@@ -24,6 +24,19 @@ export type SchemaEmissionFamily =
 const TARGET_PRODUCTS = ["terraform", "opentofu"] as const;
 type TargetProduct = (typeof TARGET_PRODUCTS)[number];
 
+/**
+ * Hand-maintained from `tools/provider-feature-availability/features-matrix.json`
+ * — specifically each feature's `documented_emitted_from` /
+ * `observed_introduced` fields per product (see that directory's README for
+ * how the dataset itself is produced/regenerated, and its "In-repo
+ * consumers" section for how this map and `providerFeatureConstraints` in
+ * `packages/cdktn/src/provider-feature-constraints.ts` relate to the
+ * matrix and to each other).
+ *
+ * There is no automated check that this map stays in sync with the matrix;
+ * updates must be applied by hand when the matrix changes. An automated
+ * drift check is tracked in #309.
+ */
 export const SCHEMA_EMISSION_BOUNDARIES: Record<
   SchemaEmissionFamily,
   Record<TargetProduct, string>

packages/cdktn/src/provider-feature-constraints.ts

@@ -5,7 +5,23 @@ import { TerraformFeatureVersionConstraints } from "./validations/validate-terra
 /**
  * Minimum CLI version per product required for a provider-protocol feature
  * family, hand-maintained from `tools/provider-feature-availability/features-matrix.json`
- * (see that directory's README for how the dataset is produced/regenerated).
+ * (see that directory's README for how the dataset is produced/regenerated,
+ * and its "In-repo consumers" section for how this map relates to the
+ * matrix and to the sibling `SCHEMA_EMISSION_BOUNDARIES` map in
+ * `packages/@cdktn/provider-schema/src/emission-check.ts`).
+ *
+ * These are *usage* (language-support) boundaries, not schema-emission
+ * boundaries — the two can differ per feature. In particular,
+ * `providerFunctions.opentofu` is deliberately pinned to `>=1.7.0`, the
+ * version where OpenTofu's HCL parser started accepting
+ * `provider::ns::fn()`, even though `tofu providers schema -json` only
+ * starts emitting the `functions` key from 1.8.0 (see
+ * `SCHEMA_EMISSION_BOUNDARIES.functions.opentofu`). Do not "fix" this
+ * mismatch without checking the matrix and the emission-check module first.
+ *
+ * There is no automated check that this map stays in sync with the matrix;
+ * updates must be applied by hand when the matrix changes. An automated
+ * drift check is tracked in #309.
  *
  * Used by synth-time `ValidateFeatureTargetSupport` checks against a
  * project's declared `targetVersions`. Deliberately not exported from

tools/provider-feature-availability/README.md

@@ -17,6 +17,27 @@ Note the provider-functions asymmetry: OpenTofu supports the
 validation uses the language boundary, schema acquisition the emission
 boundary.
 
+## In-repo consumers
+
+Two hand-maintained maps are derived from this matrix and must be kept in
+sync with it by hand:
+
+- `packages/cdktn/src/provider-feature-constraints.ts` —
+  `providerFeatureConstraints`, the _usage_ boundaries (language support) per
+  feature family, keyed off each feature's `documented_ga`/language-support
+  version here. This is where the deliberate OpenTofu `providerFunctions`
+  exception lives: 1.7.0 (language support) rather than 1.8.0 (schema
+  emission).
+- `packages/@cdktn/provider-schema/src/emission-check.ts` —
+  `SCHEMA_EMISSION_BOUNDARIES`, the _schema-emission_ boundaries (when
+  `providers schema -json` starts including the family's key) per feature
+  family, keyed off each feature's `documented_emitted_from` /
+  `observed_introduced` fields here.
+
+There is no automated check today that these two maps agree with
+`features-matrix.json` — updates must be applied by hand when the matrix
+changes. An automated drift check is tracked in #309.
+
 ## Regenerating
 
 Only the matrix JSON is vendored in this repo. The baseline data sweep that