identity

type AccountSource interface {
	AccountID(ctx context.Context) (string, error)
}

type AccountSourceFunc func(ctx context.Context) (string, error)

type Admission string

type Argument struct {
	Required bool
	Optional bool
	Computed bool
}

type AzureServerMinted struct {
	// Mints is the part of the id the server supplies, in #2147's words.
	Mints string
	// Taggable: the type's `tags` argument is the ARM tags map, so the
	// ownership marker can be written and a listing can find the object.
	Taggable bool
	// DataPlane: the object lives on a data plane Resource Graph does not
	// index, so marker discovery needs a data-plane listing.
	DataPlane bool
}

type CloudContext struct {
	// AccountID is the AWS account ID the run is against.
	AccountID string

	// Region is the region the run is against.
	Region string

	// SubscriptionID is the Azure subscription the run's environment gives
	// a provider block that names none: ARM_SUBSCRIPTION_ID, which azurerm
	// and azapi both read when their block leaves subscription_id unset
	// (GitHub issue #2133, finding 4). The caller fills it from
	// pkg/azsweep.EnvSubscriptionID, the function the Resource
	// Graph sweep's own environment fallback is, so the two cannot read the
	// environment differently. [resolver.cloudValueFor] consults it only
	// for a provider block that does not set subscription_id at all; a
	// block that sets it, statically or not, is never overridden by it,
	// as neither provider overrides it.
	SubscriptionID string

	// Environment is the Azure cloud the run's environment gives a provider
	// block that names none: ARM_ENVIRONMENT, or "public" when that is
	// unset too, which is the default both providers apply. The caller
	// fills it from pkg/azsweep.EnvEnvironment, which answers ""
	// when ARM_METADATA_HOSTNAME names a metadata host (the cloud is then
	// whatever that host serves, which nothing here reads). Like
	// SubscriptionID it is consulted only for a block that does not set
	// `environment` at all (GitHub issue #2206).
	Environment string
}

type CloudControlID struct {
	// contains filtered or unexported fields
}

type CloudValue string

