merge: flows-meetings-optional — delivers #1496

Author: codex-release

core/flows/README.md

@@ -101,6 +101,37 @@ once per process; a caller sending both is answered on the new one.
 An unreachable identity answers **503**, never 401: not being able to ask who somebody is has not
 established that their credential is bad.
 
+## Meetings is optional, and so is the agent domain
+
+Two of the three domains flows can reach are **capability** doors, and their absence is a shape of
+deployment rather than a misconfiguration (PRD decision 40.7; decision 5 for meetings, agreed by
+the founder). Unset means *that domain is not deployed*: the process boots, admits facts and serves
+its queue, and the steps that would have reached the absent domain answer `<domain>:not_present` —
+terminal, with the reason on the reaction, never a retry loop against a door that is not there.
+
+| domain | key | steps that declare it |
+|---|---|---|
+| agent | `VEXA_FLOWS_AGENT_API_URL` | thirteen, listed in `tests/test_no_agents.py` |
+| meetings | `VEXA_FLOWS_GATEWAY_URL` | `await_start` · `dispatch_bot` · `run_meeting` · `process_meeting` · `email_minutes` · `email_attendees` · `drop_to_attendees` · `prepare_meeting` |
+
+**Presence is a configuration fact, never a probe.** A health check would make *"meeting-api is
+restarting"* and *"there is no meeting-api"* the same answer, and only the second is a supported
+product — the first is an outage, and it keeps the retry path it has always had.
+
+Two things a reader should not have to discover. The meetings key still says **GATEWAY** because
+flows reaches meetings *through the edge* today, which ADR-0037 forbids and which is a separate
+change: the gateway resolves the caller's key and enriches every forward with the user's scopes,
+workspaces and **limits**, and `POST /bots` enforces the per-user concurrent-bot cap out of that
+last one — so calling meeting-api directly is not a rename. And the door resolves **at access**,
+never at import (`flows_steps.common.meetings_door`): `from .common import GATEWAY` used to run the
+refusal while `flows_steps/meeting.py` was still loading, so an unset door was an ImportError for
+the whole step vocabulary, including every step with no interest in meetings.
+
+**The class change does not close flows' `gate:domain-doors` entry, and the gate is right.** That
+gate refuses a domain naming an EDGE before it looks at any class, so the entry closes on the
+de-hop above and on nothing else; `scripts/domain-doors.allow.json` now says so, in place of a
+ruling that promised this change would close it.
+
 ## Configuration
 
 Every environment key this brick reads is declared once in `src/flows_config.py`, with its class

core/flows/src/config.v1.json

