@acmekit/acmekit 2.13.86 → 2.13.88

package/dist/templates/app/.claude/agents/code-reviewer.md

@@ -76,8 +76,11 @@ For each match: if the method name has no `_` suffix it's a public method — wr
 ```
 grep -rn "Module(" src/modules/ | grep -v "ModuleProvider\|AcmeKitService"
 grep -rn "static identifier" src/modules/
+grep -rn "this\.container_\[" src/modules/
+grep -rn "container_\." src/modules/ | grep -v "logger\|options\|container_:"
 ```
 Check: any file with `ModuleProvider` that uses `Module()` instead → wrong export format.
+Check: providers resolving other modules from `this.container_` → module-scoped container can't see other modules. Cross-module deps must be passed as method params from the workflow step through the service.
 
 **If hasWorkflows:**
 ```
@@ -93,7 +96,9 @@ grep -rn "res\.json.*result\b" src/api/
 grep -rn "validators\.ts" src/api/
 grep -rn "import.*from.*\/service\"" src/api/
 grep -rn "validatedBody as any" src/api/
+grep -rn "req\.validatedQuery[^?]" src/api/
 ```
+For `req.validatedQuery`: verify every destructuring uses `?? {}` fallback (e.g., `req.validatedQuery ?? {}`). Without it, requests with no query string crash.
 
 **If hasSubscribers:**
 ```
@@ -109,7 +114,12 @@ grep -rn "await.*service\." src/jobs/
 ```
 grep -rn "^export default function " src/admin/
 grep -rn "zone:.*\`\|zone:.*\+" src/admin/
