@ductape/mcp 0.1.14 → 0.1.15

package/dist/index.js

@@ -155,7 +155,9 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   webhooks.events.list   [app_tag, webhook_tag]
 
 ━━━ MODULE: sessions ━━━
-  sessions.create        [product_tag, data: { tag: string, name: string, description?: string, expiry: number, period: "seconds"|"minutes"|"hours"|"days", selector: string, schema: { fieldName: "string"|"number"|"boolean" } }]
+  sessions.create        [product_tag, data: { tag: string, name: string, description?: string, expiry: number, period: "seconds"|"minutes"|"hours"|"days", selector: string, schema: { fieldName: { type: "string"|"number"|"boolean"|"object"|"array", required?: boolean, description?: string } } }]
+  ← selector is the dot-path of the primary identifier field (e.g. "playerId"); it MUST exist in schema.
+  ← schema declares the shape of data encrypted in the JWT; actual values are passed at runtime via sessions.start.
   sessions.update        [product_tag, session_tag, data: { name?: string, description?: string, expiry?: number, period?: "seconds"|"minutes"|"hours"|"days", selector?: string, schema?: object }]
   sessions.fetch         [product_tag, session_tag]
   sessions.list          [product_tag]
@@ -291,8 +293,15 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   messageBrokers.fetch    [product_tag, broker_tag]
   messageBrokers.list     [product_tag]
   messageBrokers.delete   [product_tag, broker_tag]
