@ductape/mcp 0.1.50 → 0.1.52

package/dist/index.js

@@ -932,7 +932,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
     "storage.create", "storage.update"
 
   When to use this tool:
-  - Before calling ductape_execute to create or update any asset — use this to discover required fields
+  - Before constructing an administrative asset file for ductape_cli or Workbench — use this to discover required fields
   - To enumerate valid enum values (e.g. which DatabaseTypes or AuthTypes are accepted)
   - To understand nested object shapes without reading SDK docs
 `;
@@ -973,6 +973,9 @@ const payloadGenerateInputSchema = z.object({
         'For messaging: { broker: "broker_tag", topic?: "topic_tag" }.'),
     include_session: z.boolean().optional().default(true).describe('Include a session placeholder inside the generated input object. ' +
         'The placeholder is named "<session_tag_token>" to indicate it expects the runtime JWT, not the tag name.'),
+    execution_context: z.enum(['user', 'delegated', 'system']).optional().default('user').describe('Actor intent for this runtime operation. "user" means an active request initiated by the authenticated user; ' +
+        '"delegated" means work acting on behalf of a user with a short-lived delegated identity or application-owned ' +
+        'immutable actor context; "system" means intentionally unattributed background work. This drives session warnings.'),
     include_cache: z.boolean().optional().default(true).describe('Include the cache tag inside the generated input object so the caller knows which cache to reference for this query.'),
     schema_mode: z.enum(['strict', 'best_effort']).optional().default('best_effort').describe('"strict" — fail if any required field cannot be resolved. ' +
         '"best_effort" — fill what is known, leave unknowns as null/placeholder. Use best_effort when exploring.'),
@@ -1061,6 +1064,43 @@ function buildSdkInvocationArgs(payload) {
         ...(payload?.cache ? { cache: payload.cache } : {}),
     };
 }
+function operationAcceptsSession(operationFamily, method) {
+    const family = operationFamily.toLowerCase();
+    const sessionFamilies = new Set([
+        'action', 'features', 'feature', 'database', 'graph', 'vector', 'storage',
+        'notification', 'messaging', 'broker', 'events', 'event', 'quota', 'fallback',
+    ]);
+    if (!sessionFamilies.has(family))
+        return false;
+    return !['consume', 'status', 'check', 'fetch', 'list'].includes(method.toLowerCase());
+}
+function addSessionAwarenessMetadata(generated, args) {
+    const acceptsSession = operationAcceptsSession(args.operation_family, args.method);
+    const executionContext = args.execution_context ?? 'user';
+    const payloadHasSession = Boolean(generated?.payload?.session || generated?.payload?.input?.session);
+    const sessionRequested = args.include_session !== false;
+    const warnings = [];
+    if (acceptsSession && executionContext !== 'system' && (!sessionRequested || !payloadHasSession)) {
+        warnings.push(`Session attribution is missing for a ${executionContext}-context operation. ` +
+            'Pass the original full session token for immediate user work, or an approved delegated identity/immutable actor context for delayed work.');
+    }
+    if (executionContext === 'system' && payloadHasSession) {
+        warnings.push('This operation is marked system-context but contains a session placeholder. Remove it unless the work is actually user/delegated.');
+    }
+    generated.meta = {
+        ...(generated?.meta ?? {}),
+        session_awareness: {
+            accepts_session: acceptsSession,
+            execution_context: executionContext,
+            appears_user_context: executionContext === 'user',
+            session_requested: sessionRequested,
+            session_present_in_payload: payloadHasSession,
+            intentionally_system_context: executionContext === 'system',
+            warnings,
+        },
+    };
+    return generated;
+}
 function buildTypeScriptSnippet(payload, operationFamily, method) {
     const callPath = resolveSdkCallPath(operationFamily, method);
     const invocationArgs = buildSdkInvocationArgs(payload);
@@ -1405,33 +1445,9 @@ DUCTAPE DATABASE MIGRATIONS
 
 Migrations are versioned SQL/NoSQL schema change scripts managed per database component.
 
-Create a migration:
-  ductape_execute("databases.migration.create", [{
-    product: "my-product",
-    database: "core-db",
-    data: {
-      name: "add users table",
-      tag: "001-add-users",
-      value: {
-        up:   ["CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT NOT NULL UNIQUE)"],
-        down: ["DROP TABLE users"],
-      },
-    },
-  }])
-
-Run migrations (applies all pending):
-  ductape_execute("databases.migration.run", [migrations, { env: "prd" }])
-
-Rollback:
-  ductape_execute("databases.migration.rollback", [migrations, 1])  // roll back 1
-
-Check status:
-  ductape_execute("databases.migration.status", [migrations])
-
-History:
-  ductape_execute("databases.migration.history", [])
+Create migrations through the project migration files and ductape_cli, never ductape_execute.
 
-Via CLI:
+Use the access-key administrative CLI for running, rolling back, and inspecting migrations:
   ductape_cli("db migrate")              // run pending
   ductape_cli("db migrate rollback")     // roll back last
   ductape_cli("db migrate rollback -n 3")
@@ -1441,25 +1457,13 @@ MongoDB: migrations run as raw Mongo shell commands in the up/down arrays.
     indexes: `
 DUCTAPE DATABASE INDEXES
 
-Create an index:
-  ductape_execute("databases.schema.createIndex", [
-    "collection_name",
-    ["field1", "field2"],           // simple array of field names
-    { unique: true, name: "idx_email_unique" }   // options (optional)
-  ])
+Create or update indexes through migration files and ductape_cli("db migrate"), not the
+publishable-key runtime proxy. Example definitions may use ["field1", "field2"] with
+{ unique: true, name: "idx_email_unique" }, or ordered fields such as
+[{ field: "createdAt", order: "DESC" }, { field: "userId", order: "ASC" }].
 
-  // Ordered index:
-  ductape_execute("databases.schema.createIndex", [
-    "orders",
-    [{ field: "createdAt", order: "DESC" }, { field: "userId", order: "ASC" }],
-    { name: "idx_orders_date_user" }
-  ])
-
-Drop an index:
-  ductape_execute("databases.schema.dropIndex", ["collection_name", "index_name"])
-
-List indexes on a collection:
-  ductape_execute("databases.schema.indexes", ["collection_name"])
+Drop and inspect indexes through migration/CLI tooling or the database administration surface,
+not ductape_execute.
 
 Performance guidance:
   - Index fields used in WHERE clauses, JOIN conditions, and ORDER BY.
@@ -1503,18 +1507,7 @@ DUCTAPE DATABASE ACTIONS
 A database action is a saved query or mutation (SQL string or NoSQL command) stored
 on the Ductape product and executed by tag at runtime.
 
-Create an action (admin):
-  ductape_execute("databases.action.create", [{
-    product: "my-product",
-    database: "core-db",
-    data: {
-      tag: "get-active-users",
-      name: "Get active users",
-      description: "Returns all users with status=active",
-      type: "sql",                    // "sql" or "nosql"
-      query: "SELECT * FROM users WHERE status = :status",
-    },
-  }])
+Create/update actions in Workbench (administrative access), never through ductape_execute.
 
 Dispatch an action at runtime:
   → CALL ductape_generate_payload FIRST to get the canonical input shape.
@@ -1529,10 +1522,9 @@ Dispatch an action at runtime:
 List actions for a database:
   ductape_execute("databases.action.list", ["database_tag"])
 
-Fetch / update / delete:
+Fetch:
   ductape_execute("databases.action.fetch",  ["action_tag"])
-  ductape_execute("databases.action.update", ["my-product", "action_tag", { query: "..." }])
-  ductape_execute("databases.action.delete", ["action_tag"])
+Update/delete are administrative and must be performed in Workbench.
 
 Actions are the preferred way to encapsulate complex or reused queries — they can be
 scheduled, dispatched with retries, and audited via logs.
