every-plugin 2.10.1 → 3.0.0-rc.0

package/skills/plugin-development/SKILL.md

@@ -2,7 +2,7 @@
 name: plugin-development
 description: Build every-plugin modules with oRPC contracts, Effect services, and Module Federation. Use when creating or modifying plugins under plugins/ or the _template scaffold.
 metadata:
-  sources: "src/plugin.ts,src/orpc.ts,src/errors.ts,src/zod.ts,src/types.ts"
+  sources: "src/plugin.ts,src/errors.ts,src/types.ts,src/runtime/errors.ts,src/runtime/services/module-federation.service.ts,src/runtime/index.ts,plugins/_template/src/index.ts"
 ---
 
 # every-plugin Development
@@ -24,13 +24,13 @@ plugins/your-plugin/
 └── tsconfig.json
 ```
 
-## Step 1: Define the Contract
+Import `zod`, `effect`, and `@orpc/*` directly — the `every-plugin/zod`, `every-plugin/orpc`, and `every-plugin/effect` facade barrels no longer exist. The build pins zod via the workspace catalog, so version skew between plugin and framework is not a concern.
 
-Import from `every-plugin` subpath exports — not from `@orpc/*` or `zod` directly:
+## Step 1: Define the Contract
 
 ```typescript
-import { eventIterator, oc } from "every-plugin/orpc";
-import { z } from "every-plugin/zod";
+import { eventIterator, oc } from "@orpc/contract";
+import { z } from "zod";
 
 const Errors = {
   UNAUTHORIZED: { status: 401, message: "Auth required" },
@@ -58,17 +58,17 @@ export type ContractType = typeof contract;
 ```
 
 Key points:
-- Always import `oc` from `every-plugin/orpc`, `z` from `every-plugin/zod`, `Effect` from `every-plugin/effect`
+- Import `oc`/`eventIterator` from `@orpc/contract`, `z` from `zod`, `Effect`/`Layer`/`Context` from `effect`
 - Use `eventIterator(schema)` for streaming responses
 - Define error objects with `status` + `message` and pass via `.errors()`
-- Use `CommonPluginErrors` from `every-plugin/errors` for standard UNAUTHORIZED/FORBIDDEN/NOT_FOUND/BAD_REQUEST
+- Use `PluginErrors` from `every-plugin/errors` for standard UNAUTHORIZED/FORBIDDEN/NOT_FOUND/BAD_REQUEST
 
 ## Step 2: Create the Service
 
 Plain TypeScript class with Effect error handling:
 
 ```typescript
-import { Effect } from "every-plugin/effect";
+import { Effect } from "effect";
 
 export class MyService {
   constructor(private baseUrl: string, private apiKey: string) {}
@@ -93,10 +93,10 @@ export class MyService {
 ## Step 3: Wire with createPlugin
 
 ```typescript
+import { ORPCError } from "@orpc/server";
+import { Effect, Layer } from "effect";
 import { createPlugin } from "every-plugin";
-import { Effect } from "every-plugin/effect";
-import { ORPCError } from "every-plugin/orpc";
-import { z } from "every-plugin/zod";
+import { z } from "zod";
 import { contract } from "./contract";
 import { MyService } from "./service";
 
@@ -109,35 +109,37 @@ export default createPlugin({
   }),
   contract,
 
-  initialize: (config, _plugins, tools) =>
+  initialize: (config, _plugins) =>
     Effect.gen(function* () {
       const service = new MyService(config.variables.baseUrl, config.secrets.apiKey);
       yield* service.ping();
-      return { service };
-    }),
 
-  shutdown: () => Effect.void,
-
-  createRouter: (deps, builder) => {
-    const { service } = deps;
+      return Layer.succeed(MyServiceTag, service);
+    }),
 
-    const requireAuth = builder.middleware(async ({ context, next }) => {
-      if (!context.userId) throw new ORPCError("UNAUTHORIZED", { message: "Auth required" });
-      return next({ context: { ...context, userId: context.userId } });
-    });
+  createRouter: (builder) => ({
+    getById: builder.getById.effect(function* ({ input, context, errors }) {
+      if (!context.userId) {
+        return yield* Effect.fail(errors.UNAUTHORIZED({ message: "Auth required" }));
+      }
+      const service = yield* MyServiceTag;
+      return yield* service.getById(input.id);
+    }),
 
-    return {
-      getById: builder.getById.use(requireAuth).handler(async ({ input, context }) => {
-        return await Effect.runPromise(service.getById(input.id));
-      }),
-      ping: builder.ping.handler(async () => {
-        return await Effect.runPromise(service.ping());
-      }),
-    };
-  },
+    ping: builder.ping.effect(function* () {
+      const service = yield* MyServiceTag;
+      return yield* service.ping();
+    }),
+  }),
 });
 ```
 
+Key points:
+- `initialize` returns an `Effect` producing a `Layer` — services built in it are provided to `.effect()` handlers via the plugin's lifecycle scope
+- Teardown lives in Layer finalizers — there is no `shutdown` option
+- Handlers access services with `yield* Tag` (Effect-native generators)
+- For streaming handlers (async generators), use `Context.get(context["effect/context"], Tag)`
+
 ## Plugin Composition (withPlugins)
 
 When an API plugin needs to call other plugins in-process:
@@ -148,9 +150,9 @@ import type { PluginsClient } from "./lib/plugins-types.gen";
 export default createPlugin.withPlugins<PluginsClient>()({
   variables: z.object({ demoMessage: z.string().optional() }),
   contract,
-  initialize: (config, plugins, _tools) =>
+  initialize: (config, plugins) =>
     Effect.sync(() => ({ plugins, demoMessage: config.variables.demoMessage ?? "not configured" })),
-  createRouter: (deps, builder) => ({
+  createRouter: (builder) => ({
     pluginDemo: builder.pluginDemo.handler(async () => {
       const status = await deps.plugins.registry().getRegistryStatus();
       return { apiVariable: deps.demoMessage, registryStatus: status };
@@ -165,17 +167,17 @@ export default createPlugin.withPlugins<PluginsClient>()({
 
 ## Long-Lived Scoped Resources
 
-For database pools, caches, publisher channels, or any resource that should live for the plugin's lifetime, use `tools.buildService(tag, layer)` inside `initialize`:
+For database pools, caches, publisher channels, or any resource that should live for the plugin's lifetime, use `buildScoped(tag, layer)` inside `initialize` (or `buildScopedContext(layer)` for multi-service layers):
 
 ```typescript
-import { createPlugin } from "every-plugin";
-import { Effect, Layer } from "every-plugin/effect";
+import { Effect, Layer } from "effect";
+import { buildScoped, createPlugin } from "every-plugin";
 
 export default createPlugin({
   // ...
-  initialize: (config, _plugins, tools) =>
+  initialize: (config, _plugins) =>
     Effect.gen(function* () {
-      const repo = yield* tools.buildService(
+      const repo = yield* buildScoped(
         MyRepoTag,
         MyRepoLive.pipe(Layer.provide(DatabaseLive(config.secrets.MY_DATABASE_URL))),
       );
@@ -188,9 +190,19 @@ export default createPlugin({
 });
 ```
 
-`tools.buildService(tag, layer)` binds the layer's resources to the plugin's lifecycle scope.
+`buildScoped(tag, layer)` builds the layer with the plugin's lifecycle scope and resolves the service from the built context.
 Resources persist until the plugin shuts down and are automatically cleaned up during `runtime.shutdown()`.
 
+For layers that provide several services at once, use `buildScopedContext` and resolve each tag:
+
+```typescript
+const services = yield* buildScopedContext(
+  Layer.mergeAll(TenantsLive, NodesLive).pipe(Layer.provide(database)),
+);
+
+const tenants = Context.get(services, TenantsTag);
+```
+
 **Bad — creates a transient scope that closes immediately:**
 ```typescript
 const svc = yield* Effect.provide(MyTag, MyLive.pipe(Layer.provide(DatabaseLive(url))))
@@ -198,15 +210,14 @@ const svc = yield* Effect.provide(MyTag, MyLive.pipe(Layer.provide(DatabaseLive(
 
 **Good — resources persist for the plugin's lifetime:**
 ```typescript
-const svc = yield* tools.buildService(MyTag, MyLive.pipe(Layer.provide(DatabaseLive(url))))
+const svc = yield* buildScoped(MyTag, MyLive.pipe(Layer.provide(DatabaseLive(url))))
 ```
 
 Key rules:
-- Use `tools.buildService(...)` for any `Layer.scoped(...)` resource that should survive initialization
+- Use `buildScoped(...)` for any `Layer.scoped(...)` resource that should survive initialization
 - Plain class construction (new Service(...)) is still fine directly in `initialize`
-- `createRouter(deps)` receives whatever `initialize` returns — same mental model as before
+- Handlers access services via the injected oRPC context (`yield* Tag` in `.effect()` handlers), not from initialize's return value
 - Do not use `Effect.provide(Tag, Layer.scoped(...))` for persistent dependencies inside `initialize`
-- `tools` is provided by the framework and does not need to be imported
 
 ## Dev Server Config (plugin.dev.ts)
 
@@ -215,7 +226,6 @@ import type { PluginConfigInput } from "every-plugin";
 import Plugin from "./src/index";
 
 export default {
-  pluginId: "my-plugin",
   port: 3010,
   config: {
     variables: {
@@ -228,6 +238,10 @@ export default {
 };
 ```
 
+No `pluginId` field — the dev server derives the plugin id from the workspace
+itself (the `plugins/<key>` layout key and the package.json name); it never
+reads one from this file.
+
 Port assignments: host=3000, api=3001, auth=3002, ui=3003, ui-ssr=3004, plugins=3010+.
 
 ## Build Config (rspack.config.js)
@@ -254,9 +268,27 @@ export default {
 
 ## Common Mistakes
 
-- Importing `oc` from `@orpc/contract` instead of `every-plugin/orpc` — will cause version mismatches in Module Federation
-- Importing `z` from `zod` instead of `every-plugin/zod` — may cause Vitest CJS/ESM interop issues; always use `every-plugin/zod`
+- Importing `z`/`oc`/`Effect` from `every-plugin/zod`, `every-plugin/orpc`, or `every-plugin/effect` — those facade barrels were deleted; import from `zod`, `@orpc/contract`, and `effect` directly
 - Forgetting `.errors(Errors)` on routes that can throw ORPCError — untyped errors
 - Using `Effect.runPromise` inside `Effect.gen` — use `yield*` instead for proper error channel
 - Putting business logic in `createRouter` — keep it in the service class, router is just glue
-- Using `Effect.provide(Tag, Layer.scoped(...))` inside `initialize` for long-lived resources — creates a transient scope that releases the resource immediately after initialization. Use `tools.buildService(Tag, Layer.scoped(...))` instead
+- Using `Effect.provide(Tag, Layer.scoped(...))` inside `initialize` for long-lived resources — creates a transient scope that releases the resource immediately after initialization. Use `buildScoped(Tag, Layer.scoped(...))` instead
+
+## The tasks you will actually be given
+
+**"Add a route to a plugin"** — e.g. a `deleteItem` procedure. Add it to `plugins/<your-plugin>/src/contract.ts` (`.route({ method: "DELETE", path: "/items/{id}" }).input(...).errors(Errors)`), add a method on the service class, then wire it in `src/index.ts` as `deleteItem: builder.deleteItem.effect(function* ({ input, context, errors }) { ... })` — check `context.userId` first and fail with `errors.UNAUTHORIZED(...)` / `errors.NOT_FOUND(...)` inside the generator, mirroring `plugins/_template/src/index.ts` (`getById`, `deleteThing`). Verify with `cd plugins/<your-plugin> && pnpm test`, then `pnpm run typecheck` (regenerates `plugins-types.gen.ts` for cross-plugin consumers).
+
+**"Ship a new plugin"** — copy `plugins/_template/` to `plugins/<key>/`, set `name` in its package.json (this is the registry id tests use), fill in `plugin.dev.ts` (port; plugins start at 3010), and register it in the authored config with `Plugin("<key>").path("plugins/<key>", { ... })` (see `bos.app.ts`). Run `bos types gen` or restart `pnpm run dev`, then deploy with `cd plugins/<key> && bos plugin publish <key>`.
+
+**"A plugin fails to load in the host"** — capture the error words and match them in the table below; shared-identity failures are confirmed with `bos mf check` and fixed by rebuilding/redeploying the one plugin.
+
+## What comes back when it fails
+
+| Error word / shape you see | Meaning | Action |
+|---|---|---|
+| `ModuleFederationError` with "shared identity mismatch" (or the plugin's `mf-manifest.json` reports an older `pluginVersion` than the host) | plugin bundle built against a different `@module-federation/runtime`, or missing a `shared[]` dep the host requires | rebuild + redeploy that one plugin (`cd plugins/<key> && bos plugin publish <key>`); confirm with `bos mf check`. Stop editing code — this is a build/deploy problem |
+| `No valid plugin constructor found for '<id>'` / `missing the required 'binding' property` | the remote module's export was not created by `createPlugin()` | `export default createPlugin({...})` from `src/index.ts`, rebuild |
+| `PluginRuntimeError` with operation `validate-config` or `validate-secrets` and a Zod cause | runtime config violates the plugin's `variables`/`secrets` schemas (secrets hydrate into variables, then re-validate) | fix `plugin.dev.ts` in dev, or the runtime config entry; read the Zod issue paths in the error |
+| `Plugin ID '<id>' not found in registry.` | registry key mismatch | align the key used with the plugins/ directory key and package.json `name` |
+| 401 `UNAUTHORIZED` with data `{ apiKeyProvided: boolean, ... }` | no session or API key reached the handler (see `every-plugin/errors`) | caller-side problem — sign in or send `x-api-key`; do not catch it in the plugin |
+| 503 `SERVICE_UNAVAILABLE` / 502 `CONNECTION_ERROR` shapes from `every-plugin/errors` | upstream dependency of the service failed | surface them via `.errors(...)` on the contract, not ad-hoc ORPCError codes |

package/skills/plugin-testing/SKILL.md

@@ -2,7 +2,7 @@
 name: plugin-testing
 description: Test every-plugin modules with vitest and the plugin runtime. Use when writing or modifying plugin tests under plugins/*/src/__tests__/ or plugins/*/tests/.
 metadata:
-  sources: "src/testing/index.ts,src/runtime/index.ts"
+  sources: "src/index.ts,src/runtime/index.ts,src/runtime/errors.ts,plugins/_template/tests/setup.ts"
 ---
 
 # every-plugin Testing
@@ -23,7 +23,7 @@ Test the service class directly without the plugin runtime:
 
 ```typescript
 import { describe, expect, it } from "vitest";
-import { Effect } from "every-plugin/effect";
+import { Effect } from "effect";
 import { MyService } from "../service";
 
 describe("MyService", () => {
@@ -126,16 +126,27 @@ describe("API with mock registry", () => {
 
 ## Testing Scope Lifecycle
 
-When a plugin uses `tools.buildService(...)` inside `initialize`, verify that scoped resources persist after initialization and are released during shutdown:
+When a plugin uses `buildScoped(...)` inside `initialize`, verify that scoped resources persist after initialization and are released during shutdown:
 
 ```typescript
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { createPlugin, createPluginRuntime } from "every-plugin";
-import { Context, Effect, Layer } from "every-plugin/effect";
+import { Context, Effect, Layer } from "effect";
 
 let released = false;
 
-class TestTag extends Context.Tag("TestTag")<TestTag, { value: string }>() {}
+class TestTag extends Context.Service<TestTag, { value: string }>()("TestTag") {}
+
+const TestLive = Layer.effect(
+  TestTag,
+  Effect.acquireRelease(
+    Effect.sync(() => ({ value: "live" })),
+    () =>
+      Effect.sync(() => {
+        released = true;
+      }),
+  ),
+);
 
 describe("scope lifecycle", () => {
   let runtime: ReturnType<typeof createPluginRuntime>;
@@ -143,12 +154,11 @@ describe("scope lifecycle", () => {
   beforeAll(async () => {
     const plugin = createPlugin({
       // ... variables, secrets, contract ...
-      initialize: (_config, _plugins, tools) =>
-        Effect.gen(function* () {
-          const svc = yield* tools.buildService(TestTag, TestLive);
-          return { svc };
-        }),
-      createRouter: (deps) => ({
+      initialize: () =>
+        Effect.succeed(
+          TestLive,
+        ),
+      createRouter: (builder) => ({
         // ... routes ...
       }),
     });
@@ -212,6 +222,25 @@ export default defineConfig({
 
 - Not calling `runtime.shutdown()` in `afterAll` — leaves plugin scopes/resources running
 - Using `vi.fn()` without `.mockResolvedValue()` — unhandled promise rejections
-- Forgetting `vite-tsconfig-paths` plugin — path aliases like `every-plugin/orpc` won't resolve
+- Forgetting `vite-tsconfig-paths` plugin — package subpath imports like `every-plugin/errors` won't resolve
 - Omitting the `registry` object when calling `createPluginRuntime(...)` — the runtime requires explicit plugin entries
 - Testing only happy paths — always test error channels (Effect failures, ORPCError throws)
+
+## The tasks you will actually be given
+
+**"Add an integration test for a new route"** — in `plugins/<your-plugin>/tests/integration/plugin.test.ts`, follow the `_template` pattern (`plugins/_template/tests/setup.ts`): call `await getPluginClient({ userId: "user123" })` — it boots `createPluginRuntime` with the registry keyed by the package.json `name`, config from `plugin.dev.ts`, and an HTTP server that maps `x-test-user`/`x-test-session` headers to context. Then drive the route through the client and assert the response. Run with `cd plugins/<your-plugin> && pnpm test` (script `vitest run`, `testTimeout: 30000` in `vitest.config.ts`).
+
+**"Prove a service method fails with the right ORPC code"** — follow `plugins/_template/tests/unit/things-service.test.ts`: build a fresh layer with `DatabaseLive('pglite:<mkdtemp dir>')` and `Layer.succeed(PluginIdTag, "<pluginId>")`, run the failing effect through `Effect.runPromiseExit` + `Cause.squash`, then `expect(error).toBeInstanceOf(ORPCError)` and `expect(error.code).toBe("CONFLICT")` (or `NOT_FOUND`). Clean the temp dir in `afterEach`.
+
+**"A test fails at `usePlugin` with a validation error"** — the config comes from `plugin.dev.ts` via `tests/setup.ts` (`TEST_CONFIG`). The runtime validates `variables` and `secrets` against the plugin's zod schemas (`validate-config` / `validate-secrets` → `PluginRuntimeError` with a `zodError` cause). Fix the config in `plugin.dev.ts`, not the test.
+
+## What comes back when it fails
+
+| Error word / shape you see | Meaning | Action |
+|---|---|---|
+| `Plugin ID '<id>' not found in registry.` (`PluginRuntimeError`, operation `validate-plugin-id`) | the `usePlugin` key does not match a registry entry | make the registry key the package.json `name` (as `tests/setup.ts` does), then read again |
+| `PluginRuntimeError` with operation `validate-config` / `validate-secrets` and a Zod cause | `TEST_CONFIG` violates the plugin's schemas | fix `plugin.dev.ts`; do not loosen the schemas to make tests pass |
+| `ModuleFederationError` | only when loading a remote URL — in-process tests (`module: Plugin`) never produce it | if you see it, your registry entry points at a URL instead of the imported module |
+| `Cannot find module` for `every-plugin/...` subpaths | `vite-tsconfig-paths` missing from `vitest.config.ts` plugins | add it (see the Vitest Config section) |
+| Test hangs past 30s | default `testTimeout: 30000`; a streaming handler's `for await` never terminates | pass `signal`/`maxResults` limits like `_template`'s `listenBackground`, or abort the iterator |
+| Scoped resource still alive after tests finish | `runtime.shutdown()` (or `_template`'s `teardown()`) never ran | call it in `afterAll` |

package/src/build/artifact-names.ts

@@ -0,0 +1,117 @@
+import crypto from "node:crypto";
+import { z } from "zod";
+
+/** Dev-mode entry names: the in-memory dev server serves these exact names,
+ * and dev consumers (the host's html shell, the compose client payload, the
+ * readiness probe) append them — dev has no build report to discover hashed
+ * names from. */
+export const DEV_ENTRY_FILENAME = "remoteEntry.js";
+export const DEV_SERVER_ENTRY_FILENAME = "remoteEntry.server.js";
+/** Fixed-name build outputs that get additive immutable hashed copies. */
+export const MF_MANIFEST_FILENAME = "mf-manifest.json";
+export const STYLE_FILENAME = "style.css";
+export const HASHED_ENTRY_PATTERN = "remoteEntry.[contenthash].js";
+export const HASHED_SERVER_ENTRY_PATTERN = "remoteEntry.server.[contenthash].js";
+
+/** The dev-stack signal: everything a dev server spawns (watch or no-watch
+ * one-shot builds) serves the fixed dev entry names, because every dev
+ * consumer appends them and no build report exists to discover hashed names
+ * from. Every other invocation — local builds, host-test production builds,
+ * regression container builds, deploys — is a build and emits content-hashed
+ * entries + build reports. NODE_ENV cannot carry this decision (vitest runs
+ * as "test", bundler CLIs default "production" even for dev watches), and
+ * DEPLOY=true only marks deploy builds — so the dev server stamps its own
+ * children. */
+export function isBuildInvocation(): boolean {
+  return process.env.BOS_DEV_SERVER !== "1";
+}
+
+export function uiEntryFilename(input: { isBuild: boolean; server?: boolean }): string {
+  if (!input.isBuild) return input.server ? DEV_SERVER_ENTRY_FILENAME : DEV_ENTRY_FILENAME;
+  return input.server ? HASHED_SERVER_ENTRY_PATTERN : HASHED_ENTRY_PATTERN;
+}
+
+const HASH_SEGMENT_PATTERN = /\.[a-f0-9]{8,}\./;
+
+/**
+ * Serving classification for bundle objects: anything whose name carries a
+ * content-hash segment (including hashed entrypoints like
+ * `remoteEntry.8f3a….js`) is immutable by construction; fixed-name
+ * entrypoints and non-hashed files a redeploy replaces in place must
+ * revalidate.
+ */
+export function isImmutableBundlePath(name: string): boolean {
+  const base = name.split("/").pop() ?? name;
+  return HASH_SEGMENT_PATTERN.test(base);
+}
+
+export function cacheControlOf(name: string): string {
+  return isImmutableBundlePath(name)
+    ? "public, max-age=31536000, immutable"
+    : "public, max-age=0, must-revalidate";
+}
+
+/** Short content hash used to mint additive hashed copies of fixed-name artifacts. */
+export function contentHashOf(content: string | Uint8Array): string {
+  return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+
+export function hashedArtifactName(base: string, hash: string, ext: string): string {
+  return `${base}.${hash}.${ext.replace(/^\./, "")}`;
+}
+
+/** Find the content-hashed entry asset for a base name ("remoteEntry", "remoteEntry.server"). */
+export function findHashedEntry(assetNames: string[], base: string): string | null {
+  const hashed = assetNames.find((name) => {
+    const rest = name.startsWith(`${base}.`) ? name.slice(base.length + 1) : null;
+    if (rest === null) return false;
+    const hash = rest.slice(0, -3);
+    return name.endsWith(".js") && /^[a-f0-9]{8,}$/.test(hash);
+  });
+  return hashed ?? null;
+}
+
+export const BuildEntryReportSchema = z.object({
+  entry: z.string().min(1),
+  browserManifest: z.string().min(1).optional(),
+  css: z.string().min(1).optional(),
+});
+export type BuildEntryReport = z.infer<typeof BuildEntryReportSchema>;
+
+export interface ArtifactCopy {
+  from: string;
+  to: string;
+}
+
+/**
+ * The additive-copy plan for one compiled dist root: each supplied fixed-name
+ * artifact gets an immutable hashed copy. The hashed entry itself needs no
+ * copy — the build report carries its name to the deploy leg. Returns null
+ * when the build predates hashed entry names (only fixed names emitted).
+ */
+export function planArtifactCopies(input: {
+  assetNames: string[];
+  entryBase: string;
+  contents?: Record<string, string | Uint8Array | undefined>;
+}): { copies: Array<ArtifactCopy>; report: BuildEntryReport } | null {
+  const entry = findHashedEntry(input.assetNames, input.entryBase);
+  if (!entry) return null;
+
+  const copies: Array<ArtifactCopy> = [];
+  const report: BuildEntryReport = { entry };
+
+  const hashedCopy = (fixedName: string, reportField: "browserManifest" | "css") => {
+    const content = input.contents?.[fixedName];
+    if (content === undefined) return;
+    const dot = fixedName.lastIndexOf(".");
+    const base = fixedName.slice(0, dot);
+    const ext = fixedName.slice(dot + 1);
+    const hashed = hashedArtifactName(base, contentHashOf(content), ext);
+    copies.push({ from: fixedName, to: hashed });
+    report[reportField] = hashed;
+  };
+  hashedCopy(MF_MANIFEST_FILENAME, "browserManifest");
+  hashedCopy(STYLE_FILENAME, "css");
+
+  return { copies, report };
+}

package/src/build/contract-types.ts

@@ -0,0 +1,101 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export type ContractTypesStatus = "generated" | "up-to-date" | "skipped";
+
+export const CONTRACT_ENTRY = path.join("src", "contract.ts");
+export const CONTRACT_TYPES_DIR = "types";
+export const CONTRACT_TYPES_FILE = path.join("types", "contract.d.ts");
+
+export function contractTypesUpToDate(cwd: string): boolean {
+  const entry = path.join(cwd, CONTRACT_ENTRY);
+  const outFile = path.join(cwd, CONTRACT_TYPES_FILE);
+  if (!fs.existsSync(entry) || !fs.existsSync(outFile)) return false;
+  return fs.statSync(outFile).mtimeMs >= fs.statSync(entry).mtimeMs;
+}
+
+export function resolveTscBinary(cwd: string): string {
+  for (const from of [
+    path.join(cwd, "package.json"),
+    path.join(import.meta.dirname, "..", "..", "..", "package.json"),
+  ]) {
+    try {
+      const req = createRequire(path.resolve(from));
+      const pkgJsonPath = req.resolve("typescript/package.json");
+      return path.join(path.dirname(pkgJsonPath), "bin", "tsc");
+    } catch {
+      // try the next resolution root
+    }
+  }
+  return "tsc";
+}
+
+/**
+ * Regenerates types/contract.d.ts for a plugin workspace by invoking the
+ * workspace's TypeScript 7 binary with explicit flags — no tsconfig file
+ * involved, so emit layout is deterministic and there is nothing to sync.
+ *
+ * - "skipped": the workspace has no src/contract.ts
+ * - "up-to-date": types/contract.d.ts is newer than src/contract.ts
+ * - "generated": declarations were re-emitted (types/ is cleaned first, so
+ *   stale nested layouts never survive)
+ */
+export async function generateContractTypes(
+  cwd: string = process.cwd(),
+): Promise<ContractTypesStatus> {
+  const entry = path.join(cwd, CONTRACT_ENTRY);
+  if (!fs.existsSync(entry)) {
+    return "skipped";
+  }
+
+  if (contractTypesUpToDate(cwd)) {
+    return "up-to-date";
+  }
+
+  const outDir = path.join(cwd, CONTRACT_TYPES_DIR);
+  fs.rmSync(outDir, { recursive: true, force: true });
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const tsc = resolveTscBinary(cwd);
+  const args = [
+    "--ignoreConfig",
+    "--emitDeclarationOnly",
+    "--declaration",
+    "--rootDir",
+    "src",
+    "--outDir",
+    CONTRACT_TYPES_DIR,
+    "--target",
+    "esnext",
+    "--module",
+    "esnext",
+    "--moduleResolution",
+    "bundler",
+    "--strict",
+    "--skipLibCheck",
+    CONTRACT_ENTRY,
+  ];
+
+  try {
+    await execFileAsync(process.execPath, [tsc, ...args], { cwd });
+  } catch (error) {
+    const err = error as { message?: string; stdout?: string; stderr?: string };
+    const detail = [err.stderr, err.stdout, err.message].filter(Boolean).join("\n").trim();
+    throw new Error(
+      `Contract type generation failed for ${path.basename(cwd)} — tsc exited non-zero:\n${detail}`,
+    );
+  }
+
+  if (!fs.existsSync(path.join(cwd, CONTRACT_TYPES_FILE))) {
+    throw new Error(
+      `Contract type generation produced no output — expected ${path.join(cwd, CONTRACT_TYPES_FILE)}`,
+    );
+  }
+
+  return "generated";
+}

package/src/build/rspack/build-report-plugin.ts

@@ -0,0 +1,34 @@
+import type { Compiler, RspackPluginInstance } from "@rspack/core";
+import { BuildEntryReportSchema, findHashedEntry } from "../artifact-names";
+
+/**
+ * Emits `build-report.json` for the deploy leg: the container entry is hashed
+ * by the build's filename template (`remoteEntry.[contenthash].js`), and the
+ * report names it — in-compilation, so watch-mode cleans can't open a window
+ * where the report 404s (mirrors the `output.clean` rationale on the build
+ * plugin).
+ */
+export class BuildReportPlugin implements RspackPluginInstance {
+  name = "BuildReportPlugin";
+
+  constructor(private entryBase = "remoteEntry") {}
+
+  apply(compiler: Compiler) {
+    compiler.hooks.thisCompilation.tap(this.name, (compilation) => {
+      const webpack = (compiler as Compiler & { webpack?: any }).webpack;
+      const rawSource = webpack?.sources?.RawSource;
+      const stage = webpack?.Compilation?.PROCESS_ASSETS_STAGE_ADDITIONS ?? 1000;
+
+      compilation.hooks.processAssets.tap({ name: this.name, stage }, (assets) => {
+        const entry = findHashedEntry(Object.keys(assets), this.entryBase);
+        if (!entry || !rawSource) return;
+
+        const report = BuildEntryReportSchema.parse({ entry });
+        compilation.emitAsset(
+          "build-report.json",
+          new rawSource(`${JSON.stringify(report, null, 2)}\n`),
+        );
+      });
+    });
+  }
+}

package/src/build/rspack/chunk-completeness-plugin.ts

@@ -0,0 +1,57 @@
+import type { Compiler, RspackPluginInstance } from "@rspack/core";
+import { findHashedEntry } from "../artifact-names";
+
+/**
+ * Fails the build when a container entry's eager chunk references
+ * (`Promise.all([__webpack_require__.e(N), …])` in get factories) point at
+ * chunk files the compilation never emits. Rspack 2.x splitChunks re-ids the
+ * final chunk graph while the federation get-factory codegen can keep
+ * pre-split ids — the emitted entry then 404s its own chunks at load time and
+ * the failure surfaces downstream as `__webpack_modules__[r] is not a
+ * function`. SplitChunks is disabled in the composition for exactly this
+ * reason; this gate catches any regression loudly at build time instead.
+ */
+export class ChunkCompletenessPlugin implements RspackPluginInstance {
+  name = "ChunkCompletenessPlugin";
+
+  constructor(private entryBase = "remoteEntry") {}
+
+  apply(compiler: Compiler) {
+    compiler.hooks.thisCompilation.tap(this.name, (compilation) => {
+      const webpack = (compiler as Compiler & { webpack?: any }).webpack;
+      const stage = webpack?.Compilation?.PROCESS_ASSETS_STAGE_ADDITIONS ?? 1000;
+
+      compilation.hooks.processAssets.tap({ name: this.name, stage }, (assets) => {
+        const names = Object.keys(assets);
+        const entry =
+          findHashedEntry(names, this.entryBase) ?? names.find((n) => n === `${this.entryBase}.js`);
+        if (!entry) return;
+
+        const jsFiles = new Set(names.filter((n) => n.endsWith(".js")));
+        const source = assets[entry].source().toString();
+
+        const special = new Map<string, string>();
+        const u = source.match(/\.u\s*=\s*(\w+)=>([^,;]+)/);
+        if (u) {
+          for (const m of u[2].matchAll(/(\d+)\s*===\s*\w+\s*\?\s*"([^"]+)"/g)) {
+            special.set(m[1], m[2]);
+          }
+        }
+
+        for (const pa of source.matchAll(/Promise\.all\(\[([^\]]*)\]\)/g)) {
+          for (const m of pa[1].matchAll(/(?:__webpack_require__|\w+)\.e\((\d+)\)/g)) {
+            const id = m[1];
+            const file = special.has(id) ? `${special.get(id)}.js` : `${id}.js`;
+            if (!jsFiles.has(file)) {
+              compilation.errors.push(
+                new Error(
+                  `[${this.name}] entry ${entry} eagerly loads chunk ${id} (${file}) but the compilation never emitted it — the built remote would fail at load time with "__webpack_modules__[r] is not a function".`,
+                ),
+              );
+            }
+          }
+        }
+      });
+    });
+  }
+}