@ductape/mcp 0.2.6 → 0.2.7

package/dist/events-capabilities.d.ts

@@ -0,0 +1,133 @@
+export declare const EVENTS_IMPLEMENTATION_WARNING = "Ductape manages consumer delivery retries and dead-letter queues. Do not create a parallel application transport DLQ. Use an application transactional outbox only to bridge canonical database commits to Ductape publication. Consumers must remain idempotent and replay-safe.";
+export declare const EVENTS_RECOVERY_SEARCH_TERMS: string[];
+export declare const EVENTS_DELIVERY_SEMANTICS: {
+    publisherAcceptance: string;
+    consumerRetriesManagedBy: string;
+    deadLetterQueueManagedBy: string;
+    applicationDlqRequired: boolean;
+    applicationOutboxRecommended: boolean;
+    applicationOutboxPurpose: string;
+    orderingGuarantees: string;
+    deliveryGuarantee: string;
+    deduplicationGuidance: string;
+    idempotentConsumerRequired: boolean;
+    responsibilities: {
+        applicationTransactionalOutbox: string;
+        brokerDeliveryRetries: string;
+        exhaustedDeliveryDlq: string;
+        replayAndReprocessing: string;
+        domainRejectedOrInvalidCommands: string;
+        consumerMutationIdempotency: string;
+    };
+};
+export declare const EVENTS_PROVIDER_CAPABILITIES: Record<string, Record<string, unknown>>;
+type Operation = {
+    name: string;
+    description: string;
+    inputSchema: Record<string, string>;
+    outputSchema: Record<string, string>;
+    requiredIdentifiers: string[];
+    environmentRequirements: string;
+    connectionRequirements: string;
+    permissions: string;
+    idempotency: string;
+    pagination: string;
+    applicableStates: string[];
+    commonErrors: Array<{
+        error: string;
+        remediation: string;
+    }>;
+    mutatesState: boolean;
+    mayIncurProviderCost: boolean;
+};
+export declare const EVENTS_OPERATION_REGISTRY: Operation[];
+export declare function eventsCapabilityOverview(): {
+    capability: string;
+    aliases: string[];
+    implementationWarning: string;
+    deliverySemantics: {
+        publisherAcceptance: string;
+        consumerRetriesManagedBy: string;
+        deadLetterQueueManagedBy: string;
+        applicationDlqRequired: boolean;
+        applicationOutboxRecommended: boolean;
+        applicationOutboxPurpose: string;
+        orderingGuarantees: string;
+        deliveryGuarantee: string;
+        deduplicationGuidance: string;
+        idempotentConsumerRequired: boolean;
+        responsibilities: {
+            applicationTransactionalOutbox: string;
+            brokerDeliveryRetries: string;
+            exhaustedDeliveryDlq: string;
+            replayAndReprocessing: string;
+            domainRejectedOrInvalidCommands: string;
+            consumerMutationIdempotency: string;
+        };
+    };
+    recoverySearchTerms: string[];
+    documentationTopics: string[];
+    providerCapabilities: Record<string, Record<string, unknown>>;
+    operations: Operation[];
+};
+export declare function searchEventsCapabilities(query: string): {
+    query: string;
+    canonicalTopic: string;
+    recoveryMatch: boolean;
+    deliverySemantics: {
+        publisherAcceptance: string;
+        consumerRetriesManagedBy: string;
+        deadLetterQueueManagedBy: string;
+        applicationDlqRequired: boolean;
+        applicationOutboxRecommended: boolean;
+        applicationOutboxPurpose: string;
+        orderingGuarantees: string;
+        deliveryGuarantee: string;
+        deduplicationGuidance: string;
+        idempotentConsumerRequired: boolean;
+        responsibilities: {
+            applicationTransactionalOutbox: string;
+            brokerDeliveryRetries: string;
+            exhaustedDeliveryDlq: string;
+            replayAndReprocessing: string;
+            domainRejectedOrInvalidCommands: string;
+            consumerMutationIdempotency: string;
+        };
+    };
+    operations: Operation[];
+};
+export declare function inspectEventsComponent(component: any): {
+    component: any;
+    provider: any;
+    environments: any;
+    topics: any;
+    subscriptions: any;
+    consumerBindings: any;
+    messageStatistics: string;
+    availableOperationalActions: Operation[];
+    deliverySemantics: {
+        publisherAcceptance: string;
+        consumerRetriesManagedBy: string;
+        deadLetterQueueManagedBy: string;
+        applicationDlqRequired: boolean;
+        applicationOutboxRecommended: boolean;
+        applicationOutboxPurpose: string;
+        orderingGuarantees: string;
+        deliveryGuarantee: string;
+        deduplicationGuidance: string;
+        idempotentConsumerRequired: boolean;
+        responsibilities: {
+            applicationTransactionalOutbox: string;
+            brokerDeliveryRetries: string;
+            exhaustedDeliveryDlq: string;
+            replayAndReprocessing: string;
+            domainRejectedOrInvalidCommands: string;
+            consumerMutationIdempotency: string;
+        };
+    };
+    implementationWarning: string;
+    configurationWarnings: any;
+    documentationTopics: string[];
+};
+export {};
+//# sourceMappingURL=events-capabilities.d.ts.map

