@checkstack/backend 0.10.4 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # @checkstack/backend
 
+## 0.12.0
+
+### Minor Changes
+
+- 270ef29: Fix automation provider actions and `secretEnv` script actions throwing in production.
+
+  The automation dispatch engine resolved provider-action dependencies (the integration connection store, the secret resolver) through a `getService` that was a throwing stub, so Jira / Teams / Webex actions and `secretEnv` script actions threw at execute time in production. The whole dispatch test suite stubbed `getService`, so the break was invisible.
+
+  Root cause: the plugin `env` exposed `registerService` but no resolver, so the dispatch path (the only context that resolves arbitrary cross-plugin refs outside an RPC handler) had nothing real to call.
+
+  Changes:
+
+  - `@checkstack/backend-api`: add `getService<S>(ref: ServiceRef<S>): Promise<S>` to the plugin `env` (`BackendPluginRegistry`). It resolves a service registered by any plugin through the real `ServiceRegistry` using the calling plugin's identity, and throws a clear error if the ref is not registered (never silently `undefined`). **NEW PLUGIN-AUTHOR CONTRACT**: `env.getService` is now available to resolve arbitrary cross-plugin service refs at init / afterPluginsReady time.
+  - `@checkstack/backend`: implement `env.getService` in both the plugin loader and the runtime single-plugin registration path, backed by `ServiceRegistry.get(ref, { pluginId })`.
+  - `@checkstack/automation-backend`: wire the dispatch `getService` to `env.getService` (was a throwing stub). This also activates run-wide provider-credential masking, because resolving the connection store / secret resolver now flows through the run's masking interceptor.
+
+  Also fixes a test-only seam where the `core/backend` test preload registered a no-op `registerRouter`, silently disabling oRPC router registration across the suite.
+
+### Patch Changes
+
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+  - @checkstack/backend-api@0.19.0
+  - @checkstack/cache-api@0.3.7
+  - @checkstack/queue-api@0.3.7
+  - @checkstack/signal-backend@0.2.11
+
+## 0.11.0
+
+### Minor Changes
+
+- 6d52276: feat(automation): expose `trigger.actor` so automations can filter on who/what caused an event
+
+  Every platform event now carries an **actor** - the user, application (API
+  client), service (backend-to-backend), or `system` (background /
+  unauthenticated) that caused it - and the automation engine surfaces it to
+  automations as `trigger.actor`. This lets a trigger filter gate on the
+  origin of the event it reacts to:
+
+  ```text
+  {{ trigger.actor.type == "system" }}      # auto-created by the platform
+  {{ trigger.actor.type == "user" }}         # a human
+  {{ trigger.actor.id == "app-deploybot" }}  # a specific application
+  ```
+
+  `trigger.actor` is available on **every** trigger - it is injected by the
+  platform, not declared per trigger - and editor autocomplete + Run Script
+  context types include `trigger.actor.{type,id,name}`.
+
+  How it works:
+
+  - **`@checkstack/common`** adds the canonical `Actor` type / `ActorSchema`
+    and `SYSTEM_ACTOR`.
+  - **`@checkstack/backend-api`** adds `resolveActor(user)` and a
+    `HookEventMeta` envelope. The hook listener / `onHook` signature gains an
+    optional second `meta` argument (additive, backward compatible).
+  - **`@checkstack/backend`** wraps emitted hooks in an envelope so the actor
+    travels with the payload through the distributed queue, unwrapping it
+    before delivery. The RPC emit path captures the authenticated caller;
+    background emits default to the system actor. Raw/legacy queue data is
+    treated as a system-actor payload, so delivery stays backward compatible.
+  - **`@checkstack/automation-backend`** threads the actor into the dispatch
+    scope (`trigger.actor`), available to trigger filters, top-level
+    conditions, and all run templates, and persisted in the run's scope
+    snapshot. Manual runs are attributed to the invoking user.
+  - **`@checkstack/automation-common`** / **`@checkstack/automation-frontend`**
+    expose `trigger.actor` in the editor variable scope and the generated
+    Run Script `context.trigger.actor` types.
+
+  No database migration and no per-trigger schema changes: the actor rides as
+  event-envelope metadata and in the run scope snapshot.
+
+### Patch Changes
+
+- Updated dependencies [6d52276]
+- Updated dependencies [35bc682]
+  - @checkstack/common@0.12.0
+  - @checkstack/backend-api@0.18.0
+  - @checkstack/api-docs-common@0.1.15
+  - @checkstack/auth-common@0.7.2
+  - @checkstack/pluginmanager-common@0.2.4
+  - @checkstack/signal-backend@0.2.10
+  - @checkstack/signal-common@0.2.5
+  - @checkstack/cache-api@0.3.6
+  - @checkstack/queue-api@0.3.6
+
 ## 0.10.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend",