type Component struct {
	// Literal is a fixed fragment of the import ID, used for separators. On
	// a component whose Attrs is empty, Literal is the component's whole
	// contribution. On a component whose Attrs is also set, Literal instead
	// prefixes the resolved argument value in the import-ID string only -
	// see OmitIfAbsent below for why a segment needs its own separator
	// glued to it rather than a standalone literal component before it.
	// Never the identity-attribute formula: an aws_lambda_permission
	// qualifier's identity value is "qualifier_name", not ":qualifier_name"
	// - the colon is punctuation in the STRING, not part of the ATTRIBUTE.
	Literal string

	// Attrs names the resource arguments to read, in preference order. The
	// first one present in configuration supplies the value; if none is
	// present, resolution fails naming all of them - unless Default or
	// OmitIfAbsent below says what omission means.
	Attrs []string

	// Block names a singular (max_items: 1) nested list block Attrs is read
	// from, instead of the resource's own top-level body. Empty means Attrs
	// names top-level arguments, the ordinary case.
	//
	// aws_autoscaling_traffic_source_attachment is the type this exists for
	// (GitHub issue #310): its documented import ID is
	// autoscaling_group_name,traffic_source_type,traffic_source_identifier,
	// and the provider's own schema (verified against `terraform providers
	// schema -json` at 6.59.0) confirms every one of those three components
	// is a required, client-specified value - but the second and third are
	// not top-level arguments. They are the `type` and `identifier`
	// attributes of a required, max_items:1 `traffic_source` list block, so
	// {Block: "traffic_source", Attrs: []string{"type"}} is what reads them.
	//
	// This is deliberately narrow, matching [resolver.identityArgs]'s own
	// "everything else in the body, including nested blocks, is ignored"
	// rule for the ordinary case: only a component that names Block reaches
	// into one, and it reaches into exactly the one block it names, so no
	// row that leaves this empty (every row before #310) changes behavior at
	// all. The resolver reads the block's FIRST instance only - correct for
	// a schema that caps it at one, and the same "safe direction" the rest
	// of this package takes when a provider-side invariant the schema
	// enforces makes a further check redundant.
	//
	// A leaf name has to be unique across every Block this type's Components
	// use and the type's own top-level arguments; nothing here namespaces
	// one nested block's "type" apart from another's or from a same-named
	// top-level argument. No committed row needs that yet, so it is a
	// documented constraint rather than an enforced one - the same tradeoff
	// [Component.Attrs] itself makes for a duplicate name across components.
	Block string

	// Path selects INSIDE the argument Attrs names before it is resolved:
	// each step is a key of the object the argument is written as, applied
	// in order (GitHub issue #1079). kubernetes_manifest is the type this
	// exists for: its whole object is one dynamic `manifest` argument, and
	// the natural key that identifies it - apiVersion, kind,
	// metadata.namespace, metadata.name - is four keys inside that one
	// argument's object constructor, so {Attrs: []string{"manifest"}, Path:
	// []string{"metadata", "name"}} is what reads the name.
	//
	// The selection is syntactic, through [resolver.selectStaticExpr]: an
	// object constructor, a merge() of them, or a local or variable defined
	// as one is walked key by key without evaluating the whole manifest,
	// and the leaf expression found there is then resolved exactly as a
	// top-level argument's would be. A manifest that is not written out
	// that way - yamldecode(file(...)), a module output, a for expression -
	// has no key to walk and is refused as not resolvable from
	// configuration, never guessed at by evaluating it. Empty on every row
	// before #1079 and on every hand-written row, so nothing else changes.
	Path []string

	// OmitIfAbsent is true when this component is genuinely optional in the
	// provider's own grammar: not a missing identity, and not a documented
	// substitute value (that is Default), but a segment - and the Literal
	// it carries as a prefix, if any - that the import ID simply does not
	// have when none of Attrs is set.
	//
	// aws_lambda_permission is the archetype. The provider documents two
	// import forms (aws 6.59.0's Import section):
	//
	//	FUNCTION_NAME/STATEMENT_ID
	//	FUNCTION_NAME:QUALIFIER/STATEMENT_ID
	//
	// An unqualified permission's import ID has no colon and no qualifier
	// segment at all - it is not that the segment is present and empty.
	// That is spelled as a component with Attrs: []string{"qualifier"},
	// Literal: ":", OmitIfAbsent: true, immediately after the function_name
	// component: present, it contributes ":" + the qualifier value; absent,
	// it contributes nothing, including its own colon, and the ordinary
	// unqualified "/"-joined form falls out unchanged.
	//
	// Without this, the only components attrs=["qualifier"] could resolve
	// through are Default (which asserts a documented substitute value -
	// wrong here, since an unqualified permission has no qualifier at all,
	// not a default one) or the hard refusal every other missing component
	// gets, which would make every unqualified aws_lambda_permission
	// unimportable. Unlike Default and ServerAssignedIfAbsent, an absent
	// OmitIfAbsent component supplies no value to addTo either: an omitted
	// qualifier is not an empty-string qualifier, so no identity-attribute
	// formula should claim one.
	//
	// Absence is not only syntactic. terraform-aws-modules' own S3
	// notification module writes aws_lambda_permission.allow's qualifier as
	// `try(each.value.qualifier, null)` - the argument line IS present, so
	// [resolver.resolveInstance]'s attr==nil branch never sees it, but a
	// for_each instance whose map entry carries no "qualifier" key
	// statically evaluates that expression to null all the same.
	//
	// The resolver does not evaluate such a component's raw HCL expression
	// itself to check - a generic evaluator has no way to know that
	// `each.value.qualifier` is absent-on-this-instance rather than
	// not-yet-known, and resolveFallbackChain's own try()-arm selection
	// (fallback.go) already answers exactly that question using the
	// resource's real expansion. So the resolver instead runs the FULL,
	// ordinary resolution machinery on the component - the same
	// resolveExpr call every other component goes through, whatever shape
	// the author wrote: try(), a conditional, a bare literal - and only
	// afterward asks what it concluded. When resolution fails for exactly
	// one reason, a clean and wholly-known null (stringValue's "Null
	// identity argument", the same diagnostic the name/name_prefix
	// redirect above exists to avoid for the identical reason), the
	// resolver treats it exactly like a syntactically absent argument.
	// Any other failure - a truly dynamic value, an unresolvable reference,
	// the shape aws_lambda_permission's own qualifier argument takes just
	// as often when it names a live alias's version - stands and still
	// refuses through the ordinary path, because "not known until apply"
	// is a true statement about it and "absent" is not.
	//
	// A google row uses it with no Literal, between two standalone "/"
	// separator components, and then the omission is an EMPTY segment
	// rather than a missing one: stock's ReplaceVars renders an unset
	// optional argument as "", so a google_compute_global_network_endpoint
	// with only ip_address set has the id "p/neg/10.0.0.1//80". The
	// generator emits that only where the argument is optional with no
	// schema default AND every import format the provider's importer
	// accepts captures it with `[^/]*`, so the empty segment parses back
	// (#2145 item 6); see tools/gcp-row-gen's emptySegment.
	OmitIfAbsent bool

	// AtLeastOneOf names the arguments the provider's schema requires at
	// least one of (its AtLeastOneOf), when this component is one of them
	// and is [Component.OmitIfAbsent]. An instance that leaves every one of
	// them unset is refused with "Identity argument not set" naming all of
	// them, as a required argument left out is, rather than rendered with
	// every segment empty: the provider's own validation rejects that
	// configuration. Only components of the same entry are consulted.
	// Empty everywhere except the google network endpoint rows (#2145 item
	// 6), so no other row changes behavior.
	AtLeastOneOf []string

	// Default is the literal value this component contributes when none of
	// Attrs is set in the configuration, for the arguments whose omission
	// the provider itself documents as selecting a server-side default: an
	// omitted event_bus_name means the "default" event bus, and the Import
	// section says so in words ("if you omit `event_bus_name`, the
	// `default` event bus will be used" - scraped into import-grammar's
	// omitted_fallbacks field). The empty string keeps the standing rule:
	// an unset identity argument refuses resolution. A component carrying
	// one still supplies its identity attribute - under the first Attrs
	// name, since no argument was chosen per instance - so identity-object
	// import works the same whether the configuration wrote the default or
	// left it out.
	Default string

	// ServerAssignedIfAbsent is true when the provider itself documents
	// that omitting every name in Attrs is not an absence of identity but
	// a request for one: the provider assigns a fresh value - usually a
	// random, unique one - at create time, the same convention
	// [TypeIdentity.ServerAssigned] already gives a type-wide resolution
	// class to. Component narrows that convention to a single argument
	// ("If omitted, Terraform will assign a random, unique name" on an
	// otherwise ordinarily-identified type, not a type whose identity is
	// server-assigned outright), so a component whose Attrs are all unset
	// classifies [ClassNeedsDiscovery] instead of refusing outright - see
	// [resolver.identityArgs]'s attr-nil branch. Unlike Default, which
	// supplies a known literal, this supplies no value at all: the
	// resolver still cannot build the import ID, it can only say why not
	// yet. Derived by tools/row-gen/emit.go from
	// tools/importdocs-gen's Argument Reference scrape
	// (ArgumentRefEntry.ServerAssignedIfAbsent) for every ratified row, the
	// same way every other field in this file is - see #190.
	ServerAssignedIfAbsent bool

	// Cloud names a value that comes from the cloud the run is pointed at
	// rather than from the configuration: the AWS account ID, the region.
	// [CloudNone] - the zero value - means this component is a literal or an
	// argument.
	//
	// A component like this is why [CloudContext] exists. Nothing in a
	// configuration says which account it will be applied to, so an identity
	// that embeds the account is not computable from configuration alone,
	// and this package will not read it from anywhere: it is handed the
	// values or it says it does not have them. See [ResolveIn].
	//
	// Cloud and Attrs are not exclusive, and a component setting both is the
	// ordinary case rather than a contradiction: the provider documents an
	// argument whose omission means "this cloud property" and whose presence
	// means something else entirely ("If omitted, this defaults to the AWS
	// Account ID" on a Glue catalog_id, which is how a configuration points
	// at another account's Data Catalog). Attrs then wins whenever the
	// configuration sets it and Cloud is the fallback, decided per instance
	// by [resolver.cloudComponentAttr]. The field is filled in by
	// tools/row-gen's mergeCloudDefault from the provider's own Argument
	// Reference rather than ratified by hand, the same way
	// ServerAssignedIfAbsent is.
	Cloud CloudValue

	// IdentityAttr names the attribute of the provider's resource identity
	// schema that this component supplies, and is the inference the schemas
	// themselves do not carry: an identity schema says a route is identified
	// by a route_table_id, not that the route_table_id argument is where
	// that value is written.
	//
	// Three values, and the helpers below spell all three:
	//
	//   - [SameNameIdentity], what [attr] sets, is the ordinary case: the
	//     identity attribute is whichever argument supplied the value, under
	//     its own name. It is a rule rather than a name because the argument
	//     is chosen per instance - aws_route reads whichever of three
	//     destination arguments the route uses, and the provider's identity
	//     schema names all three.
	//   - An explicit attribute name, what [inAttr] sets, for the case where
	//     the two differ. Several components may name one attribute, and
	//     their rendered strings then concatenate in order to form it, which
	//     is how an SNS topic's single "arn" is built out of a literal
	//     prefix, the region, the account and the topic's name.
	//   - Empty: this component supplies no identity attribute at all. That
	//     is every separator between two identity attributes - exactly the
	//     character that stops mattering once a run imports by identity
	//     object - and it is what [idlessAttr] says about an argument whose
	//     value is part of the import string and part of no identity.
	//
	// An entry whose components do not supply every attribute the provider
	// requires for import cannot be imported by identity, and its import-ID
	// string is used instead. aws_route_table_association is the archetype:
	// the provider identifies an association by the rtbassoc- ID it assigns,
	// and the table builds the association's documented import string out of
	// a subnet and a route table. Both are right about different things, and
	// only one of them is an identity object.
	IdentityAttr string

	// SoleElement narrows this component's value before every other rule in
	// this struct's comments applies: when the argument's own expression is
	// a static list or set construct, resolution requires it to carry
	// exactly one element and uses that element's value in place of the
	// whole collection. A scalar-typed argument (another name in the same
	// Attrs list may be scalar, e.g. a mutually exclusive sibling) passes
	// through unchanged - the flag only ever narrows a collection, never
	// touches a value that already is not one.
	//
	// It exists for identities the provider documents as one segment per
	// value in a list-typed argument (aws_security_group_rule's import ID
	// appends one token per entry of whichever of cidr_blocks,
	// ipv6_cidr_blocks or prefix_list_ids is set), where cty's own convert
	// package refuses a list-to-string conversion unconditionally,
	// regardless of length (verified: even a one-element
	// cty.ListVal/cty.SetVal fails convert.Convert(..., cty.String) with
	// "string required, but have list/set of string"). The common,
	// documented single-value case - one CIDR, one prefix list ID - is
	// exactly a one-element list, so unwrapping it is not a guess about
	// which element to keep.
	//
	// More than one element refuses outright rather than picking one: the
	// AWS API, not the configuration's own list order, decides how such a
	// rule's multiple sources compose into (or split across) real
	// SecurityGroupRule objects (the provider's own docs: "Not all rule
	// permissions... need to be imported"), so no configuration-only
	// answer for the segment order would be honest. A non-static list (a
	// variable or function call, rather than a literal `[...]` or `[ref]`
	// construct written in configuration) refuses the same way, for the
	// same reason [resolver.isSymbolic] and [resolver.evalStatic] already
	// refuse other non-static identity arguments elsewhere in this
	// package.
	//
	// Two or more Attrs genuinely non-empty AT ONCE (GitHub issue #384) is
	// the alternation's own name proven wrong for that instance - "sole"
	// promises exactly one is ever populated - and resolver.
	// firstApplicablePresent's conflict return is what this main path does
	// about it: refuse, the same as the zero-element case, rather than
	// pick the first candidate silently. Where the type is also ratified
	// in [VariadicTrailingImportIDTypes], resolver.recordFallback gets a
	// second chance first: [resolveDocumentedImportID]'s variadic tail can
	// record the whole family - one token per element of every Attrs
	// member the instance actually sets, in this list's own order - as a
	// documented import string, dropping the instance to the record rung
	// instead of refusing it outright. That is a fact about the DOCUMENTED
	// IMPORT ID machinery, not about this field: SoleElement keeps meaning
	// exactly what it says above for every other reader of this table.
	SoleElement bool

	// PerElement is [SoleElement]'s opposite number, for the identities the
	// provider documents as one segment PER value of a collection-typed
	// argument rather than one segment total. aws_iam_user_group_membership
	// is the archetype: `user1/group1/group2` is a scalar user followed by
	// one segment for every member of the `groups` set, so the number of
	// segments is a property of the configuration and not of the type.
	//
	// The elements are joined by the separator this component's immediate
	// predecessor supplies - a component whose Attrs are empty and whose
	// Literal is the separator, which is how every other multi-segment row
	// in the table already spells one. That predecessor emits the separator
	// that precedes the FIRST element; this component emits the rest.
	//
	// # Why the elements may be sorted
	//
	// A set has no order, so the configuration's own spelling of `groups`
	// cannot be the answer on its own: two configurations differing only in
	// the order of that list are the same configuration, and must produce
	// the same marker. Sorting supplies the missing determinism, and it is
	// sound here because it changes nothing the provider will see. The
	// provider's schema declares groups as set(string) (aws 6.59.0, verified
	// against `terraform providers schema -json`), so the import ID's tail
	// segments are parsed straight back into a set: any permutation of them
	// yields the identical value, and a plan taken after importing one
	// permutation is the plan taken after importing any other. Order is
	// therefore free to be chosen, and this package chooses the one that is
	// stable across runs.
	//
	// # The all-or-nothing rule
	//
	// Sorting needs a key for every element, and an element that waits on a
	// live value has none: its rendered form is not known until apply, so
	// where it belongs in a sorted sequence is not known either. Sorting the
	// ones that do have keys and leaving the rest where they fell would
	// invent an order that is neither the configuration's nor a canonical
	// one. So the rule is all-or-nothing - canonicalise only when EVERY
	// element yields a key, and otherwise leave the configuration's order
	// untouched. A partial answer would mean "I do not know how to
	// canonicalise this", and the honest way to say that is to not do it.
	//
	// The rule is borrowed from the sibling project chant, which met the
	// same question about the same shape.
	//
	// # What IdentityAttr means on a component like this
	//
	// The rendered value is several segments joined by the separator, and no
	// set-typed attribute has a string for its value, so a PerElement
	// component naming an identity attribute contributes something the
	// provider's identity object could not accept as-is. That is inert
	// today - aws_iam_user_group_membership has no identity schema in aws
	// 6.59.0, so nothing builds an identity object for it and the import-ID
	// string is the whole answer - and the row keeps [SameNameIdentity] for
	// the same reason every other IAM attachment row does: the attribute
	// name is what the import string is built out of. A provider release
	// that gives this type an identity schema is the point at which the
	// question becomes real, and [checkIdentity] is what would raise it.
	PerElement bool

	// ARMTypeSegment is true on the one component of azapi_resource's
	// identity that reads its `type` argument (GitHub issue #1120): the value
	// is an ARM resource type with an API version
	// ("Microsoft.Network/virtualNetworks/subnets@2024-05-01"), and what the
	// component contributes is not that value but the text azapi puts
	// between parent_id and name when it builds the object's id. The rule is
	// [armTypeSegment]'s, read from azapi's own builder. The value has to be
	// known from configuration alone: the joining text depends on how many
	// segments the type has, so a type only a parent's live value supplies
	// is refused rather than rendered later.
	ARMTypeSegment bool

	// ARMSegmentIndex, when positive, says the argument holds an Azure ARM
	// id and this component contributes one path segment of it: the one at
	// position ARMSegmentIndex of the id split on "/" (the id's leading "/"
	// makes position 0 the empty string, so "/subscriptions/s/resourceGroups/g
	// /providers/Microsoft.KeyVault/vaults/kv" has its name at 8).
	// ARMSegmentAfter is the text of the segment before it ("vaults"),
	// compared without regard to case: a value of any other shape is refused
	// by name, never misread. The Azure data-plane ids are the users (GitHub
	// issue #2206): a Key Vault's host is the name segment of key_vault_id
	// and the cloud's suffix. A value only an apply can know, a reference to
	// the parent's id, is carried as that reference with the same two steps
	// applied to it (split on "/", element ARMSegmentIndex), so the id
	// renders once the parent's id is known.
	ARMSegmentIndex int
	ARMSegmentAfter string

	// URLEscape is the escaping azurerm applies to this argument's value
	// when it formats a URL id (GitHub issue #2206): "path" is
	// url.PathEscape, which App Configuration puts on a key, and "query"
	// is url.QueryEscape, which it puts on a label. Empty, the ordinary
	// case, is the value as written. A literal value is escaped here; a
	// value only an apply can know is refused by name, since the escape
	// reads its text and a formula cannot carry it.
	URLEscape string

	// LongForm names a rewrite the provider applies to this argument's
	// value before it becomes part of the id (#2144). Empty, the ordinary
	// case, means the value is substituted as written, which is what the
	// provider does too.
	//
	// Set, resolution composes the provider's own rewrite: see
	// [LongFormRule] for each kind. A value only an apply can know is
	// refused by name, since the rewrite reads the value's text and a
	// formula cannot carry it. Written by tools/gcp-row-gen from the
	// pinned provider source.
	LongForm LongFormRule

	// Qualifiers are the regexes the provider matches a [LongFormIAMParent]
	// or [LongFormComputedName] value against, in the provider's order and
	// spelled as its source spells them. For [LongFormTrimPrefix] it is the
	// one literal prefix trimmed, for [LongFormEnsurePrefix] the one added. Empty on a LongForm component,
	// the generator could not read the list, and a value that needs one
	// refuses the instance by name.
	Qualifiers []string
}