@@ -102,8 +102,9 @@
     },
     {
       "key": "VEXA_FLOWS_GATEWAY_URL",
-      "class": "required-explicit",
-      "description": "The meetings gateway, on the same terms.",
+      "class": "capability",
+      "description": "The meetings domain, reached through the gateway. UNSET MEANS THE MEETINGS DOMAIN IS NOT DEPLOYED (PRD decision 40.7 + decision 5) — a supported shape of deployment, not a misconfiguration, which is exactly what the `capability` class means. `required-explicit` was a refusal to BOOT: preflight named this door and exited before anything about meetings was asked, so flows+identity with no meetings could not start at all. The key still says GATEWAY because flows reaches meetings through the edge today; that hop is ADR-0037's to close and is not this class change.",
+      "capability": "meetings",
       "targets": [
         "compose"
       ]
@@ -380,6 +381,10 @@
       "description": "Harness overrides used by the dogfood rig and the offline suites.",
       "mode": "any",
       "when_unconfigured": "The real instance gate and the real transcript. This is the deployment state."
+    },
+    "meetings": {
+      "description": "This deployment carries the meetings domain — scheduling a bot into a call and reading back what it recorded (PRD decision 40.7; decision 5 for meetings).",
+      "when_unconfigured": "The meetings domain is not deployed. Flows still boots, still admits facts and still serves its queue; every flow step that would schedule or read a bot answers `meetings:not_present` — terminal, with the reason on the reaction, never a retry loop against a door that is not there."
     }
   },
   "surface_only": [

core/flows/src/flows_config.py

@@ -75,7 +75,18 @@
     #
     # A deployment default may name the SERVICE (`http://admin-api:8057`, which resolves only
     # inside the deployment's own network) and lives in compose/helm, never here.
-    "VEXA_FLOWS_GATEWAY_URL": ("required-explicit", None, "the meetings gateway."),
+    # THE MEETINGS DOOR (PRD decision 40.7 + decision 5, founder-agreed: flows → meetings is a
+    # declared OPTIONAL dependency that degrades). `capability`, which is what the class means
+    # here: unset is not a misconfiguration, it is a deployment that runs no meetings domain, and
+    # every step that would schedule or read a bot answers `not_present` instead of knocking.
+    # `required-explicit` was a refusal to BOOT — `preflight()` names the door and exits before
+    # anything about meetings is asked, so a flows+identity deployment could not start at all.
+    # The key still says GATEWAY because flows reaches meetings through the edge today; that hop
+    # is ADR-0037's to close and is not this class change (see flows_steps.common.MEETINGS_DOOR).
+    "VEXA_FLOWS_GATEWAY_URL": ("capability", None,
+                               "the meetings domain, reached through the gateway. UNSET MEANS THE "
+                               "MEETINGS DOMAIN IS NOT DEPLOYED — see "
+                               "flows_steps.common.domain_present."),
     "VEXA_FLOWS_ADMIN_API_URL": ("required-explicit", None, "admin-api's admin tier."),
     # THE LINK PORT, and `capability` is what makes it one (PRD decision 4, founder 2026-09-03
     # 09:56Z: *"fine as a port + adapter (P16): flows owns a link port, the terminal is one
@@ -229,6 +240,9 @@ class ConfigError(RuntimeError):
 #: in the table above and nowhere else.
 DOOR_KEYS = ("VEXA_FLOWS_GATEWAY_URL", "VEXA_FLOWS_ADMIN_API_URL", "VEXA_UI_URL",
              "VEXA_FLOWS_AGENT_API_URL")
+# `missing_doors` filters this tuple on the CLASS, so the two capability doors (meetings, agent)
+# drop out of the preflight by the same line that declares them optional — there is no second list
+# to keep in step, which is how the two would drift.
 
 
 def require(name: str) -> str:

core/flows/src/flows_defs/production.py

@@ -485,9 +485,14 @@ def emit_prep(ctx: StepCtx):
                  {**ctx.refs, "uid": ctx.prior["ensure_user"]["uid"]})
         return Done({})
 
-    reg.step(mt.await_start)
-    reg.step(mt.dispatch_bot)
-    reg.step(mt.run_meeting)
+    # THE THREE THAT ARE THE MEETING (PRD decision 40.7 + decision 5). They wait for a call to
+    # start, put a bot in it, and read back what it recorded — there is nothing to degrade to and
+    # nothing to fake, so a deployment with no meetings domain answers `meetings:not_present` and
+    # the reaction ends there, carrying the reason. Declared at registration rather than checked in
+    # the body, for the reason `Registry.step` gives: a body that has to remember to ask cannot be
+    # enumerated, and the next step somebody adds will not remember.
+    for _fn in (mt.await_start, mt.dispatch_bot, mt.run_meeting):
+        reg.step(needs=("meetings",))(_fn)
 
     @reg.step
     def emit_completed(ctx: StepCtx):
@@ -600,7 +605,8 @@ def require_workspace(ctx: StepCtx):
     # REACHES THE AGENT DOMAIN (PRD decision 40.7). Declared, not checked inside the body:
     # the engine answers `not_present` for this step without entering it when a deployment
     # does not run agents, so the absent door is never knocked on.