-  "version": "0.10.4",
+  "version": "0.12.0",
   "license": "Elastic-2.0",
   "checkstack": {
     "type": "backend"
@@ -14,16 +14,16 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/api-docs-common": "0.1.14",
-    "@checkstack/auth-common": "0.7.1",
-    "@checkstack/backend-api": "0.17.0",
-    "@checkstack/common": "0.11.0",
+    "@checkstack/api-docs-common": "0.1.15",
+    "@checkstack/auth-common": "0.7.2",
+    "@checkstack/backend-api": "0.18.0",
+    "@checkstack/common": "0.12.0",
     "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/cache-api": "0.3.4",
-    "@checkstack/queue-api": "0.3.4",
-    "@checkstack/signal-backend": "0.2.8",
-    "@checkstack/signal-common": "0.2.4",
-    "@checkstack/pluginmanager-common": "0.2.3",
+    "@checkstack/cache-api": "0.3.6",
+    "@checkstack/queue-api": "0.3.6",
+    "@checkstack/signal-backend": "0.2.10",
+    "@checkstack/signal-common": "0.2.5",
+    "@checkstack/pluginmanager-common": "0.2.4",
     "@hono/zod-validator": "^0.7.6",
     "@orpc/client": "^1.13.14",
     "@orpc/contract": "^1.13.14",
@@ -45,8 +45,8 @@
     "@types/bun": "latest",
     "@types/semver": "^7.5.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.3",
-    "@checkstack/test-utils-backend": "0.1.29",
+    "@checkstack/scripts": "0.3.4",
+    "@checkstack/test-utils-backend": "0.1.31",
     "drizzle-kit": "^0.31.10"
   }
 }

package/src/plugin-manager/api-router.ts

@@ -10,6 +10,7 @@ import {
   Fetch,
   HealthCheckRegistry,
   CollectorRegistry,
+  resolveActor,
   type EmitHookFn,
   type Hook,
 } from "@checkstack/backend-api";