@@ -1790,16 +1782,8 @@ DUCTAPE SECRETS
 Secrets are workspace-level encrypted key-value pairs. They are referenced in resource configs,
 connection URLs, and any string field using the $Secret{KEY_NAME} syntax.
 
-Create (admin — ductape_cli or ductape_execute):
-  ductape_execute("secrets.create", [{
-    key: "STRIPE_API_KEY",
-    value: "sk_live_...",          // plaintext — encrypted AES-256-GCM client-side before send
-    description: "Stripe live key",
-    token_type: "api",             // "api" | "password" | "certificate"
-    scope: ["my-product"],         // which products can read this secret
-    envs: ["prd"],                 // which env slugs can read this secret
-    expires_at: 1800000000,        // optional epoch ms
-  }])
+Create/update secrets with ductape_cli or Workbench (administrative access), never ductape_execute.
+Definition fields include key, value, description, token_type, scope, envs, and expires_at.
   The server never receives the plaintext value. Encryption uses the workspace private key.
 
 Fetch / resolve:
@@ -1814,10 +1798,7 @@ $Secret{} reference syntax:
   - The in-memory cache stores the encrypted form only; decryption happens on each cache hit.
   - Cache TTL: 5 minutes. Clear with: secrets.clearCache()
 
-Lifecycle:
-  ductape_execute("secrets.revoke", ["KEY"])   → disables without deleting (recoverable)
-  ductape_execute("secrets.delete", ["KEY"])   → permanent deletion (irreversible)
-  ductape_execute("secrets.update", ["KEY", { value: "new_value", expires_at: ... }])
+Lifecycle mutations (revoke/delete/update) are administrative: use ductape_cli or Workbench.
 
 List all secrets (keys only — values are not returned in list):
   ductape_execute("secrets.list", [])
@@ -1867,9 +1848,7 @@ Import from a file:
   ductape_cli("apps import <file.json> -t postman|openapi")
   Supports Postman v2.1 collection and OpenAPI 3.0 spec.
 
-Manage environments (base URLs per stage):
-  ductape_execute("app.environments.create", [app_tag, { slug, env_name, base_url }])
-  ductape_execute("app.environments.list",   [app_tag])
+Manage environments (base URLs per stage) in Workbench; this currently has no CLI command.
 
 Discover apps in a product and their actions (ALWAYS do this before writing any ctx.api.run call):
   Step 1 — list apps connected to the product:
