residue

Overview ¶

This file (package residue, colocated with residue.go and tagverbs.go for the same go:embed reason: an embed directive can only name files in its own package's directory, and live/floci-capabilities.json lives here) is the floci capability manifest: which AWS services and resource types the floci emulator this checkout pins actually implements, keyed by the image's content digest rather than its mutable tag.

The problem this closes: every batch of e2e/floci-gated work that hits an unimplemented service rediscovers the gap from scratch - a Create call that returns UnknownOperationException, a service missing from /_localstack/health, a router that dispatches one service's calls to another's handler - and writes the finding up in prose, once, in that batch's own cohort README (see live/e2e/estates/databases/README.md and live/e2e/estates/stragglers/README.md's own "Floci coverage" sections) or in a hand-written t.Skip message (internal/live/discovery's tagging_live_test.go and cloudcontrol_live_test.go). The next batch that reaches the same type pays the same discovery cost again, because nothing upstream of "read every README" could have told it the answer was already known. live/floci-capabilities.json is that answer, structured and keyed by the exact digest the finding was made against, so a test can look it up instead of a human re-deriving it, and a bumped image's stale entries are visibly stale (no entry for the new digest) rather than silently wrong.

The manifest has two grains:

• Services (botocore/AWS CLI service ids, e.g. "networkmanager", "transfer"): whether floci implements the service at all, read off floci's own /_localstack/health endpoint by tools/floci-capability-gen's default probe mode. Note the grain's coverage is its own watchlist rather than the health response: the probe re-checks every service already carrying a row and records nothing for the rest, so the four rows here sit against 82 service names the pinned image reports (#276).
• Types (Terraform provider-local resource types, e.g. "aws_redshift_cluster"), each optionally scoped to a discovery mechanism other than the ordinary create/read path ("tagging-sweep", "cloudcontrol-list", "cloudcontrol-list-scoped" - internal/live/flocitest's *CapabilityGate helpers use the same vocabulary). "cloudcontrol-list-scoped" is "cloudcontrol-list"'s counterpart for a type whose Cloud Control list handler requires scoping input (registry.Roster.EnumerationSourceScoped, the exact population EnumerationSource excludes) - tools/floci-capability-gen's -mode=cloudcontrol-scoped probes it the same way, with a synthetic placeholder scope rather than a real parent object, because floci's ListResources ignores ResourceModel scoping entirely regardless of which mechanism sent it (issue #277). This grain is finer than a health-endpoint probe can answer by itself: a service can report "running" while a specific operation it exposes is still unimplemented, or routed to the wrong handler, or reaches a handler that crashes rather than erroring cleanly. Most entries here are curated from a real `terraform apply` (or a real Cloud Control/tagging call) run against the exact pinned digest and written up once, the same hand-verification the two cohort READMEs above already did - this file just gives that verification a permanent, structured, queryable home instead of only prose a later reader has to find and re-read. tools/floci-capability-gen's -mode=cloudcontrol regenerates the "cloudcontrol-list" mechanism's entries mechanically, over every registry-ratified type, by round trip: create a resource of the type through Cloud Control, then list and look for the identifier the create just named. That round trip is the only way to tell a list that answers from one that returns - floci's ListResources answers an empty ResourceDescriptions, cleanly, for a type whose objects demonstrably exist, and an earlier sweep that recorded a bare successful call as "implemented" filled this manifest with 645 rows that said so. Re-probed as a round trip against the same image, seven of 610 hold (#279). The rest of the grain stays hand data, extended the same way tools/estate-gen/overrides.go's typeOverrides table is.

The three mechanisms are not interchangeable evidence for "does floci support this type", and reading one as a substitute for another is exactly the mistake issue #278 named:

• mechanism="" (the ordinary create/read path) is the only grain that answers what a real `tofu apply` needs: a create call that succeeds and a read/import call that returns usable properties. It is also by far the narrowest of the three - see live/floci-capabilities.json's own row counts per mechanism for the current pin, rather than a number here that would go stale - because there is no derivable minimal create recipe per type and every row is hand-curated one type at a time (issue #278's second and third options, neither attempted yet).
• "cloudcontrol-list" is the broadest grain and the weakest: its probe (tools/floci-capability-gen -mode=cloudcontrol) never creates anything and never reads a populated object. "implemented" means only that a bare ListResources call against an arbitrary (possibly empty) collection did not return UnsupportedOperation or an unparseable error - nothing about whether Create would succeed, whether the properties a real read would need come back populated, or whether the provider's own API calls (which are not Cloud Control's) work at all. Two documented cases where this grain and the ordinary path disagree: aws_athena_named_query and aws_cloudwatch_query_definition both record "implemented" here on ListResources evidence, while the API the provider itself calls for each returns UnsupportedOperation; and CloudFront's list-public-keys answers with every item's Name unset, so a "successful" list is not a usable one. Treat a "cloudcontrol-list" row as evidence for internal/live/discovery's Cloud Control fallback working, never as evidence that a plain `resource` block for that type will apply.
• "tagging-sweep" sits in between: its probe creates one real, tagged resource through the AWS CLI directly (never through Terraform or Cloud Control) and confirms it independently through that service's own native read, so "implemented" here is real evidence the type's native create/read path exists in floci - but it only ever proves that for the small, hand-curated set of types tagging.go's taggingRecipes covers, and it says nothing about whether the resourcegroupstaggingapi sweep itself (the thing this mechanism actually gates) would find a *different* type's resources.

A digest with no entry at all, a service/type with no row under a digest that does have entries, or a row recorded under a *different* mechanism than the one a caller is about to exercise, all mean "not yet investigated" for the question actually being asked - never "confirmed working". FlociServiceCapability and FlociTypeCapability report ok=false only for the first two; picking the right mechanism argument for the third is the caller's job, and FlociTypeCapability's own doc comment says which mechanism answers which question.

This file (package residue, colocated with residue.go for the reason tagverbs.go already documents: a go:embed directive can only name files in its own package's directory, and live/survey.json lives here) is issue #63's evidence-version source.

Every admitted row's import grammar, identity schema, and taggability judgment was verified against one provider version at the time tools/survey-gen last ran, recorded once in live/survey.json's header rather than per row. EvidenceVersion's doc comment is the record of why a single table-wide basis, not a per-row range, is the right answer.

survey.json is the artifact read here, of the three that carry a copy of this version (survey.json's header, import-grammar.json's header, and registry.json's pin), because it is the one this package already parses end to end for Lookup and the residue-cohort accessors: reading it a second time for one more field costs one more struct, not a second embed and a second JSON parser. import-grammar.json's provider_version header is produced by the same tools/survey-gen run and carries the identical value; registry.json's pin is a digest and an acceptance date, not a provider semver, and answers a different question ("is the CFN registry snapshot stale") rather than this one.

Package residue is the residue roster (issue #49): the named, printable set of resource types "not covered" resolves to, and why. It answers the question live/LIMITATIONS.md's untaggable list already answers for one narrow case ("which admitted types can't be swept, and why"), generalized to every type a configuration can name.

Two consumers read this package:

• tools/survey-gen renders live/LIMITATIONS.md's residue-roster span from the accessors below, and a drift test holds the doc to them.
• internal/live/lint's admission refusal calls Lookup to name a refused type's cohort, when it has one, in the refusal Detail.

Two cohorts (deprecated services and CFN-only constructs) and one roster (emulator-blocked) are hand data: no schema anywhere says a service is retired, that a CloudFormation type is a template mechanism rather than an infrastructure resource, or that an emulator gap blocks a type from e2e proof. Those three judgments are curated below, with their evidence in comments, the same way tools/survey-gen/classify.go's opsExcluded carries the credential and waiter judgments no schema can prove. (That symbol used to be cited here as living in internal/live/lint/admission.go; it moved packages, it did not go away.)

The other cohorts - unmapped (unclassified) TF types, tf-only constructs, cfn-unmodeled resources, and registry-laggard live services - are entirely computed, from the two artifacts embedded below: live/mapping.json (issue #43) and live/registry.json (issue #42). They are embedded, not copied into a hand-written table, so there is no second copy of the join to fall out of sync with the committed artifacts — a regenerated mapping.json or registry.json changes this package's answers the moment it is committed, with no separate regeneration step of its own. Issue #53's terminal taxonomy (tf-only, cfn-unmodeled, deprecated-service, alongside the original unmapped/"none") lives inside live/mapping.json's own rows (each row's via) rather than as a further cohort here of its own kind: Lookup reads a row's via directly, and TFOnlyGroups / CFNUnmodeledGroups / UnmappedGroups group live/mapping.json's rows by via the same way, one accessor per terminal class the mechanical or curated classifiers in tools/mapping-gen assign.

This file (package residue, colocated with residue.go for the same embed-directive reason: an embed directive can only name files in its own package's directory, and live/tag-verbs.json lives here) is issue #52's botocore side: internal/live/foreign/classify.go's adoptionHint used to consult a ten-row hand-written ec2Types table naming which admitted types this package knew how to write a `aws ec2 create-tags` command for, with a doc comment enumerating - by hand - the per-service tag verbs it refused to model (kms:TagResource, elasticloadbalancing:AddTags, sqs:TagQueue, ...). TagVerbForType replaces both: it joins a TF type to its CFN service the same way Lookup does (reusing the embedded mapping.json this file's sibling residue.go already parses), then looks the service up in the embedded, botocore-derived live/tag-verbs.json (tools/tagverbs-gen). A service the artifact never resolved a single tagging operation for - ambiguous (IAM, ACM, CloudWatch Logs), none (S3), or unresolved to a botocore directory at all - reports Known=true with an empty Operation and a Reason, honestly, rather than silently answering nothing.