@sidurijs/core 1.0.0

package/dist/database.d.ts

@@ -0,0 +1 @@
+export * from './siduri-db';

package/dist/database.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./siduri-db"), exports);

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,58 @@
+"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',
+            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',
+            speech: 'Hello empty',
+        });
+        const summary = await emptyDispatcher.dispatchEvents(events);
+        expect(summary.dispatched).toBe(false);
+        expect(summary.eventResults.length).toBe(0);
+    });
+});

package/dist/ear-types.d.ts

@@ -0,0 +1,33 @@
+import { RequestContext } from './context';
+import { EarPerception } from './index';
+export interface EarLimitsConfig {
+    maxTextLength?: number;
+    maxAudioBytes?: number;
+    allowedAudioMimeTypes?: string[];
+    maxDurationSeconds?: number;
+    transcriptionTimeoutMs?: number;
+}
+export interface EarPerceptionMetadata extends Record<string, unknown> {
+    source?: string;
+    channel?: string;
+    modality?: 'text' | 'audio' | 'object' | 'system';
+    confidence?: number;
+    provenance?: string;
+    actorId?: string;
+    sessionId?: string;
+    correlationId?: string;
+    byteSize?: number;
+    durationSeconds?: number;
+    mimeType?: string;
+}
+export interface HardenedEarPerception extends EarPerception {
+    modality: 'text' | 'audio' | 'object' | 'system';
+    metadata?: EarPerceptionMetadata;
+    rawConfidence?: number;
+}
+export interface EarIngestOptions {
+    source?: string;
+    context?: RequestContext;
+    mimeType?: string;
+    durationSeconds?: number;
+}

package/dist/ear-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/evidence.d.ts

@@ -0,0 +1,76 @@
+import { MemoryProposal, BehaviorProposal } from './proposals';
+export type EvidenceOrigin = 'knowledge' | 'memory' | 'life' | 'observation' | 'ocr' | 'platform' | 'conversation';
+export type EvidenceTrust = 'configured' | 'provider' | 'untrusted';
+export type EvidenceSensitivity = 'public' | 'private' | 'restricted';
+export interface EvidenceRecord {
+    evidenceId: string;
+    sourceId: string;
+    documentId?: string;
+    chunkId?: string;
+    locator?: string;
+    revision?: string;
+    origin: EvidenceOrigin;
+    confidence?: number;
+    uncertainty?: string;
+    createdAt: string;
+    expiresAt?: string;
+    trust: EvidenceTrust;
+    sensitivity?: EvidenceSensitivity;
+    companionId: string;
+    correlationId: string;
+    [key: string]: unknown;
+}
+export type ResponseApprovalStatus = 'STAGED' | 'APPROVED' | 'REJECTED' | 'EXPIRED' | 'EMITTED';
+export type ResponseGateReasonCode = 'APPROVED_DIRECT' | 'APPROVAL_REQUIRED' | 'UNKNOWN_APPROVAL_ID' | 'APPROVAL_ID_MISMATCH' | 'COMPANION_MISMATCH' | 'EVIDENCE_EXPIRED' | 'EVIDENCE_SENSITIVITY_EXCLUDED' | 'UNRESOLVED_LOW_CONFIDENCE' | 'EMPTY_SPEECH' | 'PROPOSAL_VALIDATION_FAILED' | 'EXPLICITLY_REJECTED';
+export interface ResponseCitation {
+    sourceId: string;
+    documentId?: string;
+    chunkId?: string;
+    locator?: string;
+    revision?: string;
+    evidenceId?: string;
+    provenance?: string;
+    preview?: string;
+}
+export interface StagedResponsePlan {
+    responseId: string;
+    companionId: string;
+    correlationId: string;
+    channel?: string;
+    speech: string;
+    language: string;
+    evidenceIds: string[];
+    citations: ResponseCitation[];
+    confidenceSummary: number;
+    uncertaintySummary?: string;
+    requiresApproval: boolean;
+    status: ResponseApprovalStatus;
+    createdAt: string;
+    expiresAt?: string;
+    memoryProposals?: MemoryProposal[];
+    behaviorProposals?: BehaviorProposal[];
+    internalMonologue?: string;
+    [key: string]: unknown;
+}
+export interface ResponseGateEvaluation {
+    admissible: boolean;
+    disposition: ResponseApprovalStatus;
+    reasonCode: ResponseGateReasonCode;
+    stagedPlan: StagedResponsePlan;
+    filteredEvidenceIds: string[];
+    filteredCitations: ResponseCitation[];
+    diagnostics?: Record<string, string>;
+}
+export interface EvidenceFilterOptions {
+    companionId: string;
+    channel?: string;
+    now?: string | Date;
+    [key: string]: unknown;
+}
+export declare function filterEvidenceRecords(records: EvidenceRecord[], options: EvidenceFilterOptions): {
+    admitted: EvidenceRecord[];
+    excluded: {
+        record: EvidenceRecord;
+        reason: string;
+    }[];
+};