@@ -1886,16 +1865,8 @@ Discover apps in a product and their actions (ALWAYS do this before writing any
            app resources (not for runtime input — use actions.fetch or ductape_generate_payload for that)
   NEVER assume action input field names. Always fetch the action definition first.
 
-Manage actions (individual API endpoints):
-  ductape_execute("actions.create", [app_tag, {
-    tag, name, resource: "/users/{id}", method: "GET"|"POST"|"PUT"|"PATCH"|"DELETE",
-    body?: { fieldName: { type, required? } },
-    params?: { id: { type: "string" } },
-    query?: { filter: { type: "string" } },
-    headers?: { Authorization: { type: "string" } },
-    response?: { status_code: 200, success: true, body: { ... }, response_format: "json" },
-  }])
-  ductape_execute("actions.update", [app_tag, action_tag, data])
+Manage actions (individual API endpoints) in Workbench or import an OpenAPI/Postman file.
+Creation/update are administrative and must never use ductape_execute.
   ductape_execute("actions.list",   [app_tag])
   ductape_execute("actions.fetch",  [app_tag, action_tag])
 
@@ -1916,16 +1887,14 @@ Run an action at runtime:
 
 Auth schemes (how the app authenticates outbound requests):
   Setup types: header | bearer | basic | oauth2 | apikey
-  ductape_execute("auths.create", [app_tag, { tag, name, setup_type, expiry, period, action_tag? }])
+  Configure auth in Workbench (administrative).
   ductape_execute("auths.list",   [app_tag])
 
 Webhooks (inbound events from the external service):
-  ductape_execute("webhooks.create", [app_tag, { tag, name, description, envs: [{ slug, registration_url?, method? }] }])
-  ductape_execute("webhooks.events.create", [app_tag, { tag, name, selector, description, sample }])
+  Configure webhooks and webhook events in Workbench (administrative).
 
 Variables (per-env mutable values) and Constants (fixed values):
-  ductape_execute("app.variables.create", [app_tag, { key, value, env_slug }])
-  ductape_execute("app.constants.create", [app_tag, { key, value }])
+  Configure variables and constants in Workbench (administrative).
 
 Connecting an app to a product (after creation):
   NOTE: All product.* module methods require the access key and CANNOT use ductape_execute.
@@ -1933,14 +1902,13 @@ Connecting an app to a product (after creation):
 
   FULL FLOW to make an app callable from a product:
   1. Create the app:     ductape_cli("apps create --name \\"Service Name\\" --description \\"...\\"")
-  2. Add environments:   ductape_execute("app.environments.create", [app_tag, { slug: "prd", env_name: "Production", base_url: "https://api.example.com" }])
-  3. Configure auth:     ductape_execute("auths.create", [app_tag, { tag, name, setup_type: "apikey"|"bearer"|"basic"|"oauth2", expiry, period }])
-  4. Define actions:     ductape_execute("actions.create", [app_tag, { tag, name, resource, method, body?, params?, query?, headers?, response? }])
+  2. Add environments:   Workbench
+  3. Configure auth:     Workbench
+  4. Define actions:     Workbench
                          OR import: ductape_cli("apps import <file.json> -t postman|openapi")
   5. Connect to product: Requires the product_id (from ductape_cli("products get --tag <tag> --json")).
                          There is no CLI command for this step — the SDK product.apps.add method requires
-                         an access key which only the backend can provide. Use ductape_execute via an
-                         admin-authenticated context, or connect via the Workbench UI.
+                         an access key which only the backend can provide. Connect via Workbench.
   6. Verify:             ductape_cli("products get --tag <product_tag> --json") → check apps[] contains the app
                          ductape_execute("actions.list", [app_tag]) → verify actions are registered
 `.trim(),
@@ -2015,8 +1983,8 @@ IMPORTANT — selector must be "$Session{fieldName}" format:
   CORRECT:   selector: "$Session{playerId}"
   INCORRECT: selector: "playerId"   ← WILL FAIL with "Selector should be in the format $Session{...}{key}"
 
-Example (game product — player identity in JWT):
-  ductape_execute("sessions.create", [product_tag, {
+Example definition (configure via declarative apply or Workbench, not ductape_execute):
+  {
     tag: "player-session",
     name: "Player Session",
     expiry: 24,
@@ -2028,7 +1996,7 @@ Example (game product — player identity in JWT):
       role:      "player",
       accountId: "acct_xyz",
     },
-  }])
+  }
 
 Runtime — create a session (sign a JWT):
   → CALL ductape_generate_payload FIRST (operation_family="session", method="start", targets={tag})
@@ -2068,10 +2036,33 @@ Token format: "session_tag:jwt_token" — pass this format verbatim wherever ses
 JWT is signed with the product private key (not a symmetric shared secret).
 
 SESSION PROPAGATION
-  Preserve the original full token on every user-context database, Event, Feature, notification,
-  storage, graph, vector, action, and other runtime operation that accepts session. Do not replace
-  it with the session tag, user ID, decoded claims, or refresh token. Durable user-initiated work
-  should retain the initiating token; intentional system/background work should be sessionless.
+  Extract the original full "session_tag:jwt" token once at the HTTP/transport boundary and retain
+  it separately from verified/decoded claims. Claims are authorization data; they are not a token.
+  Store a request ActorContext in a NestJS request-scoped provider or AsyncLocalStorage:
+    type ActorContext =
+      | { kind: "user"; session: string; actorId: string }
+      | { kind: "delegated"; delegatedIdentity: string; actorId: string; initiatedAt: string }
+      | { kind: "system"; reason: string };
+  Pass ActorContext explicitly through service boundaries. At each immediate Ductape runtime call,
+  pass actor.kind === "user" ? actor.session : the SDK-approved delegated identity. Put only
+  non-secret actor metadata (actorId, kind, initiatedAt, correlationId) in Event envelopes.
+  Feature execution should receive the same explicit actor classification. Never log, serialize
+  into business payloads, or attach the raw session/refresh token to traces or error messages.
+
+  SECURITY BOUNDARY FOR DURABLE WORK
+  The current SDK accepts a session string on dispatch, but it does not expose an immutable
+  attribution snapshot API, an expired-token attribution contract, or a general delegated-session
+  issuer. Therefore do NOT persist reusable JWTs indefinitely or assume an expired initiating token
+  will remain valid when delayed work executes. Pass the full token only for immediate work within
+  its validity window. For delayed/recurring work, classify execution as system-context, or use an
+  application-owned immutable actor-context envelope plus a short-lived delegated identity issued
+  by an explicitly approved auth design. Until the SDK provides that design, actor metadata is for
+  audit/correlation and must not be treated as authorization.
+
+  Distinguish contexts deliberately:
+    user      — active request; original valid full token is required when the operation accepts it
+    delegated — delayed/on-behalf-of work; approved short-lived credential + immutable actor metadata
+    system    — scheduler/maintenance with no user authority; omit session and record a reason
 
   Backend propagation attributes component activity to an actor, but it does not record frontend
   pageviews, navigation, UI intent, funnels, or client failures. Continue immediately with
@@ -2082,14 +2073,12 @@ DUCTAPE CACHES
 
 Caches are product-level Redis (or in-memory) stores for temporary key-value data with optional TTL.
 
-Registration (admin — ductape_cli or SDK):
+Registration (admin — ductape_cli):
   ductape_cli("resources caches create -f cache.json")
   File: { name, tag, description?, expiry: <milliseconds> }
   No type or envs — Ductape manages the store infrastructure.
   expiry is in MILLISECONDS: 3600000 = 1 hour, 86400000 = 1 day, 604800000 = 1 week.
 
-  SDK: ductape_execute("caches.create", [product_tag, { name, tag, description?, expiry: 3600000 }])
-
 Operations:
   caches.set   [{ product, cache, key, value: string, expiry?: string (ISO 8601), env }]
     expiry is an ABSOLUTE TIMESTAMP (not a duration).
@@ -2137,20 +2126,20 @@ DUCTAPE NOTIFICATIONS
 
 Notifications send messages across multiple channels: email, SMS, push, or HTTP callback.
 
-Create a notification (admin — ductape_execute):
-  ductape_execute("notifications.create", [product_tag, {
+Create a notification through declarative apply or Workbench (administrative), using:
+  {
     tag: "welcome-email",
     name: "Welcome Email",
     type: "email",   // optional hint; actual channels configured per env
-  }])
+  }
 
-Create a message template:
-  ductape_execute("notifications.messages.create", [product_tag, {
+Create a message template through declarative apply or Workbench:
+  {
     tag: "welcome-email:default",       // format: "notification_tag:message_tag"
     notification: "welcome-email",
     subject: { template: "Welcome, {{name}}!", data: { name: "" } },
     body:    { template: "Hi {{name}}, thanks for signing up.", data: { name: "" } },
-  }])
+  }
 
 Send at runtime (one channel at a time):
   → CALL ductape_generate_payload FIRST (operation_family="notification", method="email.send")
@@ -2188,8 +2177,15 @@ DUCTAPE RESILIENCE
 Resilience covers three mechanisms: quotas (rate-limited provider pools), fallbacks (automatic
 provider switching), and healthchecks (continuous probe monitoring with failure actions).
 
+CONFIGURATION BOUNDARY
+  Quotas, fallbacks, and health checks are administrative product configuration. Configure them in
+  Workbench (or a future access-key administrative tool explicitly documented for the asset).
+  Never route administrative create/update methods through ductape_execute: its publishable-key
+  runtime proxy will fail.
+
 QUOTAS — rate-limited multi-provider pools:
-  ductape_execute("quotas.create", [product_tag, {
+  Workbench definition shape:
+  {
     tag: "sms-quota",
     name: "SMS Provider Pool",
     input: { to: { type: "string", required: true }, message: { type: "string" } },
@@ -2203,7 +2199,7 @@ QUOTAS — rate-limited multi-provider pools:
         input: { "body:to": "$Input{to}", "body:body": "$Input{message}" },
         output: {} },
     ],
-  }])
+  }
   Providers are tried in order until quota is not exhausted.
   quotas.run      [{ product, env, tag, input }]  ← CALL ductape_generate_payload FIRST
   quotas.dispatch [{ product, env, tag, input, schedule? }]
@@ -2211,12 +2207,13 @@ QUOTAS — rate-limited multi-provider pools:
 FALLBACKS — automatic provider switching on failure:
   Same schema as quotas but options are ordered: primary first, then fallback(s).
   Primary is used first; on failure, the next provider is tried automatically.
-  ductape_execute("fallback.create", [product_tag, { tag, name, input: { ... }, options: [...] }])
+  Configure in Workbench: { tag, name, input: { ... }, options: [...] }
   fallback.run      [{ product, env, tag, input }]  ← CALL ductape_generate_payload FIRST
   fallback.dispatch [{ product, env, tag, input, schedule? }]
 
 HEALTHCHECKS — continuous probe with failure notifications:
-  ductape_execute("health.create", [product_tag, {
+  Workbench definition shape:
+  {
     tag: "payment-health",
     name: "Payment Service Health",
     probe: { type: "app", app: "stripe-app", event: "ping" },
@@ -2228,7 +2225,7 @@ HEALTHCHECKS — continuous probe with failure notifications:
         channels: { email: { recipients: ["ops@example.com"] } } }],
       webhooks: [{ url: "https://hooks.example.com/alert", method: "POST" }],
     },
-  }])
+  }
   health.run    [{ product, env, tag }]   → triggers an immediate probe
   health.check  [{ product, env, tag }]   → same as run
   health.status [{ product, env, tag }]   → current health status
@@ -2238,6 +2235,23 @@ Failure actions: notification channels, HTTP webhooks, and/or message broker emi
   be configured simultaneously on the same healthcheck.
 Input template references: $Input{field} → maps declared input to the probe's action input.
 Provider status: available | unavailable
+
+DECISION MATRIX
+  Rate/capacity allocation across providers       → quota
+  Equivalent provider after operational failure   → fallback
+  Detect failure before routing provider traffic  → health check
+  Transient failure of one operation              → bounded retry + idempotency policy
+  Multi-step business recovery/compensation       → Feature
+  Database atomicity                              → database transaction, not Feature rollback
+  Scheduled single operation                      → that component's dispatch
+  Scheduled multi-step process                    → Feature dispatch
+
+COMBINING MECHANISMS
+  A health check may keep an unhealthy provider out of a fallback/quota pool; the pool controls
+  provider selection; each operation may use bounded retries and an idempotency key; a Feature
+  coordinates business steps and compensation around those resilient operations. Do not stack them
+  reflexively: each layer needs a distinct failure it owns, bounded retry budgets, and observable
+  terminal behavior. Database transactions remain the atomicity boundary for related DB writes.
 `.trim(),
     'frontend-analytics': `
 DUCTAPE FRONTEND PRODUCT ANALYTICS AND SESSION ACTIVITY
@@ -2245,10 +2259,12 @@ DUCTAPE FRONTEND PRODUCT ANALYTICS AND SESSION ACTIVITY
 Frontend analytics and backend session attribution are complementary; neither replaces the other.
 
 BACKEND OPERATION ATTRIBUTION
-  Pass the original full Ductape session token to every user-initiated database, Event, Feature,
-  notification, storage, graph, vector, action, and other runtime operation that accepts session.
-  This attributes server work to the authenticated actor. Durable work should retain the initiating
-  session; intentional system/background work should remain sessionless.
+  Immediate user-initiated backend work should pass the original full Ductape session token to every
+  database, Event, Feature, notification, storage, graph, vector, action, and other runtime operation
+  that accepts session. This attributes immediate server work to the authenticated actor.
+  For delayed/durable work, do not persist raw JWTs indefinitely. Use system context, or an approved
+  delegated actor design with immutable non-secret actor metadata. Actor metadata supports audit and
+  correlation; it is not authorization. Intentional system/background work should remain sessionless.
 
 FRONTEND PRODUCT ANALYTICS
   Use the browser Analytics service for anonymous visits, authenticated page views, navigation,
@@ -2517,9 +2533,11 @@ STEP 4 — PRESENT the plan and get approval BEFORE writing any code or creating
   Wait for confirmation before writing code or calling any create tool.
 
 STEP 5 — CREATE missing components (only with user approval)
-  Use ductape_execute for any missing databases, apps, database actions, notification events, etc.
-  For a missing database action:
-    ductape_execute("databases.action.create", [product_tag, db_tag, { tag, name, type, query }])
+  Administrative assets must never be created through ductape_execute. Use ductape_cli for products,
+  apps, supported resources, broker topics, cloud connections, secrets, and declarative apply flows.
+  App actions, auths, Features, quotas, fallbacks, health checks, and other assets for which the CLI
+  has no command must be configured in Workbench. Do not generate an impossible publishable-key
+  create/update call. For a missing database action, configure it in Workbench, then verify it exists.
   For a missing child feature, recursively apply this same workflow.
   Tell the user what you are about to create before each tool call.
 
@@ -2643,7 +2661,11 @@ When you call features.define({ handler }), the handler runs TWICE:
 
   Invoke internal application business logic (your own NestJS/backend service code):
     → produce a broker event (ctx.messaging.produce or ductape.events.produce)
-    → consume it in your NestJS service with events.consume in onModuleInit
+    → follow ductape_docs({ topic: "events" }) and use the canonical NestJS decorator:
+      @Events.Consumer({ event: "broker-tag:topic-tag" })
+      async handle(message: MessageShape) { /* injected-service business logic; throw to nack */ }
+    → DuctapeModule auto-registers the decorated consumer; no manual onModuleInit is needed
+    → events.consume() remains a supported lower-level alternative for plain TypeScript/Node.js
     → your service method runs with full access to DI, DB transactions, etc.
     Do NOT create an App Action just to call your own service over HTTP.
 
@@ -3689,6 +3711,22 @@ async function main() {
     };
     const executeHandler = async (args) => {
         try {
+            const runtimeMutationMethods = {
+                databases: new Set(['insert', 'update', 'delete', 'upsert']),
+                graph: new Set(['insert', 'update', 'delete']),
+                vector: new Set(['insert', 'upsert', 'upsertOne', 'delete']),
+                sessions: new Set(['revoke']),
+            };
+            const isRuntimeDataMutation = runtimeMutationMethods[args.module]?.has(args.method) === true;
+            const isAdministrativeMutation = (/^migration\./.test(args.method) ||
+                /^schema\.(create|drop|add|remove|update)/.test(args.method) ||
+                /(^|\.)(create|update|delete|configure|add|remove|revoke)$/.test(args.method)) &&
+                !isRuntimeDataMutation;
+            if (isAdministrativeMutation) {
+                throw new Error(`Administrative operation "${args.module}.${args.method}" is blocked in ductape_execute. ` +
+                    'Use ductape_cli when that resource is supported by the CLI; otherwise configure it in Workbench. ' +
+                    'The runtime proxy uses a publishable key and cannot administer platform assets.');
+            }
             const key = args.publishable_key || process.env.DUCTAPE_PUBLISHABLE_KEY;
             if (!key) {
                 throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
@@ -3735,7 +3773,7 @@ async function main() {
             if (!key) {
                 throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
             }
-            const result = await generateExecutablePayload({ ...args, publishable_key: key });
+            const result = addSessionAwarenessMetadata(await generateExecutablePayload({ ...args, publishable_key: key }), args);
             let text = JSON.stringify(result ?? null, null, 2);
             if (args.operation_family === 'database') {
                 const meta = result?.meta ?? {};
@@ -3762,7 +3800,7 @@ async function main() {
                 throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
             }
             ensureSupportedSnippetOperation(args.operation_family, args.method);
-            const generated = await generateExecutablePayload({ ...args, publishable_key: key });
+            const generated = addSessionAwarenessMetadata(await generateExecutablePayload({ ...args, publishable_key: key }), args);
             const payload = generated?.payload ?? {};
             const snippet = buildSnippet(args.language, payload, args.operation_family, args.method);
             return {
@@ -3915,7 +3953,7 @@ async function main() {
                 '    Step 2 — check if the database component already exists:\n' +
                 '      ductape_cli("resources databases list <product_tag> --json")\n' +
                 '      If a component already uses the same Atlas cluster, do NOT re-import — instead update it:\n' +
-                '        ductape_execute("databases.updateDatabase", [product_tag, db_tag, { envs: [...updated envs...] }])\n' +
+                '        use ductape_cli resource update when supported; otherwise update it in Workbench\n' +
                 '      Add or change the dbName in the env\'s connection_url to switch databases on the same cluster.\n' +
                 '    Step 3 — import (only if no existing component uses this cluster):\n' +
                 '      Use import-persist-all with one entry per product env. Required fields per entry:\n' +

package/dist/proxy-client.d.ts

@@ -15,6 +15,7 @@ export interface IGenerateExecutablePayloadRequest {
     method: string;
     targets?: Record<string, unknown>;
     include_session?: boolean;
+    execution_context?: 'user' | 'delegated' | 'system';
     include_cache?: boolean;
     schema_mode?: 'strict' | 'best_effort';
     input_hint?: Record<string, unknown>;

package/dist/proxy-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy-client.d.ts","sourceRoot":"","sources":["../src/proxy-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,YAAY,4BAA4B,CAAC;AAEtD,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,KAAK,GACL,WAAW,GACX,OAAO,GACP,UAAU,GACV,eAAe,GACf,gBAAgB,GAChB,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,SAAS,GACT,UAAU,GACV,MAAM,GACN,MAAM,GACN,YAAY,GACZ,QAAQ,GACR,UAAU,GACV,SAAS,CAAC;AAUd;;GAEG;AACH,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAC/C,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,CAAC,CAAC,CAuBZ;AAED,MAAM,WAAW,iCAAiC;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,kCAAkC;IACjD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AASD,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAYvE;AA4BD,wBAAsB,yBAAyB,CAAC,CAAC,GAAG,kCAAkC,EACpF,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,CAAC,CAAC,CAwBZ"}
+{"version":3,"file":"proxy-client.d.ts","sourceRoot":"","sources":["../src/proxy-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,YAAY,4BAA4B,CAAC;AAEtD,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,KAAK,GACL,WAAW,GACX,OAAO,GACP,UAAU,GACV,eAAe,GACf,gBAAgB,GAChB,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,SAAS,GACT,UAAU,GACV,MAAM,GACN,MAAM,GACN,YAAY,GACZ,QAAQ,GACR,UAAU,GACV,SAAS,CAAC;AAUd;;GAEG;AACH,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAC/C,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,CAAC,CAAC,CAuBZ;AAED,MAAM,WAAW,iCAAiC;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACpD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,kCAAkC;IACjD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AASD,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAYvE;AA4BD,wBAAsB,yBAAyB,CAAC,CAAC,GAAG,kCAAkC,EACpF,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,CAAC,CAAC,CAwBZ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.1.50",
+  "version": "0.1.52",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",

package/scripts/check-frontend-analytics-guidance.mjs

@@ -34,4 +34,25 @@ assert.doesNotMatch(
   'MCP guidance must not use the obsolete identify({ userId, traits }) signature',
 );
 
-console.log(`frontend analytics guidance: ${checks.length + 1} acceptance checks passed`);
+const safetyChecks = [
+  ['admin execute calls removed', /ductape_execute\("[^"\n]*(?:create|update)/],
+  ['obsolete NestJS consumer removed', /events\.consume in onModuleInit/],
+  ['canonical NestJS consumer present', /@Events\.Consumer\(\{ event:/],
+  ['request actor context documented', /AsyncLocalStorage[\s\S]*ActorContext/],
+  ['raw token logging prohibited', /Never log,[\s\S]*raw session\/refresh token/],
+  ['durable token expiry semantics documented', /does not expose an immutable[\s\S]*expired-token attribution contract/],
+  ['frontend durable work prohibits persisted JWTs', /For delayed\/durable work, do not persist raw JWTs indefinitely/],
+  ['resilience decision matrix present', /DECISION MATRIX[\s\S]*Database atomicity/],
+  ['payload session-awareness metadata present', /session_awareness:[\s\S]*accepts_session/],
+  ['execute blocks administrative mutations', /Administrative operation.*is blocked in ductape_execute/],
+];
+
+for (const [name, pattern] of safetyChecks) {
+  if (name === 'admin execute calls removed' || name === 'obsolete NestJS consumer removed') {
+    assert.doesNotMatch(source, pattern, `Unsafe MCP guidance remains: ${name}`);
+  } else {
+    assert.match(source, pattern, `Missing MCP safety guidance: ${name}`);
+  }
+}
+
+console.log(`MCP guidance: ${checks.length + 1 + safetyChecks.length} acceptance checks passed`);

package/src/index.ts

@@ -943,7 +943,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
     "storage.create", "storage.update"
 
   When to use this tool:
-  - Before calling ductape_execute to create or update any asset — use this to discover required fields
+  - Before constructing an administrative asset file for ductape_cli or Workbench — use this to discover required fields
   - To enumerate valid enum values (e.g. which DatabaseTypes or AuthTypes are accepted)
   - To understand nested object shapes without reading SDK docs
 `;
@@ -998,6 +998,11 @@ const payloadGenerateInputSchema = z.object({
     'Include a session placeholder inside the generated input object. ' +
     'The placeholder is named "<session_tag_token>" to indicate it expects the runtime JWT, not the tag name.'
   ),
+  execution_context: z.enum(['user', 'delegated', 'system']).optional().default('user').describe(
+    'Actor intent for this runtime operation. "user" means an active request initiated by the authenticated user; ' +
+    '"delegated" means work acting on behalf of a user with a short-lived delegated identity or application-owned ' +
+    'immutable actor context; "system" means intentionally unattributed background work. This drives session warnings.'
+  ),
   include_cache: z.boolean().optional().default(true).describe(
     'Include the cache tag inside the generated input object so the caller knows which cache to reference for this query.'
   ),
@@ -1091,6 +1096,53 @@ function buildSdkInvocationArgs(payload: Record<string, unknown>): Record<string
   };
 }
 