package/dist/events-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events-capabilities.d.ts","sourceRoot":"","sources":["../src/events-capabilities.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,6BAA6B,sRAC2O,CAAC;AAEtR,eAAO,MAAM,4BAA4B,UAWxC,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;CAmBrC,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkDhF,CAAC;AAEF,KAAK,SAAS,GAAG;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,uBAAuB,EAAE,MAAM,CAAC;IAChC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,YAAY,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5D,YAAY,EAAE,OAAO,CAAC;IACtB,oBAAoB,EAAE,OAAO,CAAC;CAC/B,CAAC;AAyCF,eAAO,MAAM,yBAAyB,EAAE,SAAS,EA8IhD,CAAC;AAEF,wBAAgB,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWvC;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;EASrD;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiCpD"}

package/dist/events-capabilities.js

@@ -0,0 +1,311 @@
+export const EVENTS_IMPLEMENTATION_WARNING = 'Ductape manages consumer delivery retries and dead-letter queues. Do not create a parallel application transport DLQ. Use an application transactional outbox only to bridge canonical database commits to Ductape publication. Consumers must remain idempotent and replay-safe.';
+export const EVENTS_RECOVERY_SEARCH_TERMS = [
+    'dlq',
+    'dead letter',
+    'dead letters',
+    'failed messages',
+    'retry',
+    'retries',
+    'poison message',
+    'replay',
+    'reprocess',
+    'consumer failure',
+];
+export const EVENTS_DELIVERY_SEMANTICS = {
+    publisherAcceptance: 'Ductape acknowledges events accepted for publication; acceptance is not proof of consumer-side mutation.',
+    consumerRetriesManagedBy: 'ductape',
+    deadLetterQueueManagedBy: 'ductape',
+    applicationDlqRequired: false,
+    applicationOutboxRecommended: true,
+    applicationOutboxPurpose: 'Protect the canonical database transaction-to-Ductape publication boundary.',
+    orderingGuarantees: 'Provider and configuration dependent; inspect each environment. Never infer global ordering.',
+    deliveryGuarantee: 'At-least-once processing should be assumed unless the inspected provider/configuration explicitly proves otherwise.',
+    deduplicationGuidance: 'Use publishIdempotent with a stable logical-operation key where appropriate and deduplicate consumer mutations.',
+    idempotentConsumerRequired: true,
+    responsibilities: {
+        applicationTransactionalOutbox: 'application',
+        brokerDeliveryRetries: 'ductape',
+        exhaustedDeliveryDlq: 'ductape',
+        replayAndReprocessing: 'ductape',
+        domainRejectedOrInvalidCommands: 'application (not a transport DLQ)',
+        consumerMutationIdempotency: 'application',
+    },
+};
+export const EVENTS_PROVIDER_CAPABILITIES = {
+    google_pubsub: {
+        ordering: 'supported only when provider ordering keys/configuration are enabled; not inferred by Ductape',
+        acknowledgement: 'provider subscription acknowledgement deadline',
+        retriesAndBackoff: 'provider subscription policy; inspect the deployed subscription',
+        dlq: 'Ductape recovery operations are available, but provider dead-letter policy must be verified before claiming a provider DLQ exists',
+        retention: 'provider topic/subscription retention; inspect live provider configuration',
+    },
+    aws_sqs: {
+        ordering: 'FIFO only for FIFO queues; standard queues do not guarantee strict ordering',
+        acknowledgement: 'visibility timeout',
+        retriesAndBackoff: 'receive count and visibility timeout/provider redrive policy',
+        dlq: 'provider redrive/DLQ must be configured and verified; Ductape exposes tracked dead letters and reprocessing',
+        retention: 'provider queue retention',
+    },
+    azure_servicebus: {
+        ordering: 'sessions can provide ordered handling when configured; otherwise provider-controlled',
+        acknowledgement: 'message lock duration',
+        retriesAndBackoff: 'max delivery count and lock/redelivery behavior',
+        dlq: 'provider entity DLQ exists, but its configured state and access must be verified',
+        retention: 'provider entity configuration',
+    },
+    kafka: {
+        ordering: 'within a partition only',
+        acknowledgement: 'consumer offset commit',
+        retriesAndBackoff: 'Ductape consumer failure tracking plus application/provider configuration',
+        dlq: 'do not assume a native broker DLQ topic exists unless it is configured and verified',
+        retention: 'topic retention configuration',
+    },
+    rabbitmq: {
+        ordering: 'queue ordering can be affected by redelivery and multiple consumers',
+        acknowledgement: 'broker acknowledgement/nack',
+        retriesAndBackoff: 'redelivery and configured exchange/queue policies',
+        dlq: 'dead-letter exchange/queue must be configured and verified before claiming provider DLQ availability',
+        retention: 'queue/message TTL configuration',
+    },
+    redis: {
+        ordering: 'provider/mode dependent',
+        acknowledgement: 'not uniformly supported across Redis pub/sub and stream modes',
+        retriesAndBackoff: 'Ductape tracking; provider-native retry semantics may be unsupported',
+        dlq: 'no provider DLQ should be implied without a verified stream/consumer-group recovery configuration',
+        retention: 'provider/mode dependent',
+    },
+    nats: {
+        ordering: 'subject/stream configuration dependent',
+        acknowledgement: 'JetStream configuration dependent; core NATS has different semantics',
+        retriesAndBackoff: 'provider mode/configuration dependent',
+        dlq: 'do not imply a provider DLQ without verified JetStream/recovery configuration',
+        retention: 'stream configuration dependent',
+    },
+};
+const runtimeRead = {
+    environmentRequirements: 'product environment must exist and the Events component must be configured for it',
+    connectionRequirements: 'configured provider connection for the selected Events environment',
+    permissions: 'publishable-key runtime access plus product/environment access',
+    applicableStates: ['active', 'provider-ready'],
+    commonErrors: [
+        { error: 'broker/topic not found', remediation: 'inspect the Events component and use its exact broker/topic tags' },
+        { error: 'environment not configured', remediation: 'configure that environment on the Events component' },
+        { error: 'authentication/permission denied', remediation: 'verify publishable key, workspace, product, and environment access' },
+    ],
+};
+function adminOperation(name, description, inputSchema, requiredIdentifiers, mutatesState) {
+    return {
+        name, description, inputSchema,
+        outputSchema: mutatesState ? { resource: 'persisted Events component/topic' } : { resource: 'Events component/topic or array' },
+        requiredIdentifiers,
+        environmentRequirements: 'administrative product access; create/update must cover every product environment where required',
+        connectionRequirements: 'provider-specific credentials or a verified cloud connection for every configured environment',
+        permissions: 'authenticated access-key CLI session with workspace/product administration permission',
+        idempotency: mutatesState ? 'not guaranteed; fetch first and use update rather than duplicate create' : 'read-only',
+        pagination: name.endsWith('.list') ? 'provider/component list; pagination is not currently exposed by this admin method' : 'none',
+        applicableStates: ['draft', 'active', 'provider-ready'],
+        commonErrors: [
+            { error: 'missing environment/provider fields', remediation: 'read the targeted live events.create/events.update schema and cover every product environment' },
+            { error: 'unsupported provider configuration', remediation: 'use the selected env type’s live config branch; do not copy fields between providers' },
+            { error: 'permission denied', remediation: 'authenticate the CLI and select the correct workspace; do not use ductape_execute for admin writes' },
+        ],
+        mutatesState,
+        mayIncurProviderCost: mutatesState,
+    };
+}
+export const EVENTS_OPERATION_REGISTRY = [
+    adminOperation('events.create', 'Register an Events component and its per-environment provider connections.', { product: 'string', tag: 'string', name: 'string', description: 'string?', envs: 'provider-specific env[]' }, ['product', 'tag', 'name', 'envs'], true),
+    adminOperation('events.update', 'Update an Events component/provider configuration.', { product: 'string', brokerTag: 'string', data: 'targeted live events.update schema' }, ['product', 'brokerTag'], true),
+    adminOperation('events.fetch', 'Fetch one Events component.', { product: 'string', brokerTag: 'string' }, ['product', 'brokerTag'], false),
+    adminOperation('events.list', 'List Events components for a product.', { product: 'string' }, ['product'], false),
+    adminOperation('events.delete', 'Delete or retire an Events component.', { product: 'string', brokerTag: 'string' }, ['product', 'brokerTag'], true),
+    adminOperation('events.topics.create', 'Create a topic definition on a registered Events component.', { product: 'string', tag: 'broker:topic', name: 'string', sample: 'object?', idempotent: 'boolean?', queueUrls: 'array?' }, ['product', 'tag', 'name'], true),
+    adminOperation('events.topics.update', 'Update an Events topic definition.', { product: 'string', topicTag: 'broker:topic', data: 'topic patch' }, ['product', 'topicTag'], true),
+    adminOperation('events.topics.fetch', 'Fetch one Events topic definition.', { product: 'string', topicTag: 'broker:topic' }, ['product', 'topicTag'], false),
+    adminOperation('events.topics.list', 'List topic definitions for an Events component.', { product: 'string', brokerTag: 'string' }, ['product', 'brokerTag'], false),
+    {
+        name: 'events.produce', description: 'Publish an event immediately.',
+        inputSchema: { product: 'string', env: 'string', event: 'broker:topic', message: 'object', session: 'string?' },
+        outputSchema: { accepted: 'boolean', messageId: 'string?' }, requiredIdentifiers: ['product', 'env', 'event'],
+        ...runtimeRead, idempotency: 'not inherently idempotent; use events.publishIdempotent when duplicate publication matters',
+        pagination: 'none', mutatesState: true, mayIncurProviderCost: true,
+    },
+    {
+        name: 'events.publishIdempotent', description: 'Publish with a stable deduplication key.',
+        inputSchema: { product: 'string', env: 'string', event: 'broker:topic', message: 'object', idempotencyKey: 'string', idempotencyTtl: 'number?' },
+        outputSchema: { accepted: 'boolean', duplicate: 'boolean?', messageId: 'string?' }, requiredIdentifiers: ['product', 'env', 'event', 'idempotencyKey'],
+        ...runtimeRead, idempotency: 'deduplicates the logical publication for the configured TTL',
+        pagination: 'none', mutatesState: true, mayIncurProviderCost: true,
+    },
+    {
+        name: 'events.consume', description: 'Register a server-side consumer; successful return acknowledges and thrown errors trigger managed failure handling.',
+        inputSchema: { product: 'string', env: 'string', event: 'broker:topic', callback: 'function' },
+        outputSchema: { subscribed: 'boolean', consumerTag: 'string?' }, requiredIdentifiers: ['product', 'env', 'event'],
+        ...runtimeRead, permissions: 'server-side SDK access; browser clients cannot consume',
+        idempotency: 'consumer mutations must be idempotent and replay-safe', pagination: 'none',
+        mutatesState: true, mayIncurProviderCost: true,
+    },
+    {
+        name: 'events.dispatch', description: 'Queue or schedule an Events publication.',
+        inputSchema: { product: 'string', env: 'string', event: 'broker:topic', input: '{message: object}', retries: 'number?', schedule: 'object?' },
+        outputSchema: { job_id: 'string', status: 'scheduled|queued', scheduled_at: 'string?', recurring: 'boolean' },
+        requiredIdentifiers: ['product', 'env', 'event'], ...runtimeRead,
+        connectionRequirements: 'Events provider connection plus redis_url for dispatch scheduling',
+        idempotency: 'job/publication idempotency depends on stable job and message keys; consumers remain idempotent',
+        pagination: 'none', mutatesState: true, mayIncurProviderCost: true,
+    },
+    {
+        name: 'events.messages.query', description: 'Query tracked broker messages and delivery state.',
+        inputSchema: { product: 'string', env: 'string', brokerTag: 'string', topicTag: 'string?', producerTag: 'string?', consumerTag: 'string?', status: 'string?', startDate: 'ISO date?', endDate: 'ISO date?', page: 'number?', limit: 'number?' },
+        outputSchema: { messages: 'array', total: 'number', page: 'number', limit: 'number', hasMore: 'boolean' },
+        requiredIdentifiers: ['product', 'env', 'brokerTag'], ...runtimeRead,
+        idempotency: 'read-only', pagination: 'page/limit with total and hasMore', mutatesState: false, mayIncurProviderCost: false,
+    },
+    {
+        name: 'events.getEvents', description: 'Query tracked Events records by broker, topic, category, status, idempotency, and date range.',
+        inputSchema: { product: 'string', env: 'string', brokerTag: 'string', topic: 'string?', category: 'string?', status: 'string?', idempotent: 'boolean?', startDate: 'Date?', endDate: 'Date?', page: 'number?', limit: 'number?' },
+        outputSchema: { events: 'array', total: 'number', page: 'number', limit: 'number', hasMore: 'boolean' },
+        requiredIdentifiers: ['product', 'env', 'brokerTag'], ...runtimeRead,
+        idempotency: 'read-only', pagination: 'page/limit with total and hasMore',
+        mutatesState: false, mayIncurProviderCost: false,
+    },
+    {
+        name: 'events.getEvent', description: 'Fetch one tracked Events record by ID.',
+        inputSchema: { product: 'string', eventId: 'string' },
+        outputSchema: { event: 'tracked event or null' },
+        requiredIdentifiers: ['product', 'eventId'], ...runtimeRead,
+        environmentRequirements: 'the event ID must belong to the selected product',
+        idempotency: 'read-only', pagination: 'none',
+        mutatesState: false, mayIncurProviderCost: false,
+    },
+    {
+        name: 'events.getEventStats', description: 'Fetch aggregate tracked event statistics.',
+        inputSchema: { product: 'string', env: 'string', brokerTag: 'string' },
+        outputSchema: { total_events: 'number', failed_count: 'number', success_count: 'number', status_breakdown: 'object?' },
+        requiredIdentifiers: ['product', 'env', 'brokerTag'], ...runtimeRead,
+        idempotency: 'read-only', pagination: 'none',
+        mutatesState: false, mayIncurProviderCost: false,
+    },
+    {
+        name: 'events.messages.getDeadLetters', description: 'List messages whose managed consumer delivery attempts were exhausted.',
+        inputSchema: { product: 'string', env: 'string', brokerTag: 'string', topicTag: 'string?', consumerTag: 'string?', startDate: 'ISO date?', endDate: 'ISO date?', page: 'number?', limit: 'number?' },
+        outputSchema: { deadLetters: 'array', total: 'number', page: 'number', limit: 'number', hasMore: 'boolean' },
+        requiredIdentifiers: ['product', 'env', 'brokerTag'], ...runtimeRead,
+        idempotency: 'read-only', pagination: 'page/limit with total and hasMore', mutatesState: false, mayIncurProviderCost: false,
+    },
+    {
+        name: 'events.reprocessDLQ', description: 'Requeue selected or bounded dead-lettered messages for Ductape-managed delivery.',
+        inputSchema: { product: 'string', env: 'string', brokerTag: 'string', topicTag: 'string?', messageIds: 'string[]?', limit: 'number?' },
+        outputSchema: { reprocessed: 'number', failed: 'number', messageIds: 'string[]?' },
+        requiredIdentifiers: ['product', 'env', 'brokerTag'], ...runtimeRead,
+        permissions: 'publishable-key runtime mutation access plus product/environment access',
+        idempotency: 'may redeliver; consumer mutation must be idempotent', pagination: 'bounded by messageIds or limit, not page-based',
+        applicableStates: ['dead-lettered', 'provider-ready'], mutatesState: true, mayIncurProviderCost: true,
+    },
+    {
+        name: 'events.replayEvent', description: 'Replay one tracked event by event identifier.',
+        inputSchema: { product: 'string', env: 'string', eventId: 'string', force: 'boolean?' },
+        outputSchema: { replayed: 'boolean', eventId: 'string', messageId: 'string?' },
+        requiredIdentifiers: ['product', 'env', 'eventId'], ...runtimeRead,
+        permissions: 'publishable-key runtime mutation access plus product/environment access',
+        idempotency: 'replay intentionally redelivers; force may bypass replay guards; consumer mutation must be idempotent',
+        pagination: 'none', applicableStates: ['tracked', 'failed', 'dead-lettered'],
+        mutatesState: true, mayIncurProviderCost: true,
+    },
+    {
+        name: 'events.messages.getStats', description: 'Return aggregate delivery and failure statistics.',
+        inputSchema: { product: 'string', env: 'string', brokerTag: 'string' },
+        outputSchema: { totals: 'object', delivery: 'object', failures: 'object' },
+        requiredIdentifiers: ['product', 'env', 'brokerTag'], ...runtimeRead,
+        idempotency: 'read-only', pagination: 'none', mutatesState: false, mayIncurProviderCost: false,
+    },
+    {
+        name: 'events.messages.getDashboard', description: 'Return operational overview, recent messages, and recovery indicators.',
+        inputSchema: { product: 'string', env: 'string', brokerTag: 'string' },
+        outputSchema: { overview: 'object', recent_messages: 'array', health: 'object?' },
+        requiredIdentifiers: ['product', 'env', 'brokerTag'], ...runtimeRead,
+        idempotency: 'read-only', pagination: 'fixed dashboard window', mutatesState: false, mayIncurProviderCost: false,
+    },
+    {
+        name: 'events.messages.getProducers', description: 'List observed producers.',
+        inputSchema: { product: 'string', env: 'string', brokerTag: 'string', topicTag: 'string?', page: 'number?', limit: 'number?' },
+        outputSchema: { producers: 'array', total: 'number', page: 'number', limit: 'number', hasMore: 'boolean' },
+        requiredIdentifiers: ['product', 'env', 'brokerTag'], ...runtimeRead,
+        idempotency: 'read-only', pagination: 'page/limit', mutatesState: false, mayIncurProviderCost: false,
+    },
+    {
+        name: 'events.messages.getConsumers', description: 'List observed consumers and bindings.',
+        inputSchema: { product: 'string', env: 'string', brokerTag: 'string', topicTag: 'string?', page: 'number?', limit: 'number?' },
+        outputSchema: { consumers: 'array', total: 'number', page: 'number', limit: 'number', hasMore: 'boolean' },
+        requiredIdentifiers: ['product', 'env', 'brokerTag'], ...runtimeRead,
+        idempotency: 'read-only', pagination: 'page/limit', mutatesState: false, mayIncurProviderCost: false,
+    },
+    {
+        name: 'events.checkIdempotency', description: 'Check whether a publication idempotency key has already been accepted.',
+        inputSchema: { product: 'string', env: 'string', idempotencyKey: 'string' },
+        outputSchema: { exists: 'boolean', event_id: 'string?' }, requiredIdentifiers: ['product', 'env', 'idempotencyKey'],
+        ...runtimeRead, idempotency: 'read-only idempotency lookup', pagination: 'none',
+        mutatesState: false, mayIncurProviderCost: false,
+    },
+    {
+        name: 'events.testConnection', description: 'Test the configured provider connection for one Events environment.',
+        inputSchema: { product: 'string', env: 'string', broker: 'string' },
+        outputSchema: { connected: 'boolean', latency: 'number?', error: 'string?' },
+        requiredIdentifiers: ['product', 'env', 'broker'], ...runtimeRead,
+        idempotency: 'read-only connection probe', pagination: 'none',
+        mutatesState: false, mayIncurProviderCost: false,
+    },
+];
+export function eventsCapabilityOverview() {
+    return {
+        capability: 'events',
+        aliases: ['messageBrokers', 'brokers', 'messaging'],
+        implementationWarning: EVENTS_IMPLEMENTATION_WARNING,
+        deliverySemantics: EVENTS_DELIVERY_SEMANTICS,
+        recoverySearchTerms: EVENTS_RECOVERY_SEARCH_TERMS,
+        documentationTopics: ['events', 'resilience'],
+        providerCapabilities: EVENTS_PROVIDER_CAPABILITIES,
+        operations: EVENTS_OPERATION_REGISTRY,
+    };
+}
+export function searchEventsCapabilities(query) {
+    const normalized = query.toLowerCase();
+    const recoveryMatch = EVENTS_RECOVERY_SEARCH_TERMS.some(term => normalized.includes(term));
+    const operations = EVENTS_OPERATION_REGISTRY.filter(operation => recoveryMatch
+        ? /deadletter|reprocess|replay|query|getstats|getdashboard/i.test(operation.name)
+        : `${operation.name} ${operation.description}`.toLowerCase().includes(normalized));
+    return { query, canonicalTopic: 'events', recoveryMatch, deliverySemantics: EVENTS_DELIVERY_SEMANTICS, operations };
+}
+export function inspectEventsComponent(component) {
+    const environments = (component?.envs || []).map((env) => ({
+        slug: env.slug ?? env.env_slug ?? null,
+        provider: env.type ?? component.type ?? null,
+        connection: env.cloud ?? env.instance ?? (env.config ? 'configured' : null),
+        retryPolicy: env.retryPolicy ?? component.retryPolicy ?? 'provider-default',
+        maximumDeliveryAttempts: env.maxDeliveryAttempts ?? component.maxDeliveryAttempts ?? 'provider-controlled-or-unverified',
+        acknowledgementDeadline: env.acknowledgementDeadline ?? component.acknowledgementDeadline ?? 'provider-controlled-or-unverified',
+        backoff: env.backoff ?? component.backoff ?? 'provider-controlled-or-unverified',
+        dlq: env.dlq ?? component.dlq ?? { configured: 'unverified', managedBy: 'ductape' },
+        retention: env.retention ?? component.retention ?? 'provider-controlled-or-unverified',
+        ordering: env.ordering ?? component.ordering ?? 'provider-controlled-or-unverified',
+        filters: env.filters ?? component.filters ?? 'none-configured-or-unverified',
+        providerCapabilities: EVENTS_PROVIDER_CAPABILITIES[env.type ?? component.type] ??
+            { status: 'unsupported-or-unknown-provider; inspect live provider configuration' },
+    }));
+    return {
+        component,
+        provider: component?.type ?? 'environment-specific',
+        environments,
+        topics: component?.topics ?? [],
+        subscriptions: component?.subscriptions ?? 'provider-controlled-or-unverified',
+        consumerBindings: component?.consumers ?? [],
+        messageStatistics: 'Call events.messages.getStats or events.messages.getDashboard with product, env, and brokerTag.',
+        availableOperationalActions: EVENTS_OPERATION_REGISTRY,
+        deliverySemantics: EVENTS_DELIVERY_SEMANTICS,
+        implementationWarning: EVENTS_IMPLEMENTATION_WARNING,
+        configurationWarnings: environments
+            .filter((env) => env.retryPolicy === 'provider-default' || env.dlq?.configured === 'unverified')
+            .map((env) => `${env.slug ?? 'unknown env'}: retry/DLQ configuration is not verified; provider defaults may apply.`),
+        documentationTopics: ['events', 'resilience'],
+    };
+}