package/dist/evidence.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterEvidenceRecords = filterEvidenceRecords;
+function filterEvidenceRecords(records, options) {
+    const admitted = [];
+    const excluded = [];
+    const nowTime = options.now ? new Date(options.now).getTime() : Date.now();
+    for (const record of records) {
+        // 1. Companion isolation
+        if (record.companionId !== options.companionId) {
+            excluded.push({ record, reason: 'companion_isolation_mismatch' });
+            continue;
+        }
+        // 2. Expiry
+        if (record.expiresAt) {
+            const expTime = new Date(record.expiresAt).getTime();
+            if (expTime <= nowTime) {
+                excluded.push({ record, reason: 'evidence_expired' });
+                continue;
+            }
+        }
+        // In single-owner architecture, memory and evidence are partitioned strictly
+        // by companion boundary (companionId) and temporal expiration.
+        admitted.push(record);
+    }
+    return { admitted, excluded };
+}

package/dist/evidence.test.d.ts

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

package/dist/evidence.test.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const evidence_1 = require("./evidence");
+describe('T4 Evidence & Disclosure Core Contract', () => {
+    const baseRecord = {
+        evidenceId: 'ev-1',
+        sourceId: 'src-1',
+        origin: 'knowledge',
+        trust: 'configured',
+        sensitivity: 'public',
+        companionId: 'companion-a',
+        correlationId: 'corr-1',
+        createdAt: new Date(Date.now() - 5000).toISOString(),
+    };
+    test('companion isolation excludes foreign companion evidence', () => {
+        const records = [
+            { ...baseRecord, evidenceId: 'ev-mine', companionId: 'companion-a' },
+            { ...baseRecord, evidenceId: 'ev-foreign', companionId: 'companion-b' },
+        ];
+        const options = {
+            companionId: 'companion-a',
+            channel: 'public',
+        };
+        const { admitted, excluded } = (0, evidence_1.filterEvidenceRecords)(records, options);
+        expect(admitted.map((e) => e.evidenceId)).toEqual(['ev-mine']);
+        expect(excluded).toEqual([
+            expect.objectContaining({
+                record: expect.objectContaining({ evidenceId: 'ev-foreign' }),
+                reason: 'companion_isolation_mismatch',
+            }),
+        ]);
+    });
+    test('expired evidence is excluded', () => {
+        const records = [
+            { ...baseRecord, evidenceId: 'ev-valid', expiresAt: new Date(Date.now() + 60000).toISOString() },
+            { ...baseRecord, evidenceId: 'ev-expired', expiresAt: new Date(Date.now() - 1000).toISOString() },
+        ];
+        const options = {
+            companionId: 'companion-a',
+            channel: 'public',
+        };
+        const { admitted, excluded } = (0, evidence_1.filterEvidenceRecords)(records, options);
+        expect(admitted.map((e) => e.evidenceId)).toEqual(['ev-valid']);
+        expect(excluded).toEqual([
+            expect.objectContaining({
+                record: expect.objectContaining({ evidenceId: 'ev-expired' }),
+                reason: 'evidence_expired',
+            }),
+        ]);
+    });
+    test('single-owner companion admits valid evidence without multi-audience filtering', () => {
+        const records = [
+            { ...baseRecord, evidenceId: 'ev-public' },
+            { ...baseRecord, evidenceId: 'ev-direct-only' },
+        ];
+        const options = {
+            companionId: 'companion-a',
+        };
+        const { admitted, excluded } = (0, evidence_1.filterEvidenceRecords)(records, options);
+        expect(admitted.map((e) => e.evidenceId)).toEqual(['ev-public', 'ev-direct-only']);
+        expect(excluded).toEqual([]);
+    });
+    test('single-owner companion admits private and restricted sensitivity for companion owner', () => {
+        const records = [
+            { ...baseRecord, evidenceId: 'ev-pub', sensitivity: 'public' },
+            { ...baseRecord, evidenceId: 'ev-priv', sensitivity: 'private' },
+            { ...baseRecord, evidenceId: 'ev-rest', sensitivity: 'restricted' },
+        ];
+        const { admitted, excluded } = (0, evidence_1.filterEvidenceRecords)(records, {
+            companionId: 'companion-a',
+        });
+        expect(admitted.map((e) => e.evidenceId)).toEqual(['ev-pub', 'ev-priv', 'ev-rest']);
+        expect(excluded).toEqual([]);
+    });
+});

