logos-capability-module/doctests/capability-module-composition.test.yaml

name: "Composing Two Modules Through This Capability Module"
output: capability-module-composition.md
release: ""

intro: |
  `logos-capability-module` is the `core` module the host loads first: it is the
  permission broker every other module is routed through. When `logoscore` loads
  a module, and when one module calls another over IPC, the request passes the
  capability layer this module implements. So the sharpest test of a change here
  is not to call the capability module directly — it is to put it underneath a
  **real cross-module conversation** and confirm that conversation still works.

  That is exactly what this doc-test does. It builds the `logoscore` runtime with
  **this capability-module commit** wired in as the broker, then runs two ordinary
  modules on top of it — one calling the other across the process boundary —
  through every composition path the SDK offers:

  1. Create `greeter_module`, a small **callee** with a couple of methods
     (`greet`, `addInts`, `greetCount`) and a `greeted` event.
  2. Create `orchestrator_module`, a **caller** that declares `greeter_module`
     as a dependency and composes it through the generated
     `modules().greeter_module` wrapper — synchronously, asynchronously, and by
     subscribing to its event.
  3. Build both modules' `.lgx` packages (against the latest published SDK — they
     are the payload, not the unit under test).
  4. Build `logoscore` **with `logos-capability-module` pinned to the commit under
     test**, install both modules, load them together, and call the
     orchestrator's methods — each of which loads, authorises, and calls across
     the capability layer this commit provides.

  Because every `load-module` and every cross-module `call` is mediated by the
  capability module built from the commit under test, a green run is real
  evidence that this change keeps module loading and inter-module composition —
  the things the capability layer gates — working end to end.

what_you_build: "Two modules — a `greeter_module` callee and an `orchestrator_module` caller — run together in a `logoscore` whose capability broker is built from this commit, with the caller driving the callee over IPC."

what_you_learn:
  - How the capability module sits under every module load and every cross-module call
  - How one module declares another as a dependency (`metadata.json` + `flake.nix` input)
  - How the SDK generates a typed `modules().<dep>` wrapper with sync, async, and event APIs
  - How to build `logoscore` with a specific `logos-capability-module` commit pinned across its closure
  - How to load two modules in `logoscore` and chain calls so the caller drives the callee through the capability layer