+function operationAcceptsSession(operationFamily: string, method: string): boolean {
+  const family = operationFamily.toLowerCase();
+  const sessionFamilies = new Set([
+    'action', 'features', 'feature', 'database', 'graph', 'vector', 'storage',
+    'notification', 'messaging', 'broker', 'events', 'event', 'quota', 'fallback',
+  ]);
+  if (!sessionFamilies.has(family)) return false;
+  return !['consume', 'status', 'check', 'fetch', 'list'].includes(method.toLowerCase());
+}
+
+function addSessionAwarenessMetadata(
+  generated: any,
+  args: z.infer<typeof payloadGenerateInputSchema>,
+): any {
+  const acceptsSession = operationAcceptsSession(args.operation_family, args.method);
+  const executionContext = args.execution_context ?? 'user';
+  const payloadHasSession = Boolean(generated?.payload?.session || generated?.payload?.input?.session);
+  const sessionRequested = args.include_session !== false;
+  const warnings: string[] = [];
+
+  if (acceptsSession && executionContext !== 'system' && (!sessionRequested || !payloadHasSession)) {
+    warnings.push(
+      `Session attribution is missing for a ${executionContext}-context operation. ` +
+      'Pass the original full session token for immediate user work, or an approved delegated identity/immutable actor context for delayed work.',
+    );
+  }
+  if (executionContext === 'system' && payloadHasSession) {
+    warnings.push(
+      'This operation is marked system-context but contains a session placeholder. Remove it unless the work is actually user/delegated.',
+    );
+  }
+
+  generated.meta = {
+    ...(generated?.meta ?? {}),
+    session_awareness: {
+      accepts_session: acceptsSession,
+      execution_context: executionContext,
+      appears_user_context: executionContext === 'user',
+      session_requested: sessionRequested,
+      session_present_in_payload: payloadHasSession,
+      intentionally_system_context: executionContext === 'system',
+      warnings,
+    },
+  };
+  return generated;
+}
+
 function buildTypeScriptSnippet(
   payload: Record<string, unknown>,
   operationFamily: string,
@@ -1462,33 +1514,9 @@ DUCTAPE DATABASE MIGRATIONS
 
 Migrations are versioned SQL/NoSQL schema change scripts managed per database component.
 
-Create a migration:
-  ductape_execute("databases.migration.create", [{
-    product: "my-product",
-    database: "core-db",
-    data: {
-      name: "add users table",
-      tag: "001-add-users",
-      value: {
-        up:   ["CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT NOT NULL UNIQUE)"],
-        down: ["DROP TABLE users"],
-      },
-    },
-  }])
-
-Run migrations (applies all pending):
-  ductape_execute("databases.migration.run", [migrations, { env: "prd" }])
+Create migrations through the project migration files and ductape_cli, never ductape_execute.
 
-Rollback:
-  ductape_execute("databases.migration.rollback", [migrations, 1])  // roll back 1
-
-Check status:
-  ductape_execute("databases.migration.status", [migrations])
-
-History:
-  ductape_execute("databases.migration.history", [])
-
-Via CLI:
+Use the access-key administrative CLI for running, rolling back, and inspecting migrations:
   ductape_cli("db migrate")              // run pending
   ductape_cli("db migrate rollback")     // roll back last
   ductape_cli("db migrate rollback -n 3")
@@ -1499,25 +1527,13 @@ MongoDB: migrations run as raw Mongo shell commands in the up/down arrays.
   indexes: `
 DUCTAPE DATABASE INDEXES
 
-Create an index:
-  ductape_execute("databases.schema.createIndex", [
-    "collection_name",
-    ["field1", "field2"],           // simple array of field names
-    { unique: true, name: "idx_email_unique" }   // options (optional)
-  ])
+Create or update indexes through migration files and ductape_cli("db migrate"), not the
+publishable-key runtime proxy. Example definitions may use ["field1", "field2"] with
+{ unique: true, name: "idx_email_unique" }, or ordered fields such as
+[{ field: "createdAt", order: "DESC" }, { field: "userId", order: "ASC" }].
 
-  // Ordered index:
-  ductape_execute("databases.schema.createIndex", [
-    "orders",
-    [{ field: "createdAt", order: "DESC" }, { field: "userId", order: "ASC" }],
-    { name: "idx_orders_date_user" }
-  ])
-
-Drop an index:
-  ductape_execute("databases.schema.dropIndex", ["collection_name", "index_name"])
-
-List indexes on a collection:
-  ductape_execute("databases.schema.indexes", ["collection_name"])
+Drop and inspect indexes through migration/CLI tooling or the database administration surface,
+not ductape_execute.
 
 Performance guidance:
   - Index fields used in WHERE clauses, JOIN conditions, and ORDER BY.
@@ -1563,18 +1579,7 @@ DUCTAPE DATABASE ACTIONS
 A database action is a saved query or mutation (SQL string or NoSQL command) stored
 on the Ductape product and executed by tag at runtime.
 
-Create an action (admin):
-  ductape_execute("databases.action.create", [{
-    product: "my-product",
-    database: "core-db",
-    data: {
-      tag: "get-active-users",
-      name: "Get active users",
-      description: "Returns all users with status=active",
-      type: "sql",                    // "sql" or "nosql"
-      query: "SELECT * FROM users WHERE status = :status",
-    },
-  }])
+Create/update actions in Workbench (administrative access), never through ductape_execute.
 
 Dispatch an action at runtime:
   → CALL ductape_generate_payload FIRST to get the canonical input shape.
@@ -1589,10 +1594,9 @@ Dispatch an action at runtime:
 List actions for a database:
   ductape_execute("databases.action.list", ["database_tag"])
 
-Fetch / update / delete:
+Fetch:
   ductape_execute("databases.action.fetch",  ["action_tag"])
-  ductape_execute("databases.action.update", ["my-product", "action_tag", { query: "..." }])
-  ductape_execute("databases.action.delete", ["action_tag"])
+Update/delete are administrative and must be performed in Workbench.
 
 Actions are the preferred way to encapsulate complex or reused queries — they can be
 scheduled, dispatched with retries, and audited via logs.
@@ -1856,16 +1860,8 @@ DUCTAPE SECRETS
 Secrets are workspace-level encrypted key-value pairs. They are referenced in resource configs,
 connection URLs, and any string field using the $Secret{KEY_NAME} syntax.
 
-Create (admin — ductape_cli or ductape_execute):
-  ductape_execute("secrets.create", [{
-    key: "STRIPE_API_KEY",
-    value: "sk_live_...",          // plaintext — encrypted AES-256-GCM client-side before send
-    description: "Stripe live key",
-    token_type: "api",             // "api" | "password" | "certificate"
-    scope: ["my-product"],         // which products can read this secret
-    envs: ["prd"],                 // which env slugs can read this secret
-    expires_at: 1800000000,        // optional epoch ms
-  }])
+Create/update secrets with ductape_cli or Workbench (administrative access), never ductape_execute.
+Definition fields include key, value, description, token_type, scope, envs, and expires_at.
   The server never receives the plaintext value. Encryption uses the workspace private key.
 
 Fetch / resolve:
@@ -1880,10 +1876,7 @@ $Secret{} reference syntax:
   - The in-memory cache stores the encrypted form only; decryption happens on each cache hit.
   - Cache TTL: 5 minutes. Clear with: secrets.clearCache()
 
-Lifecycle:
-  ductape_execute("secrets.revoke", ["KEY"])   → disables without deleting (recoverable)
-  ductape_execute("secrets.delete", ["KEY"])   → permanent deletion (irreversible)
-  ductape_execute("secrets.update", ["KEY", { value: "new_value", expires_at: ... }])
+Lifecycle mutations (revoke/delete/update) are administrative: use ductape_cli or Workbench.
 
 List all secrets (keys only — values are not returned in list):
   ductape_execute("secrets.list", [])
@@ -1934,9 +1927,7 @@ Import from a file:
   ductape_cli("apps import <file.json> -t postman|openapi")
   Supports Postman v2.1 collection and OpenAPI 3.0 spec.
 
-Manage environments (base URLs per stage):
-  ductape_execute("app.environments.create", [app_tag, { slug, env_name, base_url }])
-  ductape_execute("app.environments.list",   [app_tag])
+Manage environments (base URLs per stage) in Workbench; this currently has no CLI command.
 
 Discover apps in a product and their actions (ALWAYS do this before writing any ctx.api.run call):
   Step 1 — list apps connected to the product:
@@ -1953,16 +1944,8 @@ Discover apps in a product and their actions (ALWAYS do this before writing any
            app resources (not for runtime input — use actions.fetch or ductape_generate_payload for that)
   NEVER assume action input field names. Always fetch the action definition first.
 
-Manage actions (individual API endpoints):
-  ductape_execute("actions.create", [app_tag, {
-    tag, name, resource: "/users/{id}", method: "GET"|"POST"|"PUT"|"PATCH"|"DELETE",
-    body?: { fieldName: { type, required? } },
-    params?: { id: { type: "string" } },
-    query?: { filter: { type: "string" } },
-    headers?: { Authorization: { type: "string" } },
-    response?: { status_code: 200, success: true, body: { ... }, response_format: "json" },
-  }])
-  ductape_execute("actions.update", [app_tag, action_tag, data])
+Manage actions (individual API endpoints) in Workbench or import an OpenAPI/Postman file.
+Creation/update are administrative and must never use ductape_execute.
   ductape_execute("actions.list",   [app_tag])
   ductape_execute("actions.fetch",  [app_tag, action_tag])
 
@@ -1983,16 +1966,14 @@ Run an action at runtime:
 
 Auth schemes (how the app authenticates outbound requests):
   Setup types: header | bearer | basic | oauth2 | apikey
-  ductape_execute("auths.create", [app_tag, { tag, name, setup_type, expiry, period, action_tag? }])
+  Configure auth in Workbench (administrative).
   ductape_execute("auths.list",   [app_tag])
 
 Webhooks (inbound events from the external service):
-  ductape_execute("webhooks.create", [app_tag, { tag, name, description, envs: [{ slug, registration_url?, method? }] }])
-  ductape_execute("webhooks.events.create", [app_tag, { tag, name, selector, description, sample }])
+  Configure webhooks and webhook events in Workbench (administrative).
 
 Variables (per-env mutable values) and Constants (fixed values):
-  ductape_execute("app.variables.create", [app_tag, { key, value, env_slug }])
-  ductape_execute("app.constants.create", [app_tag, { key, value }])
+  Configure variables and constants in Workbench (administrative).
 
 Connecting an app to a product (after creation):
   NOTE: All product.* module methods require the access key and CANNOT use ductape_execute.
@@ -2000,14 +1981,13 @@ Connecting an app to a product (after creation):
 
   FULL FLOW to make an app callable from a product:
   1. Create the app:     ductape_cli("apps create --name \\"Service Name\\" --description \\"...\\"")
-  2. Add environments:   ductape_execute("app.environments.create", [app_tag, { slug: "prd", env_name: "Production", base_url: "https://api.example.com" }])
-  3. Configure auth:     ductape_execute("auths.create", [app_tag, { tag, name, setup_type: "apikey"|"bearer"|"basic"|"oauth2", expiry, period }])
-  4. Define actions:     ductape_execute("actions.create", [app_tag, { tag, name, resource, method, body?, params?, query?, headers?, response? }])
+  2. Add environments:   Workbench
+  3. Configure auth:     Workbench
+  4. Define actions:     Workbench
                          OR import: ductape_cli("apps import <file.json> -t postman|openapi")
   5. Connect to product: Requires the product_id (from ductape_cli("products get --tag <tag> --json")).
                          There is no CLI command for this step — the SDK product.apps.add method requires
-                         an access key which only the backend can provide. Use ductape_execute via an
-                         admin-authenticated context, or connect via the Workbench UI.
+                         an access key which only the backend can provide. Connect via Workbench.
   6. Verify:             ductape_cli("products get --tag <product_tag> --json") → check apps[] contains the app
                          ductape_execute("actions.list", [app_tag]) → verify actions are registered
 `.trim(),
@@ -2084,8 +2064,8 @@ IMPORTANT — selector must be "$Session{fieldName}" format:
   CORRECT:   selector: "$Session{playerId}"
   INCORRECT: selector: "playerId"   ← WILL FAIL with "Selector should be in the format $Session{...}{key}"
 
-Example (game product — player identity in JWT):
-  ductape_execute("sessions.create", [product_tag, {
+Example definition (configure via declarative apply or Workbench, not ductape_execute):
+  {
     tag: "player-session",
     name: "Player Session",
     expiry: 24,
@@ -2097,7 +2077,7 @@ Example (game product — player identity in JWT):
       role:      "player",
       accountId: "acct_xyz",
     },
-  }])
+  }
 
 Runtime — create a session (sign a JWT):
   → CALL ductape_generate_payload FIRST (operation_family="session", method="start", targets={tag})
