@siduri-x/core 1.0.5 → 1.0.7

package/dist/cognition-planner.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateCognitionPlan = generateCognitionPlan;
+/**
+ * Invokes BrainOrgan to generate a structured ResponsePlan, or provides
+ * a graceful baseline response if Brain is absent or in headless passive mode.
+ */
+async function generateCognitionPlan(params) {
+    const { companionName, brain, systemPrompt, contextPrompt, recentMessages, recipient, perceivedText, } = params;
+    if (brain && typeof brain.generatePlan === 'function') {
+        return brain.generatePlan({
+            systemPrompt,
+            contextPrompt,
+            recentMessages,
+            recipient,
+        });
+    }
+    // Graceful baseline response when Brain is not configured or in headless passive mode
+    return {
+        speech: `[Siduri ${companionName}] Acknowledged: ${perceivedText}`,
+        language: 'en',
+    };
+}

package/dist/context-retriever.d.ts

@@ -0,0 +1,24 @@
+import { KnowledgeOrgan, MemoryOrgan, KnowledgeItem, Claim, BehaviorDirective, EvidenceRecord, ResponseCitation, RequestContext } from './index';
+export interface ContextRetrievalParams {
+    companionId: string;
+    perceivedText: string;
+    requestContext: RequestContext;
+    role: 'OWNER' | 'VIEWER' | 'OPERATOR';
+    isContextObject: boolean;
+    shouldQueryKnowledge: boolean;
+    knowledge?: KnowledgeOrgan;
+    memory?: MemoryOrgan;
+}
+export interface RetrievedContext {
+    knowledgeData: KnowledgeItem[];
+    memoryData: Claim[];
+    activeDirectives: BehaviorDirective[];
+    subsystemDiagnostics: Record<string, string>;
+    collectedEvidence: EvidenceRecord[];
+    citations: ResponseCitation[];
+}
+/**
+ * Concurrently queries Knowledge and Memory organs with graceful degradation,
+ * collecting diagnostics and synthesizing evidence records and citations.
+ */
+export declare function retrieveRuntimeContext(params: ContextRetrievalParams): Promise<RetrievedContext>;