prerequisites:
  - |
    **Nix** with flakes enabled. Install from [nixos.org](https://nixos.org/download.html), then enable flakes:

    ```bash
    mkdir -p ~/.config/nix
    echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf
    ```

    Verify: `nix flake --help >/dev/null 2>&1 && echo "Flakes enabled"`
  - "**git** — nix flakes only see files tracked by git."
  - "A Linux or macOS machine."

sections:
  - title: "Create the callee: greeter_module"
    step: true
    text: |
      `greeter_module` is an ordinary `core` module written in the pure-C++
      (`interface: universal`) style: you write one plain class, and the builder
      generates the Qt plugin glue. Every `public` method becomes callable over
      IPC, and the `logos_events:` block declares an event other modules can
      subscribe to. The greeter is a plain payload module — nothing about it
      references the capability module; that layer is exercised when it is loaded
      and called.
    steps:
      - title: "metadata.json"
        text: |
          `dependencies` is empty — the greeter calls no one. `interface:
          universal` selects the pure-C++ pattern.
        file:
          path: greeter_module/metadata.json
          language: json
          content: |
            {
              "name": "greeter_module",
              "version": "1.0.0",
              "type": "core",
              "category": "general",
              "description": "A callee module: greets, counts greetings, and emits an event",
              "main": "greeter_module_plugin",
              "interface": "universal",
              "dependencies": [],

              "nix": {
                "packages": {
                  "build": [],
                  "runtime": []
                },
                "external_libraries": [],
                "cmake": {
                  "find_packages": [],
                  "extra_sources": []
                }
              }
            }

      - title: "CMakeLists.txt"
        text: "For a universal module you list only your plain C++ sources; the generated glue is compiled automatically."
        file:
          path: greeter_module/CMakeLists.txt
          language: cmake
          content: |
            cmake_minimum_required(VERSION 3.14)
            project(GreeterModulePlugin LANGUAGES CXX)

            if(DEFINED ENV{LOGOS_MODULE_BUILDER_ROOT})
                include($ENV{LOGOS_MODULE_BUILDER_ROOT}/cmake/LogosModule.cmake)
            elseif(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/cmake/LogosModule.cmake")
                include(cmake/LogosModule.cmake)
            else()
                message(FATAL_ERROR "LogosModule.cmake not found")
            endif()

            logos_module(
                NAME greeter_module
                SOURCES
                    src/greeter_module_impl.h
                    src/greeter_module_impl.cpp
            )

      - title: "flake.nix"
        text: |
          A minimal flake that hands every input to `mkLogosModule`. The
          `{release}` on the builder URL is pinned by the doc-test runner; with no
          pin it falls back to the latest published `logos-module-builder`.
        file:
          path: greeter_module/flake.nix
          language: nix
          content: |
            {
              description = "Greeter core module - a callee for the composition doc-test";

              inputs = {
                logos-module-builder.url = "github:logos-co/logos-module-builder{release}";
              };

              outputs = inputs@{ logos-module-builder, ... }:
                logos-module-builder.lib.mkLogosModule {
                  src = ./.;
                  configFile = ./metadata.json;
                  flakeInputs = inputs;
                };
            }

      - title: "src/greeter_module_impl.h — the class"
        text: |
          Plain C++ inheriting `LogosModuleContext`. The `///` doc comments
          become each method's description; the `logos_events:` block declares
          the `greeted` event (the token expands to `public` under a normal
          compile, and the generator emits the event body).
        file:
          path: greeter_module/src/greeter_module_impl.h
          language: cpp
          content: |
            #pragma once

            #include <cstdint>
            #include <string>

            #include <logos_module_context.h>  // LogosModuleContext base + logos_events

            // A simple callee module. The orchestrator composes these methods over
            // IPC. It also emits a `greeted` event so the caller can exercise a
            // typed event subscription.
            class GreeterModuleImpl : public LogosModuleContext {
            public:
                GreeterModuleImpl() = default;
                ~GreeterModuleImpl() = default;

                /// Returns a greeting for the given name.
                std::string greet(const std::string& name);

                /// Adds two integers and returns the sum.
                int64_t addInts(int64_t a, int64_t b);

                /// Returns how many times greet() has been called on this instance.
                int64_t greetCount() const;

                /// Greets the name and also emits a `greeted` event carrying it.
                void greetNotify(const std::string& name);

            logos_events:
                /// Emitted by greetNotify() with the produced greeting string.
                void greeted(const std::string& greeting);

            private:
                int64_t m_greetCount = 0;
            };

      - title: "src/greeter_module_impl.cpp — the implementation"
        text: "Plain C++ — no Qt, no IPC plumbing. `greetNotify` fires the generated event."
        file:
          path: greeter_module/src/greeter_module_impl.cpp
          language: cpp
          content: |
            #include "greeter_module_impl.h"

            std::string GreeterModuleImpl::greet(const std::string& name)
            {
                ++m_greetCount;
                return "Hello, " + name + "!";
            }

            int64_t GreeterModuleImpl::addInts(int64_t a, int64_t b)
            {
                return a + b;
            }

            int64_t GreeterModuleImpl::greetCount() const
            {
                return m_greetCount;
            }

            void GreeterModuleImpl::greetNotify(const std::string& name)
            {
                // Emit the event declared in logos_events:. When loaded by a host
                // this reaches every subscriber; constructed outside a host it is a
                // safe no-op.
                greeted("Hello, " + name + "!");
            }

  - title: "Create the caller: orchestrator_module"
    step: true
    text: |
      `orchestrator_module` declares `greeter_module` as a dependency. That one
      line in `metadata.json` is what makes the builder run the SDK's code
      generator over the greeter's exported interface and emit a typed
      `modules().greeter_module` wrapper — with sync callers, async callers, and
      event subscribers — that the orchestrator uses without any raw `LogosAPI`.
      At runtime, the very first thing that wrapper does is ask the capability
      layer for a token to reach `greeter_module`.
    steps:
      - title: "metadata.json — declare the dependency"
        text: |
          The `dependencies` entry must match `greeter_module`'s own
          `metadata.json` `name`.
        file:
          path: orchestrator_module/metadata.json
          language: json
          content: |
            {
              "name": "orchestrator_module",
              "version": "1.0.0",
              "type": "core",
              "category": "general",
              "description": "A caller module: composes greeter_module via typed sync/async calls and an event subscription",
              "main": "orchestrator_module_plugin",
              "interface": "universal",
              "dependencies": ["greeter_module"],

              "nix": {
                "packages": {
                  "build": [],
                  "runtime": []
                },
                "external_libraries": [],
                "cmake": {
                  "find_packages": [],
                  "extra_sources": []
                }
              }
            }

      - title: "CMakeLists.txt"
        file:
          path: orchestrator_module/CMakeLists.txt
          language: cmake
          content: |
            cmake_minimum_required(VERSION 3.14)
            project(OrchestratorModulePlugin LANGUAGES CXX)

            if(DEFINED ENV{LOGOS_MODULE_BUILDER_ROOT})
                include($ENV{LOGOS_MODULE_BUILDER_ROOT}/cmake/LogosModule.cmake)
            elseif(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/cmake/LogosModule.cmake")
                include(cmake/LogosModule.cmake)
            else()
                message(FATAL_ERROR "LogosModule.cmake not found")
            endif()

            logos_module(
                NAME orchestrator_module
                SOURCES
                    src/orchestrator_module_impl.h
                    src/orchestrator_module_impl.cpp
            )

      - title: "flake.nix — add the dependency input"
        text: |
          Declare `greeter_module` as a flake input; the input name **must
          match** the dependency name in `metadata.json`. The `path:` value is a
          placeholder — we lock it to the real greeter checkout in the build step
          with `--override-input` (Nix won't accept a relative `../` path written
          directly into `flake.nix`).
        file:
          path: orchestrator_module/flake.nix
          language: nix
          content: |
            {
              description = "Orchestrator core module - calls greeter_module";

              inputs = {
                logos-module-builder.url = "github:logos-co/logos-module-builder{release}";

                # The module this one depends on. Placeholder path — locked to the
                # real checkout in the build step via --override-input.
                greeter_module.url = "path:/path/to/your/greeter_module";
              };

              outputs = inputs@{ logos-module-builder, greeter_module, ... }:
                logos-module-builder.lib.mkLogosModule {
                  src = ./.;
                  configFile = ./metadata.json;
                  flakeInputs = inputs;
                };
            }

      - title: "src/orchestrator_module_impl.h — the class"
        text: |
          Three composition paths, all through `modules().greeter_module`:
          `greetThrough`/`greetReport` (sync), `startAsyncGreet`/`asyncGreeting`
          (async), and `subscribeGreeted`/`lastGreetedEvent` (event).
        file:
          path: orchestrator_module/src/orchestrator_module_impl.h
          language: cpp
          content: |
            #pragma once

            #include <cstdint>
            #include <string>

            #include <logos_json.h>            // LogosMap
            #include <logos_module_context.h>  // LogosModuleContext base + modules()

            // A caller module. It does nothing on its own — it composes
            // greeter_module through the typed modules().greeter_module wrapper the
            // builder generates from the dependency declared in metadata.json.
            class OrchestratorModuleImpl : public LogosModuleContext {
            public:
                OrchestratorModuleImpl() = default;
                ~OrchestratorModuleImpl() = default;

                /// Calls greeter_module.greet(name) and returns its result verbatim.
                std::string greetThrough(const std::string& name);

                /// Composes several greeter_module calls into one map: a greeting,
                /// an integer sum, and the greeter's current greet count.
                LogosMap greetReport(const std::string& name, int64_t a, int64_t b);

                /// Fires greeter_module.greetAsync(name) asynchronously and returns
                /// "queued" immediately; the reply lands in a callback. Read it back
                /// with asyncGreeting().
                std::string startAsyncGreet(const std::string& name);

                /// The greeting delivered by startAsyncGreet()'s callback, or empty
                /// until it arrives.
                std::string asyncGreeting() const;

                /// Subscribes to greeter_module's `greeted` event with a typed
                /// callback. Returns "ok" once registered.
                std::string subscribeGreeted();

                /// The last greeting captured by the `greeted` subscription, or
                /// empty until the event fires.
                std::string lastGreetedEvent() const;

            private:
                std::string m_asyncGreeting;
                std::string m_lastGreetedEvent;
                bool        m_subscribed = false;
            };

      - title: "src/orchestrator_module_impl.cpp — the implementation"
        text: |
          The `.cpp` includes the generated `logos_sdk.h` (which defines
          `LogosModules`) — that's why the cross-module calls live here and not in
          the header the generator parses. Each method drives `greeter_module`
          through the generated wrapper: `.greet(...)` (sync), `.greetAsync(...,
          cb)` (async), `.onGreeted(cb)` (event).
        file:
          path: orchestrator_module/src/orchestrator_module_impl.cpp
          language: cpp
          content: |
            #include "orchestrator_module_impl.h"

            // Generated at build time by logos-cpp-generator. Defines LogosModules
            // with one std-typed accessor per metadata.json dependency — here
            // greeter_module. Included only in the .cpp so the impl header the
            // generator parses stays free of Qt and codegen types.
            #include "logos_sdk.h"

            std::string OrchestratorModuleImpl::greetThrough(const std::string& name)
            {
                // The simplest cross-module round-trip: one typed sync call.
                return modules().greeter_module.greet(name);
            }

            LogosMap OrchestratorModuleImpl::greetReport(const std::string& name,
                                                         int64_t a, int64_t b)
            {
                // Three typed sync calls into greeter_module, composed into one map.
                auto& greeter = modules().greeter_module;
                LogosMap report;
                report["greeting"]   = greeter.greet(name);
                report["sum"]        = greeter.addInts(a, b);
                report["greetCount"] = greeter.greetCount();
                return report;
            }

            std::string OrchestratorModuleImpl::startAsyncGreet(const std::string& name)
            {
                // The generated async overload returns immediately; the reply is
                // delivered to the callback on this module's event loop.
                modules().greeter_module.greetAsync(name, [this](const std::string& g) {
                    m_asyncGreeting = g;
                });
                return "queued";
            }

            std::string OrchestratorModuleImpl::asyncGreeting() const
            {
                return m_asyncGreeting;
            }

            std::string OrchestratorModuleImpl::subscribeGreeted()
            {
                if (m_subscribed) return "ok";
                // Typed subscriber generated from greeter_module's logos_events:
                // greeted(const std::string&). The accessor is `on` + the
                // capitalized event name.
                m_subscribed = modules().greeter_module.onGreeted(
                    [this](const std::string& greeting) {
                        m_lastGreetedEvent = greeting;
                    });
                return m_subscribed ? "ok" : "failed";
            }

            std::string OrchestratorModuleImpl::lastGreetedEvent() const
            {
                return m_lastGreetedEvent;
            }

  - title: "Build both modules"
    step: true
    text: |
      Nix flakes only see files tracked by git, so initialise a repo in each
      module first. Then build each module's `.lgx`. These two modules are the
      **payload**, not the unit under test — they build against the latest
      published SDK and builder. (What is pinned to the commit under test is the
      capability module, wired into the runtime in the next section.)
    steps:
      - title: "Initialise git repos"
        text: "The greeter is a dependency of the orchestrator, so both must be tracked."
        run: |
          (cd greeter_module && git init -q && git add -A)
          (cd orchestrator_module && git init -q && git add -A)
        check_file: "greeter_module/.git/HEAD"

      - title: "Build the greeter's .lgx"
        text: |
          The greeter has no module dependency, so its `#lgx` builds straight from
          its own flake.
        run: |
          nix build 'path:./greeter_module#lgx' -o greeter-lgx
        code_block: |
          # From inside the greeter clone this is simply:
          #   nix build '.#lgx'
          nix build 'path:./greeter_module#lgx' -o greeter-lgx
        post_text: "The greeter package is under `./greeter-lgx/`:"
        extra_run:
          run: "ls greeter-lgx/*.lgx"

      - title: "Build the orchestrator's .lgx"
        text: |
          The orchestrator pulls in `greeter_module` as a dependency, so we lock
          that input to the local greeter checkout — the dependency wrapper the
          generator emits is built from that same checkout.
        run: |
          nix build 'path:./orchestrator_module#lgx' \
            --override-input greeter_module 'path:./greeter_module' \
            -o orchestrator-lgx
        code_block: |
          nix build 'path:./orchestrator_module#lgx' \
            --override-input greeter_module 'path:./greeter_module' \
            -o orchestrator-lgx
        post_text: "The orchestrator package is under `./orchestrator-lgx/`:"
        extra_run:
          run: "ls orchestrator-lgx/*.lgx"

  - title: "Build the runtime with this capability module and install both modules"
    step: true
    text: |
      Build `logoscore` with `logos-capability-module` **pinned to the commit
      under test**, then build `lgpm` and install both modules into a `./modules`
      directory the daemon can scan.

      `logos-capability-module` appears twice in the `logoscore` closure — as a
      direct input of `logos-logoscore-cli` (the bundled `capability_module`
      plugin the daemon loads at boot) and inside `logos-liblogos` (the runtime
      that hosts it). Overriding both pins the whole capability layer to this
      commit.

      These are deliberately the only overrides. The caller-aware host stack is
      merged and logoscore resolves it through its normal locks; a temporary
      liblogos/SDK override would mask the cross-package compatibility this
      doc-test is meant to exercise.

      > Each override URL carries a `{release}` placeholder the doc-test runner
      > expands to a concrete ref: locally that is this `logos-capability-module`
      > checkout's `HEAD` (see `run.sh`); in CI it is the commit being tested.
      > With no pin it falls back to latest `master`.
    steps:
      - title: "Build logoscore with this capability module"
        run: |
          nix build 'github:logos-co/logos-logoscore-cli' \
            --override-input logos-capability-module 'github:logos-co/logos-capability-module{release}' \
            --override-input logos-liblogos/logos-capability-module 'github:logos-co/logos-capability-module{release}' \
            --out-link ./logos
        code_block: |
          nix build 'github:logos-co/logos-logoscore-cli' \
            --override-input logos-capability-module 'github:logos-co/logos-capability-module' \
            --override-input logos-liblogos/logos-capability-module 'github:logos-co/logos-capability-module' \
            --out-link ./logos
        check_file: "logos/bin/logoscore"
        post_text: |
          The build produces `logos/bin/logoscore` plus bundled runtime libraries
          and a `logos/modules/` directory containing the `capability_module` built
          from the commit under test — the broker every load and call goes through.

      - title: "Build lgpm"
        run: "nix build 'github:logos-co/logos-package-manager#cli' -o lgpm"
        check_file: "lgpm/bin/lgpm"

      - title: "Seed the modules directory with this capability module"
        text: |
          Loading any module goes through the host's capability layer, so the
          modules directory needs the `capability_module` that ships with the
          `logoscore` we just built — i.e. the one built from this commit. Copy it
          across first.
        run: |
          mkdir -p modules
          cp -RL ./logos/modules/. ./modules/
        check_file: "modules/capability_module/manifest.json"

      - title: "Install the greeter"
        run: "./lgpm/bin/lgpm --modules-dir ./modules --allow-unsigned install --file greeter-lgx/*.lgx"
        expect_contains:
          - "Installed to:"

      - title: "Install the orchestrator"
        run: "./lgpm/bin/lgpm --modules-dir ./modules --allow-unsigned install --file orchestrator-lgx/*.lgx"
        expect_contains:
          - "Installed to:"

      - title: "Confirm all three modules are present"
        run: "./lgpm/bin/lgpm --modules-dir ./modules list"
        expect_contains:
          - "capability_module"
          - "greeter_module"
          - "orchestrator_module"
        check_file: "modules/orchestrator_module/manifest.json"

  - title: "Load both modules and drive the caller"
    step: true
    text: |
      Start `logoscore` in daemon mode (`-D`) — it keeps each module's process
      alive between `call` commands, so an event subscription registered by one
      call is still active when a later call triggers it, and an async reply
      lands before the call that reads it. The daemon auto-loads the
      `capability_module` (this commit) at boot; loading the two payload modules
      and every cross-module call below is then mediated by it.
    steps:
      - title: "Start the daemon"
        run: "sh -c './logos/bin/logoscore -D -m ./modules > logs.txt 2>&1 &'"
        code_block: "logoscore -D -m ./modules > logs.txt &"

      - run: "sleep 3"

      - title: "Load the greeter (the dependency first)"
        run: "./logos/bin/logoscore load-module greeter_module"
        code_block: "logoscore load-module greeter_module"
        expect_contains:
          - "greeter_module"

      - title: "Load the orchestrator"
        run: "./logos/bin/logoscore load-module orchestrator_module"
        code_block: "logoscore load-module orchestrator_module"
        expect_contains:
          - "orchestrator_module"

      - title: "Confirm both report loaded"
        run: "./logos/bin/logoscore status"
        code_block: "logoscore status"
        expect_contains:
          - "greeter_module"
          - "orchestrator_module"
          - '"status":"loaded"'

      - title: "Synchronous cross-module call"
        text: |
          `greetThrough(name)` forwards straight to `greeter_module.greet(name)`
          and returns the result — one typed sync call across the process
          boundary, authorised by the capability layer:
        run: "./logos/bin/logoscore call orchestrator_module greetThrough World"
        code_block: "logoscore call orchestrator_module greetThrough World"
        expect_contains:
          - '"result":"Hello, World!"'

      - title: "Compose several calls into one result"
        text: |
          `greetReport(name, a, b)` fans out to three greeter calls — `greet`,
          `addInts`, and `greetCount` — and returns them as one map. The greeter
          has now been greeted twice (once above, once here), so `greetCount` is
          `2`:
        run: "./logos/bin/logoscore call orchestrator_module greetReport Logos 3 5"
        code_block: "logoscore call orchestrator_module greetReport Logos 3 5"
        expect_contains:
          - '"greeting":"Hello, Logos!"'
          - '"sum":8'
          - '"greetCount":2'

      - title: "Asynchronous cross-module call"
        text: |
          `startAsyncGreet(name)` fires `greeter_module.greetAsync(name)` and
          returns `"queued"` immediately. The reply arrives on the daemon's event
          loop; the next call, `asyncGreeting()`, reads what the callback stashed:
        run: "./logos/bin/logoscore call orchestrator_module startAsyncGreet Async"
        code_block: "logoscore call orchestrator_module startAsyncGreet Async"
        expect_contains:
          - '"result":"queued"'

      - run: "sleep 1"

      - title: "Read the async reply"
        run: "./logos/bin/logoscore call orchestrator_module asyncGreeting"
        code_block: "logoscore call orchestrator_module asyncGreeting"
        expect_contains:
          - '"result":"Hello, Async!"'

      - title: "Subscribe to the greeter's event"
        text: |
          `subscribeGreeted()` registers a typed callback on `greeter_module`'s
          `greeted` event. Then `greeter_module.greetNotify(...)` makes the
          greeter emit it, and `lastGreetedEvent()` reads what the subscription
          captured. Because the daemon keeps both modules loaded, the event fires
          between the calls:
        run: "./logos/bin/logoscore call orchestrator_module subscribeGreeted"
        code_block: "logoscore call orchestrator_module subscribeGreeted"
        expect_contains:
          - '"result":"ok"'

      - title: "Trigger the event from the greeter"
        run: "./logos/bin/logoscore call greeter_module greetNotify Events"
        code_block: "logoscore call greeter_module greetNotify Events"

      - run: "sleep 1"

      - title: "Read the captured event payload"
        run: "./logos/bin/logoscore call orchestrator_module lastGreetedEvent"
        code_block: "logoscore call orchestrator_module lastGreetedEvent"
        expect_contains:
          - '"result":"Hello, Events!"'

      - title: "Dump the daemon log"
        run: "cat logs.txt || true"

      - title: "Stop the daemon"
        run: "./logos/bin/logoscore stop"
        code_block: "logoscore stop"

      - run: "sleep 2"

      - title: "Confirm the daemon has stopped"
        run: "./logos/bin/logoscore status || true"
        code_block: "logoscore status"
        expect_contains:
          - '"status":"not_running"'

  - title: "Recap"
    text: |
      | Composition path | In the orchestrator | Driven via `logoscore` |
      | ---------------- | ------------------- | ---------------------- |
      | Typed **sync** call | `greetThrough()` → `greeter.greet(...)` | `"Hello, World!"` |
      | Composed sync calls | `greetReport()` → `greet` + `addInts` + `greetCount` | one map of three results |
      | Typed **async** call | `startAsyncGreet()` → `greetAsync(..., cb)` | `queued`, then `"Hello, Async!"` |
      | Typed **event** subscription | `subscribeGreeted()` → `onGreeted(cb)` | captured `"Hello, Events!"` |

      Every module load and every one of these calls was brokered by the
      `capability_module` built from the commit under test. A green run means this
      capability-module change keeps module loading and inter-module composition —
      exactly what the capability layer gates — working end to end, so the change
      does not break downstream consumers.