type ContentMatchBinding struct {
	// Argument is the resource's own top-level configuration argument to
	// read and match on - "name" for every type admitted through this
	// mechanism today.
	Argument string

	// CFNType is the CloudFormation Registry type Cloud Control lists to
	// find candidates, e.g. "AWS::CloudFront::CachePolicy".
	CFNType string

	// PropertyPath is the listed candidate's own Properties path to the
	// matching value, in Cloud Control's own nesting: a one-element path
	// for a top-level property, a two-element path
	// ["CachePolicyConfig", "Name"] for one wrapped in the resource's
	// single mutable-config object - the shape every type admitted through
	// this mechanism today has.
	PropertyPath []string
}

type DocumentedImportID struct {
	// Separator is the documented join character.
	Separator string

	// Parts are the segments in the documented order.
	Parts []DocumentedImportIDPart
}

type DocumentedImportIDPart struct {
	// Name is the segment's name in comparison form - lower case with
	// punctuation removed, so "REST-API-ID" and "rest_api_id" are one
	// name. [normalizeDocName] is the reduction, and it is applied to
	// schema attribute names here so the two sides meet in one form.
	Name string

	// Argument records whether the page's own Argument Reference names
	// this segment as a configuration argument. See
	// [resolveDocumentedImportID] for the one decision it makes.
	Argument bool
}