package/dist/experience-emitter.d.ts

@@ -0,0 +1,21 @@
+import { RequestContext, StagedResponsePlan, ResponseGateEvaluation, ExperienceDispatcher, ExperienceEvent, ExperienceAdapter, VoiceOrgan, BodyOrgan } from './index';
+export interface ExperienceEmissionParams {
+    companionId: string;
+    requestContext: RequestContext;
+    stagedPlan: StagedResponsePlan;
+    gateEval: ResponseGateEvaluation;
+    speech: string;
+    language: string;
+    dispatcher: ExperienceDispatcher;
+    voice?: VoiceOrgan | ExperienceAdapter;
+    body?: BodyOrgan | ExperienceAdapter;
+}
+export interface ExperienceEmissionResult {
+    experienceEvents: ExperienceEvent[];
+    speechId?: string;
+}
+/**
+ * Creates ExperienceEvents, dispatches them through the ExperienceDispatcher,
+ * and coordinates backward-compatible fallbacks for legacy Voice/Body adapters.
+ */
+export declare function emitExperienceEvents(params: ExperienceEmissionParams): Promise<ExperienceEmissionResult>;

package/dist/experience-emitter.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitExperienceEvents = emitExperienceEvents;
+const index_1 = require("./index");
+/**
+ * Creates ExperienceEvents, dispatches them through the ExperienceDispatcher,
+ * and coordinates backward-compatible fallbacks for legacy Voice/Body adapters.
+ */
+async function emitExperienceEvents(params) {
+    const { companionId, requestContext, stagedPlan, gateEval, speech, language, dispatcher, voice, body, } = params;
+    const experienceEvents = (0, index_1.createExperienceEvents)({
+        responseId: stagedPlan.responseId,
+        companionId,
+        correlationId: requestContext.conversation.correlationId,
+        channel: requestContext.conversation?.channel,
+        speech,
+        language: language || 'ja',
+        evidenceIds: gateEval.filteredEvidenceIds,
+        citations: gateEval.filteredCitations,
+        expression: 'neutral',
+        action: 'talk',
+        expiresAt: stagedPlan.expiresAt,
+    });
+    const dispatchResult = await dispatcher.dispatchEvents(experienceEvents);
+    let speechId;
+    const voiceResult = dispatchResult.eventResults.find((r) => r.event.kind === 'voice');
+    if (voiceResult?.result?.metadata?.speechId) {
+        speechId = voiceResult.result.metadata.speechId;
+    }
+    else if (voice &&
+        typeof voice.handleEvent !== 'function' &&
+        typeof voice.enqueueSpeech === 'function') {
+        speechId = voice.enqueueSpeech(speech, language || 'ja', 1);
+    }
+    if (body && typeof body.handleEvent !== 'function') {
+        if (typeof body.setExpression === 'function') {
+            body.setExpression('neutral');
+        }
+        if (typeof body.act === 'function') {
+            body.act('talk');
+        }
+    }
+    return {
+        experienceEvents,
+        speechId,
+    };
+}

package/dist/experience.d.ts

