@siduri-x/core 1.0.0

package/dist/capability.js

@@ -0,0 +1,102 @@
+"use strict";
+// Standard cryptographic implementations avoiding runtime ambient type dependencies
+// using node's built-in crypto module dynamically or via require for universal CommonJS compatibility
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryActionStore = void 0;
+exports.canonicalizeJson = canonicalizeJson;
+exports.computeParametersHash = computeParametersHash;
+exports.signCapabilityPayload = signCapabilityPayload;
+exports.verifyCapabilitySignature = verifyCapabilitySignature;
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const crypto = require('crypto');
+class InMemoryActionStore {
+    executions = new Map();
+    auditLog = [];
+    lastAuditHash = '0000000000000000000000000000000000000000000000000000000000000000';
+    async reserveExecution(record) {
+        if (this.executions.has(record.executionId)) {
+            return false;
+        }
+        this.executions.set(record.executionId, { ...record });
+        return true;
+    }
+    async updateExecution(record) {
+        this.executions.set(record.executionId, { ...record });
+    }
+    async getExecution(executionId) {
+        const rec = this.executions.get(executionId);
+        return rec ? { ...rec } : undefined;
+    }
+    async appendAudit(event) {
+        // Tamper-evident hash chaining: SHA-256(prevHash + ":" + canonicalEvent)
+        const eventPayload = {
+            executionId: event.executionId,
+            actionId: event.actionId,
+            toolName: event.toolName,
+            lifecycle: event.lifecycle,
+            parametersHash: event.parametersHash,
+            timestamp: event.timestamp,
+        };
+        const canonical = canonicalizeJson(eventPayload);
+        const eventHash = crypto
+            .createHash('sha256')
+            .update(`${this.lastAuditHash}:${canonical}`, 'utf8')
+            .digest('hex');
+        this.lastAuditHash = eventHash;
+        const recordWithHash = {
+            ...event,
+            resultHash: event.resultHash || eventHash,
+        };
+        this.auditLog.push(recordWithHash);
+    }
+    async getAuditLog(executionId) {
+        if (executionId) {
+            return this.auditLog.filter((e) => e.executionId === executionId).map((e) => ({ ...e }));
+        }
+        return this.auditLog.map((e) => ({ ...e }));
+    }
+}
+exports.InMemoryActionStore = InMemoryActionStore;
+function canonicalizeJson(obj) {
+    if (obj === null || typeof obj !== 'object') {
+        return JSON.stringify(obj);
+    }
+    if (Array.isArray(obj)) {
+        return `[${obj.map(canonicalizeJson).join(',')}]`;
+    }
+    const keys = Object.keys(obj).sort();
+    const pairs = keys.map((k) => `"${k}":${canonicalizeJson(obj[k])}`);
+    return `{${pairs.join(',')}}`;
+}
+function computeParametersHash(params) {
+    const canonical = canonicalizeJson(params || {});
+    return crypto.createHash('sha256').update(canonical, 'utf8').digest('hex');
+}
+function signCapabilityPayload(payload, secretKey = 'siduri_y_action_policy_secret') {
+    const canonicalStr = canonicalizeJson(payload);
+    return crypto.createHmac('sha256', secretKey).update(canonicalStr, 'utf8').digest('hex');
+}
+function verifyCapabilitySignature(capability, secretKey = 'siduri_y_action_policy_secret') {
+    if (!capability || capability.allowed !== true || typeof capability.signature !== 'string') {
+        return false;
+    }
+    const { signature, allowed, ...rest } = capability;
+    const canonicalStr = canonicalizeJson(rest);
+    const expectedSigHex = crypto.createHmac('sha256', secretKey).update(canonicalStr, 'utf8').digest('hex');
+    // Constant-time comparison to prevent timing attacks
+    try {
+        const sigBuffer = globalThis.Buffer
+            ? globalThis.Buffer.from(signature, 'hex')
+            : new Uint8Array(signature.match(/.{1,2}/g)?.map((byte) => parseInt(byte, 16)) || []);
+        const expectedBuffer = globalThis.Buffer
+            ? globalThis.Buffer.from(expectedSigHex, 'hex')
+            : new Uint8Array(expectedSigHex.match(/.{1,2}/g)?.map((byte) => parseInt(byte, 16)) || []);
+        if (sigBuffer.length !== expectedBuffer.length || sigBuffer.length === 0) {
+            return false;
+        }
+        return crypto.timingSafeEqual(sigBuffer, expectedBuffer);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/capability.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/capability.test.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const crypto = require('crypto');
+const capability_1 = require("./capability");
+const action_policy_1 = require("./action-policy");
+describe('AuthorizationCapability Cryptographic & Tamper Review', () => {
+    const secretKey = 'prod_secret_signing_key';
+    let engine;
+    let sampleContext;
+    beforeEach(() => {
+        engine = new action_policy_1.ActionPolicyEngine({
+            secretKey,
+            defaultRiskLevel: 'LOW',
+        });
+        sampleContext = {
+            companionId: 'comp-alpha',
+            actor: {
+                actorId: 'user-77',
+                sessionId: 'sess-88',
+                authorizationRole: 'operator',
+                capabilities: ['tool:send_email'],
+                authenticated: true,
+            },
+            conversation: {
+                channel: 'direct',
+                audienceId: 'aud-alpha',
+                correlationId: 'corr-999',
+            },
+        };
+        engine.registerToolDefinition({
+            name: 'send_email',
+            providerId: 'comm',
+            description: 'Send email',
+            inputSchema: {},
+            riskLevel: 'LOW',
+            requiredCapabilities: ['tool:send_email'],
+        });
+    });
+    describe('Field-Level Tampering Invalidation (HMAC-SHA-256)', () => {
+        let legitCapability;
+        beforeEach(async () => {
+            const { capability } = await engine.evaluateAction({
+                actionId: 'act-email-1',
+                toolName: 'comm/send_email',
+                parameters: { to: 'alice@example.com', subject: 'Hello' },
+                context: sampleContext,
+            });
+            expect(capability).toBeDefined();
+            legitCapability = capability;
+        });
+        it('verifies untouched authentic capability', () => {
+            expect((0, capability_1.verifyCapabilitySignature)(legitCapability, secretKey)).toBe(true);
+        });
+        it('invalidates signature if executionId is modified', () => {
+            const tampered = { ...legitCapability, executionId: 'exec-tampered-999' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if actionId is modified', () => {
+            const tampered = { ...legitCapability, actionId: 'act-tampered-999' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if toolName is modified', () => {
+            const tampered = { ...legitCapability, toolName: 'admin/delete_all' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if providerId is modified', () => {
+            const tampered = { ...legitCapability, providerId: 'untrusted_plugin' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if parametersHash is modified', () => {
+            const tampered = { ...legitCapability, parametersHash: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if actorId is modified', () => {
+            const tampered = { ...legitCapability, actorId: 'attacker-root' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if sessionId is modified', () => {
+            const tampered = { ...legitCapability, sessionId: 'hijacked-session' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if channel is modified', () => {
+            const tampered = { ...legitCapability, channel: 'public' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if correlationId is modified', () => {
+            const tampered = { ...legitCapability, correlationId: 'corr-spoofed' };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if expiresAt is modified to extend lifetime', () => {
+            const tampered = { ...legitCapability, expiresAt: new Date(Date.now() + 86400000).toISOString() };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('invalidates signature if issuedAt is modified', () => {
+            const tampered = { ...legitCapability, issuedAt: new Date(Date.now() - 100000).toISOString() };
+            expect((0, capability_1.verifyCapabilitySignature)(tampered, secretKey)).toBe(false);
+        });
+        it('rejects verification if secretKey is mismatched', () => {
+            expect((0, capability_1.verifyCapabilitySignature)(legitCapability, 'wrong_secret_key')).toBe(false);
+        });
+        it('handles malformed, truncated, or non-hex signatures safely without crashing', () => {
+            const malformed1 = { ...legitCapability, signature: 'not_a_hex_string' };
+            expect((0, capability_1.verifyCapabilitySignature)(malformed1, secretKey)).toBe(false);
+            const malformed2 = { ...legitCapability, signature: 'deadbeef' };
+            expect((0, capability_1.verifyCapabilitySignature)(malformed2, secretKey)).toBe(false);
+            const malformed3 = { ...legitCapability, signature: '' };
+            expect((0, capability_1.verifyCapabilitySignature)(malformed3, secretKey)).toBe(false);
+        });
+    });
+    describe('Deterministic Canonicalization', () => {
+        it('produces identical canonical JSON strings regardless of key insertion order', () => {
+            const objA = { b: 2, a: 1, c: { z: 26, y: 25 } };
+            const objB = { a: 1, c: { y: 25, z: 26 }, b: 2 };
+            expect((0, capability_1.canonicalizeJson)(objA)).toBe((0, capability_1.canonicalizeJson)(objB));
+            expect((0, capability_1.computeParametersHash)(objA)).toBe((0, capability_1.computeParametersHash)(objB));
+        });
+    });
+    describe('Audit Trail SHA-256 Hash Chaining and Mutation Detection', () => {
+        it('detects tampering or mutation in previous audit events in the chain', async () => {
+            const store = new capability_1.InMemoryActionStore();
+            const policyEngine = new action_policy_1.ActionPolicyEngine({ store, secretKey });
+            policyEngine.registerToolDefinition({
+                name: 'send_email',
+                providerId: 'comm',
+                description: 'Send email',
+                inputSchema: {},
+                riskLevel: 'LOW',
+            });
+            // Event 1
+            await policyEngine.evaluateAction({
+                actionId: 'act-1',
+                toolName: 'comm/send_email',
+                parameters: { step: 1 },
+                context: sampleContext,
+            });
+            // Event 2
+            await policyEngine.evaluateAction({
+                actionId: 'act-2',
+                toolName: 'comm/send_email',
+                parameters: { step: 2 },
+                context: sampleContext,
+            });
+            const auditTrail = await store.getAuditLog();
+            expect(auditTrail.length).toBe(2);
+            const event1 = auditTrail[0];
+            const event2 = auditTrail[1];
+            // Recompute expected hash chain using standard SHA-256
+            const initialPrevHash = '0000000000000000000000000000000000000000000000000000000000000000';
+            const canonical1 = (0, capability_1.canonicalizeJson)({
+                executionId: event1.executionId,
+                actionId: event1.actionId,
+                toolName: event1.toolName,
+                lifecycle: event1.lifecycle,
+                parametersHash: event1.parametersHash,
+                timestamp: event1.timestamp,
+            });
+            const expectedHash1 = crypto.createHash('sha256').update(`${initialPrevHash}:${canonical1}`, 'utf8').digest('hex');
+            expect(event1.resultHash).toBe(expectedHash1);
+            const canonical2 = (0, capability_1.canonicalizeJson)({
+                executionId: event2.executionId,
+                actionId: event2.actionId,
+                toolName: event2.toolName,
+                lifecycle: event2.lifecycle,
+                parametersHash: event2.parametersHash,
+                timestamp: event2.timestamp,
+            });
+            const expectedHash2 = crypto.createHash('sha256').update(`${expectedHash1}:${canonical2}`, 'utf8').digest('hex');
+            expect(event2.resultHash).toBe(expectedHash2);
+            // If an attacker altered event 1 retrospectively, the hash chain breaks for event 2
+            const tamperedCanonical1 = (0, capability_1.canonicalizeJson)({
+                ...JSON.parse(canonical1),
+                actionId: 'act-tampered-1',
+            });
+            const tamperedHash1 = crypto.createHash('sha256').update(`${initialPrevHash}:${tamperedCanonical1}`, 'utf8').digest('hex');
+            const brokenHash2 = crypto.createHash('sha256').update(`${tamperedHash1}:${canonical2}`, 'utf8').digest('hex');
+            expect(brokenHash2).not.toBe(event2.resultHash);
+        });
+    });
+});

package/dist/context.d.ts

@@ -0,0 +1,47 @@
+export type AuthorizationRole = 'viewer' | 'operator' | 'administrator';
+export type Channel = 'public' | 'direct' | 'private' | 'operator';
+export interface ActorContext {
+    actorId: string;
+    sessionId: string;
+    authorizationRole: AuthorizationRole;
+    capabilities: string[];
+    authenticated: boolean;
+}
+export interface ConversationContext {
+    channel: Channel;
+    audienceId: string;
+    isLive?: boolean;
+    correlationId: string;
+}
+export type SubjectKind = 'actor' | 'companion' | 'configured';
+export interface SubjectRef {
+    subjectId: string;
+    kind: SubjectKind;
+    ownerActorId?: string;
+}
+export interface RequestContext {
+    companionId: string;
+    actor: ActorContext;
+    conversation: ConversationContext;
+    subject?: SubjectRef;
+}
+export type DiagnosticCode = 'audience_defaulted_by_public_policy' | 'legacy_role_mapped_to_authorization' | 'anonymous_session_generated' | 'companion_default_mapped_for_bootstrap' | 'actor_scoped_subject_mapped' | 'legacy_primary_user_quarantined';
+export type ContextErrorCode = 'MISSING_CONTEXT' | 'INVALID_CONTEXT' | 'AMBIGUOUS_CONTEXT' | 'FORBIDDEN_CONTEXT' | 'LEGACY_PERSONAL_AUDIENCE' | 'UNAUTHORIZED_CHANNEL_OR_CAPABILITY';
+export interface ContextError {
+    code: ContextErrorCode;
+    message?: string;
+    fields?: string[];
+    field?: string;
+    conflicts?: string[];
+    correlationId?: string;
+}
+export interface RequestContextValidationResult {
+    accepted: boolean;
+    context?: RequestContext;
+    diagnostics?: DiagnosticCode[];
+    error?: ContextError;
+}
+export declare function isValidAuthorizationRole(role: unknown): role is AuthorizationRole;
+export declare function isValidChannel(channel: unknown): channel is Channel;
+export declare function isValidSubjectKind(kind: unknown): kind is SubjectKind;
+export declare function validateRequestContext(context: unknown): RequestContextValidationResult;

package/dist/context.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidAuthorizationRole = isValidAuthorizationRole;
+exports.isValidChannel = isValidChannel;
+exports.isValidSubjectKind = isValidSubjectKind;
+exports.validateRequestContext = validateRequestContext;
+function isValidAuthorizationRole(role) {
+    return role === 'viewer' || role === 'operator' || role === 'administrator';
+}
+function isValidChannel(channel) {
+    return channel === 'public' || channel === 'direct' || channel === 'private' || channel === 'operator';
+}
+function isValidSubjectKind(kind) {
+    return kind === 'actor' || kind === 'companion' || kind === 'configured';
+}
+function validateRequestContext(context) {
+    if (!context || typeof context !== 'object') {
+        return {
+            accepted: false,
+            error: {
+                code: 'MISSING_CONTEXT',
+                fields: ['context'],
+            },
+        };
+    }
+    const ctx = context;
+    const missingFields = [];
+    if (!ctx.companionId || typeof ctx.companionId !== 'string' || ctx.companionId.trim() === '') {
+        missingFields.push('companionId');
+    }
+    if (!ctx.actor || typeof ctx.actor !== 'object') {
+        missingFields.push('actor');
+    }
+    else {
+        if (!ctx.actor.actorId || typeof ctx.actor.actorId !== 'string' || ctx.actor.actorId.trim() === '') {
+            missingFields.push('actor.actorId');
+        }
+        if (!ctx.actor.sessionId || typeof ctx.actor.sessionId !== 'string' || ctx.actor.sessionId.trim() === '') {
+            missingFields.push('actor.sessionId');
+        }
+        if (!isValidAuthorizationRole(ctx.actor.authorizationRole)) {
+            missingFields.push('actor.authorizationRole');
+        }
+        if (!Array.isArray(ctx.actor.capabilities)) {
+            missingFields.push('actor.capabilities');
+        }
+        if (typeof ctx.actor.authenticated !== 'boolean') {
+            missingFields.push('actor.authenticated');
+        }
+    }
+    if (!ctx.conversation || typeof ctx.conversation !== 'object') {
+        missingFields.push('conversation');
+    }
+    else {
+        if (!isValidChannel(ctx.conversation.channel)) {
+            missingFields.push('conversation.channel');
+        }
+        if (!ctx.conversation.audienceId || typeof ctx.conversation.audienceId !== 'string' || ctx.conversation.audienceId.trim() === '') {
+            missingFields.push('conversation.audienceId');
+        }
+        if (!ctx.conversation.correlationId || typeof ctx.conversation.correlationId !== 'string' || ctx.conversation.correlationId.trim() === '') {
+            missingFields.push('conversation.correlationId');
+        }
+    }
+    if (ctx.subject !== undefined) {
+        if (!ctx.subject || typeof ctx.subject !== 'object') {
+            missingFields.push('subject');
+        }
+        else {
+            if (!ctx.subject.subjectId || typeof ctx.subject.subjectId !== 'string' || ctx.subject.subjectId.trim() === '') {
+                missingFields.push('subject.subjectId');
+            }
+            if (!isValidSubjectKind(ctx.subject.kind)) {
+                missingFields.push('subject.kind');
+            }
+        }
+    }
+    if (missingFields.length > 0) {
+        return {
+            accepted: false,
+            error: {
+                code: 'MISSING_CONTEXT',
+                fields: missingFields,
+                correlationId: ctx.conversation?.correlationId,
+            },
+        };
+    }
+    return {
+        accepted: true,
+        context: ctx,
+    };
+}

package/dist/context.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/context.test.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const context_1 = require("./context");
+describe('Core Context Contract (P1)', () => {
+    const validContext = {
+        companionId: 'companion-a',
+        actor: {
+            actorId: 'actor-a',
+            sessionId: 'session-a',
+            authorizationRole: 'viewer',
+            capabilities: ['chat:public'],
+            authenticated: false,
+        },
+        conversation: {
+            channel: 'public',
+            audienceId: 'audience-public',
+            correlationId: 'corr-a',
+        },
+        subject: {
+            subjectId: 'actor:actor-a',
+            kind: 'actor',
+            ownerActorId: 'actor-a',
+        },
+    };
+    test('validates a correct neutral RequestContext', () => {
+        const result = (0, context_1.validateRequestContext)(validContext);
+        expect(result.accepted).toBe(true);
+        expect(result.context).toEqual(validContext);
+        expect(result.error).toBeUndefined();
+    });
+    test('validates a correct RequestContext without subject', () => {
+        const { subject, ...contextWithoutSubject } = validContext;
+        const result = (0, context_1.validateRequestContext)(contextWithoutSubject);
+        expect(result.accepted).toBe(true);
+        expect(result.context?.subject).toBeUndefined();
+    });
+    test('rejects missing root context or non-object', () => {
+        const result = (0, context_1.validateRequestContext)(null);
+        expect(result.accepted).toBe(false);
+        expect(result.error?.code).toBe('MISSING_CONTEXT');
+        expect(result.error?.fields).toContain('context');
+    });
+    test('rejects missing companionId, actor, or conversation', () => {
+        const result = (0, context_1.validateRequestContext)({});
+        expect(result.accepted).toBe(false);
+        expect(result.error?.code).toBe('MISSING_CONTEXT');
+        expect(result.error?.fields).toEqual(expect.arrayContaining(['companionId', 'actor', 'conversation']));
+    });
+    test('validates authorization role constraints', () => {
+        expect((0, context_1.isValidAuthorizationRole)('viewer')).toBe(true);
+        expect((0, context_1.isValidAuthorizationRole)('operator')).toBe(true);
+        expect((0, context_1.isValidAuthorizationRole)('administrator')).toBe(true);
+        expect((0, context_1.isValidAuthorizationRole)('owner')).toBe(false);
+        expect((0, context_1.isValidAuthorizationRole)('user')).toBe(false);
+        expect((0, context_1.isValidAuthorizationRole)('MASTER')).toBe(false);
+        const invalidRoleCtx = {
+            ...validContext,
+            actor: { ...validContext.actor, authorizationRole: 'invalid_role' },
+        };
+        const result = (0, context_1.validateRequestContext)(invalidRoleCtx);
+        expect(result.accepted).toBe(false);
+        expect(result.error?.fields).toContain('actor.authorizationRole');
+    });
+    test('validates channel constraints', () => {
+        expect((0, context_1.isValidChannel)('public')).toBe(true);
+        expect((0, context_1.isValidChannel)('direct')).toBe(true);
+        expect((0, context_1.isValidChannel)('private')).toBe(true);
+        expect((0, context_1.isValidChannel)('operator')).toBe(true);
+        expect((0, context_1.isValidChannel)('chat')).toBe(false);
+        expect((0, context_1.isValidChannel)('MASTER_PRIVATE')).toBe(false);
+        const invalidChannelCtx = {
+            ...validContext,
+            conversation: { ...validContext.conversation, channel: 'invalid_channel' },
+        };
+        const result = (0, context_1.validateRequestContext)(invalidChannelCtx);
+        expect(result.accepted).toBe(false);
+        expect(result.error?.fields).toContain('conversation.channel');
+    });
+    test('validates subject kinds and constraints', () => {
+        expect((0, context_1.isValidSubjectKind)('actor')).toBe(true);
+        expect((0, context_1.isValidSubjectKind)('companion')).toBe(true);
+        expect((0, context_1.isValidSubjectKind)('configured')).toBe(true);
+        expect((0, context_1.isValidSubjectKind)('user')).toBe(false);
+        const invalidSubjectCtx = {
+            ...validContext,
+            subject: { subjectId: 'subject-1', kind: 'invalid_kind' },
+        };
+        const result = (0, context_1.validateRequestContext)(invalidSubjectCtx);
+        expect(result.accepted).toBe(false);
+        expect(result.error?.fields).toContain('subject.kind');
+    });
+    test('rejects missing correlationId and preserves correlationId in error if present', () => {
+        const missingCorr = {
+            ...validContext,
+            conversation: { ...validContext.conversation, correlationId: '' },
+        };
+        const result = (0, context_1.validateRequestContext)(missingCorr);
+        expect(result.accepted).toBe(false);
+        expect(result.error?.fields).toContain('conversation.correlationId');
+        const missingActorId = {
+            ...validContext,
+            actor: { ...validContext.actor, actorId: '' },
+        };
+        const result2 = (0, context_1.validateRequestContext)(missingActorId);
+        expect(result2.accepted).toBe(false);
+        expect(result2.error?.fields).toContain('actor.actorId');
+        expect(result2.error?.correlationId).toBe('corr-a');
+    });
+});

package/dist/dispatcher.d.ts

@@ -0,0 +1,14 @@
+import { ExperienceAdapter, ExperienceEvent, ExperienceAdapterResult } from './experience';
+export interface DispatchSummary {
+    dispatched: boolean;
+    eventResults: {
+        event: ExperienceEvent;
+        result: ExperienceAdapterResult;
+    }[];
+}
+export declare class ExperienceDispatcher {
+    private readonly adapters;
+    private readonly dispatchedEventIds;
+    registerAdapter(adapter: ExperienceAdapter): void;
+    dispatchEvents(events: ExperienceEvent[]): Promise<DispatchSummary>;
+}

package/dist/dispatcher.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExperienceDispatcher = void 0;
+class ExperienceDispatcher {
+    adapters = [];
+    dispatchedEventIds = new Set();
+    registerAdapter(adapter) {
+        this.adapters.push(adapter);
+    }
+    async dispatchEvents(events) {
+        const eventResults = [];
+        for (const event of events) {
+            // Replay / duplicate dispatch protection: each eventId is dispatched only once
+            if (this.dispatchedEventIds.has(event.eventId)) {
+                eventResults.push({
+                    event,
+                    result: {
+                        accepted: false,
+                        eventId: event.eventId,
+                        lifecycle: 'FAILED',
+                        error: 'Duplicate event ID already dispatched',
+                        reason: 'DUPLICATE_EVENT_DISPATCH',
+                    },
+                });
+                continue;
+            }
+            this.dispatchedEventIds.add(event.eventId);
+            const matchingAdapters = this.adapters.filter((a) => a.kind === event.kind);
+            for (const adapter of matchingAdapters) {
+                const result = await adapter.handleEvent(event);
+                eventResults.push({ event, result });
+            }
+        }
+        return {
+            dispatched: eventResults.some((r) => r.result.accepted),
+            eventResults,
+        };
+    }
+}
+exports.ExperienceDispatcher = ExperienceDispatcher;

package/dist/dispatcher.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dispatcher.test.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const dispatcher_1 = require("./dispatcher");
+const experience_1 = require("./experience");
+describe('T5 ExperienceDispatcher Contract Suite', () => {
+    let dispatcher;
+    let mockVoiceAdapter;
+    let mockAvatarAdapter;
+    beforeEach(() => {
+        dispatcher = new dispatcher_1.ExperienceDispatcher();
+        mockVoiceAdapter = {
+            kind: 'voice',
+            handleEvent: jest.fn().mockImplementation(async (event) => ({
+                accepted: true,
+                eventId: event.eventId,
+                lifecycle: 'STARTED',
+            })),
+        };
+        mockAvatarAdapter = {
+            kind: 'avatar',
+            handleEvent: jest.fn().mockImplementation(async (event) => ({
+                accepted: true,
+                eventId: event.eventId,
+                lifecycle: 'STARTED',
+            })),
+        };
+        dispatcher.registerAdapter(mockVoiceAdapter);
+        dispatcher.registerAdapter(mockAvatarAdapter);
+    });
+    test('dispatches experience events to matching adapters', async () => {
+        const events = (0, experience_1.createExperienceEvents)({
+            responseId: 'resp-1',
+            companionId: 'companion-a',
+            correlationId: 'corr-1',
+            channel: 'public',
+            audienceId: 'audience-public',
+            speech: 'Hello dispatch',
+            language: 'en',
+        });
+        const summary = await dispatcher.dispatchEvents(events);
+        expect(summary.dispatched).toBe(true);
+        expect(summary.eventResults.length).toBe(2);
+        expect(mockVoiceAdapter.handleEvent).toHaveBeenCalledTimes(1);
+        expect(mockAvatarAdapter.handleEvent).toHaveBeenCalledTimes(1);
+    });
+    test('does not dispatch when no matching adapters registered', async () => {
+        const emptyDispatcher = new dispatcher_1.ExperienceDispatcher();
+        const events = (0, experience_1.createExperienceEvents)({
+            responseId: 'resp-1',
+            companionId: 'companion-a',
+            correlationId: 'corr-1',
+            channel: 'public',
+            audienceId: 'audience-public',
+            speech: 'Hello empty',
+        });
+        const summary = await emptyDispatcher.dispatchEvents(events);
+        expect(summary.dispatched).toBe(false);
+        expect(summary.eventResults.length).toBe(0);
+    });
+});