Design: deterministic migration off legacy central modules

[anshulsao]

Design spec only — no code, no modules yet. Opening as a draft so the approach can be reviewed before implementation.

The problem, restated precisely

"Old identification" turned out to be a specific flag in the IaC engine:

# capillary-cloud-tf/tfmain/scripts/generate.py:182
self.is_old = module_json.get("is_old", False) and data["PRE_ALPHA"]

# :305 — the terraform module address key
if meta.is_old:  key = meta.module_name + "_" + name   # module_name = DIRECTORY name
else:            key = meta.provides    + "_" + name   # provides    = intent

So migration always moves the terraform address, and the translation (dirname → provides) is deterministic from module.json. Flavor and version never enter the address.

Scope is smaller than it looks

	count
module.json files in the tree	238
is_old: true	9
is_old: false (already migrated in-repo)	15
distinct intents in scope	5

Three findings that shaped the design

1. The v3 catalog is not a migration target. Only 2 of 171 legacy (intent, flavor) pairs exist in facets-v3-modules + facets-modules-redesign. Modules are rewrapped old-posture instead: main.tf copied byte-identical, the three engine-injected templates materialized, facets.yaml synthesized from module.json. Import is then 0-diff by construction, not by verification.

2. The in-repo precedent is only half the job. The 15 is_old: false modules bumped version and kept flavor (memorystore → memorystore_redis_alpha @ 0.2). But their main.tf differs from the original, so they carry no zero-diff guarantee — and they remain module_source == "local", so they never touched registration.

3. Renaming the flavor silently drops config. main.tf.mustache reads the advanced block by flavor key:

   advanced = lookup(lookup(local.input_{{key}}, "advanced", {}), "{{flavor}}", {})

   The script must rewrite flavor and advanced.<flavor> in lockstep, and assert no pre-rename key survives.

Pipeline

SCAN → JOIN → MAP → REWRAP → EMIT → GATE, where the gate is the existing praxis-zero-change-import bar (0 to change, 0 to destroy, nothing must be replaced) and is not modified. The mapping table accretes one project at a time rather than being built up front.

Pilot is the capillarycloud project on the root CP.

🤖 Generated with Claude Code