@@ -2137,10 +2117,33 @@ Token format: "session_tag:jwt_token" — pass this format verbatim wherever ses
 JWT is signed with the product private key (not a symmetric shared secret).
 
 SESSION PROPAGATION
-  Preserve the original full token on every user-context database, Event, Feature, notification,
-  storage, graph, vector, action, and other runtime operation that accepts session. Do not replace
-  it with the session tag, user ID, decoded claims, or refresh token. Durable user-initiated work
-  should retain the initiating token; intentional system/background work should be sessionless.
+  Extract the original full "session_tag:jwt" token once at the HTTP/transport boundary and retain
+  it separately from verified/decoded claims. Claims are authorization data; they are not a token.
+  Store a request ActorContext in a NestJS request-scoped provider or AsyncLocalStorage:
+    type ActorContext =
+      | { kind: "user"; session: string; actorId: string }
+      | { kind: "delegated"; delegatedIdentity: string; actorId: string; initiatedAt: string }
+      | { kind: "system"; reason: string };
+  Pass ActorContext explicitly through service boundaries. At each immediate Ductape runtime call,
+  pass actor.kind === "user" ? actor.session : the SDK-approved delegated identity. Put only
+  non-secret actor metadata (actorId, kind, initiatedAt, correlationId) in Event envelopes.
+  Feature execution should receive the same explicit actor classification. Never log, serialize
+  into business payloads, or attach the raw session/refresh token to traces or error messages.
+
+  SECURITY BOUNDARY FOR DURABLE WORK
+  The current SDK accepts a session string on dispatch, but it does not expose an immutable
+  attribution snapshot API, an expired-token attribution contract, or a general delegated-session
+  issuer. Therefore do NOT persist reusable JWTs indefinitely or assume an expired initiating token
+  will remain valid when delayed work executes. Pass the full token only for immediate work within
+  its validity window. For delayed/recurring work, classify execution as system-context, or use an
+  application-owned immutable actor-context envelope plus a short-lived delegated identity issued
+  by an explicitly approved auth design. Until the SDK provides that design, actor metadata is for
+  audit/correlation and must not be treated as authorization.
+
+  Distinguish contexts deliberately:
+    user      — active request; original valid full token is required when the operation accepts it
+    delegated — delayed/on-behalf-of work; approved short-lived credential + immutable actor metadata
+    system    — scheduler/maintenance with no user authority; omit session and record a reason
 
   Backend propagation attributes component activity to an actor, but it does not record frontend
   pageviews, navigation, UI intent, funnels, or client failures. Continue immediately with
