ignition-stack 0.5.0__tar.gz → 0.6.0__tar.gz

{ignition_stack-0.5.0 → ignition_stack-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ignition-stack
-Version: 0.5.0
+Version: 0.6.0
 Summary: CLI that generates ready-to-run Docker Compose stacks for Ignition 8.3 SCADA demos and SE engagements
 Author-email: Eric Knorr <etknorr@gmail.com>
 License: MIT
@@ -33,7 +33,7 @@ Description-Content-Type: text/markdown
 [![Docs](https://github.com/ia-eknorr/ignition-stack/actions/workflows/docs.yml/badge.svg)](https://github.com/ia-eknorr/ignition-stack/actions/workflows/docs.yml)
 [![Documentation](https://img.shields.io/badge/docs-ia--eknorr.github.io-blue)](https://ia-eknorr.github.io/ignition-stack/)
 
-CLI that generates ready-to-run Docker Compose stacks for Ignition 8.3 SCADA demos and SE engagements. Picks an architecture profile, asks a few questions, writes a self-contained project with a hand-readable compose file, env, file-config seed resources, and a `POST-SETUP.md` listing only what could not be pre-seeded.
+CLI that generates ready-to-run Docker Compose stacks for Ignition 8.3 SCADA demos and SE engagements. Pick a system architecture (`basic`, `scale-out`, or `hub-and-spoke`), layer on services, and it writes a self-contained project: a hand-readable compose file, `.env`, file-config seed resources, and a `POST-SETUP.md` listing only what could not be pre-seeded.
 
 See [`docs/docs/reference/seeding-matrix.md`](docs/docs/reference/seeding-matrix.md) for which Ignition 8.3 connection types can be provisioned from the filesystem and env on a live 8.3.6 gateway. Full documentation lives in the [`docs/`](docs/) Docusaurus site.
 
@@ -55,23 +55,25 @@ pipx install git+https://github.com/ia-eknorr/ignition-stack.git@<branch>
 Generate a project and bring it up:
 
 ```sh
-ignition-stack init demo
+ignition-stack init demo --arch basic
 cd demo
 docker compose up -d
 ```
 
 The gateway reaches RUNNING with no UI prompts. The admin user is `admin / password` and the gateway is at `http://localhost:9088`. The default Postgres credentials are `ignition / ignition` on the `db` service.
 
+Run `init` without `--arch` to walk the interactive wizard instead: it opens architecture-first, then layers database, edition, IIoT, services, and exposure on top, with a summary you can preview, tweak, or generate.
+
 Everything that ships in the generated project is hand-readable: `docker-compose.yaml`, `.env`, `scripts/docker-bootstrap.sh`, and a `services/ignition/` resources tree the gateway reads on first boot.
 
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `init <name>` | Generate a project at `./<name>/` from a profile and a few prompts. |
+| `init <name>` | Generate a project at `./<name>/` from an architecture and a few prompts. |
 | `modules` | Download, verify, and manage the `.modl` / JDBC catalog. |
 | `reset` | Re-run generation from an SE-demo project's recorded config. |
-| `switch-profile` | Reshape an SE-demo project under a different profile. |
+| `switch-arch` | Reshape an SE-demo project under a different architecture. |
 | `wipe` | Remove this project's containers and volumes only. |
 
 See the [CLI reference](docs/docs/reference/cli.md) for every command, argument, and option.

{ignition_stack-0.5.0 → ignition_stack-0.6.0}/README.md

@@ -4,7 +4,7 @@
 [![Docs](https://github.com/ia-eknorr/ignition-stack/actions/workflows/docs.yml/badge.svg)](https://github.com/ia-eknorr/ignition-stack/actions/workflows/docs.yml)
 [![Documentation](https://img.shields.io/badge/docs-ia--eknorr.github.io-blue)](https://ia-eknorr.github.io/ignition-stack/)
 
-CLI that generates ready-to-run Docker Compose stacks for Ignition 8.3 SCADA demos and SE engagements. Picks an architecture profile, asks a few questions, writes a self-contained project with a hand-readable compose file, env, file-config seed resources, and a `POST-SETUP.md` listing only what could not be pre-seeded.
+CLI that generates ready-to-run Docker Compose stacks for Ignition 8.3 SCADA demos and SE engagements. Pick a system architecture (`basic`, `scale-out`, or `hub-and-spoke`), layer on services, and it writes a self-contained project: a hand-readable compose file, `.env`, file-config seed resources, and a `POST-SETUP.md` listing only what could not be pre-seeded.
 
 See [`docs/docs/reference/seeding-matrix.md`](docs/docs/reference/seeding-matrix.md) for which Ignition 8.3 connection types can be provisioned from the filesystem and env on a live 8.3.6 gateway. Full documentation lives in the [`docs/`](docs/) Docusaurus site.
 
@@ -26,23 +26,25 @@ pipx install git+https://github.com/ia-eknorr/ignition-stack.git@<branch>
 Generate a project and bring it up:
 
 ```sh
-ignition-stack init demo
+ignition-stack init demo --arch basic
 cd demo
 docker compose up -d
 ```
 
 The gateway reaches RUNNING with no UI prompts. The admin user is `admin / password` and the gateway is at `http://localhost:9088`. The default Postgres credentials are `ignition / ignition` on the `db` service.
 
+Run `init` without `--arch` to walk the interactive wizard instead: it opens architecture-first, then layers database, edition, IIoT, services, and exposure on top, with a summary you can preview, tweak, or generate.
+
 Everything that ships in the generated project is hand-readable: `docker-compose.yaml`, `.env`, `scripts/docker-bootstrap.sh`, and a `services/ignition/` resources tree the gateway reads on first boot.
 
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `init <name>` | Generate a project at `./<name>/` from a profile and a few prompts. |
+| `init <name>` | Generate a project at `./<name>/` from an architecture and a few prompts. |
 | `modules` | Download, verify, and manage the `.modl` / JDBC catalog. |
 | `reset` | Re-run generation from an SE-demo project's recorded config. |
-| `switch-profile` | Reshape an SE-demo project under a different profile. |
+| `switch-arch` | Reshape an SE-demo project under a different architecture. |
 | `wipe` | Remove this project's containers and volumes only. |
 
 See the [CLI reference](docs/docs/reference/cli.md) for every command, argument, and option.

ignition_stack-0.6.0/ignition_stack/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.6.0"

ignition_stack-0.6.0/ignition_stack/architectures/__init__.py

@@ -0,0 +1,35 @@
+"""System architectures: pre-canned shapes that turn intent into config.
+
+The slugs mirror Ignition's documented system architectures (Basic / Scale Out
+/ Hub and Spoke). Importing this package registers every built-in architecture
+by side-effect so ``get_architecture("scale-out")`` works without explicit
+module imports.
+"""
+
+from ignition_stack.architectures import basic, hub_and_spoke, scale_out  # noqa: F401
+from ignition_stack.architectures.advisory import Advisory, spoke_advisory
+from ignition_stack.architectures.base import (
+    Architecture,
+    ArchOptions,
+    apply_iiot,
+    build_architecture,
+    can_host_redundant_role,
+    get_architecture,
+    list_architectures,
+    mark_redundant,
+)
+from ignition_stack.architectures.hub_and_spoke import ArchitectureError
+
+__all__ = [
+    "Advisory",
+    "ArchOptions",
+    "Architecture",
+    "ArchitectureError",
+    "apply_iiot",
+    "build_architecture",
+    "can_host_redundant_role",
+    "get_architecture",
+    "list_architectures",
+    "mark_redundant",
+    "spoke_advisory",
+]

{ignition_stack-0.5.0/ignition_stack/profiles → ignition_stack-0.6.0/ignition_stack/architectures}/advisory.py

@@ -1,6 +1,6 @@
 """Hub-and-spoke RAM advisory.
 
-The hub-and-spoke profile spins up one hub gateway plus *N* spokes; each
+The hub-and-spoke architecture spins up one hub gateway plus *N* spokes; each
 Ignition gateway needs ~1.5 GB to run comfortably. The advisory turns that
 math into a proportional friction signal so SEs can see the cost of a
 large demo without being silently blocked when they really do want it:

{ignition_stack-0.5.0/ignition_stack/profiles → ignition_stack-0.6.0/ignition_stack/architectures}/base.py

@@ -1,19 +1,21 @@
-"""Profile contract + options + registry.
+"""Architecture contract + options + registry.
 
-A *profile* is the small piece of code that turns the user's high-level
-intent ("scaleout", "hub-and-spoke with 3 spokes", "mcp-n8n demo") into a
-fully-formed :class:`ProjectConfig`. The compose engine and the dependency
-resolver are profile-agnostic; profiles only shape the inputs they take.
+An *architecture* is the small piece of code that turns the user's high-level
+intent ("scale-out", "hub-and-spoke with 3 spokes") into a fully-formed
+:class:`ProjectConfig`. The slugs mirror Ignition's own documented system
+architectures (Basic / Scale Out / Hub and Spoke). The compose engine and the
+dependency resolver are architecture-agnostic; architectures only shape the
+inputs they take.
 
 Two-stage pipeline:
 
-1. Either the CLI flags or the wizard answers populate a
-   :class:`ProfileOptions` and pick a profile slug.
-2. ``build_profile(slug, name, options)`` looks up the profile and calls
-   its ``build()`` method, returning a ``ProjectConfig`` that
+1. Either the CLI flags or the wizard answers populate an
+   :class:`ArchOptions` and pick an architecture slug.
+2. ``build_architecture(slug, name, options)`` looks up the architecture and
+   calls its ``build()`` method, returning a ``ProjectConfig`` that
    ``services.resolver.resolve()`` then expands the usual implicit deps on.
 
-Each profile is a small dataclass with three pieces:
+Each architecture is a small dataclass with three pieces:
 
 - ``slug`` - the wizard/flag value users type.
 - ``summary`` - one-line description for the wizard menu + docs.
@@ -39,8 +41,8 @@ from ignition_stack.config import (
 
 
 @dataclass(frozen=True)
-class ProfileOptions:
-    """Inputs each profile reads to shape the resolved config.
+class ArchOptions:
+    """Inputs each architecture reads to shape the resolved config.
 
     Every field has a sensible default so callers only set what they
     actually care about. The wizard fills in many of these from prompts;
@@ -49,10 +51,10 @@ class ProfileOptions:
     """
 
     spokes: int = 3
-    """Hub-and-spoke spoke count. Ignored by other profiles."""
+    """Hub-and-spoke spoke count. Ignored by other architectures."""
 
     frontends: int = 1
-    """Scaleout frontend gateway count. Ignored by other profiles.
+    """Scale-out frontend gateway count. Ignored by other architectures.
 
     1 yields a single gateway named ``frontend``; N>1 yields
     ``frontend-1``..``frontend-N``. A ``backend`` gateway is always added
@@ -65,16 +67,16 @@ class ProfileOptions:
     network_split: bool | None = None
     """Tri-state override for the frontend/backend network split.
 
-    ``None`` lets each profile apply its own default (scaleout splits,
+    ``None`` lets each architecture apply its own default (scale-out splits,
     hub-and-spoke does not). ``True``/``False`` force the split on or off
-    regardless of the profile default.
+    regardless of the architecture default.
     """
 
     edge_role: str | None = None
     """Which gateway role (if any) runs the Edge edition.
 
-    For scaleout this is typically 'frontend'; for hub-and-spoke it can
-    be 'spoke' (every spoke runs Edge) or None. The profile is free to
+    For scale-out this is typically 'frontend'; for hub-and-spoke it can
+    be 'spoke' (every spoke runs Edge) or None. The architecture is free to
     apply its own default when this is None.
     """
 
@@ -85,26 +87,27 @@ class ProfileOptions:
     """SQL database for the stack. None = no database (gateway-only)."""
 
     services: tuple[str, ...] = ()
-    """Additional service catalog slugs the user picked beyond profile defaults."""
+    """Additional service catalog slugs the user picked beyond architecture defaults."""
 
     redundant_role: str | None = None
     """Role (or gateway name) to make redundant, expanding it into a master +
     backup pair. ``None`` (default) builds no redundancy. Must name a singleton
-    workhorse role (scaleout 'backend', hub-and-spoke 'hub', standalone
+    workhorse role (scale-out 'backend', hub-and-spoke 'hub', basic
     'gateway'); replicated tiers ('frontend', 'spoke') are rejected."""
 
     disable_builtins: tuple[str, ...] = ()
     """Built-in module slugs to turn off on every gateway in the stack.
 
     Empty (default) leaves all built-ins on. Applied uniformly by
-    ``build_profile`` - the demo intent is "drop Vision/SFC everywhere", and
-    per-gateway disabling stays a declarative-config-only feature. Slugs are
-    validated against builtin_modules.yaml by ``GatewayConfig``."""
+    ``build_architecture`` - the demo intent is "drop Vision/SFC everywhere",
+    and per-gateway disabling stays a declarative-config-only feature. Slugs
+    are validated against builtin_modules.yaml by ``GatewayConfig``."""
 
     iiot: bool = False
     """Overlay an MQTT/Sparkplug IIoT pipeline (a broker + Cirrus Link
-    Transmission/Engine) onto the stack. Off by default; ``build_profile`` calls
-    :func:`apply_iiot` when this is set, defaulting the broker to ``chariot``."""
+    Transmission/Engine) onto the stack. Off by default; ``build_architecture``
+    calls :func:`apply_iiot` when this is set, defaulting the broker to
+    ``chariot``."""
 
     iiot_broker: str | None = None
     """MQTT broker slug the IIoT overlay wires to. ``None`` with ``iiot`` on
@@ -112,41 +115,41 @@ class ProfileOptions:
     when ``iiot`` is False. Validated against the catalog by :func:`apply_iiot`."""
 
 
-class Profile(Protocol):
-    """A factory that turns ``ProfileOptions`` into a ``ProjectConfig``."""
+class Architecture(Protocol):
+    """A factory that turns ``ArchOptions`` into a ``ProjectConfig``."""
 
     slug: str
     summary: str
 
-    def build(self, name: str, options: ProfileOptions) -> ProjectConfig: ...
+    def build(self, name: str, options: ArchOptions) -> ProjectConfig: ...
 
 
-# Registry populated by the profile modules at import time. Keep alphabetical
-# insertion-order for stable wizard menus + --help listings.
-_REGISTRY: dict[str, Profile] = {}
+# Registry populated by the architecture modules at import time. Keep
+# alphabetical insertion-order for stable wizard menus + --help listings.
+_REGISTRY: dict[str, Architecture] = {}
 
 
-def register(profile: Profile) -> Profile:
-    """Register a profile by slug. Returns the profile so module-level uses
-    can write ``standalone = register(StandaloneProfile())``.
+def register(architecture: Architecture) -> Architecture:
+    """Register an architecture by slug. Returns the architecture so module-level
+    uses can write ``basic = register(BasicArchitecture())``.
     """
-    if profile.slug in _REGISTRY:
-        raise ValueError(f"profile '{profile.slug}' is already registered")
-    _REGISTRY[profile.slug] = profile
-    return profile
+    if architecture.slug in _REGISTRY:
+        raise ValueError(f"architecture '{architecture.slug}' is already registered")
+    _REGISTRY[architecture.slug] = architecture
+    return architecture
 
 
-def get_profile(slug: str) -> Profile:
-    """Look up a registered profile by slug. Raises ``KeyError`` if unknown."""
+def get_architecture(slug: str) -> Architecture:
+    """Look up a registered architecture by slug. Raises ``KeyError`` if unknown."""
     try:
         return _REGISTRY[slug]
     except KeyError as exc:
         known = ", ".join(sorted(_REGISTRY))
-        raise KeyError(f"unknown profile '{slug}'; known profiles: {known}") from exc
+        raise KeyError(f"unknown architecture '{slug}'; known architectures: {known}") from exc
 
 
-def list_profiles() -> list[Profile]:
-    """All registered profiles in stable insertion order."""
+def list_architectures() -> list[Architecture]:
+    """All registered architectures in stable insertion order."""
     return list(_REGISTRY.values())
 
 
@@ -170,9 +173,9 @@ def _matching_gateways(config: ProjectConfig, redundant_role: str) -> list:
 def can_host_redundant_role(config: ProjectConfig, redundant_role: str) -> bool:
     """True when ``config`` has exactly one gateway that can be paired as master.
 
-    ``switch-profile`` uses this to decide whether redundancy intent recovered
-    from the old stack can carry to the target profile, without raising the way
-    :func:`mark_redundant` does - a profile-specific role (e.g. standalone's
+    ``switch-arch`` uses this to decide whether redundancy intent recovered from
+    the old stack can carry to the target architecture, without raising the way
+    :func:`mark_redundant` does - an architecture-specific role (e.g. basic's
     ``gateway``) simply may not exist in the destination.
     """
     if redundant_role in _NON_REDUNDANT_ROLES:
@@ -186,7 +189,7 @@ def mark_redundant(config: ProjectConfig, redundant_role: str | None) -> Project
     Returns ``config`` unchanged when ``redundant_role`` is None. The expansion
     into a master+backup pair happens later in
     :func:`ignition_stack.services.resolver.resolve`; this only marks which
-    gateway to pair, so the same logic serves every profile and the wizard.
+    gateway to pair, so the same logic serves every architecture and the wizard.
 
     Raises ``ValueError`` (surfaced by the CLI as a usage error, exit code 2)
     when the role is a replicated frontend/spoke tier, unknown, or ambiguous
@@ -197,7 +200,7 @@ def mark_redundant(config: ProjectConfig, redundant_role: str | None) -> Project
     if redundant_role in _NON_REDUNDANT_ROLES:
         raise ValueError(
             f"role '{redundant_role}' is horizontally replicated, not paired; "
-            "redundancy applies to a single gateway (e.g. a scaleout 'backend' "
+            "redundancy applies to a single gateway (e.g. a scale-out 'backend' "
             "or a hub-and-spoke 'hub'), never to frontends or spokes"
         )
     matches = _matching_gateways(config, redundant_role)
@@ -211,15 +214,16 @@ def mark_redundant(config: ProjectConfig, redundant_role: str | None) -> Project
     return config
 
 
-def build_profile(slug: str, name: str, options: ProfileOptions) -> ProjectConfig:
-    """Materialize a ``ProjectConfig`` for the named profile.
+def build_architecture(slug: str, name: str, options: ArchOptions) -> ProjectConfig:
+    """Materialize a ``ProjectConfig`` for the named architecture.
 
-    The profile builds the base topology; ``mark_redundant`` then stamps the
-    redundancy master when ``options.redundant_role`` is set, leaving the
-    resolver to expand the pair. Keeping the stamp here (not in each profile)
-    means one eligibility rule serves every profile and the wizard alike.
+    The architecture builds the base topology; ``mark_redundant`` then stamps
+    the redundancy master when ``options.redundant_role`` is set, leaving the
+    resolver to expand the pair. Keeping the stamp here (not in each
+    architecture) means one eligibility rule serves every architecture and the
+    wizard alike.
     """
-    config = get_profile(slug).build(name, options)
+    config = get_architecture(slug).build(name, options)
     config = mark_redundant(config, options.redundant_role)
     config = apply_disable_builtins(config, options.disable_builtins)
     broker = (options.iiot_broker or _IIOT_DEFAULT_BROKER) if options.iiot else None
@@ -230,9 +234,9 @@ def apply_disable_builtins(config: ProjectConfig, disable_builtins: tuple[str, .
     """Stamp ``disable_builtins`` onto every gateway in ``config``.
 
     Applied centrally (like :func:`mark_redundant`) so one rule serves every
-    profile and the wizard. Uniform across gateways: the demo intent is to drop
-    a module everywhere, and a redundant pair must agree on its module set. The
-    resolver later copies the list onto any expanded backup node.
+    architecture and the wizard. Uniform across gateways: the demo intent is to
+    drop a module everywhere, and a redundant pair must agree on its module set.
+    The resolver later copies the list onto any expanded backup node.
     """
     if not disable_builtins:
         return config
@@ -254,9 +258,9 @@ def apply_disable_builtins(config: ProjectConfig, disable_builtins: tuple[str, .
 _IIOT_DEFAULT_BROKER = "chariot"
 
 # Gateway roles that run MQTT Transmission (edge-side: publish Sparkplug to the
-# broker) versus MQTT Engine (central: subscribe and aggregate). A
-# standalone/mcp-n8n shape has neither role, so its single gateway runs both for
-# a self-contained demo loop through the broker.
+# broker) versus MQTT Engine (central: subscribe and aggregate). A basic shape
+# has neither role, so its single gateway runs both for a self-contained demo
+# loop through the broker.
 _TRANSMISSION_ROLES = frozenset({"spoke", "frontend"})
 _ENGINE_ROLES = frozenset({"hub", "backend"})
 
@@ -273,9 +277,9 @@ def apply_iiot(config: ProjectConfig, broker: str | None) -> ProjectConfig:
       plus the Transmission module (they publish Sparkplug to the broker);
     - ``hub`` / ``backend`` gateways get an ``mqtt-engine`` attachment plus the
       Engine module (they subscribe and aggregate);
-    - if NO gateway carries any of those roles (standalone / mcp-n8n shapes), the
-      single/first gateway gets BOTH attachments + both modules - a self-contained
-      demo loop through the broker.
+    - if NO gateway carries any of those roles (a basic shape), the single/first
+      gateway gets BOTH attachments + both modules - a self-contained demo loop
+      through the broker.
 
     Brokers are not ``never_on_edge``, so an Edge spoke attaching with role
     ``mqtt-transmission`` is correct and expected. Idempotent: guards on

ignition_stack-0.6.0/ignition_stack/architectures/basic.py

@@ -0,0 +1,45 @@
+"""Basic architecture: one full Ignition gateway + optional SQL DB.
+
+This mirrors Ignition's documented Basic architecture - a single gateway
+that does everything - surfaced as a named architecture so the wizard can
+offer it alongside the multi-gateway architectures. The only knobs are the
+database choice (defaults to Postgres) and the optional reverse-proxy
+scaffold.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ignition_stack.architectures.base import Architecture, ArchOptions, register
+from ignition_stack.config import DatabaseConfig, GatewayConfig, ProjectConfig
+
+
+@dataclass(frozen=True)
+class BasicArchitecture:
+    slug: str = "basic"
+    summary: str = "One full Ignition 8.3 gateway + Postgres. The default starter stack."
+
+    def build(self, name: str, options: ArchOptions) -> ProjectConfig:
+        gateway = GatewayConfig()
+        if options.edge_role in {"gateway", "basic"}:
+            gateway = gateway.model_copy(update={"ignition_edition": "edge"})
+
+        return ProjectConfig(
+            name=name,
+            architecture=self.slug,
+            gateways=[gateway],
+            database=_database(options),
+            services=list(options.services),
+            reverse_proxy=options.reverse_proxy,
+        )
+
+
+def _database(options: ArchOptions) -> DatabaseConfig | None:
+    if options.database_kind is None:
+        return None
+    return DatabaseConfig(kind=options.database_kind)
+
+
+# Side-effect: registers this architecture when the module is imported.
+architecture: Architecture = register(BasicArchitecture())

{ignition_stack-0.5.0/ignition_stack/profiles → ignition_stack-0.6.0/ignition_stack/architectures}/carry.py

@@ -1,25 +1,25 @@
-"""Carry a resolved service registry across a ``switch-profile`` reshape.
+"""Carry a resolved service registry across a ``switch-arch`` reshape.
 
-``switch-profile`` rebuilds a stack under a new architecture profile. The
-profile only knows how to lay down topology + the inputs ``ProfileOptions``
-carries; it cannot know about the *richer* registry shapes a hand-authored or
-Custom-wizard config can hold:
+``switch-arch`` rebuilds a stack under a new architecture. The architecture
+only knows how to lay down topology + the inputs ``ArchOptions`` carries; it
+cannot know about the *richer* registry shapes a hand-authored or
+composer-built config can hold:
 
 - a custom instance ``id`` that differs from its service slug;
 - per-instance ``image`` / ``env`` / ``user`` / ``password`` overrides;
-- a second database (distinct kind) beyond the profile's default;
+- a second database (distinct kind) beyond the architecture's default;
 - partial / role-specific attachment sets (an instance attached to only some
   gateways, not fanned to all).
 
-Anything *not* expressible through ``ProfileOptions.services`` /
-``database_kind`` rides here instead: :func:`carry_registry` re-grafts those
-instances onto the freshly built config and re-maps their attachments by role
-into the new topology. Attachments whose source gateway has no counterpart in
-the target topology - or that would violate a new-topology invariant - are
-**dropped with a printed advisory** rather than failing the reshape.
+Anything *not* expressible through ``ArchOptions.services`` / ``database_kind``
+rides here instead: :func:`carry_registry` re-grafts those instances onto the
+freshly built config and re-maps their attachments by role into the new
+topology. Attachments whose source gateway has no counterpart in the target
+topology - or that would violate a new-topology invariant - are **dropped with
+a printed advisory** rather than failing the reshape.
 
-The IIoT overlay is *not* carried here: ``switch-profile`` recovers IIoT intent
-into ``ProfileOptions.iiot`` / ``iiot_broker`` so ``apply_iiot`` re-wires the
+The IIoT overlay is *not* carried here: ``switch-arch`` recovers IIoT intent
+into ``ArchOptions.iiot`` / ``iiot_broker`` so ``apply_iiot`` re-wires the
 broker + Transmission/Engine roles natively in the new topology. The broker
 instance and its ``mqtt-transmission`` / ``mqtt-engine`` attachments are
 therefore skipped here to avoid double-wiring.
@@ -40,9 +40,9 @@ from ignition_stack.services.loader import load_all_services
 from ignition_stack.services.manifest import ServiceManifest
 
 # Roles that aggregate centrally (full gateways) versus roles that sit on the
-# edge side and publish/scale out. A role-less gateway (standalone / mcp-n8n)
-# is central - it is the one full gateway in its topology. The two-way name
-# preference (hub<->backend, spoke<->frontend) is tried before the class match.
+# edge side and publish/scale out. A role-less gateway (basic) is central - it
+# is the one full gateway in its topology. The two-way name preference
+# (hub<->backend, spoke<->frontend) is tried before the class match.
 _CENTRAL_ROLES = frozenset({"hub", "backend"})
 _EDGE_SIDE_ROLES = frozenset({"spoke", "frontend"})
 _ROLE_COUNTERPART = {
@@ -52,7 +52,7 @@ _ROLE_COUNTERPART = {
     "frontend": "spoke",
 }
 
-# Attachment roles the IIoT overlay owns; carried via ProfileOptions.iiot, never
+# Attachment roles the IIoT overlay owns; carried via ArchOptions.iiot, never
 # re-grafted here (apply_iiot re-wires them in the new topology).
 _IIOT_ROLES = frozenset({"mqtt-transmission", "mqtt-engine"})
 
@@ -66,13 +66,13 @@ def is_default_representable(
     config: ProjectConfig,
     catalog: dict[str, ServiceManifest],
 ) -> bool:
-    """True when ``instance`` is faithfully carried by ``ProfileOptions`` alone.
+    """True when ``instance`` is faithfully carried by ``ArchOptions`` alone.
 
     The "today's behavior" carry: an instance whose ``id`` equals its service
     slug, carries no per-instance override, and is attached as a plain
     ``consumer`` on every *eligible* gateway (every gateway, minus the Edge
     gateways a ``never_on_edge`` service skips). Such an instance is fully
-    reproduced by listing its slug in ``ProfileOptions.services`` and letting
+    reproduced by listing its slug in ``ArchOptions.services`` and letting
     the resolver re-lower it, so it does not need re-grafting.
 
     Databases are never representable through ``services`` (they ride
@@ -103,7 +103,7 @@ def is_default_representable(
 
 
 def database_carried_by_kind(config: ProjectConfig, catalog: dict[str, ServiceManifest]) -> ServiceInstance | None:
-    """The primary database iff it rides ``ProfileOptions.database_kind`` cleanly.
+    """The primary database iff it rides ``ArchOptions.database_kind`` cleanly.
 
     ``database_kind`` always rebuilds a database with the canonical id ``db``,
     default credentials, the kind's default image, and a consumer attachment on
@@ -149,8 +149,8 @@ def detect_iiot_broker(config: ProjectConfig) -> str | None:
     Detection is by attachment role: a stack carrying any ``mqtt-transmission``
     or ``mqtt-engine`` attachment was built with ``apply_iiot``; the instance
     those attachments reference is the broker. Returning its *service slug*
-    (not its id) lets ``switch-profile`` re-apply the overlay with
-    ``ProfileOptions.iiot_broker``.
+    (not its id) lets ``switch-arch`` re-apply the overlay with
+    ``ArchOptions.iiot_broker``.
     """
     by_id = {inst.id: inst for inst in config.service_instances}
     for gw in config.gateways:
@@ -200,7 +200,7 @@ def carry_registry(
     """Re-graft ``old_config``'s richer registry onto the freshly built config.
 
     Mutates and returns ``new_config``. For every old instance that is *not*
-    already default-representable (carried via ``ProfileOptions``) and *not* the
+    already default-representable (carried via ``ArchOptions``) and *not* the
     IIoT broker, the instance is added to the registry (preserving id +
     overrides) and its non-IIoT attachments are re-mapped by role into the new
     topology. Attachments are dropped - each with a printed
@@ -212,7 +212,7 @@ def carry_registry(
 
     The order matters: instances are added before attachments so an attachment's
     referenced instance always exists, and the per-gateway db cap is checked
-    against attachments already present (including those the profile/lowering
+    against attachments already present (including those the architecture/lowering
     produced) so the carry never over-attaches.
     """
     catalog = load_all_services()
@@ -222,7 +222,7 @@ def carry_registry(
     dropped_instance: dict[str, str] = {}
 
     for old_inst in old_config.service_instances:
-        # The IIoT broker rides ProfileOptions.iiot; apply_iiot re-adds it.
+        # The IIoT broker rides ArchOptions.iiot; apply_iiot re-adds it.
         if iiot_broker_slug is not None and old_inst.service == iiot_broker_slug:
             continue
         if is_default_representable(old_inst, old_config, catalog):
@@ -303,7 +303,7 @@ def _try_attach(
     """
     manifest = catalog[inst.service]
     if any(a.instance == inst.id and a.role == att.role for a in target.services):
-        return  # already attached (idempotent / profile already produced it)
+        return  # already attached (idempotent / architecture already produced it)
 
     if manifest.placement.never_on_edge and target.ignition_edition == "edge":
         dropped.setdefault(inst.id, []).append(f"'{inst.service}' must not run on Edge gateway '{target.name}'")