package/dist/context-retriever.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retrieveRuntimeContext = retrieveRuntimeContext;
+/**
+ * Concurrently queries Knowledge and Memory organs with graceful degradation,
+ * collecting diagnostics and synthesizing evidence records and citations.
+ */
+async function retrieveRuntimeContext(params) {
+    const { companionId, perceivedText, requestContext, role, isContextObject, shouldQueryKnowledge, knowledge, memory, } = params;
+    const queryOptions = isContextObject
+        ? {
+            channel: requestContext.conversation.channel,
+            audienceId: requestContext.conversation.audienceId,
+            limit: 5,
+        }
+        : role;
+    const subsystemDiagnostics = {};
+    const [knowledgeData, memoryData, activeDirectives] = await Promise.all([
+        knowledge && shouldQueryKnowledge && typeof knowledge.search === 'function'
+            ? knowledge.search(perceivedText).catch((e) => {
+                console.error('[SiduriRuntime] Knowledge search failed:', e.message);
+                subsystemDiagnostics['knowledge'] = `UNAVAILABLE: ${e.message}`;
+                return [];
+            })
+            : Promise.resolve([]),
+        memory && typeof memory.searchClaims === 'function'
+            ? memory.searchClaims(perceivedText, queryOptions, 5).catch((e) => {
+                console.error('[SiduriRuntime] Memory search failed:', e.message);
+                subsystemDiagnostics['memory_claims'] = `UNAVAILABLE: ${e.message}`;
+                return [];
+            })
+            : Promise.resolve([]),
+        memory && typeof memory.getDirectives === 'function'
+            ? memory.getDirectives().catch((e) => {
+                console.error('[SiduriRuntime] Memory directives failed:', e.message);
+                subsystemDiagnostics['memory_directives'] = `UNAVAILABLE: ${e.message}`;
+                return [];
+            })
+            : Promise.resolve([]),
+    ]);
+    // Build evidence records from retrieved knowledge context
+    const collectedEvidence = [];
+    const citations = [];
+    if (knowledgeData.length > 0) {
+        for (const k of knowledgeData) {
+            if (k.evidenceRecord) {
+                const nativeRecord = {
+                    ...k.evidenceRecord,
+                };
+                collectedEvidence.push(nativeRecord);
+                citations.push({
+                    sourceId: nativeRecord.sourceId,
+                    revision: nativeRecord.revision,
+                    documentId: nativeRecord.documentId || k.citations?.[0]?.documentId,
+                    chunkId: nativeRecord.chunkId || k.citations?.[0]?.chunkId,
+                    locator: nativeRecord.locator || k.citations?.[0]?.locator,
+                });
+            }
+            else {
+                // Synthesize fallback evidence record with provenance
+                const evId = `ev-know-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+                const sourceId = k.provenance || 'configured-knowledge';
+                collectedEvidence.push({
+                    evidenceId: evId,
+                    sourceId,
+                    revision: k.revision,
+                    origin: 'knowledge',
+                    trust: 'configured',
+                    sensitivity: 'public',
+                    companionId,
+                    correlationId: requestContext.conversation.correlationId,
+                    createdAt: new Date().toISOString(),
+                });
+                citations.push({
+                    sourceId,
+                    revision: k.revision,
+                    documentId: k.citations?.[0]?.documentId,
+                    chunkId: k.citations?.[0]?.chunkId,
+                    locator: k.citations?.[0]?.locator,
+                });
+            }
+        }
+    }
+    return {
+        knowledgeData,
+        memoryData,
+        activeDirectives,
+        subsystemDiagnostics,
+        collectedEvidence,
+        citations,
+    };
+}

package/dist/context.d.ts

@@ -0,0 +1,45 @@
+export interface ActorContext {
+    actorId: string;
+    sessionId: string;
+    authenticated?: boolean;
+    capabilities?: string[];
+    [key: string]: unknown;
+}
+export interface ConversationContext {
+    correlationId: string;
+    sessionId?: string;
+    channel?: string;
+    audienceId?: string;
+    [key: string]: unknown;
+}
+export type SubjectKind = 'actor' | 'companion' | 'configured';
+export interface SubjectRef {
+    subjectId: string;
+    kind: SubjectKind;
+    ownerActorId?: string;
+}
+export interface RequestContext {
+    companionId: string;
+    actor: ActorContext;
+    conversation: ConversationContext;
+    source?: 'local' | 'external' | string;
+    subject?: SubjectRef;
+    metadata?: Record<string, unknown>;
+}
+export type DiagnosticCode = 'legacy_role_removed' | 'anonymous_session_generated' | 'companion_default_mapped_for_bootstrap' | 'actor_scoped_subject_mapped';
+export type ContextErrorCode = 'MISSING_CONTEXT' | 'INVALID_CONTEXT' | 'FORBIDDEN_CONTEXT' | 'LEGACY_PERSONAL_AUDIENCE' | 'AMBIGUOUS_CONTEXT' | 'UNAUTHORIZED_CAPABILITY';
+export interface ContextError {
+    code: ContextErrorCode;
+    message?: string;
+    fields?: string[];
+    field?: string;
+    correlationId?: string;
+}
+export interface RequestContextValidationResult {
+    accepted: boolean;
+    context?: RequestContext;
+    diagnostics?: DiagnosticCode[];
+    error?: ContextError;
+}
+export declare function isValidSubjectKind(kind: unknown): kind is SubjectKind;
+export declare function validateRequestContext(context: unknown): RequestContextValidationResult;

package/dist/context.js

@@ -0,0 +1,72 @@
+"use strict";
+// Single-owner, single-machine context model
+// Security perimeter is the local machine boundary (external vs internal).
+// No internal audience, viewer, or owner role hierarchies.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidSubjectKind = isValidSubjectKind;
+exports.validateRequestContext = validateRequestContext;
+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 (!ctx.conversation || typeof ctx.conversation !== 'object') {
+        missingFields.push('conversation');
+    }
+    else {
+        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,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const context_1 = require("./context");
+describe('Core Context Contract (Single-Owner Single-Machine)', () => {
+    const validContext = {
+        companionId: 'companion-a',
+        actor: {
+            actorId: 'local-user',
+            sessionId: 'session-a',
+            authenticated: true,
+            capabilities: ['chat:interact'],
+        },
+        conversation: {
+            correlationId: 'corr-a',
+        },
+        subject: {
+            subjectId: 'actor:local-user',
+            kind: 'actor',
+            ownerActorId: 'local-user',
+        },
+    };
+    test('validates a correct 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 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);
+    });
+});

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' | '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;
+    [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' | '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?: string;
+    audienceId?: 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;
+    audienceId?: 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,47 @@
+"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. Optional audience intersection (audience-public is accessible everywhere)
+        if (options.audienceId &&
+            record.allowedAudiences &&
+            record.allowedAudiences.length > 0 &&
+            !record.allowedAudiences.includes('audience-public') &&
+            !record.allowedAudiences.includes(options.audienceId)) {
+            excluded.push({ record, reason: 'audience_not_allowed' });
+            continue;
+        }
+        // 4. Optional channel sensitivity policy (if channel explicitly specified)
+        if (options.channel === 'public') {
+            if (record.sensitivity && 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 {};