@@ -2152,14 +2155,12 @@ DUCTAPE CACHES
 
 Caches are product-level Redis (or in-memory) stores for temporary key-value data with optional TTL.
 
-Registration (admin — ductape_cli or SDK):
+Registration (admin — ductape_cli):
   ductape_cli("resources caches create -f cache.json")
   File: { name, tag, description?, expiry: <milliseconds> }
   No type or envs — Ductape manages the store infrastructure.
   expiry is in MILLISECONDS: 3600000 = 1 hour, 86400000 = 1 day, 604800000 = 1 week.
 
-  SDK: ductape_execute("caches.create", [product_tag, { name, tag, description?, expiry: 3600000 }])
-
 Operations:
   caches.set   [{ product, cache, key, value: string, expiry?: string (ISO 8601), env }]
     expiry is an ABSOLUTE TIMESTAMP (not a duration).
@@ -2208,20 +2209,20 @@ DUCTAPE NOTIFICATIONS
 
 Notifications send messages across multiple channels: email, SMS, push, or HTTP callback.
 
-Create a notification (admin — ductape_execute):
-  ductape_execute("notifications.create", [product_tag, {
+Create a notification through declarative apply or Workbench (administrative), using:
+  {
     tag: "welcome-email",
     name: "Welcome Email",
     type: "email",   // optional hint; actual channels configured per env
-  }])
+  }
 
