Nobody plans a 4,000-resource Terraform state. It accretes: the network module lands next to the database because that's where the file was open, someone adds DNS "temporarily," and eighteen months later a plan takes eleven minutes and touching a tag forces a full-stack review.

State is a blast radius, not a folder

Every resource in a state file shares fate with every other resource in it. A bad refactor, a provider bug, a mistyped terraform state rm — the damage is scoped to the file. That makes the state boundary the most important architectural decision in an IaC codebase, and it's usually made by accident.

Three questions locate a sane boundary:

1. Change cadence — does this change weekly or yearly? Networking and DNS move slowly; application infrastructure moves constantly. Separate them.
2. Failure tolerance — if this state were corrupted, what's the recovery story? Keep hard-to-rebuild things (stateful stores, zones) away from things you'd happily recreate.
3. Ownership — can one team apply this without paging another? If not, the file is a meeting disguised as infrastructure.

A shape that survives growth

Cross-state references go through data sources or remote state reads, and the dependency arrow only points down the table — apps read platform outputs, never the reverse:

data "terraform_remote_state" "platform" {
  backend = "s3"

  config = {
    bucket = "acme-tfstate"
    key    = "platform/terraform.tfstate"
    region = "us-east-1"
  }
}

resource "aws_ecs_service" "api" {
  name    = "api"
  cluster = data.terraform_remote_state.platform.outputs.cluster_arn
}

The migration nobody wants

Splitting a monolithic state is terraform state mv drudgery, but it's mechanical and it's reversible. The longer version of this post would cover moved blocks and how to stage the split behind CI. The short version: do it while the plan still finishes in single-digit minutes, because the cost only compounds.

Every data pipeline eventually gets run twice. A worker dies mid-batch and the orchestrator retries. Someone discovers a bug in June's numbers and backfills the month. A deploy goes sideways and you rerun the day by hand at 2am. The question is never whether a run will be repeated — it's whether repeating it is safe.

The property, stated plainly

A pipeline step is idempotent when running it twice with the same inputs produces the same state as running it once. Not similar state — the same state. That rules out three habits that feel harmless in development:

• Appending to a table without a dedup key
• Using wall-clock time as an input ("process everything since now minus one hour")
• Writing partial output before the step has fully succeeded

What it looks like in practice

The cheapest implementation is delete-then-insert scoped to the partition being processed:

BEGIN;

DELETE FROM fact_orders
 WHERE order_date = '2026-06-17';

INSERT INTO fact_orders
SELECT o.id,
       o.customer_id,
       o.total_cents,
       o.order_date
  FROM staging_orders o
 WHERE o.order_date = '2026-06-17';

COMMIT;

Run it once, you get June 17th. Run it five times, you still get June 17th. The partition boundary is the contract: as long as every step owns a disjoint slice of the output, retries are boring — which is the highest compliment you can pay an operational property.

In an orchestrator, the same idea shows up as parameterizing every task by its logical date rather than the current time:

@task
def load_orders(logical_date: date) -> None:
    """Load exactly one day; safe to rerun for any day, any number of times."""
    partition = read_staging("orders", day=logical_date)
    replace_partition("fact_orders", day=logical_date, rows=partition)

Why this beats every other feature

Monitoring, lineage, cataloging — all useful, all secondary. When a pipeline is idempotent, incidents end with "rerun it." When it isn't, incidents end with a forensic reconstruction of which rows were double-counted. One of these is a five-minute fix. The other is a postmortem with an action-items section nobody finishes.