@biffo/cli 0.38.0 → 0.41.0

package/_skeletons/plugin-template/registry-schema.json

@@ -0,0 +1,294 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Biffo Plugin Manifest",
+  "description": "Schema for biffo.plugin.json — declares what a plugin provides and needs.",
+  "type": "object",
+  "required": ["name", "version", "tables", "api_routes", "ui_components"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Unique plugin slug (lowercase, kebab-case)."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semver version of this plugin release."
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Human-readable summary shown in the marketplace."
+    },
+    "author": {
+      "type": "string",
+      "default": "Biffo Team",
+      "description": "Publisher name."
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Categorisation tags for filtering/search."
+    },
+    "required_core_version": {
+      "type": "string",
+      "default": ">=0.0.0",
+      "description": "Minimum Biffo core version (npm-style range)."
+    },
+    "tables": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$",
+            "description": "PostgreSQL table name (snake_case)."
+          },
+          "columns": {
+            "type": "array",
+            "description": "Additional columns beyond id/tenant_id/created_at/updated_at, which are auto-injected on every table per ADR-0001 and must NOT be declared here — doing so fails validation (ColumnDefinition/PluginTableDefinition in services/api/src/api/models/plugin_table.py).",
+            "items": {
+              "type": "object",
+              "required": ["name", "type"],
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "not": { "enum": ["id", "tenant_id", "created_at", "updated_at"] },
+                  "description": "Column name. The names id, tenant_id, created_at, and updated_at are reserved (auto-injected) and rejected here."
+                },
+                "type": {
+                  "type": "string",
+                  "pattern": "^(String|Integer|Text|Boolean|Float|DateTime)(\\(.*\\))?$",
+                  "description": "SQLAlchemy column type constructor string, e.g. 'String(255)', 'Integer', or 'DateTime(timezone=True)'. Must be one of the base types plugin_table.py's _TYPE_MAP resolves (String, Integer, Text, Boolean, Float, DateTime) — anything else silently falls back to String, so this schema rejects it up front rather than allowing a PostgreSQL-style type name (e.g. UUID, TIMESTAMP) that looks valid but isn't."
+                },
+                "primary_key": {
+                  "type": "boolean",
+                  "default": false,
+                  "description": "Whether this is the primary key."
+                },
+                "nullable": {
+                  "type": "boolean",
+                  "default": false,
+                  "description": "Whether NULL values are allowed. Defaults to false (NOT NULL)."
+                },
+                "index": {
+                  "type": "boolean",
+                  "default": false,
+                  "description": "Create a database index on this column."
+                },
+                "default": { "type": "string", "description": "SQL default value expression." },
+                "description": {
+                  "type": "string",
+                  "default": "",
+                  "description": "Human-readable column description."
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "indexes": {
+            "type": "array",
+            "description": "Explicit (optionally multi-column or unique) indexes on the table, beyond any single-column indexes already requested via a column's index: true.",
+            "items": {
+              "type": "object",
+              "required": ["name", "columns"],
+              "properties": {
+                "name": { "type": "string", "description": "Index name in the database." },
+                "columns": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "minItems": 1,
+                  "description": "Column names included in the index."
+                },
+                "unique": {
+                  "type": "boolean",
+                  "default": false,
+                  "description": "Whether the index enforces uniqueness."
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "permissions": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Declarative per-operation generic-CRUD permissions (ADR-0004; TablePermissions in services/api/src/api/models/plugin_table.py). Default-deny: an absent permissions block, an absent operation key, or an operation with allowed:false ALL make the table invisible to the generic CRUD layer for that operation. required_role is an any-of allow-list matched against the caller's roles (cognito:groups); an empty list means any authenticated caller. Tenant scoping (ADR-0001) is always applied and is deliberately not configurable here. Only the five operation keys below are permitted.",
+            "properties": {
+              "list": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "allowed": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Whether the generic CRUD layer exposes this operation at all."
+                  },
+                  "required_role": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "default": [],
+                    "description": "Any-of role allow-list; empty means any authenticated caller."
+                  }
+                }
+              },
+              "read": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "allowed": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Whether the generic CRUD layer exposes this operation at all."
+                  },
+                  "required_role": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "default": [],
+                    "description": "Any-of role allow-list; empty means any authenticated caller."
+                  }
+                }
+              },
+              "create": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "allowed": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Whether the generic CRUD layer exposes this operation at all."
+                  },
+                  "required_role": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "default": [],
+                    "description": "Any-of role allow-list; empty means any authenticated caller."
+                  }
+                }
+              },
+              "update": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "allowed": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Whether the generic CRUD layer exposes this operation at all."
+                  },
+                  "required_role": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "default": [],
+                    "description": "Any-of role allow-list; empty means any authenticated caller."
+                  }
+                }
+              },
+              "delete": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "allowed": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Whether the generic CRUD layer exposes this operation at all."
+                  },
+                  "required_role": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "default": [],
+                    "description": "Any-of role allow-list; empty means any authenticated caller."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "additionalProperties": false
+      },
+      "description": "Database tables the plugin creates via Alembic migrations."
+    },
+    "api_routes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["method", "path", "table", "operation"],
+        "properties": {
+          "method": {
+            "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"],
+            "description": "HTTP method. Must be compatible with `operation` (list/read=GET, create=POST, update=PUT/PATCH, delete=DELETE) — see plugin_route.py's _OPERATION_METHODS."
+          },
+          "path": {
+            "type": "string",
+            "pattern": "^/[a-zA-Z0-9/_{}-]+$",
+            "description": "Path relative to the plugin's mount point (/api/v1/plugins/<name>), e.g. '/widgets' or '/widgets/{id}'. Must start with '/'. Single-row operations (read/update/delete) address a row via an '{id}' path parameter; collection operations (list/create) must not."
+          },
+          "table": {
+            "type": "string",
+            "description": "Name of a table declared in this manifest's `tables` that this route exposes. A route cannot reference another plugin's table (RouteDefinition / parse_plugin_routes_from_manifest in services/api/src/api/models/plugin_route.py)."
+          },
+          "operation": {
+            "enum": ["list", "read", "create", "update", "delete"],
+            "description": "Generic CRUD operation the Core API synthesizes for this route against `table`, scoped to the caller's tenant_id (ADR-0001). A plugin manifest cannot ship executable handler code the Core API imports and runs (ADR-0002); routes are declarative (issue #19)."
+          },
+          "description": { "type": "string" }
+        }
+      },
+      "description": "Declarative generic-CRUD routes the Core API synthesizes against this plugin's own tables (issue #19 / ADR-0002), mounted under /api/v1/plugins/<name>."
+    },
+    "event_subscriptions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["detail_type"],
+        "properties": {
+          "source": { "type": "string", "default": "biffo.core" },
+          "detail_type": { "type": "string" },
+          "handler": { "type": "string" }
+        }
+      },
+      "description": "EventBridge events the plugin subscribes to."
+    },
+    "infra_modules": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "compute",
+          "storage",
+          "events",
+          "cdn",
+          "database",
+          "auth",
+          "networking",
+          "oidc",
+          "api-gateway"
+        ]
+      },
+      "description": "Terraform module categories the plugin provisions."
+    },
+    "ui_components": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["type", "label", "path"],
+        "properties": {
+          "type": {
+            "enum": ["nav-link", "page", "dashboard-widget", "modal", "dialog"],
+            "description": "UI component type."
+          },
+          "label": { "type": "string" },
+          "path": { "type": "string" },
+          "icon": { "type": "string" },
+          "requires_auth": { "type": "boolean", "default": true }
+        }
+      },
+      "description": "Portal UI elements the plugin adds."
+    },
+    "dependencies": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Python package dependencies (including biffo-plugin-sdk)."
+    }
+  },
+  "additionalProperties": false
+}