-Create a message template:
-  ductape_execute("notifications.messages.create", [product_tag, {
+Create a message template through declarative apply or Workbench:
+  {
     tag: "welcome-email:default",       // format: "notification_tag:message_tag"
     notification: "welcome-email",
     subject: { template: "Welcome, {{name}}!", data: { name: "" } },
     body:    { template: "Hi {{name}}, thanks for signing up.", data: { name: "" } },
-  }])
+  }
 
 Send at runtime (one channel at a time):
   → CALL ductape_generate_payload FIRST (operation_family="notification", method="email.send")
@@ -2260,8 +2261,15 @@ DUCTAPE RESILIENCE
 Resilience covers three mechanisms: quotas (rate-limited provider pools), fallbacks (automatic
 provider switching), and healthchecks (continuous probe monitoring with failure actions).
 
+CONFIGURATION BOUNDARY
+  Quotas, fallbacks, and health checks are administrative product configuration. Configure them in
+  Workbench (or a future access-key administrative tool explicitly documented for the asset).
+  Never route administrative create/update methods through ductape_execute: its publishable-key
+  runtime proxy will fail.
+
 QUOTAS — rate-limited multi-provider pools:
-  ductape_execute("quotas.create", [product_tag, {
+  Workbench definition shape:
+  {
     tag: "sms-quota",
     name: "SMS Provider Pool",
     input: { to: { type: "string", required: true }, message: { type: "string" } },
@@ -2275,7 +2283,7 @@ QUOTAS — rate-limited multi-provider pools:
         input: { "body:to": "$Input{to}", "body:body": "$Input{message}" },
         output: {} },
     ],
-  }])
+  }
   Providers are tried in order until quota is not exhausted.
   quotas.run      [{ product, env, tag, input }]  ← CALL ductape_generate_payload FIRST
   quotas.dispatch [{ product, env, tag, input, schedule? }]
@@ -2283,12 +2291,13 @@ QUOTAS — rate-limited multi-provider pools:
 FALLBACKS — automatic provider switching on failure:
   Same schema as quotas but options are ordered: primary first, then fallback(s).
   Primary is used first; on failure, the next provider is tried automatically.
-  ductape_execute("fallback.create", [product_tag, { tag, name, input: { ... }, options: [...] }])
+  Configure in Workbench: { tag, name, input: { ... }, options: [...] }
   fallback.run      [{ product, env, tag, input }]  ← CALL ductape_generate_payload FIRST
   fallback.dispatch [{ product, env, tag, input, schedule? }]
 
 HEALTHCHECKS — continuous probe with failure notifications:
-  ductape_execute("health.create", [product_tag, {
+  Workbench definition shape:
+  {
     tag: "payment-health",
     name: "Payment Service Health",
     probe: { type: "app", app: "stripe-app", event: "ping" },
@@ -2300,7 +2309,7 @@ HEALTHCHECKS — continuous probe with failure notifications:
         channels: { email: { recipients: ["ops@example.com"] } } }],
       webhooks: [{ url: "https://hooks.example.com/alert", method: "POST" }],
     },
-  }])
+  }
   health.run    [{ product, env, tag }]   → triggers an immediate probe
   health.check  [{ product, env, tag }]   → same as run
   health.status [{ product, env, tag }]   → current health status