-    @reg.step(needs=("agent",))
+    # ALSO REACHES MEETINGS — reads the room order, the meeting row and the transcript (`mt.room_order`, `mt.meeting_row`, `mt.transcript_text`).
+    @reg.step(needs=("agent", "meetings"))
     def process_meeting(ctx: StepCtx):
         """ONE REAL AGENT TURN on session meet-<id>, producing ONE SHARED ARTEFACT: the meeting's
         report, the same words for everybody who was in the room.
@@ -817,7 +823,8 @@ def _shared_report_rules(room_read: list, group: str) -> str:
     # REACHES THE AGENT DOMAIN (PRD decision 40.7). Declared, not checked inside the body:
     # the engine answers `not_present` for this step without entering it when a deployment
     # does not run agents, so the absent door is never knocked on.
-    @reg.step(needs=("agent",))
+    # ALSO REACHES MEETINGS — stamps the meeting's date and mints the link's refs (`_meeting_stamp` → `mt.meeting_start`).
+    @reg.step(needs=("agent", "meetings"))
     def email_minutes(ctx: StepCtx):
         """Send the committed note VERBATIM in the body + the feedback ask + ONE link into the
         minutes terminal, already primed on this meeting. Cannot run before the commit: its input
@@ -1047,7 +1054,8 @@ def _attendees(ctx) -> list:
     # REACHES THE AGENT DOMAIN (PRD decision 40.7). Declared, not checked inside the body:
     # the engine answers `not_present` for this step without entering it when a deployment
     # does not run agents, so the absent door is never knocked on.
-    @reg.step(needs=("agent",))
+    # ALSO REACHES MEETINGS — reads the meeting row and mints a transcript share per attendee (`mt.meeting_row`, `mt.mint_transcript_share`).
+    @reg.step(needs=("agent", "meetings"))
     def email_attendees(ctx: StepCtx):
         """Every inside-domain ATTENDEE gets the follow-up plus ONE button into a chat the click
         composes. Cannot run before the note: its input is process_meeting's receipt.
@@ -1338,7 +1346,8 @@ def _write_if_changed(their_uid: str, path: str, content: str) -> bool:
     # REACHES THE AGENT DOMAIN (PRD decision 40.7). Declared, not checked inside the body:
     # the engine answers `not_present` for this step without entering it when a deployment
     # does not run agents, so the absent door is never knocked on.
-    @reg.step(needs=("agent",))
+    # ALSO REACHES MEETINGS — stamps the meeting's day and its scaffold refs (`_meeting_stamp` → `mt.meeting_start`).
+    @reg.step(needs=("agent", "meetings"))
     def drop_to_attendees(ctx: StepCtx):
         """The meeting's ARTEFACT into every desk in the room — the organiser's included. Plain
         code, no agent turn, no LLM (founder decisions 20 and 22).
@@ -1476,7 +1485,8 @@ def drop_to_attendees(ctx: StepCtx):
     # REACHES THE AGENT DOMAIN (PRD decision 40.7). Declared, not checked inside the body:
     # the engine answers `not_present` for this step without entering it when a deployment
     # does not run agents, so the absent door is never knocked on.
-    @reg.step(needs=("agent",))
+    # ALSO REACHES MEETINGS — ensures the meeting row exists before the call (`mt.ensure_meeting_row`).
+    @reg.step(needs=("agent", "meetings"))
     def prepare_meeting(ctx: StepCtx):
         """The front door of the loop whose back door is email_minutes: one short note asking
         whether they want to walk in ready, carrying `?ask=prep&meeting=<ref>`.

core/flows/src/flows_steps/common.py

@@ -19,6 +19,21 @@
 #: convenience.
 AGENT_API = flows_config.get("VEXA_FLOWS_AGENT_API_URL")
 
+#: THE MEETINGS DOOR, and the name is a defect this change does not close. The key still says
+#: GATEWAY because flows reaches meetings THROUGH THE EDGE today — eleven call sites, all of them
+#: `{gateway}/meetings`, `{gateway}/bots`, `{gateway}/transcripts/…`. ADR-0037 forbids that hop
+#: ("fronting a sibling's door with the edge does not make it not-an-edge") and it is a separate
+#: change with its own consequences, measured and stated on this PR: the gateway resolves the
+#: caller's key and enriches every forward with X-User-Id, X-User-Scopes, X-User-Workspaces and
+#: X-User-Limits — and `POST /bots` enforces the per-user concurrent-bot cap out of that last one
+#: (`meeting_api/bot_spawn/router.py:208` `_resolve_max_concurrent`). Calling meeting-api directly
+#: without carrying those forward would silently drop the cap, so the de-hop is not a rename.
+#:
+#: What IS decided here (decision 5, founder-agreed) is the DEPENDENCY: meetings is optional, and
+#: its absence is a supported configuration rather than a refusal to boot.
+MEETINGS_DOOR = "VEXA_FLOWS_GATEWAY_URL"
+MEETINGS_API = flows_config.get(MEETINGS_DOOR)
+
 
 def domain_present(domain: str) -> bool:
     """Is this domain deployed alongside flows? (PRD decision 40.7.)