package/_skeletons/plugin-template/src/example_plugin/__init__.py

@@ -0,0 +1,10 @@
+"""Example plugin — reference implementation shipped with the plugin
+repository template.
+
+Rename this package (and `example_plugin` throughout the repo) to your
+plugin's own name when you start from this template. See README.md.
+"""
+
+from .plugin import ExamplePlugin
+
+__all__ = ["ExamplePlugin"]

package/_skeletons/plugin-template/src/example_plugin/main.py

@@ -0,0 +1,63 @@
+"""Example plugin Lambda entrypoint.
+
+Mirrors the RBAC reference plugin's `services/rbac/src/rbac/main.py` and
+`services/_template/src/service/main.py`'s documented event shape and rules
+(ADR-0002): never import a DB client, talk to the Core API only via
+`BiffoAPIClient`, react to state changes via EventBridge.
+
+This handler's only responsibility is dispatching EventBridge events the
+plugin subscribes to (see `plugin.py`) through `ExamplePlugin`'s
+`EventSubscriber`. It is not wired to a real Lambda in this template — that
+wiring (an EventBridge rule targeting this function) belongs to your
+plugin's own `terraform/` module, added once ADR-0003's conditional plugin
+Terraform inclusion (issue #25) lands in a generated project.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.utilities.typing import LambdaContext
+from biffo_plugin_sdk import create_event_handler
+
+from .plugin import ExamplePlugin
+
+logger = Logger()
+tracer = Tracer()
+
+# Reuse one event loop across warm invocations. asyncio.run() closes the loop
+# each call, but the plugin's reused httpx client pools connections bound to
+# the first loop -> "RuntimeError: Event loop is closed" on the next
+# invocation. Mirrors services/api/src/api/main.py.
+_loop = asyncio.new_event_loop()
+asyncio.set_event_loop(_loop)
+
+_plugin: ExamplePlugin | None = None
+
+
+def _get_plugin() -> ExamplePlugin:
+    """Lazily construct the plugin singleton, reused across warm invocations
+    — a misconfigured environment (e.g. missing BIFFO_CORE_API_URL) surfaces
+    at first use rather than being buried inside every event."""
+    global _plugin
+    if _plugin is None:
+        _plugin = ExamplePlugin()
+    return _plugin
+
+
+@logger.inject_lambda_context
+@tracer.capture_lambda_handler
+def handler(event: dict, context: LambdaContext) -> dict:
+    logger.info("Received event", extra={"event": event})
+
+    global _loop
+    if _loop.is_closed():
+        _loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(_loop)
+
+    biffo_event = create_event_handler(event)
+    plugin = _get_plugin()
+    _loop.run_until_complete(plugin.events.dispatch(biffo_event))
+
+    return {"statusCode": 200}

package/_skeletons/plugin-template/src/example_plugin/manifest.py

@@ -0,0 +1,30 @@
+"""Path to this plugin's manifest file, shared by plugin.py and tests.
+
+Mirrors the RBAC reference plugin's `services/rbac/src/rbac/manifest.py`
+(PR #76) — same rationale: `plugin.py` and the tests both need a reliable
+absolute path to `biffo.plugin.json` regardless of the current working
+directory the process was started from.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+# src/example_plugin/manifest.py -> src/example_plugin -> src -> repo root
+# (plugin root, where biffo.plugin.json lives alongside pyproject.toml).
+def _resolve_manifest_path() -> Path:
+    # Walk up from this module to find biffo.plugin.json, so it resolves in both
+    # the repo layout (src/<pkg>/manifest.py, manifest at the plugin root) and the
+    # deployed Lambda (handler <pkg>.main.handler unzips <pkg>/ at the task root,
+    # manifest bundled at /var/task/biffo.plugin.json). A fixed parents[2]
+    # resolved to /var in the Lambda and raised FileNotFoundError on first invoke.
+    here = Path(__file__).resolve()
+    for base in here.parents:
+        candidate = base / "biffo.plugin.json"
+        if candidate.is_file():
+            return candidate
+    return here.parent.parent / "biffo.plugin.json"
+
+
+MANIFEST_PATH = _resolve_manifest_path()

package/_skeletons/plugin-template/src/example_plugin/plugin.py

@@ -0,0 +1,92 @@
+"""ExamplePlugin — this plugin's BiffoPluginBase implementation.
+
+Seeds a single default widget on install and reacts to
+`biffo.core/UserCreated` by logging the new user. Replace both with real
+logic for your own plugin — this exists to show a working, correctly-wired
+skeleton: constructor -> manifest loading -> `self.api` -> `@self.subscribe`
+-> `on_install`/`on_uninstall`, exercised end to end by the tests in
+`tests/test_example_plugin.py`.
+
+Modelled directly on the RBAC reference plugin's
+`services/rbac/src/rbac/plugin.py` (PR #76) in the biffo-template monorepo —
+see that file (and its README) for a more elaborate example with multiple
+tables, an event-driven side effect, and an in-process (non-CRUD) helper.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from aws_lambda_powertools import Logger
+from biffo_plugin_sdk import BiffoAPIClient, BiffoEvent, BiffoPluginBase, load_manifest
+
+from .manifest import MANIFEST_PATH
+
+logger = Logger()
+
+_PLUGIN_BASE_PATH = "/api/v1/plugins/example-plugin"
+
+# Seeded by on_install(). Real plugins would seed whatever baseline data
+# their feature needs (RBAC's plugin.py seeds three roles, for example).
+_DEFAULT_WIDGET: dict[str, Any] = {
+    "name": "starter-widget",
+    "description": "Created automatically by on_install(). Safe to delete.",
+    "is_active": True,
+}
+
+
+class ExamplePlugin(BiffoPluginBase):
+    """The example plugin shipped with the plugin repository template."""
+
+    def __init__(self, api: BiffoAPIClient | None = None) -> None:
+        manifest = load_manifest(MANIFEST_PATH)
+        super().__init__(manifest, api=api)
+
+        @self.subscribe("UserCreated")
+        async def _on_user_created(event: BiffoEvent) -> None:
+            await self._log_user_created(event)
+
+    def on_install(self) -> None:
+        """Called by the CLI when the plugin is installed.
+
+        `BiffoPluginBase.on_install` is declared synchronous but
+        `BiffoAPIClient` is entirely async (same constraint the RBAC
+        reference plugin documents) — bridge with `asyncio.run` here and
+        keep the actual async logic in the public `seed_default_widget()`,
+        which tests and any future async caller can `await` directly.
+        """
+        asyncio.run(self.seed_default_widget())
+
+    async def seed_default_widget(self) -> None:
+        """The async core of on_install().
+
+        Generic CRUD (issue #19) has no upsert — every POST creates a new
+        row — so this lists existing widgets first and only creates the
+        default one if it's missing by name, making repeated installs a
+        no-op instead of creating duplicate rows.
+        """
+        existing = await self.api.get(f"{_PLUGIN_BASE_PATH}/widgets")
+        existing_names = {row.get("name") for row in existing}
+        if _DEFAULT_WIDGET["name"] not in existing_names:
+            await self.api.post(f"{_PLUGIN_BASE_PATH}/widgets", json=dict(_DEFAULT_WIDGET))
+
+    def on_uninstall(self) -> None:
+        """Called by the CLI when the plugin is uninstalled.
+
+        No-op: dropping this plugin's tables is the CLI's job (ADR-0003
+        section 9 — `biffo plugin uninstall` applies a generated migration
+        that drops them). Override this if your plugin needs additional
+        cleanup beyond that (e.g. deleting objects it created outside its
+        own tables).
+        """
+        return None
+
+    async def _log_user_created(self, event: BiffoEvent) -> None:
+        """Example event handler. Replace with real logic, or remove the
+        `@self.subscribe` registration in `__init__` if your plugin doesn't
+        need to react to this event."""
+        logger.info(
+            "New user created",
+            extra={"tenant_id": event.tenant_id, "payload": event.payload},
+        )

package/_skeletons/plugin-template/terraform/README.md

@@ -0,0 +1,146 @@
+# `terraform/` — this plugin's infrastructure
+
+This is the plugin's own Terraform module, per [ADR-0003](https://github.com/keiranholloway/biffo-template/blob/main/docs/ADR/0003-plugin-system-and-marketplace.md) section 2. It is a verbatim copy of biffo-template's `modules/plugins/_template/`, kept here so a plugin built from this skeleton is **deployable out of the box**: without it, the `event_subscriptions` in `biffo.plugin.json` are declared, handled in code, unit-tested — and inert in every real deployment, because nothing creates the Lambda or the EventBridge rule to fire them.
+
+`biffo plugin install <name>@<minor>` copies this directory into the user's monorepo at `modules/plugins/<name>/`. Note that the install path is where it becomes valid Terraform: `main.tf`'s `source = "../../cloud/aws/compute"` is relative to `modules/plugins/<name>/`, so `terraform validate` does **not** run against this directory in place — neither here nor in biffo-template, whose Terraform CI job scopes itself to `infra/` and `modules/`. Do not "fix" that path; changing it breaks the install target.
+
+Rename `example_plugin`/`<name>` references to your plugin's slug and adjust `handler`, `event_subscriptions`, and `memory_size`/`timeout` to match your manifest. The rest of this file is the module's own documentation, unchanged.
+
+---
+
+## Original module notes
+
+## What it wraps, and why
+
+This module is a thin wrapper around two existing modules, not a reimplementation:
+
+- **`modules/cloud/aws/compute`** — the plugin's Lambda function (IAM role, DLQ, log group, tracing — the same baseline every Biffo function gets).
+- **`modules/cloud/aws/events`**, via the `event_bus_name` passed in from the root config — this module only adds the EventBridge rule/target/permission needed to route the plugin's declared `event_subscriptions` to its Lambda. It never creates a bus of its own.
+
+Per **ADR-0002** ("no DB clients outside `services/api/`; microservices call the API via HTTP and react to EventBridge events"), a plugin module:
+
+- **Never receives `db_credentials_secret_arn`.** Only the Core API's Lambda (`module.core_api` in the root config) gets that grant. A plugin that needs platform data calls the Core API over HTTPS using `BIFFO_CORE_API_URL` (wired here from `var.core_api_url`) via the plugin SDK's Core client — see [Calling the Core API](#calling-the-core-api-adr-0009) below for how that call is authenticated.
+- **Is not VPC-attached by default.** `enable_vpc_access` defaults to `false` in both this module and `modules/cloud/aws/compute`, so the plugin's Lambda runs with normal Lambda internet egress — required to reach the Core API's public endpoint, especially in NAT-less environments like dev (`enable_nat_gateway = false`). Only set `enable_vpc_access = true` (and pass `vpc_id`/`private_subnet_ids`) if the plugin has a genuine ADR-0002-compliant reason to reach a VPC-only resource (e.g. ElastiCache) — never to reach the database directly. `enable_vpc_access` must be an explicit boolean, not inferred from `vpc_id` — Terraform's `count`/`for_each` can't depend on a `vpc_id` that's only known after apply.
+
+## Variables
+
+See `variables.tf`. The standard set every plugin module receives from the root config: `project_name`, `environment`, `plugin_name`, `event_bus_name`, `core_api_url`, `tags`, plus `core_api_execution_arn` for any plugin that calls the Core API. Everything else (`handler`, `event_subscriptions`, `environment_variables`, etc.) is plugin-specific.
+
+## Calling the Core API (ADR-0009)
+
+A plugin may not touch the database (ADR-0002), so anything it needs from the
+platform it fetches from the Core API. The Core API's **internal** routes
+(`/api/v1/internal/*`) are authorized by **IAM SigV4**, not by a Cognito JWT —
+per [ADR-0009](https://github.com/keiranholloway/biffo-template/blob/main/docs/ADR/0009-internal-service-authentication.md). There
+is no bearer token to issue, store, or rotate; the credential is the plugin
+Lambda's own role.
+
+Three things must line up, and all three are wired for you — this module
+does the first two, and `biffo plugin install` does the third:
+
+1. **Sign the request.** The plugin SDK's `SignedCoreClient` does this, and
+   `BiffoPluginBase` builds one by default (`create_core_client()`), so plugin
+   code that just calls `self.api.post(...)` is already signing. `botocore` is
+   preinstalled in the Lambda Python runtime; outside Lambda install the
+   `biffo-plugin-sdk[sigv4]` extra.
+2. **Grant `execute-api:Invoke`.** Set `core_api_execution_arn` (the root
+   config's `module.api_gateway.execution_arn`) and this module attaches an
+   inline policy to the plugin's Lambda role allowing `execute-api:Invoke` on
+   `<execution_arn>/*/*/api/v1/internal/*` — that prefix only, never the whole
+   API. Leave the variable empty and no grant is created.
+3. **Allowlist the role on the Core API.** _Automatic since issue #201._ The
+   Core API independently re-checks the resolved caller ARN against
+   `BIFFO_SERVICE_PRINCIPAL_ARN_ALLOWLIST` and **fails closed** on an empty or
+   non-matching allowlist, so step 2 alone would get you a `403`. At runtime the
+   caller ARN is the assumed-role session form, so the allowlist entry is a
+   glob:
+
+   ```
+   arn:aws:sts::<account-id>:assumed-role/<project>-<env>-plugin-<name>-role/*
+   ```
+
+   The template-owned `modules/cloud/aws/plugin-allowlist` module builds that
+   list, mapping over the root config's `var.enabled_plugins`
+   — so adding the plugin to `enabled_plugins` (which `biffo plugin install`
+   does for you, via the generated `plugins.auto.tfvars.json`) is what
+   allowlists it. Nothing to copy by hand, and the grant and the allowlist
+   cannot drift apart.
+
+   The role name is deterministic, which is what makes this possible:
+   `modules/cloud/aws/compute` names the role `<function_name>-role`, where
+   `function_name` is `<project_name>-<environment>-plugin-<plugin_name>`. It is
+   also this module's `role_name` output — useful for auditing, but the root
+   config deliberately does not read it (see below).
+
+### Why the allowlist is a static string, not this module's output
+
+Tempting as it is to write
+`BIFFO_SERVICE_PRINCIPAL_ARN_ALLOWLIST = module.plugin_<name>.role_arn`, that
+creates a Terraform **dependency cycle** (issue
+[#201](https://github.com/keiranholloway/biffo-template/issues/201)):
+
+```
+core_api  ->  api_gateway  ->  plugin  ->  core_api
+   (needs the plugin's role ARN)   (needs the API's execution ARN)
+```
+
+The plugin needs the API Gateway's `execution_arn` to scope its grant, and the
+Core API Lambda would need the plugin's `role_arn` for its allowlist env var.
+Terraform cannot order that.
+
+The resolution — the same one the orchestrator uses — is that the arrow only
+ever points **one way**: API Gateway -> plugin. The allowlist entry is written as
+the _predictable_ role-name glob above, interpolated from values the root config
+already knows (`project_name`, `environment`, plugin name) rather than read back
+out of the plugin module.
+
+**How close the cycle actually is.** Measured on the current module, wiring
+`role_arn` does _not_ deadlock today: Terraform's dependency graph is
+resource-level, not module-level, and this module's `aws_iam_role` does not
+itself depend on API Gateway — only the separate `aws_iam_role_policy.core_api`
+does. So a `terraform plan` with `role_arn` wired in currently builds. That is
+an accident of this module's internals, not a property you can rely on: a plugin
+that attached its Core API policy to the role resource itself (an inline
+`inline_policy` block rather than a separate `aws_iam_role_policy`) closes the
+loop immediately, and the resulting cycle error lands on whoever _installed_
+that plugin, far from the code that caused it. It would also make the Core API
+un-plannable whenever any installed plugin module is broken.
+
+The static glob has no dependency on the plugin module at all, for any plugin,
+which is the property worth having. Keep it that way.
+
+## Loose coupling
+
+This module must never reference another plugin's module or resources. Each plugin is instantiated independently by the root config's `for_each`-gated `module "plugin_<name>"` block — no plugin module may assume any other plugin is installed.
+
+## Wiring into the root config
+
+`biffo plugin install` generates this block for you, into a CLI-owned
+`infra/environments/<env>/plugins.generated.tf` (issue #201) — you should not
+need to write it by hand. It is reproduced here so you know what your module is
+instantiated with.
+
+The root config cannot dynamically discover plugin module directories —
+Terraform requires a module's `source` argument to be a static string literal,
+so each plugin needs its own explicit block, gated on membership in
+`enabled_plugins`:
+
+```hcl
+module "plugin_<name>" {
+  source   = "../../../modules/plugins/<name>"
+  for_each = contains(var.enabled_plugins, "<name>") ? { "<name>" = true } : {}
+
+  project_name   = var.project_name
+  environment    = local.environment
+  plugin_name    = "<name>"
+  handler        = "src.lambda.main.handler"
+  event_bus_name = module.events.event_bus_name
+  core_api_url   = module.api_gateway.api_endpoint
+  tags           = local.tags
+
+  # Only if the plugin calls the Core API — see "Calling the Core API" below.
+  core_api_execution_arn = module.api_gateway.execution_arn
+}
+```
+
+The generator emits only the arguments your module actually declares a `variable` block for, so a module predating one of these inputs still wires in cleanly. See `infra/environments/dev/README.md` for the full convention.