@@ -0,0 +1,55 @@
+import { ResponseCitation } from './evidence';
+export type ExperienceEventKind = 'voice' | 'caption' | 'avatar' | 'platform_action';
+export type ExperienceEventLifecycle = 'STARTED' | 'PROGRESS' | 'COMPLETED' | 'FAILED';
+export interface ExperienceEvent {
+    eventId: string;
+    companionId: string;
+    responseId: string;
+    correlationId: string;
+    channel?: string;
+    approval: 'APPROVED';
+    kind: ExperienceEventKind;
+    lifecycle: ExperienceEventLifecycle;
+    evidenceIds: string[];
+    citations?: ResponseCitation[];
+    text?: string;
+    language?: string;
+    action?: string;
+    expression?: string;
+    createdAt: string;
+    expiresAt?: string;
+    [key: string]: unknown;
+}
+export interface ExperienceAdapterResult {
+    accepted: boolean;
+    eventId: string;
+    lifecycle: ExperienceEventLifecycle;
+    error?: string;
+    reason?: string;
+    audioBuffer?: Uint8Array;
+    metadata?: Record<string, unknown>;
+}
+export interface ExperienceAdapter {
+    readonly kind: ExperienceEventKind;
+    handleEvent(event: ExperienceEvent): Promise<ExperienceAdapterResult>;
+}
+export interface CreateExperienceEventsOptions {
+    responseId: string;
+    companionId: string;
+    correlationId: string;
+    channel?: string;
+    speech: string;
+    language?: string;
+    evidenceIds?: string[];
+    citations?: ResponseCitation[];
+    expression?: string;
+    action?: string;
+    expiresAt?: string;
+    now?: string | Date;
+    [key: string]: unknown;
+}
+export declare function createExperienceEvents(options: CreateExperienceEventsOptions): ExperienceEvent[];
+export declare function validateExperienceEvent(event: unknown): {
+    valid: boolean;
+    error?: string;
+};

