feat(wiring): library composition — LibraryGroup + closure-as-membership with cross-package type travel (#333)

Author: zoe-codez

.github/workflows/check.yml

@@ -32,6 +32,7 @@ jobs:
       - run: yarn
       - run: yarn build
       - run: yarn lint
+      - run: yarn type-check
       - run: yarn test --coverage
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v7.0.0
@@ -46,3 +47,6 @@ jobs:
 
   test-pipelines-bun:
     uses: ./.github/workflows/test-pipelines-bun.yml
+
+  test-implies-propagation:
+    uses: ./.github/workflows/test-implies-propagation.yml

.github/workflows/test-implies-propagation.yml

@@ -0,0 +1,27 @@
+name: Test Implies Propagation
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test-implies-propagation:
+    runs-on: ubuntu-latest
+    # cold-cache guard: run.sh builds core + two demo packages from scratch
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - run: corepack enable
+      - run: yarn config set enableImmutableInstalls false
+      - run: yarn
+      # Builds local core, type-checks the consumer (the proof that an implied
+      # library's types travel across the package boundary), then runs the demo.
+      # If a future TS/core change breaks the function-declaration import edge,
+      # params.lighting stops resolving and this step goes red.
+      - name: Demo + regression guard (implies cross-package type propagation)
+        run: bash examples/implies-propagation/run.sh

.github/workflows/test-pipelines-deno.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Test config-error with deno
         run: |
           set +e
-          output=$(deno run --allow-read --allow-env testing/pipelines/config-error.mts 2>&1)
+          output=$(deno run --allow-read --allow-env --allow-sys testing/pipelines/config-error.mts 2>&1)
           exit_code=$?
           echo "Exit code: $exit_code"
           echo "Output: $output"
@@ -34,7 +34,7 @@ jobs:
       - name: Test thrown-bootstrap-error with deno
         run: |
           set +e
-          output=$(deno run --allow-read --allow-env testing/pipelines/thrown-bootstrap-error.mts 2>&1)
+          output=$(deno run --allow-read --allow-env --allow-sys testing/pipelines/thrown-bootstrap-error.mts 2>&1)
           exit_code=$?
           echo "Exit code: $exit_code"
           echo "Output: $output"
@@ -50,7 +50,7 @@ jobs:
       - name: Test simple-success with deno
         run: |
           set +e
-          output=$(deno run --allow-read --allow-env testing/pipelines/simple-success.mts 2>&1)
+          output=$(deno run --allow-read --allow-env --allow-sys testing/pipelines/simple-success.mts 2>&1)
           exit_code=$?
           echo "Exit code: $exit_code"
           echo "Output: $output"

.gitignore

@@ -125,3 +125,4 @@ dynamic.d.mts
 /obsidian/.obsidian
 .yarn/install-state.gz
 .env
+examples/**/dist

cspell.config.yaml

@@ -142,6 +142,8 @@ words:
   - reftimes
   - RGBW
   - RGBWW
+  - rollup
+  - rollups
   - rosybrown
   - royalblue
   - rrule

examples/implies-propagation/README.md

@@ -0,0 +1,82 @@
+# `implies` type propagation — demo + regression guard
+
+A tiny two-package workspace that proves a non-obvious property of
+`@digital-alchemy/core`: when a library lists another library in `implies`, a
+downstream consumer that imports **only** the first library gets the second one
+both **wired at runtime** and **fully typed at compile time** — with no
+`LoadedRollups` registration and no manual re-export.
+
+It is also a durable regression guard: it compiles and runs against the real
+local core, so if a future TypeScript release changes how declaration-merge
+augmentations travel across package boundaries, `run.sh` fails loudly.
+
+## Run it
+
+```bash
+bash run.sh
+```
+
+That builds core, builds `@demo/home-libraries`, type-checks `@demo/home-app`
+(the proof), then runs it (the demo). Expected output ends with the lights being
+driven by a library the app never imported:
+
+```
+[INFO][living_room:Scenes]: ☀️  good morning
+[INFO][lighting:Lights]: 💡 lights → 80%
+[INFO][home:Routine]: lighting reports 80% — typed, no registration
+```
+
+## Layout
+
+| Package | Role |
+|---|---|
+| `home-libraries/src/lighting.mts` | A plain library. Its service is a **named `function` declaration** — the load-bearing detail. |
+| `home-libraries/src/living-room.mts` | `implies: [LIGHTING]` (membership + types) and `depends: [LIGHTING]` (wiring order). Registers only `living_room`. |
+| `home-app/src/main.mts` | Imports **only** `LIVING_ROOM`, lists **only** `LIVING_ROOM`. Uses `params.lighting` — typed and live. |
+| `home-app/src/proof.mts` | Type-only guard (`@ts-expect-error` probes) — never executed, only type-checked. |
+
+## Why it works (and why named functions matter)
+
+Capturing `implies` as a literal tuple makes the implier's emitted `.d.mts`
+reference each member. With **named-function** services the reference is a real
+module edge:
+
+```ts
+// living-room.d.mts — NAMED fn: a genuine import edge to lighting.mjs
+readonly [LibraryDefinition<{ Lights: typeof import("./lighting.mjs").Lights }, …>]
+```
+
+That `import("./lighting.mjs")` pulls `lighting.d.mts` into the consumer's
+program, so its `declare module { interface LoadedModules { lighting } }`
+augmentation activates and `TServiceParams` gains `lighting` automatically.
+
+An **arrow** service would be inlined anonymously with **no** edge:
+
+```ts
+// hypothetical arrow version — anonymous, no edge, augmentation never travels
+readonly [LibraryDefinition<{ read: (p: TServiceParams) => { … } }, …>]
+```
+
+so the member would wire at runtime but `params.<member>` would be untyped. Named
+function declarations are not a style preference here — they are what makes the
+cross-package type edge exist.
+
+## Membership vs. ordering
+
+The two fields on `living_room` are orthogonal and both intentional:
+
+- `implies: [LIGHTING]` — **membership + types.** The app can omit `lighting`
+  from `libraries`; it is pulled into the resolved set and its types travel.
+- `depends: [LIGHTING]` — **ordering only.** `params` is a wire-time snapshot, so
+  `lighting` must wire *before* `living_room` for `Scenes` to call it.
+
+Drop `implies` and the app must list `lighting` itself (or boot throws
+`MISSING_DEPENDENCY`). Drop `depends` and `lighting` may wire after `living_room`,
+leaving `params.lighting` undefined at call time.
+
+## The core change this depends on
+
+One thing: `CreateLibrary` captures `implies` as a `const` tuple, carried as a
+third type parameter on `LibraryDefinition`. No `TServiceParams` machinery —
+deriving member keys for `TServiceParams` directly is provably circular; letting
+the member's own augmentation ride the import edge is what avoids that.

examples/implies-propagation/home-app/package.json

@@ -0,0 +1 @@
+{ "name": "@demo/home-app", "version": "1.0.0", "type": "module", "private": true }

examples/implies-propagation/home-app/src/main.mts

@@ -0,0 +1,42 @@
+/**
+ * Downstream app. The whole point of this file:
+ *
+ *   - It imports ONLY `LIVING_ROOM`.
+ *   - It lists ONLY `LIVING_ROOM` in `libraries`.
+ *   - It never imports, names, or registers `lighting` anywhere.
+ *
+ * Yet `params.lighting` is fully typed AND wired at runtime — it arrived purely
+ * through `LIVING_ROOM`'s `implies`. Membership comes along (runtime), and the
+ * types come along (compile time), with zero extra wiring.
+ */
+import { CreateApplication, type TServiceParams } from "@digital-alchemy/core";
+import { LIVING_ROOM } from "@demo/home-libraries/living-room";
+
+function Routine({ living_room, lighting, lifecycle, logger }: TServiceParams) {
+  lifecycle.onReady(() => {
+    logger.info("— a day in the (imaginary) living room —");
+    living_room.Scenes.goodMorning();
+
+    // `lighting` was never imported or listed here. It is implied by LIVING_ROOM.
+    // It is typed (try `lighting.Lights.dim("bright")` — it won't compile) and live.
+    logger.info(`lighting reports ${lighting.Lights.brightness}% — typed, no registration`);
+
+    living_room.Scenes.goodNight();
+    logger.info(`...and down to ${lighting.Lights.brightness}%`);
+  });
+}
+
+const HOME = CreateApplication({
+  name: "home",
+  libraries: [LIVING_ROOM], // only the top library; `lighting` is implied
+  services: { Routine },
+});
+
+declare module "@digital-alchemy/core" {
+  interface LoadedModules {
+    home: typeof HOME;
+  }
+}
+
+await HOME.bootstrap();
+await HOME.teardown();

examples/implies-propagation/home-app/src/proof.mts

@@ -0,0 +1,34 @@
+/**
+ * Type-only regression guard. NOT executed — only type-checked by `tsc`.
+ *
+ * The acceptance criterion this guards: a file that references NOTHING — it
+ * imports neither the implier (LIVING_ROOM) nor the implied member (lighting) —
+ * still sees `lighting` fully typed on `TServiceParams`. The app root
+ * (main.mts) lists only LIVING_ROOM; the `implies`/`depends` augmentation is
+ * program-global, so every file in the app gets the implied member's types with
+ * zero registration and zero references. No import here is deliberate — adding
+ * one to "make the types appear" would be proving a weaker thing than the AC.
+ *
+ * If the propagation regresses, this fails two ways:
+ *   1. `lighting` disappears from `TServiceParams` -> the destructure below errors.
+ *   2. `lighting` degrades to `any` -> the `@ts-expect-error` directives below
+ *      become UNUSED, which is itself a compile error.
+ */
+import type { TServiceParams } from "@digital-alchemy/core";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function _guard({ lighting }: TServiceParams) {
+  // present AND correctly typed (brightness is a number)
+  const level: number = lighting.Lights.brightness;
+  void level;
+
+  // @ts-expect-error brightness is a number, not a string — only catchable if genuinely typed
+  const wrong: string = lighting.Lights.brightness;
+  void wrong;
+
+  // @ts-expect-error dim() takes a number, not a string — only catchable if genuinely typed
+  lighting.Lights.dim("bright");
+
+  // @ts-expect-error there is no `flicker` method — only catchable if genuinely typed
+  lighting.Lights.flicker();
+}

examples/implies-propagation/home-app/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "es2022",
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}