@siduri-x/core 1.0.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,72 @@
+export type EvidenceOrigin = 'knowledge' | '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;
+    allowedAudiences: string[];
+    companionId: string;
+    correlationId: string;
+}
+export type ResponseApprovalStatus = 'STAGED' | 'APPROVED' | 'REJECTED' | 'EXPIRED' | 'EMITTED';
+export type ResponseGateReasonCode = 'APPROVED_DIRECT' | 'APPROVAL_REQUIRED' | 'UNKNOWN_APPROVAL_ID' | 'APPROVAL_ID_MISMATCH' | 'COMPANION_MISMATCH' | 'AUDIENCE_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;
+}
+export interface StagedResponsePlan {
+    responseId: string;
+    companionId: string;
+    correlationId: string;
+    channel: 'public' | 'direct' | 'private' | 'operator';
+    audienceId: string;
+    speech: string;
+    language: string;
+    evidenceIds: string[];
+    citations: ResponseCitation[];
+    confidenceSummary: number;
+    uncertaintySummary?: string;
+    requiresApproval: boolean;
+    status: ResponseApprovalStatus;
+    createdAt: string;
+    expiresAt?: string;
+    memoryProposals?: any[];
+    behaviorProposals?: any[];
+    internalMonologue?: string;
+}
+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: 'public' | 'direct' | 'private' | 'operator';
+    audienceId: string;
+    now?: string | Date;
+}
+export declare function filterEvidenceRecords(records: EvidenceRecord[], options: EvidenceFilterOptions): {
+    admitted: EvidenceRecord[];
+    excluded: {
+        record: EvidenceRecord;
+        reason: string;
+    }[];
+};

package/dist/evidence.js

@@ -0,0 +1,45 @@
+"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;
+            }
+        }
+        // 3. Audience intersection
+        if (record.allowedAudiences &&
+            record.allowedAudiences.length > 0 &&
+            !record.allowedAudiences.includes(options.audienceId)) {
+            excluded.push({ record, reason: 'audience_not_allowed' });
+            continue;
+        }
+        // 4. Sensitivity policy based on channel
+        if (options.channel === 'public') {
+            if (record.sensitivity !== 'public') {
+                excluded.push({ record, reason: 'sensitivity_private_in_public_channel' });
+                continue;
+            }
+        }
+        else if (options.channel === 'direct') {
+            if (record.sensitivity === 'restricted') {
+                excluded.push({ record, reason: 'sensitivity_restricted_in_direct_channel' });
+                continue;
+            }
+        }
+        admitted.push(record);
+    }
+    return { admitted, excluded };
+}

package/dist/evidence.test.d.ts

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

package/dist/evidence.test.js

