@adonis-agora/durable 1.0.0-rc.2 → 1.0.0-rc.21

package/dist/stubs/config/durable_dashboard.stub

@@ -2,41 +2,21 @@
   exports({ to: app.configPath('durable_dashboard.ts') })
 }}}
 import { defineConfig } from '@adonis-agora/durable/dashboard'
-// Used by the commented-out dashboardAuth example below.
-// import env from '#start/env'
 
 /**
- * Configuration for the @adonis-agora/durable dashboard.
+ * Configuration for the @adonis-agora/durable console.
  *
- * By default the dashboard FAILS CLOSED in every environment: it requires a
- * bearer token equal to \`DURABLE_DASHBOARD_TOKEN\`, and denies everything when
- * that env var is unset. Replace \`authorize\` with your own guard (session,
- * role, IP allow-list, …), or set \`allowUnauthenticated: true\` for a trusted
- * local network only. \`authorize\` returns a boolean or a decision
- * \`{ allowed, reason?: 'unauthenticated' | 'forbidden' }\` — \`'unauthenticated'\`
- * answers 401, any other denial 403.
- *
- * \`dashboardAuth\` is an ADDITIVE, optional session gate on top of \`authorize\` —
- * a signed cookie minted via a built-in login page (Mode B: \`login\`) and/or a
- * "open the console from your app" endpoint (Mode A: \`session\`). At least one
- * of the two is required when \`dashboardAuth\` is set; either or both may be
- * configured. See \`docs/observability/dashboard-auth.mdx\`.
+ * Without \`authorize\` the console is open outside production and answers 403
+ * to every request in production. Set \`authorize\` to choose who may open it:
+ * a function, an authorizer class, or a lazy import of one
+ * (\`() => import('#policies/console_access')\`). It returns a boolean,
+ * \`{ allowed, reason?: 'unauthenticated' | 'forbidden' }\` (\`'unauthenticated'\`
+ * answers 401, any other denial 403) or \`{ redirectTo }\`. For scripts, use
+ * \`authorizeByToken({ token: env.get('CONSOLE_TOKEN') })\`.
  */
 export default defineConfig({
   // enabled: true,
   // path: '/durable',
   // authorize: (ctx) => ctx.auth.user?.isAdmin === true,
-  // dashboardAuth: {
-  //   secret: env.get('DURABLE_DASHBOARD_SECRET'),
-  //   ttl: '8h',
-  //   // Mode B — standalone login page.
-  //   login: async (username, password) => {
-  //     if (username === 'admin' && password === env.get('DURABLE_DASHBOARD_PASSWORD')) {
-  //       return { id: 'admin', name: 'Admin' }
-  //     }
-  //     return null
-  //   },
-  //   // Mode A — mint a session for an already-authenticated host request.
-  //   // session: async (request) => (request.user?.isAdmin ? { id: request.user.id } : null),
-  // },
+  // authorize: () => import('#policies/console_access'),
 })

package/dist/stubs/database/migrations/create_durable_tables.stub

@@ -1,10 +1,20 @@
 {{{
   exports({ to: app.migrationsPath(`${new Date().getTime()}_create_durable_tables.ts`) })
 }}}
+import app from '@adonisjs/core/services/app'
 import { BaseSchema } from '@adonisjs/lucid/schema'
 import db from '@adonisjs/lucid/services/db'
 import { createDurableTables, dropDurableTables } from '@adonis-agora/durable'
 