@@ -126,7 +127,12 @@ async function resolveRequestContext({
   const user = await (auth as AuthService).authenticate(c.req.raw);
 
   const emitHook: EmitHookFn = async <T>(hook: Hook<T>, payload: T) => {
-    await (eventBus as EventBus).emit(hook, payload);
+    // Capture the authenticated caller as the event actor so automations can
+    // filter on who/what caused the event (falls back to the system actor for
+    // unauthenticated callers).
+    await (eventBus as EventBus).emit(hook, payload, {
+      actor: resolveActor(user),
+    });
   };
 
   const pluginMetadata: PluginMetadata | undefined =

package/src/plugin-manager/core-services.ts

@@ -9,6 +9,7 @@ import {
   RpcClient,
   EventBus as IEventBus,
   AuthenticationStrategy,
+  createAdvisoryLockService,
 } from "@checkstack/backend-api";
 import { AuthApi } from "@checkstack/auth-common";
 import type { ServiceRegistry } from "../services/service-registry";
@@ -97,6 +98,16 @@ export function registerCoreServices({
     return createScopedDb(db, assignedSchema);
   });
 
+  // 1b. Advisory Lock Factory (server-global, backed by the shared admin
+  // pool). Session locks need connection affinity, so the service checks
+  // out a dedicated client per acquired lock and releases on the SAME
+  // client — the scoped per-query DB proxy can't provide that.
+  const advisoryLockService = createAdvisoryLockService(adminPool);
+  registry.registerFactory(
+    coreServices.advisoryLock,
+    () => advisoryLockService,
+  );
+
   // 2. Logger Factory
   registry.registerFactory(coreServices.logger, (metadata) => {
     return rootLogger.child({ plugin: metadata.pluginId });

package/src/plugin-manager/plugin-loader.getservice.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect } from "bun:test";
+import {
+  createServiceRef,
+  createBackendPlugin,
+  type BackendPluginRegistry,
+  type ServiceRef,
+} from "@checkstack/backend-api";
+import type { AccessRule, PluginMetadata } from "@checkstack/common";
+import { ServiceRegistry } from "../services/service-registry";
+import { createExtensionPointManager } from "./extension-points";
+import { registerPlugin, type PluginLoaderDeps } from "./plugin-loader";
+import type { PendingInit } from "./types";
+import type { AnyContractRouter } from "@orpc/contract";
+
+/**
+ * Framework-level coverage for the plugin `env.getService`, the registry-backed
+ * resolver added so the automation dispatch path can resolve arbitrary
+ * cross-plugin refs (connection store, secret resolver) at execute time.
+ *
+ * Prior to this, `env` exposed `registerService` but NO resolver, so the
+ * dispatch engine stubbed `getService` with a throwing placeholder and every
+ * provider action threw in production. These tests assert `env.getService`
+ * resolves through the REAL `ServiceRegistry` and fails loudly on a missing
+ * ref (never silently `undefined`).
+ */
+
+function makeDeps(registry: ServiceRegistry): PluginLoaderDeps {
+  return {
+    registry,
+    pluginRpcRouters: new Map<string, unknown>(),
+    pluginHttpHandlers: new Map<string, (req: Request) => Promise<Response>>(),
+    extensionPointManager: createExtensionPointManager(),
+    registeredAccessRules: [] as (AccessRule & { pluginId: string })[],
+    getAllAccessRules: () => [],
+    db: {} as PluginLoaderDeps["db"],
+    pluginMetadataRegistry: new Map<string, PluginMetadata>(),
+    cleanupHandlers: new Map<string, Array<() => Promise<void>>>(),
+    pluginContractRegistry: new Map<string, AnyContractRouter>(),
+  };
+}
+
+/**
+ * Register a no-op plugin whose `register` callback captures the `env` so the
+ * test can call `env.getService` the same way a plugin would at init time.
+ */
+function captureEnv(deps: PluginLoaderDeps): BackendPluginRegistry {
+  let captured: BackendPluginRegistry | undefined;
+  const plugin = createBackendPlugin({
+    metadata: { pluginId: "consumer-plugin" },
+    register: (env) => {
+      captured = env;
+    },
+  });
+  const pendingInits: PendingInit[] = [];
+  registerPlugin({
+    backendPlugin: plugin,
+    pluginPath: "/virtual/consumer-plugin",
+    pendingInits,
+    providedBy: new Map<string, string>(),
+    deps,
+  });
+  if (!captured) throw new Error("env was not captured");
+  return captured;
+}
+
+describe("plugin env.getService", () => {
+  it("resolves a service registered by another plugin through the real ServiceRegistry", async () => {
+    const registry = new ServiceRegistry();
+    const ref = createServiceRef<{ ping: () => string }>("other.service");
+    const impl = { ping: () => "pong" };
+    registry.register(ref, impl);
+
+    const env = captureEnv(makeDeps(registry));
+    const resolved = await env.getService(ref);
+
+    expect(resolved).toBe(impl);
+    expect(resolved.ping()).toBe("pong");
+  });
+
+  it("resolves a service the SAME plugin registered via env.registerService", async () => {
+    const registry = new ServiceRegistry();
+    const env = captureEnv(makeDeps(registry));
+    const ref = createServiceRef<{ n: number }>("self.service");
+
+    env.registerService(ref, { n: 42 });
+    const resolved = await env.getService(ref);
+
+    expect(resolved.n).toBe(42);
+  });
+
+  it("throws a clear error (never undefined) when the ref is not registered", async () => {
+    const registry = new ServiceRegistry();
+    const env = captureEnv(makeDeps(registry));
+    const missing: ServiceRef<{ x: number }> =
+      createServiceRef<{ x: number }>("missing.service");
+
+    let error: unknown;
+    try {
+      await env.getService(missing);
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain("missing.service");
+    // Consumer identity is THIS plugin (audit / scoped factories).
+    expect((error as Error).message).toContain("consumer-plugin");
+  });
+});

package/src/plugin-manager/plugin-loader.ts

@@ -149,6 +149,14 @@ export function registerPlugin({
       providedBy.set(ref.id, pluginId);
       rootLogger.debug(`   -> Registered service '${ref.id}'`);
     },
+    // Registry-backed resolver for arbitrary cross-plugin refs. The
+    // consumer identity is THIS plugin (`pluginId`), which is the correct
+    // audit identity for scoped factories. `registry.get` throws a clear
+    // error when the ref is unregistered, so a missing service (e.g. a
+    // connection store the automation dispatch path needs) fails loudly
+    // rather than silently resolving `undefined`.
+    getService: <T>(ref: ServiceRef<T>): Promise<T> =>
+      deps.registry.get(ref, { pluginId }),
     registerExtensionPoint: (ref, impl) => {
       deps.extensionPointManager.registerExtensionPoint(ref, impl);
     },

package/src/plugin-manager.ts

@@ -634,6 +634,12 @@ export class PluginManager {
         registerService: (ref, impl) => {
           this.registry.register(ref, impl);
         },
+        // Registry-backed resolver for arbitrary cross-plugin refs, using
+        // this plugin's identity as the consumer. Mirrors the plugin-loader
+        // `env.getService`; resolves through the real ServiceRegistry and
+        // throws clearly on a missing ref (never silently undefined).
+        getService: <T>(ref: ServiceRef<T>) =>
+          this.registry.get(ref, backendPlugin.metadata),
         registerExtensionPoint: (ref, impl) => {
           this.extensionPointManager.registerExtensionPoint(ref, impl);
         },

package/src/rpc-rest-compat.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, mock, beforeEach } from "bun:test";
 import { PluginManager } from "./plugin-manager";
-import { coreServices, os, RpcContext } from "@checkstack/backend-api";
+import { coreServices, os, createBackendPlugin } from "@checkstack/backend-api";
 import { Hono } from "hono";
 import { createMockDbModule } from "@checkstack/test-utils-backend";
 import { createMockLoggerModule } from "@checkstack/test-utils-backend";
@@ -10,7 +10,27 @@ mock.module("./db", () => createMockDbModule());
 
 mock.module("./logger", () => createMockLoggerModule());
 
-describe("RPC REST Compatibility", () => {
+/**
+ * Guards the oRPC router REGISTRATION + MOUNTING wiring contract.
+ *
+ * Background (silent-failure seam): the core/backend test preload used to
+ * register a mock `rpc` service whose `registerRouter` was a no-op, so across
+ * the ENTIRE suite a plugin's router never landed in the shared maps the
+ * `/api/:pluginId/*` dispatcher reads. The one "reachability" test that
+ * existed only asserted on a 200 inside an `if`, so it passed forever on a
+ * 404. These tests assert the concrete wiring that was silently broken:
+ *
+ *   1. Resolving `coreServices.rpc` for a plugin and calling `registerRouter`
+ *      lands the router AND its contract in the shared maps, keyed by the
+ *      resolving plugin id (consumed by `createApiRouteHandler`).
+ *   2. `loadPlugins` mounts the `/api/:pluginId/*` route on the Hono app, so
+ *      requests to a registered plugin reach the handler (no Hono-level 404).
+ *
+ * Note: exercising oRPC's RPC wire protocol end-to-end requires the plugin's
+ * real contract + protocol encoding; that is out of scope here. These guards
+ * cover the registration/mounting seam — the exact thing the no-op mock hid.
+ */
+describe("oRPC router registration + mounting wiring", () => {
   let pluginManager: PluginManager;
   let app: Hono;
 
@@ -19,69 +39,58 @@ describe("RPC REST Compatibility", () => {
     app = new Hono();
   });
 
-  it("should handle GET /api/auth/accessRules via oRPC router", async () => {
-    // 1. Setup a mock auth router
+  it("registers a plugin router + contract into the shared maps the API handler reads", async () => {
     const authRouter = os.router({
-      accessRules: os.handler(async () => {
-        return { accessRules: ["test-perm"] };
-      }),
+      accessRules: os.handler(async () => ({ accessRules: ["test-perm"] })),
     });
+    const contract = { accessRules: {} };
 
-    // 2. Register it in plugin manager (now using new pattern - router AND contract required)
-    // Note: In real usage, the path is derived from pluginId. For test, we manually set it.
-    const rpcService = await pluginManager.getService(coreServices.rpc);
-    // The new API auto-prefixes based on pluginId, but for test we need to manually set the map key
-    // Since we're testing the router handler directly, we use the derived name "auth"
-    // Second argument is the contract (for OpenAPI generation) - using a mock object for test
-    rpcService?.registerRouter(authRouter, { accessRules: {} });
+    // Resolve the rpc service scoped to the `auth` plugin and register the
+    // router — exactly how a plugin does it during init().
+    const rpcService = await pluginManager
+      .getRegistry()
+      .get(coreServices.rpc, { pluginId: "auth" });
+    rpcService.registerRouter(authRouter, contract);
 
-    // 3. Mock the auth service to skip real authentication
-    const mockAuth: any = {
-      authenticate: mock(async () => ({ id: "user-1", accessRules: ["*"] })),
-    };
-    pluginManager.registerService(coreServices.auth, mockAuth);
-
-    // Register other dummy services needed for context
-    pluginManager.registerService(coreServices.logger, {
-      info: mock(),
-      debug: mock(),
-      error: mock(),
-      warn: mock(),
-    } as any);
-    pluginManager.registerService(coreServices.database, {} as any);
-    pluginManager.registerService(coreServices.fetch, {} as any);
-    pluginManager.registerService(coreServices.healthCheckRegistry, {} as any);
-    pluginManager.registerService(coreServices.queuePluginRegistry, {
-      getPlugins: () => [],
-    } as any);
-    pluginManager.registerService(coreServices.queueManager, {
-      getActivePlugin: () => "none",
-      getQueue: () => ({}),
-    } as any);
-    pluginManager.registerService(coreServices.cachePluginRegistry, {
-      getPlugins: () => [],
-    } as any);
-    pluginManager.registerService(coreServices.cacheManager, {
-      getActivePlugin: () => "memory",
-      getProvider: () => ({}),
-    } as any);
+    // The contract MUST land in the shared registry the API route handler
+    // (and OpenAPI generation) consumes, keyed by the plugin id —
+    // `registerRouter` sets the router map and the contract map together. A
+    // no-op `registerRouter` (the prior regression) would leave this empty.
+    expect(pluginManager.getAllContracts().get("auth")).toBe(contract);
+  });
 
-    // 4. Mount the plugins
-    await pluginManager.loadPlugins(app);
+  it("mounts the /api/:pluginId/* route so a registered plugin reaches the handler (not a Hono 404)", async () => {
+    const authRouter = os.router({
+      accessRules: os.handler(async () => ({ accessRules: ["test-perm"] })),
+    });
+    const rpcService = await pluginManager
+      .getRegistry()
+      .get(coreServices.rpc, { pluginId: "auth" });
+    rpcService.registerRouter(authRouter, { accessRules: {} });
+    pluginManager.registerCorePluginMetadata({ pluginId: "auth" });
 
-    // 5. Simulate the request that frontend makes (now /api/auth instead of /api/auth-backend)
-    const res = await app.request("/api/auth/accessRules", {
-      method: "GET",
+    // At least one (manual) plugin is required for loadPlugins to proceed
+    // past its "no plugins" early-return and actually mount the
+    // `/api/:pluginId/*` route.
+    const noopPlugin = createBackendPlugin({
+      metadata: { pluginId: "noop" },
+      register: () => {},
     });
+    await pluginManager.loadPlugins(app, [noopPlugin], { skipDiscovery: true });
 
-    // If it's a 404, my theory about dots vs slashes or GET vs POST is correct
-    console.log("Response status:", res.status);
-    if (res.status === 200) {
-      const body = await res.json();
-      console.log("Response body:", JSON.stringify(body));
-      expect(body.accessRules).toContain("test-perm");
-    } else {
-      console.log("Response text:", await res.text());
-    }
+    // A request to `/api/:pluginId/*` must REACH the assembled API handler
+    // (the dispatcher), not fall through to a Hono 404. The dispatcher
+    // resolves the RpcContext first and, in this minimal harness, returns a
+    // handler-level 500 ("Core services not initialized") — which is exactly
+    // the proof we want: the route is mounted and the request reached the
+    // handler. (A regression that fails to mount the route would surface as
+    // a Hono 404 here instead.)
+    const reached = await app.request("/api/auth/accessRules", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: "{}",
+    });
+    expect(reached.status).not.toBe(404);
+    expect(reached.status).toBe(500);
   });
 });

package/src/services/event-bus.test.ts

@@ -3,6 +3,7 @@ import { EventBus } from "./event-bus";
 import type { QueueManager } from "@checkstack/queue-api";
 import type { Logger, Hook } from "@checkstack/backend-api";
 import { createHook } from "@checkstack/backend-api";
+import { SYSTEM_ACTOR } from "@checkstack/common";
 import {
   createMockLogger,
   createMockQueueManager,
@@ -272,6 +273,63 @@ describe("EventBus", () => {
     });
   });
 
+  describe("Actor metadata", () => {
+    it("delivers the system actor by default when no meta is provided", async () => {
+      const testHook = createHook<{ value: number }>("test.actor.hook");
+      let receivedActor: unknown;
+
+      await eventBus.subscribe("plugin-1", testHook, async (_payload, meta) => {
+        receivedActor = meta?.actor;
+      });
+
+      await eventBus.emit(testHook, { value: 1 });
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      expect(receivedActor).toEqual(SYSTEM_ACTOR);
+    });
+
+    it("delivers the provided actor alongside the payload", async () => {
+      const testHook = createHook<{ value: number }>("test.actor.hook");
+      let received: { value: number } | undefined;
+      let receivedActor: unknown;
+
+      await eventBus.subscribe("plugin-1", testHook, async (payload, meta) => {
+        received = payload;
+        receivedActor = meta?.actor;
+      });
+
+      const actor = { type: "user", id: "user-1", name: "Nico" } as const;
+      await eventBus.emit(testHook, { value: 7 }, { actor });
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      expect(received).toEqual({ value: 7 });
+      expect(receivedActor).toEqual(actor);
+    });
+
+    it("delivers actor meta on instance-local emit", async () => {
+      const testHook = createHook<{ value: number }>("test.actor.local");
+      let receivedActor: unknown;
+
+      await eventBus.subscribe(
+        "plugin-1",
+        testHook,
+        async (_payload, meta) => {
+          receivedActor = meta?.actor;
+        },
+        { mode: "instance-local" },
+      );
+
+      const actor = {
+        type: "application",
+        id: "app-deploybot",
+        name: "Deploy Bot",
+      } as const;
+      await eventBus.emitLocal(testHook, { value: 1 }, { actor });
+
+      expect(receivedActor).toEqual(actor);
+    });
+  });
+
   describe("Shutdown", () => {
     it("should stop all queue channels", async () => {
       const hook1 = createHook<{ test: string }>("hook1");

package/src/services/event-bus.ts

@@ -1,13 +1,55 @@
 import type { Queue, QueueManager } from "@checkstack/queue-api";
 import type {
   Hook,
+  HookEventMeta,
   HookSubscribeOptions,
   HookUnsubscribe,
   Logger,
 } from "@checkstack/backend-api";
 import type { EventBus as IEventBus } from "@checkstack/backend-api";
+import { SYSTEM_ACTOR } from "@checkstack/common";
 
-export type HookListener<T> = (payload: T) => Promise<void>;
+export type HookListener<T> = (
+  payload: T,
+  meta?: HookEventMeta,
+) => Promise<void>;
+
+/**
+ * Internal queue envelope. Hooks are enqueued wrapped so event metadata (the
+ * acting `actor`) rides alongside the typed payload through the distributed
+ * queue. `invokeListener` unwraps it before calling listeners, so subscribers
+ * still receive the payload as their first argument (plus optional `meta`).
+ */
+const HOOK_ENVELOPE_MARKER = "__checkstackHookEnvelope" as const;
+
+interface HookEnvelope<T> {
+  [HOOK_ENVELOPE_MARKER]: 1;
+  payload: T;
+  meta: HookEventMeta;
+}
+
+function isHookEnvelope(data: unknown): data is HookEnvelope<unknown> {
+  return (
+    typeof data === "object" &&
+    data !== null &&
+    (data as Record<string, unknown>)[HOOK_ENVELOPE_MARKER] === 1
+  );
+}
+
+/**
+ * Unwrap queued hook data into `{ payload, meta }`. Data emitted before the
+ * envelope existed (or enqueued by other producers) is treated as a raw
+ * payload with the system actor, so delivery stays backward compatible.
+ */
+function unwrapHookData(data: unknown): {
+  payload: unknown;
+  meta: HookEventMeta;
+} {
+  if (isHookEnvelope(data)) {
+    return { payload: data.payload, meta: data.meta };
+  }
+  return { payload: data, meta: { actor: SYSTEM_ACTOR } };
+}
 
 interface ListenerRegistration {
   id: string;
@@ -201,7 +243,11 @@ export class EventBus implements IEventBus {
    * need cross-process delivery must therefore ensure at least one
    * listener registers on every replica that should receive the hook.
    */
-  async emit<T>(hook: Hook<T>, payload: T): Promise<void> {
+  async emit<T>(
+    hook: Hook<T>,
+    payload: T,
+    meta?: HookEventMeta,
+  ): Promise<void> {
     const hasDistributedListeners =
       (this.listeners.get(hook.id)?.length ?? 0) > 0;
     const hasLocalListeners =
@@ -218,11 +264,18 @@ export class EventBus implements IEventBus {
 
     // Create channel lazily if not exists
     if (!channel) {
-      channel = this.queueManager.getQueue<T>(hook.id);
+      channel = this.queueManager.getQueue<unknown>(hook.id);
       this.queueChannels.set(hook.id, channel);
     }
 
-    await channel.enqueue(payload);
+    // Enqueue the payload wrapped in an envelope so the acting actor (defaulting
+    // to the system actor for background/unauthenticated emits) travels with it.
+    const envelope: HookEnvelope<T> = {
+      [HOOK_ENVELOPE_MARKER]: 1,
+      payload,
+      meta: meta ?? { actor: SYSTEM_ACTOR },
+    };
+    await channel.enqueue(envelope);
     this.logger.debug(`Emitted hook: ${hook.id}`);
   }
 
@@ -231,7 +284,11 @@ export class EventBus implements IEventBus {
    * Use this for instance-local hooks like pluginDeregistering.
    * Uses Promise.allSettled to ensure one listener error doesn't block others.
    */
-  async emitLocal<T>(hook: Hook<T>, payload: T): Promise<void> {
+  async emitLocal<T>(
+    hook: Hook<T>,
+    payload: T,
+    meta?: HookEventMeta,
+  ): Promise<void> {
     const registrations = this.localListeners.get(hook.id) || [];
 
     if (registrations.length === 0) {
@@ -239,10 +296,13 @@ export class EventBus implements IEventBus {
       return;
     }
 
+    // Local hooks bypass the queue, so deliver `meta` straight to listeners
+    // (defaulting to the system actor when none was provided).
+    const resolvedMeta: HookEventMeta = meta ?? { actor: SYSTEM_ACTOR };
     const results = await Promise.allSettled(
       registrations.map(async (reg) => {
         try {
-          await reg.listener(payload);
+          await reg.listener(payload, resolvedMeta);
           this.logger.debug(
             `Local listener ${reg.id} (${reg.pluginId}) processed successfully`
           );
@@ -315,10 +375,11 @@ export class EventBus implements IEventBus {
    */
   private async invokeListener(
     registration: ListenerRegistration,
-    payload: unknown
+    data: unknown
   ): Promise<void> {
+    const { payload, meta } = unwrapHookData(data);
     try {
-      await registration.listener(payload);
+      await registration.listener(payload, meta);
       this.logger.debug(
         `Listener ${registration.id} (${registration.consumerGroup}) processed successfully`
       );

package/src/test-preload.ts

@@ -43,11 +43,18 @@ mock.module(loggerPath, () => createMockLoggerModule());
 mock.module(coreServicesPath, () => ({
   registerCoreServices: ({
     registry,
+    pluginRpcRouters,
+    pluginContractRegistry,
   }: {
     registry: {
-      registerFactory: (ref: { id: string }, factory: unknown) => void;
+      registerFactory: (
+        ref: { id: string },
+        factory: (metadata: { pluginId: string }) => unknown,
+      ) => void;
       register: (ref: { id: string }, impl: unknown) => void;
     };
+    pluginRpcRouters?: Map<string, unknown>;
+    pluginContractRegistry?: Map<string, unknown>;
   }) => {
     // Register mock database factory - includes dialect.migrate for migration tests
     registry.registerFactory(coreServices.database, () => ({
@@ -101,9 +108,20 @@ mock.module(coreServicesPath, () => ({
       getAllStrategies: () => [...strategies.values()],
     }));
 
-    // Register mock RPC service factory
-    registry.registerFactory(coreServices.rpc, () => ({
-      registerRouter: () => {},
+    // Register mock RPC service factory.
+    //
+    // This MUST mirror the production factory's router wiring: it keys the
+    // router + contract by the resolving plugin's id into the SAME shared
+    // maps the API route handler reads. A previous version stubbed
+    // `registerRouter` as a no-op, which silently disabled router
+    // registration across the entire core/backend test suite — making oRPC
+    // router reachability impossible to verify (a 404 looked identical to a
+    // wired route to any test that didn't assert hard).
+    registry.registerFactory(coreServices.rpc, (metadata) => ({
+      registerRouter: (router: unknown, contract: unknown): void => {
+        pluginRpcRouters?.set(metadata.pluginId, router);
+        pluginContractRegistry?.set(metadata.pluginId, contract);
+      },
       registerHttpHandler: () => {},
     }));