package/dist/index.js

@@ -15,6 +15,7 @@ import { homedir } from 'os';
 import { delimiter, join } from 'path';
 import { z } from 'zod';
 import { executeViaProxy, generateExecutablePayload, getAssetSchemas, } from './proxy-client.js';
+import { EVENTS_DELIVERY_SEMANTICS, EVENTS_IMPLEMENTATION_WARNING, eventsCapabilityOverview, inspectEventsComponent, searchEventsCapabilities, } from './events-capabilities.js';
 const MODULES = [
     'product', 'app', 'databases', 'graph', 'webhooks', 'notifications',
     'events', 'messageBrokers', 'storage', 'vector', 'caches', 'sessions', 'quotas',
@@ -556,6 +557,14 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   events.messages.getDeadLetters [{ product, env, brokerTag, topicTag?, consumerTag?, startDate?, endDate?, page?, limit? }]
   events.messages.getStats      [{ product, env, brokerTag }]
   events.messages.getDashboard  [{ product, env, brokerTag }]
+  events.getEvents              [{ product, env, brokerTag, topic?, category?, status?, idempotent?, startDate?, endDate?, page?, limit? }]
+  events.getEvent               [{ product, eventId }]
+  events.getEventStats          [{ product, env, brokerTag }]
+  events.replayEvent            [{ product, env, eventId, force? }]
+  events.reprocessDLQ           [{ product, env, brokerTag, topicTag?, messageIds?, limit? }]
+  events.publishIdempotent      [{ product, env, event, message, idempotencyKey, idempotencyTtl? }]
+  events.checkIdempotency       [{ product, env, idempotencyKey }]
+  events.testConnection         [{ product, env, broker }]
 
 ━━━ MODULE: storage ━━━
   storage.create   [{ product: string, tag: string, name: string, description?: string, envs: [{ slug: string, type: "aws"|"azure"|"gcp", config: { bucket?: string, region?: string, accessKeyId?: string, secretAccessKey?: string, containerName?: string, connectionString?: string, projectId?: string, keyFilename?: string } }] }]
@@ -1342,6 +1351,11 @@ const docsInputSchema = z.object({
         'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
         'notifications, resilience, features, events, logs, migration, frontend, frontend-analytics, client, react, vue'),
 });