type GoogleAssetImport struct {
	// Host is the service host the Asset name carries:
	// "compute.googleapis.com".
	Host string

	// Asset is the Asset name's path after the host, in ReplaceVars
	// syntax: "projects/{{project}}/zones/{{zone}}/disks/{{name}}".
	Asset string

	// Import is the import ID the parts parsed out of Asset are put into.
	// Equal to Asset when the importer accepts the Asset path as it is.
	Import GoogleImportFormat

	// Documented is set when the provider source states no Asset name for
	// the type, and Asset is the one Google documents for its asset type
	// (https://docs.cloud.google.com/asset-inventory/docs/asset-names,
	// last updated 2026-10-19, read into live/gcp-asset-names.json). The
	// page's every variable is one path segment, so each placeholder of
	// such an Asset matches exactly one: a bucket's is its bare name.
	Documented bool
}

type GoogleIdentityImport struct {
	// Via names the importer code that reads the identity, as
	// tools/gcp-row-gen read it at the pin: "parse_import_id",
	// "importer" or "iam_parent".
	Via string

	// Required are the attributes the importer cannot do without, plus
	// every attribute the identity schema requires for import.
	Required []string

	// Defaulted are the attributes the importer fills from the provider
	// configuration when the identity leaves them unset.
	Defaulted []string
}