+/**
+ * The database schema the durable tables live in (a database on MySQL): the top-level
+ * \`schema\` of config/durable.ts, read when the migration runs (\`undefined\` uses the
+ * connection's current schema). If you set it on \`stores.lucid({ schema })\` instead,
+ * put that value here.
+ */
+const configured = app.config.get('durable.schema', undefined)
+const schema = typeof configured === 'string' ? configured : undefined
+
 /**
  * Durable workflow tables for the @adonis-agora/durable \`lucid\` state store: runs, step checkpoints,
  * the search-attribute side-table, signal waiters, buffered signals, buffered events and persisted
@@ -39,10 +49,10 @@ export default class extends BaseSchema {
   static disableTransactions = true
 
   async up() {
-    await createDurableTables(db, this.db.connectionName)
+    await createDurableTables(db, this.db.connectionName, { schema })
   }
 
   async down() {
-    await dropDurableTables(db, this.db.connectionName)
+    await dropDurableTables(db, this.db.connectionName, { schema })
   }
 }

package/dist/stubs/database/migrations/create_durable_transport_messages.stub

@@ -1,8 +1,21 @@
 {{{
   exports({ to: app.migrationsPath(`${new Date().getTime()}_create_durable_transport_messages.ts`) })
 }}}
+import app from '@adonisjs/core/services/app'
 import { BaseSchema } from '@adonisjs/lucid/schema'
 
+/**
+ * The database schema the tables live in (a database on MySQL): the top-level
+ * \`schema\` of config/durable.ts, read when the migration runs (\`undefined\` uses the
+ * connection's current schema). If you set it on \`transports.db({ schema })\` (or on the queue
+ * transport's \`workerKeysSchema\`) instead, put that value here.
+ */
+const configured = app.config.get('durable.schema', undefined)
+const schema = typeof configured === 'string' ? configured : undefined
+
+/** \`name\` in {@link schema}: Knex quotes \`schema.table\` part by part. */
+const inSchema = (name: string) => (schema ? \`\${schema}.\${name}\` : name)
+
 /**
  * The message channel of the @adonis-agora/durable \`db\` transport: remote-workflow decisions and step
  * events, and the store-less (tenant pod) protocol's start-run, run-request, run-reply and tenant-event
@@ -12,7 +25,16 @@ import { BaseSchema } from '@adonisjs/lucid/schema'
  */
 export default class extends BaseSchema {
   async up() {
-    this.schema.createTable('durable_transport_messages', (table) => {
+    if (schema) {
+      // Runs before the tables below (calls run in order); \`??\` quotes the name as an identifier.
+      this.defer(async (db) => {
+        await db.rawQuery(
+          db.dialect.name === 'mysql' ? 'create database if not exists ??' : 'create schema if not exists ??',
+          [schema]
+        )
+      })
+    }
+    this.schema.createTable(inSchema('durable_transport_messages'), (table) => {
       table.increments('id').primary()
       table.string('kind', 32).notNullable()
       table.string('namespace').notNullable().defaultTo('default')
@@ -29,15 +51,22 @@ export default class extends BaseSchema {
     // it with one, whichever of the two migrations runs first.)
     // Each check takes a fresh schema builder: a Knex schema builder is stateful.
     this.defer(async (db) => {
-      if (!(await db.schema.hasTable('durable_transport_tasks'))) return
-      if (await db.schema.hasColumn('durable_transport_tasks', 'kind')) return
-      await db.schema.alterTable('durable_transport_tasks', (table) => {
+      if (!(await (schema ? db.schema.withSchema(schema) : db.schema).hasTable('durable_transport_tasks'))) return
+      // With a schema, the catalog is asked directly: Knex's MySQL hasColumn ignores withSchema.
+      const hasKind = schema
+        ? (await db
+            .from('information_schema.columns')
+            .where({ table_schema: schema, table_name: 'durable_transport_tasks', column_name: 'kind' })
+            .first()) !== null
+        : await db.schema.hasColumn('durable_transport_tasks', 'kind')
+      if (hasKind) return
+      await db.schema.alterTable(inSchema('durable_transport_tasks'), (table) => {
         table.string('kind', 16).notNullable().defaultTo('step')
       })
     })
   }
 
   async down() {
-    this.schema.dropTableIfExists('durable_transport_messages')
+    this.schema.dropTableIfExists(inSchema('durable_transport_messages'))
   }
 }

package/dist/stubs/database/migrations/create_durable_transport_tables.stub

@@ -1,8 +1,21 @@
 {{{
   exports({ to: app.migrationsPath(`${new Date().getTime()}_create_durable_transport_tables.ts`) })
 }}}
+import app from '@adonisjs/core/services/app'
 import { BaseSchema } from '@adonisjs/lucid/schema'
 
+/**
+ * The database schema the tables live in (a database on MySQL): the top-level
+ * \`schema\` of config/durable.ts, read when the migration runs (\`undefined\` uses the
+ * connection's current schema). If you set it on \`transports.db({ schema })\` (or on the queue
+ * transport's \`workerKeysSchema\`) instead, put that value here.
+ */
+const configured = app.config.get('durable.schema', undefined)
+const schema = typeof configured === 'string' ? configured : undefined
+
+/** \`name\` in {@link schema}: Knex quotes \`schema.table\` part by part. */
+const inSchema = (name: string) => (schema ? \`\${schema}.\${name}\` : name)
+
 /**
  * Transport tables for the @adonis-agora/durable \`db\` transport: the point-to-point work channels (tasks /
  * results / heartbeats / control) that let durable remote steps run cross-process over the database
@@ -12,7 +25,16 @@ import { BaseSchema } from '@adonisjs/lucid/schema'
  */
 export default class extends BaseSchema {
   async up() {
-    this.schema.createTable('durable_transport_tasks', (table) => {
+    if (schema) {
+      // Runs before the tables below (calls run in order); \`??\` quotes the name as an identifier.
+      this.defer(async (db) => {
+        await db.rawQuery(
+          db.dialect.name === 'mysql' ? 'create database if not exists ??' : 'create schema if not exists ??',
+          [schema]
+        )
+      })
+    }
+    this.schema.createTable(inSchema('durable_transport_tasks'), (table) => {
       table.string('step_id').primary()
       table.string('run_id').notNullable()
       table.integer('seq').notNullable()
@@ -33,7 +55,7 @@ export default class extends BaseSchema {
       table.index(['namespace', 'grp', 'claimed_at', 'created_at'], 'durable_transport_tasks_grp_idx')
     })
 
-    this.schema.createTable('durable_transport_results', (table) => {
+    this.schema.createTable(inSchema('durable_transport_results'), (table) => {
       table.string('step_id').primary()
       table.string('run_id').notNullable()
       table.integer('seq').notNullable()
@@ -49,7 +71,7 @@ export default class extends BaseSchema {
       table.index(['namespace', 'claimed_at', 'created_at'], 'durable_transport_results_idx')
     })
 
-    this.schema.createTable('durable_transport_heartbeats', (table) => {
+    this.schema.createTable(inSchema('durable_transport_heartbeats'), (table) => {
       table.increments('id').primary()
       table.string('run_id').notNullable()
       table.integer('seq').notNullable()
@@ -62,7 +84,7 @@ export default class extends BaseSchema {
       table.index(['namespace', 'claimed_at', 'created_at'], 'durable_transport_heartbeats_idx')
     })
 
-    this.schema.createTable('durable_transport_control', (table) => {
+    this.schema.createTable(inSchema('durable_transport_control'), (table) => {
       table.increments('id').primary()
       table.text('payload', 'longtext').notNullable()
       table.string('namespace').notNullable().defaultTo('default')
@@ -74,9 +96,9 @@ export default class extends BaseSchema {
   }
 
   async down() {
-    this.schema.dropTableIfExists('durable_transport_control')
-    this.schema.dropTableIfExists('durable_transport_heartbeats')
-    this.schema.dropTableIfExists('durable_transport_results')
-    this.schema.dropTableIfExists('durable_transport_tasks')
+    this.schema.dropTableIfExists(inSchema('durable_transport_control'))
+    this.schema.dropTableIfExists(inSchema('durable_transport_heartbeats'))
+    this.schema.dropTableIfExists(inSchema('durable_transport_results'))
+    this.schema.dropTableIfExists(inSchema('durable_transport_tasks'))
   }
 }

package/dist/stubs/database/migrations/create_durable_transport_worker_keys.stub

@@ -1,8 +1,21 @@
 {{{
   exports({ to: app.migrationsPath(`${new Date().getTime()}_create_durable_transport_worker_keys.ts`) })
 }}}
+import app from '@adonisjs/core/services/app'
 import { BaseSchema } from '@adonisjs/lucid/schema'
 
+/**
+ * The database schema the tables live in (a database on MySQL): the top-level
+ * \`schema\` of config/durable.ts, read when the migration runs (\`undefined\` uses the
+ * connection's current schema). If you set it on \`transports.db({ schema })\` (or on the queue
+ * transport's \`workerKeysSchema\`) instead, put that value here.
+ */
+const configured = app.config.get('durable.schema', undefined)
+const schema = typeof configured === 'string' ? configured : undefined
+
+/** \`name\` in {@link schema}: Knex quotes \`schema.table\` part by part. */
+const inSchema = (name: string) => (schema ? \`\${schema}.\${name}\` : name)
+
 /**
  * The worker advertisement keys for the @adonis-agora/durable \`db\` transport: the descriptor and
  * heartbeat a worker runtime publishes (what it serves, and that it is alive), each with an expiry so a
@@ -10,7 +23,16 @@ import { BaseSchema } from '@adonisjs/lucid/schema'
  */
 export default class extends BaseSchema {
   async up() {
-    this.schema.createTable('durable_transport_worker_keys', (table) => {
+    if (schema) {
+      // Runs before the tables below (calls run in order); \`??\` quotes the name as an identifier.
+      this.defer(async (db) => {
+        await db.rawQuery(
+          db.dialect.name === 'mysql' ? 'create database if not exists ??' : 'create schema if not exists ??',
+          [schema]
+        )
+      })
+    }
+    this.schema.createTable(inSchema('durable_transport_worker_keys'), (table) => {
       table.string('key', 512).primary()
       table.text('value', 'longtext').notNullable()
       table.bigInteger('expires_at').notNullable()
@@ -19,6 +41,6 @@ export default class extends BaseSchema {
   }
 
   async down() {
-    this.schema.dropTableIfExists('durable_transport_worker_keys')
+    this.schema.dropTableIfExists(inSchema('durable_transport_worker_keys'))
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/durable",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.21",
   "description": "Durable cross-app workflows for AdonisJS — deterministic replay engine, AdonisJS binding, ace commands, dashboard, OpenTelemetry, Telescope, testing harness and Redis admission, all in one package. Part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {
@@ -106,6 +106,16 @@
       "import": "./dist/src/control-plane-redis/index.js",
       "default": "./dist/src/control-plane-redis/index.js"
     },
+    "./diagnostics": {
+      "types": "./dist/src/diagnostics/index.d.ts",
+      "import": "./dist/src/diagnostics/index.js",
+      "default": "./dist/src/diagnostics/index.js"
+    },
+    "./doctor": {
+      "types": "./dist/src/doctor/index.d.ts",
+      "import": "./dist/src/doctor/index.js",
+      "default": "./dist/src/doctor/index.js"
+    },
     "./commands": {
       "types": "./dist/commands/main.d.ts",
       "import": "./dist/commands/main.js",
@@ -125,9 +135,10 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@adonis-agora/filter": ">=0.11.2 <2.0.0 || >=1.0.0-rc.0 <2.0.0"
+    "@adonis-agora/filter": ">=1.0.0-rc.5 <2.0.0"
   },
   "peerDependencies": {
+    "@adonis-agora/diagnostics": ">=1.0.0 <2.0.0 || >=1.0.0-rc.1 <2.0.0",
     "@adonisjs/assembler": "^8.4.0",
     "@adonisjs/core": "^7.3.0",
     "@adonisjs/lucid": "^22.4.0",
@@ -166,27 +177,33 @@
     },
     "vitest": {
       "optional": true
+    },
+    "@adonis-agora/diagnostics": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "@adonis-agora/durable-dashboard": "1.0.0-rc.0",
+    "@adonis-agora/diagnostics": "1.0.0-rc.1",
+    "@adonis-agora/durable-dashboard": "1.0.0-rc.8",
     "@adonisjs/assembler": "8.6.0",
+    "@adonisjs/auth": "10.1.0",
     "@adonisjs/core": "7.6.0",
     "@adonisjs/lucid": "22.4.2",
     "@adonisjs/queue": "0.7.0",
     "@adonisjs/redis": "11.0.0",
     "@opentelemetry/api": "1.10.0",
-    "@opentelemetry/context-async-hooks": "3.1.0",
+    "@opentelemetry/context-async-hooks": "3.1.1",
     "@opentelemetry/sdk-trace-base": "2.12.0",
     "@poppinss/hooks": "7.3.1",
     "@tanstack/intent": "0.5.6",
     "@types/better-sqlite3": "9.6.0",
-    "@types/node": "26.6.5",
+    "@types/node": "26.6.6",
     "arktype": "2.2.9",
     "better-sqlite3": "13.0.3",
-    "bullmq": "6.7.2",
+    "bullmq": "6.7.3",
     "cron-parser": "5.10.4",
     "ioredis": "6.0.0",
+    "jose": "6.2.17",
     "mysql2": "3.24.6",
     "pg": "8.23.1",
     "typescript": "7.0.2",
@@ -204,6 +221,7 @@
     "copy:stubs": "mkdir -p dist/stubs/config dist/stubs/database/migrations dist/stubs/make/workflow dist/assets && cp stubs/config/durable.stub dist/stubs/config/durable.stub && cp stubs/config/durable_dashboard.stub dist/stubs/config/durable_dashboard.stub && cp -r stubs/database/migrations/. dist/stubs/database/migrations/ && cp stubs/make/workflow/main.stub dist/stubs/make/workflow/main.stub && rm -rf dist/assets/spa && cp -r ../dashboard/dist/spa dist/assets/spa",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest",
-    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.tests.json"
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.tests.json",
+    "check:agora-doctor": "node ../../scripts/check-agora-doctor.mjs ."
   }
 }

package/skills/durable-cluster/SKILL.md

@@ -2,12 +2,12 @@
 name: durable-cluster
 description: >-
   Scale @adonis-agora/durable across processes and runtimes: the
-  role-discriminated config (standalone, control-plane, store-less tenant with
+  topology-discriminated config (standalone, control-plane, store-less tenant with
   compile-time store exclusion), durable:work vs durable:worker entrypoints,
   WorkerRuntime + RedisWorkerRegistry descriptors, handshake negotiation
   (compatible/degraded/incompatible) and capability routing (requires → blocked
   runs), layered tenant auth (signTenantToken/hmacTenantVerifier/verifyTenant),
-  runGateway as the role-portable read/control surface, namespace vs partition,
+  runGateway as the topology-portable read/control surface, namespace vs partition,
   tenant pods over bullmq, the @adonisjs/queue transport or the db transport, and Python
   (durable-worker) / NestJS interop over the bullmq wire. Use when
   splitting web from workers, isolating tenants, or adding polyglot workers.
@@ -19,7 +19,7 @@ metadata:
   framework: adonisjs
 sources:
   - 'DavideCarvalho/adonis-durable:docs/cluster/index.mdx'
-  - 'DavideCarvalho/adonis-durable:docs/cluster/roles-and-config.mdx'
+  - 'DavideCarvalho/adonis-durable:docs/cluster/topology-and-config.mdx'
   - 'DavideCarvalho/adonis-durable:docs/cluster/thin-workers.mdx'
   - 'DavideCarvalho/adonis-durable:docs/cluster/handshake.mdx'
   - 'DavideCarvalho/adonis-durable:docs/cluster/interop.mdx'
@@ -29,14 +29,23 @@ sources:
 
 # Cluster topologies & interop
 
-`config/durable.ts` is a **role-discriminated union**: one `role` field picks
+`config/durable.ts` is a **topology-discriminated union**: one `topology` field picks
 the topology and TypeScript narrows the rest. Workflows (`app/workflows`) and
-steps (`app/steps`) are byte-identical across every role — only where bodies
+steps (`app/steps`) are byte-identical across every topology — only where bodies
 execute changes.
 
-| Role | Owns the store | Executes bodies | Serves HTTP |
+`topology` is Agora-wide vocabulary (the cluster shape), not durable-only: a
+`tenant` is any process with no state of its own (API/dashboard pods included),
+not a customer — customer isolation is the separate `tenancy` / `tenantId`
+(organizations), which shares one pool by default. It is independent of the separate `role` axis (`all`/`api`/
+`worker`); durable has no `role` field and covers that axis with `drive`,
+`consumers` and `worker.embedded`. Durable connects tenants over a broker
+transport (`bullmq`/`queue`/`db`) with `partition`, `tenant.token`,
+`verifyTenant` and `capabilities`.
+
+| Topology | Owns the store | Executes bodies | Serves HTTP |
 |------|:---:|:---:|:---:|
-| `standalone` (default — omit `role`) | ✅ | ✅ embedded | optional |
+| `standalone` (default — omit `topology`) | ✅ | ✅ embedded | optional |
 | `control-plane` | ✅ required | ❌ | optional |
 | `tenant` | ❌ typed `never` | worker pods ✅ | api/dashboard pod |
 
@@ -48,7 +57,7 @@ Split fleet: a pure coordinator plus store-less tenant workers.
 import { defineConfig, hmacTenantVerifier, stores, transports } from '@adonis-agora/durable'
 
 export default defineConfig({
-  role: 'control-plane',
+  topology: 'control-plane',
   transport: 'bullmq', // or 'queue' / 'db' for Adonis-only fleets
   transports: { bullmq: transports.bullmq({ connection: { host: '127.0.0.1', port: 6379 } }) },
   store: 'lucid',
@@ -61,11 +70,11 @@ export default defineConfig({
 import { defineConfig, transports } from '@adonis-agora/durable'
 
 export default defineConfig({
-  role: 'tenant',
+  topology: 'tenant',
   transport: 'bullmq',
   transports: { bullmq: transports.bullmq({ connection: process.env.REDIS_URL }) },
   partition: 'acme-corp', // which pool this pod serves (required)
-  tenant: { token: process.env.DURABLE_TENANT_TOKEN }, // its signed claim
+  tenant: { token: process.env.DURABLE_TENANT_TOKEN }, // or a function/credentials class
   requestTimeoutMs: 10_000,
   // store: 'lucid'  // ❌ COMPILE ERROR — a tenant config cannot name a store
 })
@@ -76,6 +85,13 @@ node ace durable:work    # store-backed loop: pending, recovery, timers, sweeps,
 node ace durable:worker  # store-less tenant loop: serves app/steps, heartbeats, drains
 ```
 
+`verifyTenant` takes a function (`hmacTenantVerifier(secret)`), a class implementing
+`TenantVerifierContract` (`verify({ token })` → `{ tenant, capabilities? } | null`; built
+through the container), a lazy import of one, or an object with `verify`. `tenant.token`
+takes a string, a function called before every request, or the same forms of a
+`TenantCredentialsContract` (`token()`). Ready-made pieces for `@adonisjs/auth` access
+tokens, authkit and any OIDC provider are in the "Authenticate tenants" docs page.
+
 Isolation is three-layered: type (`store` is `never` on tenant), container (no
 store binding registered), object (`WorkerRuntime`/`ProxyRunGateway` have no
 store field).
@@ -91,7 +107,7 @@ database:
 
 ```ts title="config/durable.ts (tenant pod, queue transport)"
 export default defineConfig({
-  role: 'tenant',
+  topology: 'tenant',
   transport: 'queue',
   transports: { queue: transports.queue({ connection: 'redis', workerKeys: false }) },
   partition: 'acme-corp',
@@ -117,9 +133,9 @@ applies a decision by run id). Needs the
 
 ## Core patterns
 
-### Pattern 1 — role-portable code via `runGateway`
+### Pattern 1 — topology-portable code via `runGateway`
 
-Every role exposes the same read/control surface; identical controller code runs
+Every topology exposes the same read/control surface; identical controller code runs
 on a store pod (direct reads) or a store-less pod (wire requests answered by the
 control plane's `RunRequestResponder`):
 
@@ -146,7 +162,7 @@ Verbs: `getRun`, `listRuns`, `getCheckpoints`, `getRunChildren`,
 `workerHealth`, `subscribe`, `topology()`, and the NestJS gateway's `retry`
 (in-place requeue), `continue` (breakpoint), `retryWithInput`, `runFacets`,
 `runValueFacets`, `waitingFor` (optional on the interface; both built-in
-gateways implement them, tenant-scoped by the responder). Never branch on `role`.
+gateways implement them, tenant-scoped by the responder). Never branch on `topology`.
 
 ```ts
 // Each fan of more than 50 members — or declared wider than 50 — comes back as one FanSummary in `fans`.
@@ -162,7 +178,7 @@ tenant console degrades `retry` to a re-dispatch; it remembers the old control
 plane for a minute. `republishLifecycle` and `workflowLifecycle` have no fallback —
 the proxy rejects with `RunGatewayError` (`unsupported-request`), which the dashboard
 answers as `501`. Every request gets a reply, even when the gateway throws.
-Source: `docs/cluster/roles-and-config.mdx`.
+Source: `docs/cluster/topology-and-config.mdx`.
 
 ### Pattern 2 — capability-aware routing and blocked runs
 
@@ -256,7 +272,7 @@ fails fast rather than hanging. Source: `docs/python.mdx`,
 
 ## Common mistakes
 
-### HIGH launching `durable:worker` on a store-backed role
+### HIGH launching `durable:worker` on a store-backed topology
 
 Wrong:
 
@@ -270,7 +286,7 @@ Correct:
 node ace durable:work     # the store-backed dispatch/recovery/timers/schedules loop
 ```
 
-Mechanism: `durable:worker` boots the store-less `WorkerRuntime`; on a role that
+Mechanism: `durable:worker` boots the store-less `WorkerRuntime`; on a topology that
 owns a store it logs a warning and refuses — the two commands are different
 topologies, not aliases. Source: `docs/cli.mdx`.
 
@@ -335,10 +351,14 @@ Correct:
 transports.bullmq({ connection: REDIS_URL, partition: 'david-dev' })
 ```
 
-Mechanism: a worker on no partition serves the bare `<name>` tokens — exactly
-the queues the deployed fleet consumes — so the local process steals production
-tasks; docs call this out under Tenancy pitfalls ("competes for, and steals, the
-deployed fleet's tasks"). Source: `docs/concepts/tenancy.mdx`.
+Mechanism: a worker on no partition and no non-`default` namespace serves the
+bare `<name>` tokens — exactly the queues the deployed fleet consumes — so the
+local process steals production tasks; docs call this out under Tenancy pitfalls
+("competes for, and steals, the deployed fleet's tasks"). With a non-`default`
+namespace and no `partition`, the `db`/`queue`/`bullmq` transports serve
+`<name>@<namespace>` instead, matching what that engine dispatches to (an
+explicit `partition`, including `'default'` for the bare tokens, still wins).
+Source: `docs/concepts/tenancy.mdx`.
 
 ### HIGH a db-transport tenant pod on a database of its own
 
@@ -346,14 +366,14 @@ Wrong:
 
 ```ts
 // the pod's default Lucid connection is its own app database
-defineConfig({ role: 'tenant', transport: 'db', transports: { db: transports.db() }, partition: 'acme' })
+defineConfig({ topology: 'tenant', transport: 'db', transports: { db: transports.db() }, partition: 'acme' })
 ```
 
 Correct:
 
 ```ts
 // a connection to the CONTROL PLANE's database (config/database.ts), used only for the transport tables
-defineConfig({ role: 'tenant', transport: 'db', transports: { db: transports.db({ connection: 'durable' }) }, partition: 'acme' })
+defineConfig({ topology: 'tenant', transport: 'db', transports: { db: transports.db({ connection: 'durable' }) }, partition: 'acme' })
 ```
 
 Mechanism: on `db` the wire IS the transport tables, so a pod writing its

package/skills/durable-reliability/SKILL.md

@@ -10,7 +10,7 @@ description: >-
   the dead-letter queue (maxRecoveryAttempts, deadLetterWorkflow, deadLetter()
   method, onDead, retryWithInput), retention (maxAge/maxCount policies), the
   stuck-run playbook (stranded signature, redispatchPending,
-  remoteRedispatchMs, remoteAdvanceSilenceMs for remote workflow turns), ace ops commands (durable:work/runs/retry --stale), and
+  remoteRedispatchMs, remoteAdvanceSilenceMs for remote workflow turns), ace ops commands (durable:work, durable:runs, durable:runs:retry --stale), and
   the testing harness (createTestEngine, tick, failOnce, conformance kits).
 license: MIT
 metadata:
@@ -94,8 +94,8 @@ envelope (`{ input, output }`). Engine-level `compensationRetries` (default 1)
 bounds transient undo failures; failing compensations are skipped so they can't
 mask the original error. Trigger deliberately with
 `await engine.cancel(runId, { compensate: true })` or
-`engine.cancelWhere(filter, { compensate: true })`. The cancel is durable (a
-`cancel:<runId>` marker) and honored on every exit of the turn running when it
+`engine.cancelWhere(filter, { compensate: true })`. The cancel is durable (the
+persisted `cancelling` status) and honored on every exit of the turn running when it
 lands: return, throw, continue-as-new or suspend all compensate and settle
 `cancelled`. Every undo surfaces as a visible `compensate:<step>` event.
 Source: `docs/reliability/sagas.mdx`.
@@ -142,7 +142,7 @@ status into a handler workflow — the engine starts it as `dlq:<runId>`
 (idempotent) with a `DeadLetter` input `{ deadRunId, workflow, input, error }`
 in the dead run's namespace. A run
 whose remote step is still in flight is parked `suspended`, never counted, and a
-retry (`requeue` / `durable:retry`) of a `dead`/`failed` run resets
+retry (`requeue` / `durable:runs:retry`) of a `dead`/`failed` run resets
 `recoveryAttempts` to 0:
 
 ```ts title="config/durable.ts"
@@ -168,7 +168,7 @@ throws. A `dlq:` handler run that dies is not routed again; a failed start
 (handler not registered) is `console.warn`-ed. `engine.onDead(run => …)` still
 fires first and is the manual escape hatch (keep the `dlq:<runId>` id).
 
-A dead run stays inspectable and retriable (`durable:retry <runId>`, dashboard
+A dead run stays inspectable and retriable (`durable:runs:retry <runId>`, dashboard
 retry, or `engine.retryWithInput(runId, fixedInput)` for bad data).
 Source: `docs/reliability/dead-letter.mdx`.
 
@@ -194,10 +194,16 @@ signature: status `suspended`, stale `updatedAt`, newest checkpoint
 `kind: 'remote' / status: 'pending'`, old `enqueuedAt`. Find it, then heal it:
 
 ```bash
-node ace durable:runs --stale=1h   # threshold above your longest legitimate step
-node ace durable:retry checkout:1234
+node ace durable:runs --stale=1h          # threshold above your longest legitimate step
+node ace durable:runs:redispatch checkout:1234 --force   # re-send the lost step
+node ace durable:runs:retry checkout:1234                # or re-run from its checkpoints
 ```
 
+Every console action has an ace twin that runs the console's own handler
+(`durable:runs:show`, `durable:runs:cancel`, `durable:runs:signal`,
+`durable:runs:bulk`, `durable:schedules:pause`, `durable:health`, …; `--json` on
+reads, `--force` to skip a confirmation). See `docs/cli.mdx`.
+
 ```ts title="app/controllers/ops_controller.ts"
 import type { HttpContext } from '@adonisjs/core/http'
 import { DEFAULT_STALE_MS, attachLiveness, filterStale, listRuns } from '@adonis-agora/durable'