@@ -39,6 +54,8 @@ def domain_present(domain: str) -> bool:
         return True
     if domain == "agent":
         return bool((AGENT_API or "").strip())
+    if domain == "meetings":
+        return bool((MEETINGS_API or "").strip())
     return True
 
 
@@ -65,6 +82,38 @@ def agent_door() -> str:
     return base.rstrip("/")
 
 
+class MeetingsDomainAbsent(RuntimeError):
+    """A helper that reaches the meetings domain was called in a deployment that does not run it.
+
+    The sibling of `AgentDomainAbsent`, and the same second line of defence: the engine answers
+    `not_present` for a step that declared `needs=("meetings",)` without entering its body
+    (`flows/loop.tick`), so this should never fire. It exists because the first line is a
+    DECLARATION, and the next step somebody adds will not remember to make it.
+
+    Deliberately NOT `flows_config.ConfigError`. That one says *this deployment is misconfigured*,
+    and an absent optional domain is a supported configuration — the whole point of the class
+    change behind it. A refusal that names the wrong cause sends an operator to fix a door that
+    was never supposed to be there."""
+
+
+def meetings_door() -> str:
+    """The meetings base, or `MeetingsDomainAbsent`. Reads the MODULE attribute so a test can set
+    the world with one `monkeypatch.setattr`, exactly as `agent_door` does.
+
+    RESOLVED AT ACCESS, never at import. `from .common import GATEWAY` ran `flows_config.require`
+    while `flows_steps/meeting.py` was still loading, so an unset door was an ImportError for the
+    entire step vocabulary — every step, including the ones with no interest in meetings. An
+    optional domain has to be absent-able at boot, at import AND at the step; this is the middle
+    one."""
+    base = (MEETINGS_API or "").strip()
+    if not base:
+        raise MeetingsDomainAbsent(
+            f"this deployment does not run the meetings domain ({MEETINGS_DOOR} is unset). "
+            "A flow step that needs it must declare `needs=(\"meetings\",)` so the engine answers "
+            "`not_present` instead of reaching for a door that is not there.")
+    return base.rstrip("/")
+
+
 def _door(name: str) -> str:
     """A required door, resolved at ACCESS time and refused when unnamed (see flows_config.require).
 
@@ -82,8 +131,11 @@ def __getattr__(name: str) -> str:                     # PEP 562
     raise AttributeError(name)
 
 
-_DOORS = {"GATEWAY": "VEXA_FLOWS_GATEWAY_URL",
-          "ADMIN_API": "VEXA_FLOWS_ADMIN_API_URL",
+# `GATEWAY` is GONE from this map on purpose. `__getattr__` resolves a name here through
+# `flows_config.require`, which REFUSES an empty value — correct for a door the process cannot work
+# without, and exactly wrong for an optional domain. The meetings door is reached through
+# `meetings_door()` above, which answers with a typed absence instead.
+_DOORS = {"ADMIN_API": "VEXA_FLOWS_ADMIN_API_URL",
           "UI_URL": "VEXA_UI_URL"}