type GoogleImportFormat struct {
	// Template is the form, in ReplaceVars syntax:
	// "{{key_ring}}/cryptoKeys/{{name}}".
	Template string

	// Regex is the importer's own ParseImportId regex for Template, when the
	// importer is the generated one. A composed ID must match it. Empty
	// when the importer is custom code and Template comes from the type's
	// documented Import formats instead.
	Regex string
}

type LongFormRule string

type ParentLink struct {
	// Attr is the argument on the child's own resource block that supplies
	// the value - the config argument one of its identity [Component]s
	// reads.
	Attr string

	// Parent is the admitted type whose identity this argument's value
	// matches.
	Parent string
}

type Schema struct {
	// Identity maps each identity attribute to whether the provider
	// requires it for import. Nil means the provider serves no identity
	// schema for the type; an empty, non-nil map is an identity schema
	// with no attributes.
	Identity map[string]bool

	// Arguments are the resource schema's top-level attributes. Nil means
	// the provider serves no resource schema.
	Arguments map[string]Argument

	// Nested maps each nested block, and each attribute of a nested type,
	// to the names of the attributes it holds.
	Nested map[string][]string
}

type SchemaSet interface {
	// Each calls fn for every type in the set, in unspecified order, until
	// fn returns false.
	Each(fn func(typeName string, schema TypeSchema) bool)
}