-  messageBrokers.topics.create [product_tag, data: { tag: string, name: string, broker: string, type: "producer"|"consumer"|"both" }]
-  messageBrokers.topics.update [product_tag, topic_tag, data: { name?: string, type?: "producer"|"consumer"|"both" }]
+  messageBrokers.topics.create [product_tag, data: { tag: string, name: string, broker: string,
+    description?: string, sample?: object, idempotent?: boolean,
+    queueUrls?: [{ env_slug: string, url: string }]  // SQS only: per-env queue URL per topic
+  }]
+  ← A broker can have unlimited topics. Add one per logical event type.
+  ← For SQS: each topic needs queueUrls mapping env slug → the SQS queue URL for that topic+env.
+  ← For Pub/Sub and Service Bus: topic name resolves from the tag or broker env config; no queueUrls needed.
+  messageBrokers.topics.update [product_tag, topic_tag, data: { name?: string, description?: string,
+    sample?: object, idempotent?: boolean, queueUrls?: [{ env_slug: string, url: string }] }]
   messageBrokers.topics.fetch  [product_tag, topic_tag]
   messageBrokers.topics.list   [product_tag, broker_tag]
   messageBrokers.produce  [{ product, env, event: "broker_tag:topic_tag", message: { key: value }, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="messaging", method="produce", targets={broker, event})
@@ -584,7 +593,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   caches.list    [product_tag]
   caches.delete  [product_tag, cache_tag]
   caches.get     [{ key: string }]
-  caches.set     [{ product, cache, key, value: string, componentTag?, componentType?, expiry?: Date }]
+  caches.set     [{ product, cache, key, value: string, componentTag?, componentType?, expiry?: string (ISO 8601 absolute timestamp — NOT a duration; e.g. new Date(Date.now()+3600000).toISOString() for 1h TTL), env }]
   caches.clear   [{ key: string }]
   caches.clearAll [{ product, cache, env? }]
   caches.fetchValues [{ product, cache, env?, page?, limit?, expiryFilter?: "all"|"expiring"|"permanent"|"expired" }]
@@ -1618,24 +1627,48 @@ Bootstrap (single API call returning product context + component config + privat
     sessions: `
 DUCTAPE SESSIONS
 
-A session is a named JWT schema on a product. It defines: a tag, an expiry duration, a selector
-(which field in the data object is the user identifier), and a schema (the shape of the JWT payload).
-
-Define a session (admin — ductape_execute):
+A session is a named JWT schema on a product. It defines:
+  - tag / name        — unique identifier and display name
+  - expiry + period   — how long each issued JWT is valid (duration, not an absolute date)
+  - selector          — the dot-path of the field inside the data object that is the PRIMARY
+                        user identifier (e.g. "playerId"). This field becomes the lookup key
+                        for revoke, list, and analytics. It MUST exist in the schema.
+  - schema            — the complete shape of data that will be embedded in the JWT payload.
+                        Each field is declared as { type, required?, description? }.
+                        This is a TYPE DECLARATION, not sample data. The actual values
+                        are passed at runtime when calling sessions.start.
+
+IMPORTANT — schema field format: { fieldName: { type, required?, description? } }
+  type values: "string" | "number" | "boolean" | "object" | "array"
+  Do NOT use the shorthand { fieldName: "string" } — pass the full object form.
+
+Example (game product — player identity in JWT):
   ductape_execute("sessions.create", [product_tag, {
-    tag: "user-session",
-    name: "User Session",
+    tag: "player-session",
+    name: "Player Session",
     expiry: 24,
-    period: "hours",                    // "seconds" | "minutes" | "hours" | "days"
-    selector: "userId",                 // field in data that identifies the user
-    schema: { userId: "string", role: "string", email: "string" },
+    period: "hours",
+    selector: "playerId",               // primary identifier — must be in schema below
+    schema: {
+      playerId:  { type: "string",  required: true,  description: "Unique player ID" },
+      username:  { type: "string",  required: true,  description: "Player display name" },
+      role:      { type: "string",  required: false, description: "admin | player | guest" },
+      accountId: { type: "string",  required: false, description: "Linked account ID" },
+    },
   }])
 
 Runtime — create a session (sign a JWT):
   → CALL ductape_generate_payload FIRST (operation_family="session", method="start", targets={tag})
-  ductape_execute("sessions.start", [{ product, env, tag: "user-session",
-    data: { userId: "u_123", role: "admin", email: "user@example.com" } }])
-  → returns token: "user-session:eyJ..."   ← format is always "session_tag:jwt"
+    to discover the exact data field names accepted for this session tag.
+  ductape_execute("sessions.start", [{ product, env, tag: "player-session",
+    data: {
+      playerId:  "player_abc123",   // must match selector — used as the revocation/lookup key
+      username:  "ShadowBlade",
+      role:      "player",
+      accountId: "acct_xyz",
+    } }])
+  → returns token: "player-session:eyJ..."   ← format is always "session_tag:jwt"
+  The token embeds all schema fields in the JWT payload, signed with the product private key.
 
 Verify a token:
   ductape_execute("sessions.verify", [{ product, env, tag: "user-session", token: "user-session:eyJ..." }])
@@ -1672,11 +1705,16 @@ Registration (admin — ductape_cli):
           envs: [{ slug, connection_url }] }
 
 Operations:
-  caches.set   [{ product, cache, key, value: string, expiry?: Date, env }]
+  caches.set   [{ product, cache, key, value: string, expiry?: string (ISO 8601), env }]
+    expiry is an ABSOLUTE TIMESTAMP (not a duration).
+    To expire in 1 hour: expiry = new Date(Date.now() + 3600_000).toISOString()
+    To expire in 24 hours: expiry = new Date(Date.now() + 86400_000).toISOString()
+    To never expire: omit expiry entirely.
+    Via MCP: pass an ISO 8601 string e.g. "2026-07-17T12:00:00.000Z"
     → Writes to Redis synchronously, then fires remote API write in background (non-blocking).
   caches.get   [{ key: string }]
     → Checks Redis first; on miss falls through to remote API; on hit from API, populates Redis.
-    → Enforces TTL by comparing stored expiry field against current time.
+    → Enforces TTL by comparing the stored expiry timestamp against current time (client-side check).
   caches.clear [{ key: string }]
     → Deletes from Redis and from remote API.
   caches.clearAll [{ product, cache, env? }]
@@ -1691,13 +1729,22 @@ Tier architecture (three tiers applied automatically):
   Tier 2: Redis hash (hSet/hGetAll) with optional EXPIRE
   Tier 3: Remote Ductape API
 
+Practical examples:
+  // Cache a player leaderboard for 5 minutes:
+  { product, cache: "leaderboard-cache", key: "top-100", value: JSON.stringify(rows),
+    expiry: new Date(Date.now() + 300_000).toISOString(), env: "prd" }
+
+  // Cache a session token lookup for 1 hour:
+  { product, cache: "session-cache", key: "player:u_123", value: token,
+    expiry: new Date(Date.now() + 3_600_000).toISOString(), env: "prd" }
+
 Important:
   - Redis is optional; without it all reads/writes go through the remote API.
-  - expiry is a stored Date field, not a Redis TTL — expiry check happens client-side.
-  - clearAll only clears via remote API; Redis retains stale entries until accessed and found expired.
+  - expiry is stored as a Date field, not a Redis TTL — the expiry check happens client-side on read.
+  - clearAll only clears via the remote API bulk endpoint; Redis may retain stale entries until evicted.
   - Cache entries are stored as Redis hashes (not plain strings).
-  - Other services (storage, graph, notifications, sessions) also use the CacheManager for
-    their own result caching — configure a shared Redis URL at SDK init to share the pool.
+  - Other services (storage, graph, notifications, sessions) also use CacheManager internally —
+    configure a shared Redis URL at SDK init to share the pool.
 `.trim(),
     notifications: `
 DUCTAPE NOTIFICATIONS
@@ -1885,55 +1932,142 @@ Code-first (define API — compiles async handler to JSON step schema):
     events: `
 DUCTAPE EVENTS (MESSAGE BROKERS)
 
-Supported broker types: kafka | rabbitmq | redis | aws_sqs | azure_servicebus | google_pubsub | nats
+ARCHITECTURE — always two separate steps:
+  Step 1: Register the BROKER COMPONENT (establishes the connection to the broker service).
+          The broker's envs[] holds connection credentials and host/project info, NOT topics.
+  Step 2: Create TOPIC DEFINITIONS on that broker (unlimited; each is a named subject or queue).
+          Topics are separate from the broker registration and added after.
+  A single broker component can have as many topics as needed.
+
+━━━ SUPPORTED BROKER TYPES ━━━
+
+Cloud-managed (provision OR import via cloud connection):
+  GCP Pub/Sub    → service: "pubsub",      type in envs: "google_pubsub"
+  AWS SQS        → service: "sqs",         type in envs: "aws_sqs"
+  Azure SvcBus   → service: "servicebus",  type in envs: "azure_servicebus"
+
+Self-hosted (import-only — supply connection URL manually):
+  Kafka          → type in envs: "kafka"
+  RabbitMQ       → type in envs: "rabbitmq"
+  Redis          → type in envs: "redis"
+  NATS           → type in envs: "nats"
+
+━━━ STEP 1A: REGISTER VIA CLOUD CONNECTION (cloud-managed brokers) ━━━
+
+Provision (create a NEW resource in the cloud):
+  ductape_cli("cloud resources provision-persist-all -f brokers.json --json")
+  File: JSON ARRAY — one entry per env, same product + component tag across all entries.
+  type field: "messageBrokers" (exact — not "messagebrokers" or "events")
+
+  GCP Pub/Sub — creates a new Pub/Sub topic in GCP, stores credentials in secrets:
+    [{"cloud":"gcp-snd","service":"pubsub","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"snd",
+      "topicName":"my-product-notifications-snd"},
+     {"cloud":"gcp-prd","service":"pubsub","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"prd",
+      "topicName":"my-product-notifications-prd"}]
+    If topicName is omitted a timestamped name is generated — always supply it explicitly.
+
+  AWS SQS — creates a new SQS queue per env:
+    [{"cloud":"aws-snd","service":"sqs","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"snd",
+      "queueName":"my-product-notifications-snd"},
+     {"cloud":"aws-prd","service":"sqs","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"prd",
+      "queueName":"my-product-notifications-prd"}]
+
+  Azure Service Bus — creates a namespace + queue per env:
+    [{"cloud":"azure-snd","service":"servicebus","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"snd",
+      "namespaceName":"myproduct-snd","queueName":"notifications"},
+     {"cloud":"azure-prd","service":"servicebus","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"prd",
+      "namespaceName":"myproduct-prd","queueName":"notifications"}]
+
+Import (register an EXISTING cloud resource):
+  Same as above but use import-persist-all and supply "resource" (the existing resource name/ID):
+    ductape_cli("cloud resources import-persist-all -f brokers.json --json")
+    Each entry: { cloud, service, type: "messageBrokers", product, component, env, resource: "<id>" }
 
-CLI aliases for the messageBrokers module: events, event, broker, brokers, message-brokers
-  ductape_cli("resources events list <product_tag> --json")
+  IMPORTANT: Never share one cloud resource (topic/queue) across snd and prd envs — use
+  separate resources per env to avoid mixing sandbox and production events.
 
-Registration (admin — ductape_cli):
-  Message brokers are IMPORT-ONLY (no provision-persist). Use import-persist-all:
-    ductape_cli("cloud resources import-persist-all -f brokers.json --json")
-  File is a JSON ARRAY — one entry per env.
-  service identifiers: pubsub (GCP Pub/Sub) | sqs (AWS SQS) | servicebus (Azure Service Bus)
-  type field: "messageBrokers" (not "messagebrokers" or "events")
+━━━ STEP 1B: REGISTER SELF-HOSTED BROKER (no cloud connection needed) ━━━
+
+  ductape_cli("resources events create -f broker.json")
+  File: {
+    name: string, tag: string, description?: string,
+    envs: [
+      {
+        slug: "snd",
+        type: "kafka"|"rabbitmq"|"redis"|"nats",
+        config: <see config shapes below>
+      },
+      { slug: "prd", type: "kafka", config: { ... } }
+    ]
+  }
+
+  Config shapes per type:
+    kafka:    { brokers: ["host:9092"], clientId: "my-app", groupId?: "...",
+                ssl?: true, sasl?: { mechanism: "plain", username, password } }
+    rabbitmq: { url: "amqp://user:pass@host:5672/vhost" }
+    redis:    { host: "...", port: 6379, password?: "..." }
+    nats:     { servers: ["nats://host:4222"], token?: "...", user?: "...", pass?: "...", tls?: true }
+
+━━━ STEP 2: ADD TOPIC DEFINITIONS (all broker types — add as many as needed) ━━━
 
-After importing, create topics:
   ductape_execute("messageBrokers.topics.create", [product_tag, {
-    tag: "user-events", name: "User Events", broker: "broker-tag",
-    type: "producer"|"consumer"|"both",
+    tag: "player-joined",
+    name: "Player Joined",
+    broker: "notifications-broker",   // broker component tag
+    description?: string,
+    sample: { playerId: "string", username: "string" },  // example message shape
+    idempotent?: boolean,
+    // SQS only — map per-env queue URLs (each topic can be a different queue):
+    queueUrls?: [
+      { env_slug: "snd", url: "https://sqs.us-east-1.amazonaws.com/123456/my-product-player-joined-snd" },
+      { env_slug: "prd", url: "https://sqs.us-east-1.amazonaws.com/123456/my-product-player-joined-prd" }
+    ]
   }])
 
-Produce a message (runtime):
-  → CALL ductape_generate_payload FIRST (operation_family="messaging", method="produce")
-  messageBrokers.produce [{ product, env, event: "broker_tag:topic_tag", message: { key: value } }]
-  Idempotent publish:
-    messageBrokers.publishIdempotent [{ product, env, event, message, idempotency_key, ttl? }]
-    → checks if key was already processed; returns cached result if so.
+  For GCP Pub/Sub and Azure Service Bus, the SDK resolves the topic name from the topic tag (or
+  config.topicName on the env config). No extra per-topic URL mapping is needed beyond the tag.
+  For SQS, every topic definition needs queueUrls to point to the specific per-env queue.
+  Repeat this call for each logical event type — there is no limit on number of topics.
 
-Consume a message (subscribe):
-  messageBrokers.consume [{ product, env, event: "broker_tag:topic_tag",
-    callback: async (message) => { ... } }]
-  Callback tracking is deferred (setImmediate) so user callback latency is unaffected.
-  Callback errors are re-thrown so the broker can nack/retry.
+  List topics on a broker:
+    ductape_execute("messageBrokers.topics.list", [product_tag, "broker-tag"])
 
-Background dispatch with scheduling:
-  messageBrokers.dispatch [{ product, env, broker, event, input: { message },
-    schedule?: { start_at?, cron?, every?, limit?, endDate?, tz? } }]
-  → CALL ductape_generate_payload FIRST (operation_family="messaging", method="dispatch")
+━━━ RUNTIME: PRODUCE AND CONSUME ━━━
+
+  Produce (publish a message):
+    → CALL ductape_generate_payload FIRST (operation_family="messaging", method="produce")
+    messageBrokers.produce [{ product, env, event: "broker_tag:topic_tag", message: { key: value } }]
+    Idempotent publish (deduplicates by key, default TTL 86400 s):
+      messageBrokers.publishIdempotent [{ product, env, event, message, idempotency_key, ttl? }]
+
+  Consume (subscribe):
+    messageBrokers.consume [{ product, env, event: "broker_tag:topic_tag",
+      callback: async (message) => { ... } }]
+    Callback errors are re-thrown so the broker can nack/retry.
+
+  Background dispatch with scheduling:
+    messageBrokers.dispatch [{ product, env, broker, event, input: { message },
+      schedule?: { start_at?, cron?, every?, limit?, endDate?, tz? } }]
+    → CALL ductape_generate_payload FIRST (operation_family="messaging", method="dispatch")
+
+Event format string: "broker_tag:topic_tag" — always colon-separated.
+Message payload is AES-encrypted before the tracking API call — tracking never sees plaintext.
+
+━━━ OBSERVABILITY ━━━
 
-Event tracking and observability:
   messageBrokers.messages.query        [{ product, env, brokerTag, topicTag?, status?, page?, limit? }]
   messageBrokers.messages.getStats     [{ product, env, brokerTag }]
-    → { total_events, success_count, failed_count, dead_letter_count, events_by_topic }
   messageBrokers.messages.getDashboard [{ product, env, brokerTag }]
   messageBrokers.messages.getDeadLetters [{ product, env, brokerTag, topicTag?, limit? }]
   messageBrokers.replayEvent           [{ product, env, eventId, force? }]
   messageBrokers.reprocessDLQ         [{ product, env, brokerTag, topicTag?, messageIds?, limit? }]
-  messageBrokers.checkIdempotency      [{ product, env, brokerTag, idempotency_key }] → { exists, event_id? }
-
-Event format string: "broker_tag:topic_tag" — always colon-separated; parsed by the SDK.
-Message payload is AES-encrypted before the tracking API call — tracking endpoint never sees plaintext.
-Connection pool: deduplicates live connections across BrokersService instances by workspace+product+config.
+  messageBrokers.checkIdempotency      [{ product, env, brokerTag, idempotency_key }]
 `.trim(),
     logs: `
 DUCTAPE LOGS

package/package.json

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

package/src/index.ts

@@ -166,7 +166,9 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   webhooks.events.list   [app_tag, webhook_tag]
 
 ━━━ MODULE: sessions ━━━
-  sessions.create        [product_tag, data: { tag: string, name: string, description?: string, expiry: number, period: "seconds"|"minutes"|"hours"|"days", selector: string, schema: { fieldName: "string"|"number"|"boolean" } }]
+  sessions.create        [product_tag, data: { tag: string, name: string, description?: string, expiry: number, period: "seconds"|"minutes"|"hours"|"days", selector: string, schema: { fieldName: { type: "string"|"number"|"boolean"|"object"|"array", required?: boolean, description?: string } } }]
+  ← selector is the dot-path of the primary identifier field (e.g. "playerId"); it MUST exist in schema.
+  ← schema declares the shape of data encrypted in the JWT; actual values are passed at runtime via sessions.start.
   sessions.update        [product_tag, session_tag, data: { name?: string, description?: string, expiry?: number, period?: "seconds"|"minutes"|"hours"|"days", selector?: string, schema?: object }]
   sessions.fetch         [product_tag, session_tag]
   sessions.list          [product_tag]
@@ -302,8 +304,15 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   messageBrokers.fetch    [product_tag, broker_tag]
   messageBrokers.list     [product_tag]
   messageBrokers.delete   [product_tag, broker_tag]
-  messageBrokers.topics.create [product_tag, data: { tag: string, name: string, broker: string, type: "producer"|"consumer"|"both" }]
-  messageBrokers.topics.update [product_tag, topic_tag, data: { name?: string, type?: "producer"|"consumer"|"both" }]
+  messageBrokers.topics.create [product_tag, data: { tag: string, name: string, broker: string,
+    description?: string, sample?: object, idempotent?: boolean,
+    queueUrls?: [{ env_slug: string, url: string }]  // SQS only: per-env queue URL per topic
+  }]
+  ← A broker can have unlimited topics. Add one per logical event type.
+  ← For SQS: each topic needs queueUrls mapping env slug → the SQS queue URL for that topic+env.
+  ← For Pub/Sub and Service Bus: topic name resolves from the tag or broker env config; no queueUrls needed.
+  messageBrokers.topics.update [product_tag, topic_tag, data: { name?: string, description?: string,
+    sample?: object, idempotent?: boolean, queueUrls?: [{ env_slug: string, url: string }] }]
   messageBrokers.topics.fetch  [product_tag, topic_tag]
   messageBrokers.topics.list   [product_tag, broker_tag]
   messageBrokers.produce  [{ product, env, event: "broker_tag:topic_tag", message: { key: value }, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="messaging", method="produce", targets={broker, event})
@@ -595,7 +604,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   caches.list    [product_tag]
   caches.delete  [product_tag, cache_tag]
   caches.get     [{ key: string }]
-  caches.set     [{ product, cache, key, value: string, componentTag?, componentType?, expiry?: Date }]
+  caches.set     [{ product, cache, key, value: string, componentTag?, componentType?, expiry?: string (ISO 8601 absolute timestamp — NOT a duration; e.g. new Date(Date.now()+3600000).toISOString() for 1h TTL), env }]
   caches.clear   [{ key: string }]
   caches.clearAll [{ product, cache, env? }]
   caches.fetchValues [{ product, cache, env?, page?, limit?, expiryFilter?: "all"|"expiring"|"permanent"|"expired" }]
@@ -1682,24 +1691,48 @@ Bootstrap (single API call returning product context + component config + privat
   sessions: `
 DUCTAPE SESSIONS
 
-A session is a named JWT schema on a product. It defines: a tag, an expiry duration, a selector
-(which field in the data object is the user identifier), and a schema (the shape of the JWT payload).
-
-Define a session (admin — ductape_execute):
+A session is a named JWT schema on a product. It defines:
+  - tag / name        — unique identifier and display name
+  - expiry + period   — how long each issued JWT is valid (duration, not an absolute date)
+  - selector          — the dot-path of the field inside the data object that is the PRIMARY
+                        user identifier (e.g. "playerId"). This field becomes the lookup key
+                        for revoke, list, and analytics. It MUST exist in the schema.
+  - schema            — the complete shape of data that will be embedded in the JWT payload.
+                        Each field is declared as { type, required?, description? }.
+                        This is a TYPE DECLARATION, not sample data. The actual values
+                        are passed at runtime when calling sessions.start.
+
+IMPORTANT — schema field format: { fieldName: { type, required?, description? } }
+  type values: "string" | "number" | "boolean" | "object" | "array"
+  Do NOT use the shorthand { fieldName: "string" } — pass the full object form.
+
+Example (game product — player identity in JWT):
   ductape_execute("sessions.create", [product_tag, {
-    tag: "user-session",
-    name: "User Session",
+    tag: "player-session",
+    name: "Player Session",
     expiry: 24,
-    period: "hours",                    // "seconds" | "minutes" | "hours" | "days"
-    selector: "userId",                 // field in data that identifies the user
-    schema: { userId: "string", role: "string", email: "string" },
+    period: "hours",
+    selector: "playerId",               // primary identifier — must be in schema below
+    schema: {
+      playerId:  { type: "string",  required: true,  description: "Unique player ID" },
+      username:  { type: "string",  required: true,  description: "Player display name" },
+      role:      { type: "string",  required: false, description: "admin | player | guest" },
+      accountId: { type: "string",  required: false, description: "Linked account ID" },
+    },
   }])
 
 Runtime — create a session (sign a JWT):
   → CALL ductape_generate_payload FIRST (operation_family="session", method="start", targets={tag})
-  ductape_execute("sessions.start", [{ product, env, tag: "user-session",
-    data: { userId: "u_123", role: "admin", email: "user@example.com" } }])
-  → returns token: "user-session:eyJ..."   ← format is always "session_tag:jwt"
+    to discover the exact data field names accepted for this session tag.
+  ductape_execute("sessions.start", [{ product, env, tag: "player-session",
+    data: {
+      playerId:  "player_abc123",   // must match selector — used as the revocation/lookup key
+      username:  "ShadowBlade",
+      role:      "player",
+      accountId: "acct_xyz",
+    } }])
+  → returns token: "player-session:eyJ..."   ← format is always "session_tag:jwt"
+  The token embeds all schema fields in the JWT payload, signed with the product private key.
 
 Verify a token:
   ductape_execute("sessions.verify", [{ product, env, tag: "user-session", token: "user-session:eyJ..." }])
@@ -1737,11 +1770,16 @@ Registration (admin — ductape_cli):
           envs: [{ slug, connection_url }] }
 
 Operations:
-  caches.set   [{ product, cache, key, value: string, expiry?: Date, env }]
+  caches.set   [{ product, cache, key, value: string, expiry?: string (ISO 8601), env }]
+    expiry is an ABSOLUTE TIMESTAMP (not a duration).
+    To expire in 1 hour: expiry = new Date(Date.now() + 3600_000).toISOString()
+    To expire in 24 hours: expiry = new Date(Date.now() + 86400_000).toISOString()
+    To never expire: omit expiry entirely.
+    Via MCP: pass an ISO 8601 string e.g. "2026-07-17T12:00:00.000Z"
     → Writes to Redis synchronously, then fires remote API write in background (non-blocking).
   caches.get   [{ key: string }]
     → Checks Redis first; on miss falls through to remote API; on hit from API, populates Redis.
-    → Enforces TTL by comparing stored expiry field against current time.
+    → Enforces TTL by comparing the stored expiry timestamp against current time (client-side check).
   caches.clear [{ key: string }]
     → Deletes from Redis and from remote API.
   caches.clearAll [{ product, cache, env? }]
@@ -1756,13 +1794,22 @@ Tier architecture (three tiers applied automatically):
   Tier 2: Redis hash (hSet/hGetAll) with optional EXPIRE
   Tier 3: Remote Ductape API
 
+Practical examples:
+  // Cache a player leaderboard for 5 minutes:
+  { product, cache: "leaderboard-cache", key: "top-100", value: JSON.stringify(rows),
+    expiry: new Date(Date.now() + 300_000).toISOString(), env: "prd" }
+
+  // Cache a session token lookup for 1 hour:
+  { product, cache: "session-cache", key: "player:u_123", value: token,
+    expiry: new Date(Date.now() + 3_600_000).toISOString(), env: "prd" }
+
 Important:
   - Redis is optional; without it all reads/writes go through the remote API.
-  - expiry is a stored Date field, not a Redis TTL — expiry check happens client-side.
-  - clearAll only clears via remote API; Redis retains stale entries until accessed and found expired.
+  - expiry is stored as a Date field, not a Redis TTL — the expiry check happens client-side on read.
+  - clearAll only clears via the remote API bulk endpoint; Redis may retain stale entries until evicted.
   - Cache entries are stored as Redis hashes (not plain strings).
-  - Other services (storage, graph, notifications, sessions) also use the CacheManager for
-    their own result caching — configure a shared Redis URL at SDK init to share the pool.
+  - Other services (storage, graph, notifications, sessions) also use CacheManager internally —
+    configure a shared Redis URL at SDK init to share the pool.
 `.trim(),
 
   notifications: `
@@ -1954,55 +2001,142 @@ Code-first (define API — compiles async handler to JSON step schema):
   events: `
 DUCTAPE EVENTS (MESSAGE BROKERS)
 
-Supported broker types: kafka | rabbitmq | redis | aws_sqs | azure_servicebus | google_pubsub | nats
+ARCHITECTURE — always two separate steps:
+  Step 1: Register the BROKER COMPONENT (establishes the connection to the broker service).
+          The broker's envs[] holds connection credentials and host/project info, NOT topics.
+  Step 2: Create TOPIC DEFINITIONS on that broker (unlimited; each is a named subject or queue).
+          Topics are separate from the broker registration and added after.
+  A single broker component can have as many topics as needed.
+
+━━━ SUPPORTED BROKER TYPES ━━━
+
+Cloud-managed (provision OR import via cloud connection):
+  GCP Pub/Sub    → service: "pubsub",      type in envs: "google_pubsub"
+  AWS SQS        → service: "sqs",         type in envs: "aws_sqs"
+  Azure SvcBus   → service: "servicebus",  type in envs: "azure_servicebus"
+
+Self-hosted (import-only — supply connection URL manually):
+  Kafka          → type in envs: "kafka"
+  RabbitMQ       → type in envs: "rabbitmq"
+  Redis          → type in envs: "redis"
+  NATS           → type in envs: "nats"
+
+━━━ STEP 1A: REGISTER VIA CLOUD CONNECTION (cloud-managed brokers) ━━━
+
+Provision (create a NEW resource in the cloud):
+  ductape_cli("cloud resources provision-persist-all -f brokers.json --json")
+  File: JSON ARRAY — one entry per env, same product + component tag across all entries.
+  type field: "messageBrokers" (exact — not "messagebrokers" or "events")
+
+  GCP Pub/Sub — creates a new Pub/Sub topic in GCP, stores credentials in secrets:
+    [{"cloud":"gcp-snd","service":"pubsub","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"snd",
+      "topicName":"my-product-notifications-snd"},
+     {"cloud":"gcp-prd","service":"pubsub","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"prd",
+      "topicName":"my-product-notifications-prd"}]
+    If topicName is omitted a timestamped name is generated — always supply it explicitly.
+
+  AWS SQS — creates a new SQS queue per env:
+    [{"cloud":"aws-snd","service":"sqs","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"snd",
+      "queueName":"my-product-notifications-snd"},
+     {"cloud":"aws-prd","service":"sqs","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"prd",
+      "queueName":"my-product-notifications-prd"}]
+
+  Azure Service Bus — creates a namespace + queue per env:
+    [{"cloud":"azure-snd","service":"servicebus","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"snd",
+      "namespaceName":"myproduct-snd","queueName":"notifications"},
+     {"cloud":"azure-prd","service":"servicebus","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"prd",
+      "namespaceName":"myproduct-prd","queueName":"notifications"}]
+
+Import (register an EXISTING cloud resource):
+  Same as above but use import-persist-all and supply "resource" (the existing resource name/ID):
+    ductape_cli("cloud resources import-persist-all -f brokers.json --json")
+    Each entry: { cloud, service, type: "messageBrokers", product, component, env, resource: "<id>" }
 
-CLI aliases for the messageBrokers module: events, event, broker, brokers, message-brokers
-  ductape_cli("resources events list <product_tag> --json")
+  IMPORTANT: Never share one cloud resource (topic/queue) across snd and prd envs — use
+  separate resources per env to avoid mixing sandbox and production events.
 
-Registration (admin — ductape_cli):
-  Message brokers are IMPORT-ONLY (no provision-persist). Use import-persist-all:
-    ductape_cli("cloud resources import-persist-all -f brokers.json --json")
-  File is a JSON ARRAY — one entry per env.
-  service identifiers: pubsub (GCP Pub/Sub) | sqs (AWS SQS) | servicebus (Azure Service Bus)
-  type field: "messageBrokers" (not "messagebrokers" or "events")
+━━━ STEP 1B: REGISTER SELF-HOSTED BROKER (no cloud connection needed) ━━━
+
+  ductape_cli("resources events create -f broker.json")
+  File: {
+    name: string, tag: string, description?: string,
+    envs: [
+      {
+        slug: "snd",
+        type: "kafka"|"rabbitmq"|"redis"|"nats",
+        config: <see config shapes below>
+      },
+      { slug: "prd", type: "kafka", config: { ... } }
+    ]
+  }
+
+  Config shapes per type:
+    kafka:    { brokers: ["host:9092"], clientId: "my-app", groupId?: "...",
+                ssl?: true, sasl?: { mechanism: "plain", username, password } }
+    rabbitmq: { url: "amqp://user:pass@host:5672/vhost" }
+    redis:    { host: "...", port: 6379, password?: "..." }
+    nats:     { servers: ["nats://host:4222"], token?: "...", user?: "...", pass?: "...", tls?: true }
+
+━━━ STEP 2: ADD TOPIC DEFINITIONS (all broker types — add as many as needed) ━━━
 
-After importing, create topics:
   ductape_execute("messageBrokers.topics.create", [product_tag, {
-    tag: "user-events", name: "User Events", broker: "broker-tag",
-    type: "producer"|"consumer"|"both",
+    tag: "player-joined",
+    name: "Player Joined",
+    broker: "notifications-broker",   // broker component tag
+    description?: string,
+    sample: { playerId: "string", username: "string" },  // example message shape
+    idempotent?: boolean,
+    // SQS only — map per-env queue URLs (each topic can be a different queue):
+    queueUrls?: [
+      { env_slug: "snd", url: "https://sqs.us-east-1.amazonaws.com/123456/my-product-player-joined-snd" },
+      { env_slug: "prd", url: "https://sqs.us-east-1.amazonaws.com/123456/my-product-player-joined-prd" }
+    ]
   }])
 
-Produce a message (runtime):
-  → CALL ductape_generate_payload FIRST (operation_family="messaging", method="produce")
-  messageBrokers.produce [{ product, env, event: "broker_tag:topic_tag", message: { key: value } }]
-  Idempotent publish:
-    messageBrokers.publishIdempotent [{ product, env, event, message, idempotency_key, ttl? }]
-    → checks if key was already processed; returns cached result if so.
+  For GCP Pub/Sub and Azure Service Bus, the SDK resolves the topic name from the topic tag (or
+  config.topicName on the env config). No extra per-topic URL mapping is needed beyond the tag.
+  For SQS, every topic definition needs queueUrls to point to the specific per-env queue.
+  Repeat this call for each logical event type — there is no limit on number of topics.
 
-Consume a message (subscribe):
-  messageBrokers.consume [{ product, env, event: "broker_tag:topic_tag",
-    callback: async (message) => { ... } }]
-  Callback tracking is deferred (setImmediate) so user callback latency is unaffected.
-  Callback errors are re-thrown so the broker can nack/retry.
+  List topics on a broker:
+    ductape_execute("messageBrokers.topics.list", [product_tag, "broker-tag"])
 
-Background dispatch with scheduling:
-  messageBrokers.dispatch [{ product, env, broker, event, input: { message },
-    schedule?: { start_at?, cron?, every?, limit?, endDate?, tz? } }]
-  → CALL ductape_generate_payload FIRST (operation_family="messaging", method="dispatch")
+━━━ RUNTIME: PRODUCE AND CONSUME ━━━
+
+  Produce (publish a message):
+    → CALL ductape_generate_payload FIRST (operation_family="messaging", method="produce")
+    messageBrokers.produce [{ product, env, event: "broker_tag:topic_tag", message: { key: value } }]
+    Idempotent publish (deduplicates by key, default TTL 86400 s):
+      messageBrokers.publishIdempotent [{ product, env, event, message, idempotency_key, ttl? }]
+
+  Consume (subscribe):
+    messageBrokers.consume [{ product, env, event: "broker_tag:topic_tag",
+      callback: async (message) => { ... } }]
+    Callback errors are re-thrown so the broker can nack/retry.
+
+  Background dispatch with scheduling:
+    messageBrokers.dispatch [{ product, env, broker, event, input: { message },
+      schedule?: { start_at?, cron?, every?, limit?, endDate?, tz? } }]
+    → CALL ductape_generate_payload FIRST (operation_family="messaging", method="dispatch")
+
+Event format string: "broker_tag:topic_tag" — always colon-separated.
+Message payload is AES-encrypted before the tracking API call — tracking never sees plaintext.
+
+━━━ OBSERVABILITY ━━━
 
-Event tracking and observability:
   messageBrokers.messages.query        [{ product, env, brokerTag, topicTag?, status?, page?, limit? }]
   messageBrokers.messages.getStats     [{ product, env, brokerTag }]
-    → { total_events, success_count, failed_count, dead_letter_count, events_by_topic }
   messageBrokers.messages.getDashboard [{ product, env, brokerTag }]
   messageBrokers.messages.getDeadLetters [{ product, env, brokerTag, topicTag?, limit? }]
   messageBrokers.replayEvent           [{ product, env, eventId, force? }]
   messageBrokers.reprocessDLQ         [{ product, env, brokerTag, topicTag?, messageIds?, limit? }]
-  messageBrokers.checkIdempotency      [{ product, env, brokerTag, idempotency_key }] → { exists, event_id? }
-
-Event format string: "broker_tag:topic_tag" — always colon-separated; parsed by the SDK.
-Message payload is AES-encrypted before the tracking API call — tracking endpoint never sees plaintext.
-Connection pool: deduplicates live connections across BrokersService instances by workspace+product+config.
+  messageBrokers.checkIdempotency      [{ product, env, brokerTag, idempotency_key }]
 `.trim(),
 
   logs: `