@@ -0,0 +1,101 @@
+"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',
+        allowedAudiences: ['audience-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',
+            audienceId: 'audience-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',
+            audienceId: 'audience-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('audience intersection excludes non-matching audiences', () => {
+        const records = [
+            { ...baseRecord, evidenceId: 'ev-public', allowedAudiences: ['audience-public'] },
+            { ...baseRecord, evidenceId: 'ev-direct-only', allowedAudiences: ['audience-direct-a'] },
+        ];
+        const options = {
+            companionId: 'companion-a',
+            channel: 'public',
+            audienceId: 'audience-public',
+        };
+        const { admitted, excluded } = (0, evidence_1.filterEvidenceRecords)(records, options);
+        expect(admitted.map((e) => e.evidenceId)).toEqual(['ev-public']);
+        expect(excluded).toEqual([
+            expect.objectContaining({
+                record: expect.objectContaining({ evidenceId: 'ev-direct-only' }),
+                reason: 'audience_not_allowed',
+            }),
+        ]);
+    });
+    test('sensitivity policy excludes private and restricted evidence from public channels', () => {
+        const records = [
+            { ...baseRecord, evidenceId: 'ev-pub', sensitivity: 'public', allowedAudiences: ['audience-public'] },
+            { ...baseRecord, evidenceId: 'ev-priv', sensitivity: 'private', allowedAudiences: ['audience-public'] },
+            { ...baseRecord, evidenceId: 'ev-rest', sensitivity: 'restricted', allowedAudiences: ['audience-public'] },
+        ];
+        const { admitted, excluded } = (0, evidence_1.filterEvidenceRecords)(records, {
+            companionId: 'companion-a',
+            channel: 'public',
+            audienceId: 'audience-public',
+        });
+        expect(admitted.map((e) => e.evidenceId)).toEqual(['ev-pub']);
+        expect(excluded.map((e) => e.record.evidenceId)).toEqual(['ev-priv', 'ev-rest']);
+    });
+    test('direct channel permits private sensitivity but excludes restricted', () => {
+        const records = [
+            { ...baseRecord, evidenceId: 'ev-pub', sensitivity: 'public', allowedAudiences: ['audience-direct-a'] },
+            { ...baseRecord, evidenceId: 'ev-priv', sensitivity: 'private', allowedAudiences: ['audience-direct-a'] },
+            { ...baseRecord, evidenceId: 'ev-rest', sensitivity: 'restricted', allowedAudiences: ['audience-direct-a'] },
+        ];
+        const { admitted, excluded } = (0, evidence_1.filterEvidenceRecords)(records, {
+            companionId: 'companion-a',
+            channel: 'direct',
+            audienceId: 'audience-direct-a',
+        });
+        expect(admitted.map((e) => e.evidenceId)).toEqual(['ev-pub', 'ev-priv']);
+        expect(excluded.map((e) => e.record.evidenceId)).toEqual(['ev-rest']);
+    });
+});

package/dist/experience.d.ts

@@ -0,0 +1,56 @@
+import { Channel } from './context';
+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: Channel;
+    audienceId: string;
+    approval: 'APPROVED';
+    kind: ExperienceEventKind;
+    lifecycle: ExperienceEventLifecycle;
+    evidenceIds: string[];
+    citations?: ResponseCitation[];
+    text?: string;
+    language?: string;
+    action?: string;
+    expression?: string;
+    createdAt: string;
+    expiresAt?: string;
+}
+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: Channel;
+    audienceId: string;
+    speech: string;
+    language?: string;
+    evidenceIds?: string[];
+    citations?: ResponseCitation[];
+    expression?: string;
+    action?: string;
+    expiresAt?: string;
+    now?: string | Date;
+}
+export declare function createExperienceEvents(options: CreateExperienceEventsOptions): ExperienceEvent[];
+export declare function validateExperienceEvent(event: unknown): {
+    valid: boolean;
+    error?: string;
+};

package/dist/experience.js

@@ -0,0 +1,78 @@
+"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,
+        audienceId: options.audienceId,
+        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,
+        audienceId: options.audienceId,
+        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.audienceId || typeof e.audienceId !== 'string')
+        return { valid: false, error: 'Missing or invalid audienceId' };
+    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,58 @@
+"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',
+        audienceId: 'audience-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 missingCorr = { ...events[0], correlationId: '' };
+        expect((0, experience_1.validateExperienceEvent)(missingCorr).valid).toBe(false);
+        const missingAudience = { ...events[0], audienceId: '' };
+        expect((0, experience_1.validateExperienceEvent)(missingAudience).valid).toBe(false);
+    });
+});

package/dist/gating.d.ts

@@ -0,0 +1,45 @@
+import { RequestContext } from './context';
+import { EvidenceRecord, StagedResponsePlan, ResponseGateEvaluation, ResponseCitation } from './evidence';
+export interface StageResponseOptions {
+    requestContext: RequestContext;
+    candidateSpeech: string;
+    candidateLanguage: string;
+    internalMonologue?: string;
+    memoryProposals?: any[];
+    behaviorProposals?: any[];
+    evidenceRecords?: EvidenceRecord[];
+    citations?: ResponseCitation[];
+    requiresApproval?: boolean;
+    ttlMs?: number;
+    now?: string | Date;
+}
+export interface ApproveResponseOptions {
+    responseId: string;
+    companionId: string;
+    correlationId: string;
+    audienceId?: 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;
+}