type Schemas map[string]Schema

type ServiceOf func(tfType string) (string, bool)

type TypeIdentity struct {
	// Type is the resource type name, e.g. "aws_route".
	Type string

	// ServerAssigned is true when the identity is minted by the provider's
	// API at create time and appears nowhere in configuration. Instances of
	// such a type always classify as ClassNeedsDiscovery, whatever their
	// arguments say.
	ServerAssigned bool

	// Reason is the operator-facing explanation attached to every
	// ClassNeedsDiscovery resolution of this type. Required when
	// ServerAssigned, unused otherwise.
	Reason string

	// RecordBacked is true when this type's identity is not observed from
	// the cloud at all: the type is one of GitHub issue #73's
	// RECORD_ADMITTED logical types (internal/live/lint), whose whole
	// existence is a persisted micro-state record. Instances of such a
	// type would always classify [ClassRecordBacked], whatever their
	// arguments say, the same way ServerAssigned instances always classify
	// ClassNeedsDiscovery above.
	//
	// Live since #73 phase (d): ten rows of [DefaultTable] set it
	// (null_resource, terraform_data, the random_* and time_* families),
	// and internal/live/projection consumes ClassRecordBacked to hydrate
	// such an instance from the record store without a cloud read. Lint
	// still refuses these types when no record_store is configured, which
	// is why a configuration without one never reaches a row that sets
	// this. [SynthesizeTypeIdentity] never produces it.
	RecordBacked bool

	// SecretMaterial is true when this [RecordBacked] type's schema carries
	// a live sensitive attribute, so the record holding its whole value
	// holds secret material - a generated password, a private key, the
	// contents of a file the provider marks sensitive.
	//
	// It never appears without RecordBacked. The two are derived from one
	// measurement of one artifact (live/logical-schemas.json, through
	// tools/row-gen's recordBackedTypes and secretMaterialTypes): the flag
	// above says the record is where this type's prior state comes from, and
	// this one says what is in it.
	//
	// # What it gates, and where
	//
	// GitHub issue #365's `strict { secrets = ... }`. Such a type resolves
	// [ClassRecordBacked] under the default, [strict.Store], which is what
	// stock OpenTofu does - a stock state file holds random_password.result
	// in clear, and the estate's record store is where this fork keeps what
	// a state file would. Under [strict.Refuse] it does not resolve at all.
	//
	// THREE places branch on it, and the third is the one an audit of this
	// change had to find because the first draft of this comment denied it
	// existed.
	//
	// internal/live/lint is the gate a configuration meets first (its
	// RuleLogicalResource refusal names the setting), and [resolver.resolveInstance]
	// asks the same question again at the layer that acts, so a caller that
	// skipped lint gets a refusal rather than a record full of secrets. That
	// double-asking is the same shape the `markers "record"` selection
	// already has, and it is here for the same reason: the two layers must
	// never disagree about what the operator asked for.
	//
	// internal/live/liveimport's ratifyOne is the third, and it is NOT
	// covered by the other two: `choudoufu live-import` runs no lint pass and
	// builds no resolver at all. What it would write is not an identity and
	// not a residue attribute but the instance's WHOLE prior object, read
	// straight out of the stock state file being migrated - so it is the only
	// thing standing between an operator who set [strict.Refuse] and exactly
	// the outcome they turned off.
	//
	// Every OTHER consumer of RecordBacked - discovery's cloudObservable,
	// projection's write-back, internal/command's live-plan provider set,
	// tools/survey-gen's untaggable render - is asking "does this type have a
	// cloud object", and the answer is no whatever the secrets setting says.
	// The distinction worth carrying forward is the one that hid the defect:
	// a consumer asking about the OBJECT can ignore this flag, and a consumer
	// deciding what to WRITE cannot.
	SecretMaterial bool

	// NonAWSProvider is true when this type is a real, live object - unlike
	// RecordBacked - but belongs to a provider other than AWS, so
	// live/survey-full.json (CloudFormation-registry-backed, and by
	// construction carrying only the AWS provider's roster) has no row for
	// it and never will. Issue #326 is the first time the admission table
	// crossed that line: the four hand-ratified Kubernetes-provider rows
	// (kubernetes_cluster_role_binding, kubernetes_config_map,
	// kubernetes_namespace, kubernetes_storage_class). Unlike RecordBacked,
	// this says nothing about how the type resolves or classifies - it
	// exists only so live/admission_coverage_test.go's
	// TestAdmittedTableNamesOnlyTypesTheProviderServes can ask the row
	// itself which provider-roster artifact backs it, rather than falling
	// back to a hand-maintained exemption list that would go stale the way
	// its own doc comment forbids. tools/row-gen never sets it; only a
	// ratified.json row can.
	//
	// It is also set on a runtime-synthesized entry the moment a type's
	// SCHEMA matches the Kubernetes object-metadata or manifest convention
	// ([synthesizeMetadataIdentity], [synthesizeManifestIdentity]), which is
	// a claim about shape, not about which provider actually serves the
	// type or whether any estate-wide sweep leg reaches it - a type from an
	// unrelated provider can share that shape by coincidence. GitHub issue
	// #1581: [resolver.warnUnsweepableTypes] used to read this field as
	// "the Kubernetes sweep covers it" and ask [internal/live/substrate]
	// instead.
	NonAWSProvider bool

	// Components build the import identity by concatenation, in order.
	// Required unless ServerAssigned or RecordBacked.
	Components []Component

	// ImportSyntax documents the provider's import-ID grammar for this
	// type, in the provider documentation's own notation (e.g.
	// "ROUTETABLEID_DESTINATION"). Documentation only for every other
	// purpose - Components is what the code follows for composing an
	// import ID - with one narrow, deliberate exception:
	// internal/live/discovery's importsWholeARNString reads it to tell a
	// server-assigned type whose provider-documented legacy import ID IS
	// its own ARN (a single ImportSyntax token ending "ARN", e.g.
	// "TASKDEFINITIONARN") apart from one whose ARN-shaped Cloud Control
	// identifier should be stripped to its bare resource-id segment
	// instead (e.g. "WORKSPACEID") - see that function's doc comment and
	// issue #298.
	ImportSyntax string

	// IdentityAttrs are the attribute names whose value equals this type's
	// identity, so that a reference to one of them from another resource
	// can be resolved without a cloud read. A reference to any other
	// attribute of this type is an error rather than a guess.
	//
	// An empty list means no attribute of this type is usable as an
	// identity source, which is the honest answer for types whose "id"
	// attribute is a provider-synthesized value distinct from the import
	// ID.
	IdentityAttrs []string

	// IdentityObjectOnly is true for an entry whose identity has more than
	// one attribute and no separator to join them with, so there is no
	// import-ID string to build. A resolution of such a type carries
	// [Resolution.IdentityValues] and an empty [Resolution.ImportID], and
	// the projection imports it by identity object or not at all.
	//
	// It exists because the alternative is worse than a refusal. Component
	// values are concatenated with nothing between them
	// (internal/live/identity/resolve.go's classify), so a two-attribute
	// composite with cluster="prod" and name="svc" would produce the import
	// ID "prodsvc" - not empty, so every guard that tests for emptiness
	// passes it through, and a run that fell back from the identity object
	// would import "prodsvc" against a real account with a TRACE log to say
	// so. GitHub issue #105 names that as the thing to guard before relaxing
	// the composite refusal at all.
	//
	// Only [SynthesizeTypeIdentity] sets it. A hand-written row states its
	// separator, which is the whole reason those rows are hand-written.
	IdentityObjectOnly bool

	// Synthesized is true when this entry was not written by hand but built
	// from the provider's own identity schema at resolution time. See
	// [SynthesizeTypeIdentity].
	Synthesized bool

	// Admits records what backed a synthesized entry: the schemas alone
	// ([AdmitSchema]) or the schemas plus this configuration
	// ([AdmitConfigSignal]). Empty for a hand-written row, which is asserted
	// rather than derived.
	Admits Admission

	// UniqueName is set when AWS itself guarantees that the name this
	// type's configuration supplies identifies at most one object in the
	// account and region an enumeration covers, so a live object can be
	// recognised by that name instead of by an ownership marker. It is only
	// ever set on a ServerAssigned row: a row whose identity the
	// configuration already states has no need of it.
	//
	// It is the exception internal/live/uniquename's package comment argues
	// for, and it is narrow on purpose. internal/live/foreign matches a live
	// object's content against a declaration and refuses to bind on the
	// result, because "inferring it from a content match would be exactly
	// the guess the marker spec exists to forbid". That refusal is right for
	// content in general - two objects can carry the same CIDR, the same
	// policy document, the same anything. A name AWS refuses to issue twice
	// is not content: "the cache policy called static-assets" names exactly
	// one object in the account, so reading it off a listing is not
	// inference, it is reading the identity the configuration already
	// states.
	//
	// Nothing here is hand-maintained, and the guarantee's absence fails
	// closed: tools/row-gen sets this only where the provider's own argument
	// reference and the CloudFormation registry schema INDEPENDENTLY assert
	// the name is unique (live/import-grammar.json's declared_unique and
	// live/registry.json's unique_name_property, both computed by
	// internal/live/uniquename.Asserted). A type with one source, or none,
	// leaves this zero and never reaches the binding leg at all.
	UniqueName UniqueName

	// ARMResourceID is true when the identity this entry builds is an Azure
	// Resource Manager resource id (GitHub issue #1120, ruled on #1122): a
	// whole address, subscription and resource group and provider namespace
	// included, that ARM compares case-insensitively. Two consequences
	// follow, and [resolver.checkCollisions] applies both: two resolutions
	// with such ids that differ only in letter case name one object, and
	// they name it whatever type or provider declares them, because an
	// azurerm block and an azapi_resource block for one virtual network are
	// one object declared twice. Only the Azure family's synthesis sets it
	// (substrate.Azure.SynthesizeIdentity); no ratified row does.
	ARMResourceID bool
}