package/dist/experience.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createExperienceEvents = createExperienceEvents;
+exports.validateExperienceEvent = validateExperienceEvent;
+function generateEventId(kind) {
+    return `evt-${kind}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function createExperienceEvents(options) {
+    const nowStr = options.now
+        ? new Date(options.now).toISOString()
+        : new Date().toISOString();
+    const events = [];
+    // 1. Voice event
+    events.push({
+        eventId: generateEventId('voice'),
+        companionId: options.companionId,
+        responseId: options.responseId,
+        correlationId: options.correlationId,
+        channel: options.channel,
+        approval: 'APPROVED',
+        kind: 'voice',
+        lifecycle: 'STARTED',
+        evidenceIds: options.evidenceIds ?? [],
+        citations: options.citations,
+        text: options.speech,
+        language: options.language || 'ja',
+        createdAt: nowStr,
+        expiresAt: options.expiresAt,
+    });
+    // 2. Avatar/Body event
+    events.push({
+        eventId: generateEventId('avatar'),
+        companionId: options.companionId,
+        responseId: options.responseId,
+        correlationId: options.correlationId,
+        channel: options.channel,
+        approval: 'APPROVED',
+        kind: 'avatar',
+        lifecycle: 'STARTED',
+        evidenceIds: options.evidenceIds ?? [],
+        text: options.speech,
+        language: options.language || 'ja',
+        expression: options.expression || 'neutral',
+        action: options.action || 'talk',
+        createdAt: nowStr,
+        expiresAt: options.expiresAt,
+    });
+    return events;
+}
+function validateExperienceEvent(event) {
+    if (!event || typeof event !== 'object') {
+        return { valid: false, error: 'Event must be an object' };
+    }
+    const e = event;
+    if (!e.eventId || typeof e.eventId !== 'string')
+        return { valid: false, error: 'Missing or invalid eventId' };
+    if (!e.companionId || typeof e.companionId !== 'string')
+        return { valid: false, error: 'Missing or invalid companionId' };
+    if (!e.responseId || typeof e.responseId !== 'string')
+        return { valid: false, error: 'Missing or invalid responseId' };
+    if (!e.correlationId || typeof e.correlationId !== 'string')
+        return { valid: false, error: 'Missing or invalid correlationId' };
+    if (e.approval !== 'APPROVED')
+        return { valid: false, error: 'Event approval must be APPROVED' };
+    if (!['voice', 'caption', 'avatar', 'platform_action'].includes(e.kind)) {
+        return { valid: false, error: `Invalid kind: ${e.kind}` };
+    }
+    if (!['STARTED', 'PROGRESS', 'COMPLETED', 'FAILED'].includes(e.lifecycle)) {
+        return { valid: false, error: `Invalid lifecycle: ${e.lifecycle}` };
+    }
+    if (!Array.isArray(e.evidenceIds))
+        return { valid: false, error: 'Missing or invalid evidenceIds array' };
+    return { valid: true };
+}

package/dist/experience.test.d.ts

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

package/dist/experience.test.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const experience_1 = require("./experience");
+describe('T5 Experience Event Contract Suite', () => {
+    const baseEventOptions = {
+        responseId: 'resp-123',
+        companionId: 'companion-a',
+        correlationId: 'corr-123',
+        channel: 'public',
+        speech: 'Hello world',
+        language: 'en',
+        evidenceIds: ['ev-1'],
+        expression: 'happy',
+        action: 'wave',
+    };
+    test('creates structured voice and avatar experience events from approved response options', () => {
+        const events = (0, experience_1.createExperienceEvents)(baseEventOptions);
+        expect(events.length).toBe(2);
+        const voiceEvent = events.find((e) => e.kind === 'voice');
+        expect(voiceEvent).toBeDefined();
+        expect(voiceEvent?.approval).toBe('APPROVED');
+        expect(voiceEvent?.companionId).toBe('companion-a');
+        expect(voiceEvent?.correlationId).toBe('corr-123');
+        expect(voiceEvent?.text).toBe('Hello world');
+        expect(voiceEvent?.language).toBe('en');
+        expect(voiceEvent?.evidenceIds).toEqual(['ev-1']);
+        const avatarEvent = events.find((e) => e.kind === 'avatar');
+        expect(avatarEvent).toBeDefined();
+        expect(avatarEvent?.approval).toBe('APPROVED');
+        expect(avatarEvent?.expression).toBe('happy');
+        expect(avatarEvent?.action).toBe('wave');
+    });
+    test('validates experience event envelope correctly', () => {
+        const events = (0, experience_1.createExperienceEvents)(baseEventOptions);
+        for (const e of events) {
+            const val = (0, experience_1.validateExperienceEvent)(e);
+            expect(val.valid).toBe(true);
+            expect(val.error).toBeUndefined();
+        }
+    });
+    test('rejects unapproved experience event', () => {
+        const events = (0, experience_1.createExperienceEvents)(baseEventOptions);
+        const unapproved = { ...events[0], approval: 'STAGED' };
+        const val = (0, experience_1.validateExperienceEvent)(unapproved);
+        expect(val.valid).toBe(false);
+        expect(val.error).toContain('Event approval must be APPROVED');
+    });
+    test('rejects missing metadata (companionId, responseId, etc.)', () => {
+        const events = (0, experience_1.createExperienceEvents)(baseEventOptions);
+        const missingCompanion = { ...events[0], companionId: '' };
+        expect((0, experience_1.validateExperienceEvent)(missingCompanion).valid).toBe(false);
+        const missingResponseId = { ...events[0], responseId: '' };
+        expect((0, experience_1.validateExperienceEvent)(missingResponseId).valid).toBe(false);
+    });
+});

package/dist/gating.d.ts

@@ -0,0 +1,45 @@
+import { RequestContext } from './context';
+import { MemoryProposal, BehaviorProposal } from './proposals';
+import { EvidenceRecord, StagedResponsePlan, ResponseGateEvaluation, ResponseCitation } from './evidence';
+export interface StageResponseOptions {
+    requestContext: RequestContext;
+    candidateSpeech: string;
+    candidateLanguage: string;
+    internalMonologue?: string;
+    memoryProposals?: MemoryProposal[];
+    behaviorProposals?: BehaviorProposal[];
+    evidenceRecords?: EvidenceRecord[];
+    citations?: ResponseCitation[];
+    requiresApproval?: boolean;
+    ttlMs?: number;
+    now?: string | Date;
+}
+export interface ApproveResponseOptions {
+    responseId: string;
+    companionId: string;
+    correlationId: string;
+}
+export interface RejectResponseOptions {
+    responseId: string;
+    companionId: string;
+    correlationId: string;
+    reason?: string;
+}
+export declare class ResponseGatingEngine {
+    private readonly stagedPlans;
+    private readonly consumedApprovals;
+    stageResponse(options: StageResponseOptions): StagedResponsePlan;
+    evaluateGate(staged: StagedResponsePlan, allEvidence?: EvidenceRecord[], now?: string | Date): ResponseGateEvaluation;
+    approveResponse(options: ApproveResponseOptions): {
+        success: boolean;
+        reason?: string;
+        plan?: StagedResponsePlan;
+    };
+    rejectResponse(options: RejectResponseOptions): {
+        success: boolean;
+        reason?: string;
+        plan?: StagedResponsePlan;
+    };
+    getStagedPlan(responseId: string): StagedResponsePlan | undefined;
+    findStagedPlanByCorrelation(companionId: string, correlationId: string): StagedResponsePlan | undefined;
+}