+grep -rn "from [\"']zod[\"']" src/admin/
+grep -rn "<SectionRow.*>" src/admin/ | grep "children\|>" | grep -v "/>"
+grep -rn "react-hook-form\|@hookform" package.json
+grep -rn "useDataTable" src/admin/
 ```
+For each `useDataTable` match with `filtering` config: check that the companion `useQuery` includes filter/search state in `queryKey` AND passes filter params in `queryFn`. A static `queryKey` like `["items"]` with filtering enabled means filters do nothing (server-side filtering, `manualFiltering: true`).
 
 ### Step 5 — Read matched files
 For every file with a hit, read it fully to confirm the issue in context.
@@ -155,6 +165,7 @@ Only work through sections for detected features. Explicitly skip and note secti
 - [ ] `PREFIX` and `IDENTIFIER_KEY` constants defined once in `constants.ts`, never hardcoded inline
 - [ ] `createProvidersLoader` used for modules accepting providers — no hand-rolled provider loops
 - [ ] Service resolves providers via `this.providers.resolve(id)` — NOT `(this as any).__container__`
+- [ ] Providers do NOT resolve other modules from `this.container_` (constructor or property access) — provider containers are module-scoped. Cross-module deps must be received as method parameters, resolved by the workflow step and passed through the parent module's service
 
 ### Workflows — only if hasWorkflows
 - [ ] Steps in `src/workflows/steps/<name>.ts` — one per file, not in workflow files
@@ -180,6 +191,7 @@ Only work through sections for detected features. Explicitly skip and note secti
 - [ ] `defineRouteConfig` with Zod body (`.strict()`) and/or query schemas
 - [ ] No `validators.ts` for new routes
 - [ ] `req.validatedBody`, `req.validatedQuery`, `req.queryConfig` — not `req.remoteQueryConfig`
+- [ ] `req.validatedQuery` destructured with `?? {}` fallback — undefined when request has no query string
 - [ ] Every method that uses `req.queryConfig` has BOTH `query` and `queryConfig` in its config — `queryConfig` without `query` is silently ignored
 - [ ] `additional_data` destructured without `as any` — `validatedBody` is already typed
 - [ ] Mutations: workflow → `query.graph()` refetch → return refetched data
@@ -217,6 +229,12 @@ Only work through sections for detected features. Explicitly skip and note secti
 - [ ] `usePrompt()` before destructive actions
 - [ ] API calls via shared SDK from `src/admin/lib/sdk.ts`
 - [ ] `useRouteModal().handleSuccess()` for navigation after create/edit
+- [ ] Zod imported from `@acmekit/deps/zod` — NOT bare `"zod"`
+- [ ] `SectionRow` uses only `title`, `value`, `actions` props — no `children` (use `value` for custom JSX)
+- [ ] `onRowClick` callback uses `row.original.id` — NOT `row.id` (runtime is TanStack `Row<TData>` despite type)
+- [ ] DataTable with `filtering` config: `useQuery` queryKey includes filter/search/pagination state — NOT static like `["items"]`
+- [ ] DataTable with `filtering` config: `queryFn` passes filter state as query params to API — NOT fetching unfiltered data
+- [ ] `react-hook-form` and `@hookform/resolvers` in `peerDependencies` (not only `devDependencies`) — they are provided by acmekit
 
 ### Middlewares — only if hasMiddlewares
 - [ ] Every middleware calls `next()`

package/dist/templates/app/.claude/agents/test-writer.md

@@ -8,10 +8,24 @@ maxTurns: 20
 
 You are an AcmeKit test engineer. Generate comprehensive integration tests using the unified `integrationTestRunner` with the correct mode and patterns.
 
-**BEFORE writing any test:**
-1. Read `.claude/rules/testing.md` — it contains anti-patterns, fixtures, lifecycle, and error handling rules you MUST follow
-2. Read the source code you're testing — understand service methods, route paths, validators, and response shapes
-3. Identify the correct test tier (HTTP, app, module, or unit)
+**MANDATORY PRE-FLIGHT CHECKLIST — complete ALL steps before writing any test code:**
+
+1. **Read `.claude/rules/testing.md`** — contains anti-patterns, fixtures, lifecycle, and error handling rules you MUST follow.
+
+2. **Verify migrations are current.** If model files changed, run `npx acmekit db:generate <module>` and `npx acmekit db:migrate`. `mode: "app"` runs real migrations — missing migration files cause `TableNotFoundException`.
+
+3. **Verify jest config buckets.** Read `jest.config.js` and confirm the test bucket you need exists:
+   - `integration:http` → `integration-tests/http/`
+   - `integration:app` → `integration-tests/app/`
+   - `integration:modules` → `src/modules/*/__tests__/`
+   - `unit` → `src/**/__tests__/*.unit.spec.ts`
+   If the bucket is missing, add it to `jest.config.js` and create the directory BEFORE writing the test.
+
+4. **Read the source code under test** — understand service methods, route paths, validators, response shapes, and error handling (throws vs returns).
+
+5. **Read mock interfaces.** If your test uses auto-injected mocks (`MockEventBusService`, `MockLockingService`, `MockSecretsService`), read their actual source to verify exact method names and signatures. Do NOT guess — mocks have convenience methods (e.g., `setSecret()`, `getEmittedEvents()`) not on real services, and may not implement every real service method.
+
+6. **Identify the correct test tier** (HTTP, app, module, or unit).
 
 ---
 
@@ -450,29 +464,23 @@ describe("MyProvider", () => {
 
 ---
 
-## Asserting Domain Events (module mode)
-
-```typescript
-import { MockEventBusService } from "@acmekit/test-utils"
-
-let eventBusSpy: jest.SpyInstance
+## Asserting Domain Events
 
-beforeEach(() => {
-  eventBusSpy = jest.spyOn(MockEventBusService.prototype, "emit")
-})
+`MockEventBusService` accumulates emitted events — use `.getEmittedEvents()` directly, no spy needed.
 
-afterEach(() => {
-  eventBusSpy.mockClear()
-})
+```typescript
+import { Modules } from "@acmekit/framework/utils"
 
 it("should emit post.created event", async () => {
   await service.createPosts([{ title: "Event Test" }])
 
-  const events = eventBusSpy.mock.calls[0][0]
+  // Access events directly from the mock event bus — no spy needed
+  const eventBus = getContainer().resolve(Modules.EVENT_BUS)
+  const events = eventBus.getEmittedEvents()
   expect(events).toEqual(
     expect.arrayContaining([
       expect.objectContaining({
-        name: "post.created",
+        name: "post.created",  // NOTE: property is "name", NOT "eventName"
         data: expect.objectContaining({ id: expect.any(String) }),
       }),
     ])
@@ -480,6 +488,8 @@ it("should emit post.created event", async () => {
 })
 ```
 
+> `emitEventStep` maps `eventName` to `name` internally — always assert on `event.name`.
+
 ---
 
 ## What to Test

package/dist/templates/app/.claude/rules/admin-components.md

@@ -36,10 +36,18 @@ useDataTable({
   filtering:   { state: DataTableFilteringState, onFilteringChange: (v) => void },
   pagination:  { state: DataTablePaginationState, onPaginationChange: (v) => void },
   rowSelection: { state: DataTableRowSelectionState, onRowSelectionChange: (v) => void, enableRowSelection?: boolean | ((row) => boolean) },
-  onRowClick:  (event, row) => void,
+  onRowClick:  (event, row) => void,  // see note below
 })
 ```
 
+**`onRowClick` row parameter:** The TypeScript signature declares `row: TData`, but at runtime `row` is a TanStack `Row<TData>` object. Access your data via `row.original`:
+
+```tsx
+onRowClick: (_event, row) => navigate(row.original.id),
+```
+
+This is a known type mismatch in `useDataTable`. TypeScript may report an error on `row.original` — cast if needed: `(row as any).original.id`.
+
 State types: `DataTablePaginationState`, `DataTableSortingState`, `DataTableFilteringState`, `DataTableRowSelectionState` — all from `@acmekit/ui`.
 
 **`DataTable.Table` emptyState shape:**
@@ -274,6 +282,8 @@ const useFilters = () => {
 
 **Best practice**: For API-loaded filter options, fetch with `{ limit: 1000 }` and conditionally add the filter only when data is available.
 
+**CRITICAL**: `useDataTable` uses server-side filtering (`manualFiltering: true`). Defining filters alone does NOT filter data — you MUST wire filter state to the API query. See the "DataTable Server-Side Filtering" section in the admin-data rules for the complete pattern (building `queryParams` from filter/search state, including them in `queryKey`, and passing as URL query params in `queryFn`).
+
 ---
 
 ## Forms — Form.Field Compound Component
@@ -284,7 +294,11 @@ const useFilters = () => {
 import { Form, Input, Textarea, Select, Switch } from "@acmekit/ui"
 import { useForm } from "react-hook-form"
 import { zodResolver } from "@hookform/resolvers/zod"
-import * as zod from "zod"
+import * as zod from "@acmekit/deps/zod"
+
+// NOTE: react-hook-form and @hookform/resolvers are provided by acmekit.
+// In plugins: list them in peerDependencies (NOT devDependencies).
+// In apps: they are available transitively — no extra dependency needed.
 
 const Schema = zod.object({
   title: zod.string().min(1, "Title is required"),
@@ -412,7 +426,7 @@ import { useForm } from "react-hook-form"
 import { zodResolver } from "@hookform/resolvers/zod"
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
 import { useParams } from "react-router-dom"
-import * as zod from "zod"
+import * as zod from "@acmekit/deps/zod"
 import { sdk } from "../../../../lib/sdk"
 
 const EditSchema = zod.object({
@@ -544,7 +558,7 @@ import { Button, RouteFocusModal, Form, Heading, Input, Text, Textarea, toast, K
 import { useForm } from "react-hook-form"
 import { zodResolver } from "@hookform/resolvers/zod"
 import { useMutation, useQueryClient } from "@tanstack/react-query"
-import * as zod from "zod"
+import * as zod from "@acmekit/deps/zod"
 import { sdk } from "../../../lib/sdk"
 
 const CreateSchema = zod.object({

package/dist/templates/app/.claude/rules/admin-data.md

@@ -75,6 +75,69 @@ const { data, isLoading } = useQuery({
 })
 ```
 
+### DataTable Server-Side Filtering
+
+**`useDataTable` uses `manualFiltering: true`** — it does NOT filter data client-side. Filter/search/pagination state must be sent to the API as query parameters. If you don't wire state to the query, changing filters has no effect.
+
+```tsx
+const [search, setSearch] = useState("")
+const [filtering, setFiltering] = useState<DataTableFilteringState>({})
+const [pagination, setPagination] = useState<DataTablePaginationState>({
+  pageIndex: 0,
+  pageSize: 20,
+})
+
+// Build query params from filter/search/pagination state
+const queryParams = useMemo(() => {
+  const params: Record<string, string> = {}
+
+  Object.entries(filtering).forEach(([key, value]) => {
+    if (value == null) return
+    if (Array.isArray(value) && value.length > 0) {
+      params[key] = value.join(",")
+    } else if (!Array.isArray(value)) {
+      params[key] = String(value)
+    }
+  })
+
+  if (search) {
+    params.q = search
+  }
+
+  return params
+}, [filtering, search])
+
+// Include queryParams in queryKey so React Query refetches on filter changes
+const { data, isLoading } = useQuery({
+  queryKey: ["wallets", queryParams],
+  queryFn: () => {
+    const qs = new URLSearchParams(queryParams).toString()
+    return sdk.admin.fetch(`/wallets${qs ? `?${qs}` : ""}`, {
+      method: "GET",
+    })
+  },
+})
+
+const table = useDataTable({
+  data: data?.wallets ?? [],
+  columns,
+  filters,
+  getRowId: (row) => row.id,
+  rowCount: data?.count ?? data?.wallets?.length ?? 0,
+  isLoading,
+  search: { state: search, onSearchChange: setSearch },
+  filtering: { state: filtering, onFilteringChange: setFiltering },
+  pagination: { state: pagination, onPaginationChange: setPagination },
+})
+```
+
+**Key rules:**
+- `queryKey` MUST include filter/search/pagination state — otherwise React Query won't refetch when filters change
+- `queryFn` MUST pass state as query parameters to the API
+- Multiselect filters produce `string[]` — serialize as comma-separated for query params
+- Radio filters produce `string` — pass directly
+- The API route must handle these params (see `api-routes.md` for array filter handling)
+
 ---
 
 ## Action Menus — ActionMenu Component
@@ -247,6 +310,10 @@ const confirmed = await prompt({
 **Entity types:**
 - Hand-writing `type Payment = { id: string; status: string; created_at: string }` instead of inferring from SDK. Hand-written types drift from response schemas: date fields should be `string | Date` (from `z.union`), nullable fields need `| null`, enum fields are `string` (not the user enum). Always use `type Payment = Awaited<ReturnType<typeof sdk.admin.fetch<"/admin/payments", "GET">>>["items"][0]`
 
+**Imports & dependencies:**
+- Importing `zod` from `"zod"` in admin code — use `import * as zod from "@acmekit/deps/zod"` to share the same zod instance as acmekit
+- Adding `react-hook-form` or `@hookform/resolvers` to `devDependencies` — they are provided by acmekit. In plugins: list them in `peerDependencies` (+ `devDependencies` mirror). In apps: they are available transitively, no extra dependency needed
+
 **Form context:**
 - Using `Form.Field`, `Form.Label`, `SwitchBox`, or any `Form.*` sub-component without a form provider — they call `useFormContext()` and crash with "Cannot destructure property 'getFieldState' of 'useFormContext(...)' as it is null". `RouteDrawer.Form` / `RouteFocusModal.Form` provide this automatically; standalone pages must wrap with `<Form {...form}>` from `@acmekit/ui`
 - Importing `FormProvider` from `react-hook-form` directly — causes dual-instance context mismatch. Always use `Form` from `@acmekit/ui` (it IS the FormProvider re-export)
@@ -265,6 +332,8 @@ const confirmed = await prompt({
 - Not using `size="small"` on ALL buttons (header actions, form buttons, table actions)
 
 **DataTable:**
+- **Static `queryKey` with filters** — using `queryKey: ["posts"]` when the table has filters/search/pagination. The `queryKey` MUST include filter/search/pagination state so React Query refetches when they change: `queryKey: ["posts", queryParams]`
+- **Not passing filter state to the API** — `useDataTable` uses `manualFiltering: true` (server-side). If the `queryFn` doesn't send filter values as query parameters, changing filters has zero effect on the displayed data
 - Passing `columns`, `filters`, `heading`, `emptyState` as props to `<DataTable>` — it only accepts `instance`. Use sub-components: `DataTable.Toolbar`, `DataTable.Table`, etc.
 - Using boolean flags like `enablePagination: true` in `useDataTable` — pass state objects: `pagination: { state, onPaginationChange }`
 - Using `table.getState().rowSelection` — use `table.getRowSelection()` instead
@@ -272,6 +341,7 @@ const confirmed = await prompt({
 - Passing `commands` as a prop to `<DataTable>` — pass to `useDataTable` hook and render `<DataTable.CommandBar>`
 - Using `Container className="divide-y p-0"` for DataTable pages — use `Container className="flex flex-col overflow-hidden p-0"` (DataTable needs flex layout)
 - Rendering a `DataTable.*` sub-component without its matching state in `useDataTable` — causes runtime crash. `.Search` requires `search`, `.SortingMenu` requires `sorting`, `.FilterMenu` requires `filters`, `.CommandBar` requires `commands` + `rowSelection`. Never add a sub-component without wiring its state.
+- Using `row.id` in `onRowClick` — `row` is a TanStack `Row<TData>` at runtime (despite the `TData` type signature). Access data via `row.original.id`. Cast if needed: `(row as any).original.id`.
 
 **Error handling:**
 - Using `toast.error` for query errors — throw them (`if (isError) throw error`) for error boundary
@@ -299,6 +369,9 @@ const confirmed = await prompt({
 - Not breaking large detail pages into section components — if a detail page has 3+ sections, each should be its own component in `components/`
 - Putting delete logic inline instead of extracting a reusable `useDelete*Action` hook when the same delete is used in multiple places
 
+**SectionRow:**
+- Passing `children` to `SectionRow` — it does NOT accept children. Use the `value` prop for custom JSX content (badges, copy buttons, formatted text). `SectionRow` only accepts `title`, `value`, and `actions`.
+
 **Wrong component for context:**
 - Using `StatusBadge` in DataTable columns — use `StatusCell` instead (dot indicator, truncation-safe)
 - Using raw `Switch` + manual label/description instead of `SwitchBox` for toggle settings

package/dist/templates/app/.claude/rules/admin-patterns.md

@@ -535,6 +535,26 @@ import { SectionRow } from "@acmekit/ui"
 
 **Props**: `title: string`, `value?: ReactNode | string | null`, `actions?: ReactNode`.
 
+**SectionRow does NOT accept `children`.** Pass custom JSX through the `value` prop instead:
+
+```tsx
+// WRONG — children is not a valid prop (TypeScript error)
+<SectionRow title="Address">
+  <div className="font-mono">{wallet.address}</div>
+</SectionRow>
+
+// RIGHT — use value prop for custom JSX content
+<SectionRow
+  title="Address"
+  value={
+    <div className="group flex items-center gap-x-2">
+      <Text size="small" className="font-mono">{wallet.address}</Text>
+      <Copy content={wallet.address} className="hidden group-hover:block" />
+    </div>
+  }
+/>
+```
+
 ---
 
 ## Component Organization — Scaling Beyond page.tsx

package/dist/templates/app/.claude/rules/api-routes.md

@@ -145,6 +145,24 @@ query: z.object({
 })
 ```
 
+**Query schemas — multiselect filter params:**
+- Admin DataTable multiselect filters send array values as comma-separated strings (e.g., `?status=active,draft`)
+- Use `z.preprocess` to split comma-separated strings into arrays:
+```typescript
+status: z.preprocess(
+  (v) => (typeof v === "string" ? v.split(",") : v),
+  z.array(z.string()).optional()
+),
+```
+- For enum arrays, chain with `z.enum()` inside the array:
+```typescript
+network: z.preprocess(
+  (v) => (typeof v === "string" ? v.split(",") : v),
+  z.array(z.enum(["mainnet", "testnet"])).optional()
+),
+```
+- In the handler, pass non-empty arrays to the service filter: `if (status?.length) listFilters.status = status`
+
 **Body schemas:**
 - `.strict()` on create/update bodies to reject unknown fields
 - `.nullish()` on fields that can be explicitly cleared to null (not just `.optional()`)
@@ -346,7 +364,7 @@ res.status(200).json({ id, object: "blog_post", deleted: true })
 | Property | Available on | Description |
 |---|---|---|
 | `req.validatedBody` | POST routes with `body` config | Validated request body |
-| `req.validatedQuery` | Routes with `query` config | Validated query params (all params) |
+| `req.validatedQuery` | Routes with `query` config | Validated query params (all params). **Can be `undefined` when request has no query string** — always destructure with `?? {}` fallback |
 | `req.filterableFields` | Routes with `query` config | Query params minus pagination/fields/order |
 | `req.queryConfig.fields` | Routes with `queryConfig` | Array of field strings to select |
 | `req.queryConfig.pagination` | Routes with `queryConfig` | `{ skip, take, order }` |
@@ -748,4 +766,10 @@ const { additional_data, ...body } = req.validatedBody as any  // ❌ defeats al
 
 // RIGHT — validatedBody is already typed from the body schema; no cast needed
 const { additional_data, ...body } = req.validatedBody  // ✅ type inferred from defineRouteConfig
+
+// WRONG — destructuring req.validatedQuery without fallback (undefined when no query params sent)
+const { enabled, ...filters } = req.validatedQuery  // ❌ crashes if request has no query string
+
+// RIGHT — always provide fallback when destructuring validatedQuery
+const { enabled, ...filters } = req.validatedQuery ?? {}  // ✅ safe when no query params
 ```

package/dist/templates/app/.claude/rules/modules.md

@@ -396,6 +396,149 @@ Options flow: host config `providers[].options` → constructor second argument
 
 Available domain abstracts: `AbstractNotificationProviderService`, `AbstractFileProviderService`, `AbstractAuthModuleProvider`, `AbstractAnalyticsProviderService`, `AbstractModuleProvider<TConfig>` (generic base).
 
+### Provider Container Scoping
+
+**Providers are module-scoped.** The `container` passed to a provider constructor is the **parent module's** awilix cradle — not the application root container. This is by design: modules are isolated, self-contained units.
+
+**Providers CAN access:**
+- Sibling registrations within the parent module (e.g., `logger`, services registered by the module's loaders)
+- Their own `this.options_` (from `providers[].options` in host config)
+
+**Providers CANNOT access:**
+- Other modules — a provider under `RELAYER_MODULE` cannot resolve `TRON_MODULE`, `Modules.USER`, or any module outside its parent
+- Application-level container registrations not propagated to the module scope
+
+**Attempting to resolve another module from the provider's container silently returns `undefined` or throws at runtime** — there is no compile-time error.
+
+#### Cradle vs AcmeKitContainer — Two Different Objects
+
+AcmeKit has two container representations. Confusing them causes silent `undefined` at runtime.
+
+| | **Cradle** (awilix proxy) | **AcmeKitContainer** |
+|---|---|---|
+| What is it | Proxy object — property access triggers resolution | Full container with `.resolve()` method |
+| Access pattern | `container.logger`, `container[MODULE]` | `container.resolve(MODULE)` |
+| Who gets it | Provider constructors, service constructors | Workflow steps (`{ container }`), `req.scope` |
+| Type | `Record<string, unknown>` (or typed cradle) | `AcmeKitContainer` from `@acmekit/framework/types` |
+
+```typescript
+// Provider constructor — receives CRADLE (property access)
+constructor(container: Cradle, options: Options) {
+  this.logger_ = container.logger          // ✅ property access
+  this.logger_ = container.resolve("logger")  // ❌ cradle has no .resolve()
+}
+
+// Workflow step — receives ACMEKIT CONTAINER (.resolve() method)
+async (input, { container }) => {
+  const svc = container.resolve(MY_MODULE)      // ✅ .resolve() method
+  const svc = container[MY_MODULE]              // ❌ undefined — not a cradle
+}
+```
+
+**When passing the application container to a provider method, the provider must use `.resolve()` — not bracket access:**
+
+```typescript
+import type { AcmeKitContainer } from "@acmekit/framework/types"
+
+class MyProvider {
+  async doWork(request: Request, appContainer?: AcmeKitContainer) {
+    // appContainer is from the workflow step — use .resolve()
+    const otherService = appContainer?.resolve<IOtherService>(OTHER_MODULE)  // ✅
+    const otherService = appContainer?.[OTHER_MODULE]  // ❌ undefined!
+  }
+}
+```
+
+#### Simple Providers — No Cross-Module Dependencies
+
+When a provider's job is a single external operation (send email, upload file, call API), it needs only `this.options_` and sibling registrations. No special handling required.
+
+```typescript
+class SendGridNotification extends AbstractNotificationProviderService {
+  static identifier = "sendgrid"
+
+  async send(notification) {
+    // Only needs this.options_.apiKey — no other modules
+    return this.client_.send({ to: notification.to, template: notification.template })
+  }
+}
+```
+
+#### Complex Providers — Cross-Module Dependencies via Method Parameters
+
+Some providers need other modules to do their job — e.g., a chain relayer provider that calls external APIs but also manages chain-specific DB state in a companion module. The provider can't resolve the companion module from `this.container_` (module-scoped), and splitting into workflow steps isn't always possible (the calling workflow belongs to a different plugin/package).
+
+**The correct pattern: the workflow step passes the `AcmeKitContainer` through the parent module's service method to the provider. The provider uses `.resolve()` on the passed container — never bracket access.**
+
+```typescript
+import type { AcmeKitContainer } from "@acmekit/framework/types"
+
+// 1. Workflow step — passes the full application container
+export const executeOnChainStep = createStep(
+  { name: "execute-on-chain-step", noCompensation: true },
+  async ({ request }, { container }) => {
+    const relayerService = container.resolve<IRelayerModuleService>(RELAYER_MODULE)
+    // Pass container (AcmeKitContainer) — provider will .resolve() what it needs
+    const result = await relayerService.relay(request, container)
+    return new StepResponse(result)
+  },
+  async () => {}
+)
+
+// 2. Parent module service — forwards AcmeKitContainer to the provider
+class RelayerModuleService {
+  @InjectManager()
+  async relay(
+    request: RelayRequest,
+    appContainer?: AcmeKitContainer,
+    @AcmeKitContext() sharedContext: Context = {}
+  ) {
+    return await this.relay_(request, appContainer, sharedContext)
+  }
+
+  @InjectTransactionManager()
+  protected async relay_(
+    request: RelayRequest,
+    appContainer?: AcmeKitContainer,
+    @AcmeKitContext() sharedContext: Context = {}
+  ) {
+    const provider = this.resolveChainRelayer(request.chain)
+    const wallet = await this.selectWallet_(request.chain, sharedContext)
+    return await provider.relay({ ...request, wallet }, appContainer)
+  }
+}
+
+// 3. Provider — uses .resolve() on the passed AcmeKitContainer
+class TronChainRelayer implements IChainRelayer {
+  static identifier = "tron-chain-relayer"
+
+  async relay(request: RelayRequest, appContainer?: AcmeKitContainer): Promise<RelayResult> {
+    // .resolve() with optional chaining — NOT bracket access
+    const tronService = appContainer?.resolve<ITronModuleService>(TRON_MODULE)
+    const delegation = await tronService.createDelegationRecords([...])
+    // this.options_ for own config (module-scoped — always available)
+    const client = new TronWeb({ fullHost: this.options_.fullNodeUrl })
+    const txResult = await client.broadcast(request.payload)
+    await tronService.reconcileDelegation(delegation.id, txResult)
+    return txResult
+  }
+}
+```
+
+**Key constraints:**
+- Provider constructor container (`this.container_`) is a **cradle** — property access only, ONLY for sibling registrations
+- The `AcmeKitContainer` passed as a method parameter uses **`.resolve()`** — never bracket access
+- The `appContainer` parameter is optional (`?`) — the provider interface uses the looser `Record<string, unknown>` type; implementations narrow to `AcmeKitContainer`
+- The workflow step is the only place that has the full `AcmeKitContainer`
+- Import: `import type { AcmeKitContainer } from "@acmekit/framework/types"`
+
+**When to use which tier:**
+
+| Provider type | Cross-module deps? | Pattern |
+|---|---|---|
+| File storage, notifications, SMS | No | Use `this.options_` and `this.container_` only |
+| Payment processors, chain relayers | Yes — companion modules for state/records | Receive deps as method params from workflow step |
+
 ### Module() vs ModuleProvider()
 
 | | `Module()` | `ModuleProvider()` |
@@ -590,6 +733,32 @@ class MyProvider {
   }
 }
 
+// WRONG — provider resolving another module from its own container (cradle)
+// Provider container is scoped to the PARENT module — other modules are not visible
+class TronRelayer implements IChainRelayer {
+  async relay(request: RelayRequest) {
+    const tronService = this.container_[TRON_MODULE]  // ❌ undefined — not in module scope
+    await tronService.createDelegationRecords([...])  // crashes
+  }
+}
+
+// WRONG — using bracket access on AcmeKitContainer (it's NOT a cradle)
+class TronRelayer implements IChainRelayer {
+  async relay(request: RelayRequest, appContainer?: AcmeKitContainer) {
+    const svc = appContainer[TRON_MODULE]             // ❌ undefined — wrong access pattern!
+    const svc2 = appContainer[TRON_MODULE] as any     // ❌ same bug, hidden by cast
+  }
+}
+
+// RIGHT — use .resolve() on AcmeKitContainer passed from workflow step
+class TronRelayer implements IChainRelayer {
+  async relay(request: RelayRequest, appContainer?: AcmeKitContainer) {
+    const tronService = appContainer?.resolve<ITronModuleService>(TRON_MODULE)  // ✅
+    await tronService.createDelegationRecords([...])
+    return await this.client_.broadcast(request.payload)
+  }
+}
+
 // WRONG — hardcoding prefix/identifiersKey inline in multiple files
 // A typo between createProvidersLoader and AcmeKitService silently breaks resolution
 createProvidersLoader({ prefix: "cr_", identifiersKey: "chain_relayer_providers_identifier" })