type TypeSchema interface {
	// HasIdentity reports whether the provider serves an identity schema
	// for the type.
	HasIdentity() bool

	// EachIdentityAttribute calls fn once for every attribute of the
	// identity schema, with whether the provider requires it for import.
	// The order is unspecified. It calls nothing when HasIdentity is false.
	EachIdentityAttribute(fn func(name string, requiredForImport bool))

	// HasResource reports whether the provider serves a resource schema for
	// the type.
	HasResource() bool

	// Argument returns the resource schema's top-level attribute called
	// name, and false when there is none (or no resource schema at all).
	Argument(name string) (Argument, bool)

	// NestedAttribute reports whether the resource schema has a nested
	// block, or an attribute of a nested type, called container, and that
	// nested shape has an attribute called leaf.
	NestedAttribute(container, leaf string) bool
}

type UniqueName struct {
	// Attrs names the configuration arguments carrying the name, in
	// preference order, the same convention [Component.Attrs] uses. In
	// practice one entry, "name" - the two-source rule only clears a
	// REQUIRED argument literally called name, because an optional one is a
	// name a configuration may leave out and a name the configuration does
	// not state is a name no listing can be matched against.
	Attrs []string

	// Property is the path, inside a Cloud Control ResourceDescription's
	// Properties map, at which the same name appears: "Name" at the top
	// level, or a "/"-separated descent into a configuration sub-object
	// ("CachePolicyConfig/Name"). It comes from the CloudFormation registry
	// schema, which is also where the second half of the uniqueness evidence
	// comes from - so a type whose registry schema does not carry the claim
	// has no path here either, and cannot be bound by name even if the
	// provider docs alone had said it was unique.
	Property string
}