@@ -2310,6 +2319,23 @@ Failure actions: notification channels, HTTP webhooks, and/or message broker emi
   be configured simultaneously on the same healthcheck.
 Input template references: $Input{field} → maps declared input to the probe's action input.
 Provider status: available | unavailable
+
+DECISION MATRIX
+  Rate/capacity allocation across providers       → quota
+  Equivalent provider after operational failure   → fallback
+  Detect failure before routing provider traffic  → health check
+  Transient failure of one operation              → bounded retry + idempotency policy
+  Multi-step business recovery/compensation       → Feature
+  Database atomicity                              → database transaction, not Feature rollback
+  Scheduled single operation                      → that component's dispatch
+  Scheduled multi-step process                    → Feature dispatch
+
+COMBINING MECHANISMS
+  A health check may keep an unhealthy provider out of a fallback/quota pool; the pool controls
+  provider selection; each operation may use bounded retries and an idempotency key; a Feature
+  coordinates business steps and compensation around those resilient operations. Do not stack them
+  reflexively: each layer needs a distinct failure it owns, bounded retry budgets, and observable
+  terminal behavior. Database transactions remain the atomicity boundary for related DB writes.
 `.trim(),
 
   'frontend-analytics': `
@@ -2318,10 +2344,12 @@ DUCTAPE FRONTEND PRODUCT ANALYTICS AND SESSION ACTIVITY
 Frontend analytics and backend session attribution are complementary; neither replaces the other.
 
 BACKEND OPERATION ATTRIBUTION
-  Pass the original full Ductape session token to every user-initiated database, Event, Feature,
-  notification, storage, graph, vector, action, and other runtime operation that accepts session.
-  This attributes server work to the authenticated actor. Durable work should retain the initiating
-  session; intentional system/background work should remain sessionless.
+  Immediate user-initiated backend work should pass the original full Ductape session token to every
+  database, Event, Feature, notification, storage, graph, vector, action, and other runtime operation
+  that accepts session. This attributes immediate server work to the authenticated actor.
+  For delayed/durable work, do not persist raw JWTs indefinitely. Use system context, or an approved
+  delegated actor design with immutable non-secret actor metadata. Actor metadata supports audit and
+  correlation; it is not authorization. Intentional system/background work should remain sessionless.
 
 FRONTEND PRODUCT ANALYTICS
   Use the browser Analytics service for anonymous visits, authenticated page views, navigation,
@@ -2591,9 +2619,11 @@ STEP 4 — PRESENT the plan and get approval BEFORE writing any code or creating
   Wait for confirmation before writing code or calling any create tool.
 
 STEP 5 — CREATE missing components (only with user approval)
-  Use ductape_execute for any missing databases, apps, database actions, notification events, etc.
-  For a missing database action:
-    ductape_execute("databases.action.create", [product_tag, db_tag, { tag, name, type, query }])
+  Administrative assets must never be created through ductape_execute. Use ductape_cli for products,
+  apps, supported resources, broker topics, cloud connections, secrets, and declarative apply flows.
+  App actions, auths, Features, quotas, fallbacks, health checks, and other assets for which the CLI
+  has no command must be configured in Workbench. Do not generate an impossible publishable-key
+  create/update call. For a missing database action, configure it in Workbench, then verify it exists.
   For a missing child feature, recursively apply this same workflow.
   Tell the user what you are about to create before each tool call.
 
@@ -2717,7 +2747,11 @@ When you call features.define({ handler }), the handler runs TWICE:
 
   Invoke internal application business logic (your own NestJS/backend service code):
     → produce a broker event (ctx.messaging.produce or ductape.events.produce)
-    → consume it in your NestJS service with events.consume in onModuleInit
+    → follow ductape_docs({ topic: "events" }) and use the canonical NestJS decorator:
+      @Events.Consumer({ event: "broker-tag:topic-tag" })
+      async handle(message: MessageShape) { /* injected-service business logic; throw to nack */ }
+    → DuctapeModule auto-registers the decorated consumer; no manual onModuleInit is needed
+    → events.consume() remains a supported lower-level alternative for plain TypeScript/Node.js
     → your service method runs with full access to DI, DB transactions, etc.
     Do NOT create an App Action just to call your own service over HTTP.
 
@@ -3789,6 +3823,25 @@ async function main() {
 
   const executeHandler = async (args: { publishable_key?: string; module: SDKModule; method: string; params: unknown[] }) => {
     try {
+      const runtimeMutationMethods: Partial<Record<SDKModule, Set<string>>> = {
+        databases: new Set(['insert', 'update', 'delete', 'upsert']),
+        graph: new Set(['insert', 'update', 'delete']),
+        vector: new Set(['insert', 'upsert', 'upsertOne', 'delete']),
+        sessions: new Set(['revoke']),
+      };
+      const isRuntimeDataMutation = runtimeMutationMethods[args.module]?.has(args.method) === true;
+      const isAdministrativeMutation =
+        (/^migration\./.test(args.method) ||
+          /^schema\.(create|drop|add|remove|update)/.test(args.method) ||
+          /(^|\.)(create|update|delete|configure|add|remove|revoke)$/.test(args.method)) &&
+        !isRuntimeDataMutation;
+      if (isAdministrativeMutation) {
+        throw new Error(
+          `Administrative operation "${args.module}.${args.method}" is blocked in ductape_execute. ` +
+          'Use ductape_cli when that resource is supported by the CLI; otherwise configure it in Workbench. ' +
+          'The runtime proxy uses a publishable key and cannot administer platform assets.',
+        );
+      }
       const key = args.publishable_key || process.env.DUCTAPE_PUBLISHABLE_KEY;
       if (!key) {
         throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
@@ -3839,7 +3892,10 @@ async function main() {
       if (!key) {
         throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
       }
-      const result = await generateExecutablePayload({ ...args, publishable_key: key });
+      const result = addSessionAwarenessMetadata(
+        await generateExecutablePayload({ ...args, publishable_key: key }),
+        args,
+      );
 
       let text = JSON.stringify(result ?? null, null, 2);
 
@@ -3871,7 +3927,10 @@ async function main() {
         throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
       }
       ensureSupportedSnippetOperation(args.operation_family, args.method);
-      const generated = await generateExecutablePayload({ ...args, publishable_key: key });
+      const generated = addSessionAwarenessMetadata(
+        await generateExecutablePayload({ ...args, publishable_key: key }),
+        args,
+      );
       const payload = (generated as any)?.payload ?? {};
       const snippet = buildSnippet(args.language, payload, args.operation_family, args.method);
       return {
@@ -4055,7 +4114,7 @@ async function main() {
           '    Step 2 — check if the database component already exists:\n' +
           '      ductape_cli("resources databases list <product_tag> --json")\n' +
           '      If a component already uses the same Atlas cluster, do NOT re-import — instead update it:\n' +
-          '        ductape_execute("databases.updateDatabase", [product_tag, db_tag, { envs: [...updated envs...] }])\n' +
+          '        use ductape_cli resource update when supported; otherwise update it in Workbench\n' +
           '      Add or change the dbName in the env\'s connection_url to switch databases on the same cluster.\n' +
           '    Step 3 — import (only if no existing component uses this cluster):\n' +
           '      Use import-persist-all with one entry per product env. Required fields per entry:\n' +

package/src/proxy-client.ts

@@ -76,6 +76,7 @@ export interface IGenerateExecutablePayloadRequest {
   method: string;
   targets?: Record<string, unknown>;
   include_session?: boolean;
+  execution_context?: 'user' | 'delegated' | 'system';
   include_cache?: boolean;
   schema_mode?: 'strict' | 'best_effort';
   input_hint?: Record<string, unknown>;