+const eventsDiscoveryInputSchema = z.object({
+    query: z.string().optional().describe('Capability or recovery search, including DLQ, dead letter, failed messages, retry, poison message, replay, or consumer failure.'),
+    product: z.string().optional().describe('Product tag used for live component inspection.'),
+    component: z.string().optional().describe('Events component/broker tag used for live inspection.'),
+});
 const migrationInputSchema = z.object({
     source: z.string().describe('Absolute path to the existing codebase.'),
     e2e_baseline: z.string().describe('Absolute path to a passing migration-e2e baseline manifest created before migration inspection.'),
@@ -2807,6 +2821,13 @@ DUCTAPE RESILIENCE
 Resilience covers three mechanisms: quotas (rate-limited provider pools), fallbacks (automatic
 provider switching), and healthchecks (continuous probe monitoring with failure actions).
 
+EVENTS DELIVERY BOUNDARY
+  Events transport retries, exhausted-delivery DLQs, replay, and reprocessing are Ductape
+  responsibilities. Applications own transactional outboxes at the database-to-publication
+  boundary, domain rejection records, and idempotent/replay-safe consumer mutations. Never advise
+  a parallel application transport DLQ. See ductape_docs({ topic: "events" }) and
+  ductape_events_discover({ query: "consumer failure" }).
+
 CONFIGURATION BOUNDARY
   Quotas, fallbacks, and health checks are administrative product configuration. Manage them with
   the authenticated CLI:
@@ -3471,6 +3492,19 @@ When you call features.define({ handler }), the handler runs TWICE:
     events: `
 DUCTAPE EVENTS (MESSAGE BROKERS)
 
+RELIABILITY OWNERSHIP — DO NOT DUPLICATE THE TRANSPORT DLQ
+  Ductape owns broker delivery retries, exhausted-delivery dead-letter handling, replay,
+  reprocessing, and message observability. Do not build a parallel MongoDB/application transport
+  DLQ. The application may use a transactional outbox only to bridge its canonical database commit
+  to Ductape publication. Domain-invalid or rejected commands remain application records and are
+  not transport dead letters. Every consumer mutation must be idempotent and replay-safe.
+  Recovery operations: events.messages.getDeadLetters, events.reprocessDLQ, events.replayEvent,
+  events.messages.query, events.messages.getStats, and events.messages.getDashboard.
+  Structured contracts and live component inspection:
+    ductape_events_discover({ query: "DLQ" })
+    ductape_events_discover({ product: "<product-tag>", component: "<events-tag>" })
+  Resilience boundary reference: ductape_docs({ topic: "resilience" }).
+
 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.
@@ -3775,6 +3809,9 @@ Import (register an EXISTING cloud resource):
   events.messages.getDeadLetters [{ product, env, brokerTag, topicTag?, consumerTag?, limit? }]
   events.messages.getProducers [{ product, env, brokerTag, topicTag?, page?, limit? }]
   events.messages.getConsumers [{ product, env, brokerTag, topicTag?, page?, limit? }]
+  events.getEvents              [{ product, env, brokerTag, topic?, category?, status?, idempotent?, startDate?, endDate?, page?, limit? }]
+  events.getEvent               [{ product, eventId }]
+  events.getEventStats          [{ product, env, brokerTag }]
   events.replayEvent           [{ product, env, eventId, force? }]
   events.reprocessDLQ         [{ product, env, brokerTag, topicTag?, messageIds?, limit? }]
   events.checkIdempotency      [{ product, env, brokerTag, idempotency_key }]
@@ -4371,7 +4408,9 @@ DEPRECATED ALIASES
 `.trim(),
 };
 const docsHandler = async (args) => {
-    const key = args.topic.toLowerCase().trim();
+    const requested = args.topic.toLowerCase().trim();
+    const recoveryAliases = /^(dlq|dead[- ]?letters?|failed messages?|retry|retries|poison messages?|replay|reprocess|consumer failures?)$/;
+    const key = recoveryAliases.test(requested) ? 'events' : requested;
     const doc = DOCS[key];
     if (!doc) {
         const available = Object.keys(DOCS).join(', ');
@@ -4379,7 +4418,16 @@ const docsHandler = async (args) => {
             content: [{ type: 'text', text: `Unknown topic "${args.topic}". Available topics: ${available}` }],
         };
     }
-    return { content: [{ type: 'text', text: doc }] };
+    const structured = key === 'events'
+        ? `\n\nSTRUCTURED EVENTS CAPABILITY INDEX\n${JSON.stringify(eventsCapabilityOverview(), null, 2)}`
+        : key === 'resilience'
+            ? `\n\nEVENTS DELIVERY RESPONSIBILITY BOUNDARY\n${JSON.stringify({
+                implementationWarning: EVENTS_IMPLEMENTATION_WARNING,
+                deliverySemantics: EVENTS_DELIVERY_SEMANTICS,
+                canonicalDocumentationTopic: 'events',
+            }, null, 2)}`
+            : '';
+    return { content: [{ type: 'text', text: doc + structured }] };
 };
 const cliInputSchema = z.object({
     command: z.string().describe('The ductape CLI command to run, without the leading "ductape" word. ' +
@@ -4528,6 +4576,74 @@ async function main() {
             ...(result.success ? {} : { isError: true }),
         };
     };
+    const eventsDiscoveryHandler = async (args) => {
+        try {
+            if (args.product || args.component) {
+                if (!args.product || !args.component) {
+                    throw new Error('Both product and component are required for live Events inspection.');
+                }
+                const result = await cliHandler({
+                    command: `products components get --product-tag ${shellArgument(args.product)} --type events --json`,
+                });
+                if (result.isError)
+                    return result;
+                const raw = result.content?.[0]?.text ?? '';
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch {
+                    throw new Error(`Events inspection did not return JSON. ${raw}`);
+                }
+                const candidates = Array.isArray(parsed)
+                    ? parsed
+                    : Array.isArray(parsed?.events)
+                        ? parsed.events
+                        : Array.isArray(parsed?.messageBrokers)
+                            ? parsed.messageBrokers
+                            : [parsed];
+                const component = candidates.find((item) => item?.tag === args.component || item?._id === args.component);
+                if (!component) {
+                    throw new Error(`Events component "${args.component}" was not found in product "${args.product}". ` +
+                        'Use the exact component tag or ID returned by products components get --type events.');
+                }
+                const inspection = inspectEventsComponent(component);
+                const key = process.env.DUCTAPE_PUBLISHABLE_KEY;
+                if (key) {
+                    inspection.messageStatistics = {};
+                    for (const environment of inspection.environments) {
+                        if (!environment.slug)
+                            continue;
+                        try {
+                            inspection.messageStatistics[environment.slug] = await executeViaProxy(key, 'events', 'messages.getStats', [{ product: args.product, env: environment.slug, brokerTag: component.tag }]);
+                        }
+                        catch (error) {
+                            inspection.messageStatistics[environment.slug] = {
+                                status: 'unavailable',
+                                error: error instanceof Error ? error.message : String(error),
+                                remediation: 'Verify publishable-key permission, environment configuration, provider readiness, and the exact broker tag.',
+                            };
+                        }
+                    }
+                }
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(inspection, null, 2) }],
+                };
+            }
+            const data = args.query ? searchEventsCapabilities(args.query) : eventsCapabilityOverview();
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error: ${message}\nRemediation: verify product/component identifiers, CLI authentication, workspace selection, and environment/provider configuration.`,
+                    }],
+                isError: true,
+            };
+        }
+    };
     const migrationHandler = async (args) => {
         if (args.mode === 'new-codebase' && !args.destination) {
             return {
@@ -4687,7 +4803,13 @@ async function main() {
             if (args.method && !args.module) {
                 throw new Error('module is required when method is provided');
             }
-            const data = await getAssetSchemas(args.module, args.method);
+            const requestedMethod = args.method;
+            const schemaMethod = requestedMethod === 'events.create'
+                ? 'messageBrokers.create'
+                : requestedMethod === 'events.update'
+                    ? 'messageBrokers.update'
+                    : requestedMethod;
+            const data = await getAssetSchemas(args.module, schemaMethod);
             const compactData = args.module &&
                 !args.method &&
                 data &&
@@ -4700,7 +4822,36 @@ async function main() {
                     hint: `Call ductape_schema with module="${args.module}" and one method for its complete field schema`,
                 }
                 : data;
-            return { content: [{ type: 'text', text: JSON.stringify(compactData ?? null, null, 2) }] };
+            const isEventsSchema = args.module === 'product' &&
+                Boolean(requestedMethod && /^(events|messageBrokers)\.(create|update)$/.test(requestedMethod));
+            const enrichedData = isEventsSchema
+                ? {
+                    ...compactData,
+                    method: requestedMethod,
+                    eventsCapability: {
+                        implementationWarning: EVENTS_IMPLEMENTATION_WARNING,
+                        deliverySemantics: EVENTS_DELIVERY_SEMANTICS,
+                        operations: eventsCapabilityOverview().operations,
+                        configurationValidation: {
+                            retryOrDlqUnspecified: 'Warn that provider defaults apply and inspect the deployed provider asset before claiming DLQ availability.',
+                            unsupportedFields: 'The live Joi schema rejects provider settings not supported by the selected env type; use the reported field path and provider matrix for remediation.',
+                            costSensitive: 'Azure Service Bus tier must be confirmed; provider operations may incur usage charges.',
+                        },
+                        documentationTopics: ['events', 'resilience'],
+                    },
+                }
+                : args.module === 'product' && !requestedMethod
+                    ? {
+                        ...compactData,
+                        eventsOwnership: {
+                            implementationWarning: EVENTS_IMPLEMENTATION_WARNING,
+                            deliverySemantics: EVENTS_DELIVERY_SEMANTICS,
+                            schemaMethods: ['events.create', 'events.update', 'messageBrokers.create', 'messageBrokers.update'],
+                            discoveryTool: 'ductape_events_discover',
+                        },
+                    }
+                    : compactData;
+            return { content: [{ type: 'text', text: JSON.stringify(enrichedData ?? null, null, 2) }] };
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -4762,6 +4913,14 @@ async function main() {
                 'notifications, resilience, features, events, logs, migration, frontend, frontend-analytics, client, react, vue',
             inputSchema: docsInputSchema,
         }, docsHandler);
+        server.registerTool('ductape_events_discover', {
+            title: 'Ductape Events Capability Discovery',
+            description: 'Discover Ductape Events delivery ownership, retries, dead-letter queues, replay/reprocessing, observability operations, ' +
+                'live input/output contracts, and provider-aware component configuration. Search recovery synonyms with query, or pass ' +
+                'product and component together for live inspection. Ductape owns transport retries and exhausted-delivery DLQs; ' +
+                'applications own transactional outboxes, domain rejection handling, and idempotent consumer mutations.',
+            inputSchema: eventsDiscoveryInputSchema,
+        }, eventsDiscoveryHandler);
         server.registerTool('ductape_migration_plan', {
             title: 'Ductape AI Migration Guidance',
             description: 'Inspect a TypeScript, Go, Java, or .NET repository without exposing secret values. ' +
@@ -4886,6 +5045,7 @@ async function main() {
         server.tool('ductape_generate_snippet', snippetGenerateInputSchema.shape, snippetGenerateHandler);
         server.tool('ductape_schema', schemaInputSchema.shape, schemaHandler);
         server.tool('ductape_docs', docsInputSchema.shape, docsHandler);
+        server.tool('ductape_events_discover', eventsDiscoveryInputSchema.shape, eventsDiscoveryHandler);
         server.tool('ductape_migration_plan', migrationInputSchema.shape, migrationHandler);
         server.tool('ductape_cli', cliInputSchema.shape, cliHandler);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "node scripts/check-frontend-analytics-guidance.mjs",
+    "test": "npm run build && node scripts/check-frontend-analytics-guidance.mjs && node scripts/check-events-discovery.mjs",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"
   },