@sidurijs/core 1.0.0

package/dist/chat-contract.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchCompanionChat = dispatchCompanionChat;
+/**
+ * Canonical helper to dispatch a chat request to a SiduriRuntime instance.
+ * Guarantees a 1:1 identical response structure for localweb (apps/api) and standalone CLI.
+ */
+async function dispatchCompanionChat(runtime, payload) {
+    const runner = 'runtime' in runtime && typeof runtime.handleUserMessage !== 'function'
+        ? runtime.runtime
+        : runtime;
+    const userMessage = payload.message || payload.text || '';
+    const history = Array.isArray(payload.history) ? payload.history : [];
+    let roleOrContext;
+    if (payload.context) {
+        roleOrContext = payload.context;
+    }
+    else if (payload.role) {
+        roleOrContext = payload.role;
+    }
+    else {
+        roleOrContext = 'OWNER';
+    }
+    const requestedSubtitleLang = payload.subtitleLanguage || payload.subtitle_language;
+    const runtimeResult = (payload.medium || payload.signal || requestedSubtitleLang)
+        ? await runner.handleUserMessage(userMessage, roleOrContext, history, payload.medium, payload.signal, requestedSubtitleLang)
+        : await runner.handleUserMessage(userMessage, roleOrContext, history);
+    const delivery = runtimeResult?.delivery;
+    // Normalize response plan
+    const speech = delivery?.displayText ||
+        delivery?.text ||
+        runtimeResult?.response?.subtitle_ja ||
+        runtimeResult?.response?.subtitle_en ||
+        '';
+    const audioUrl = delivery?.audioUrl || runtimeResult?.response?.audio_url;
+    // Extract avatar expression if any event was generated or provided by Mouth delivery
+    let expression = delivery?.expression || 'neutral';
+    if (expression === 'neutral') {
+        const events = runtimeResult?.metadata?.events || [];
+        const avatarEvent = events.find((e) => e.kind === 'avatar' || e.kind === 'body');
+        if (avatarEvent && avatarEvent.expression) {
+            expression = avatarEvent.expression;
+        }
+    }
+    const resolvedSubtitles = {
+        ...(runtimeResult?.response?.subtitles || {}),
+        ...(delivery?.subtitles || {}),
+    };
+    const subtitle = (requestedSubtitleLang && resolvedSubtitles[requestedSubtitleLang]) ||
+        runtimeResult?.response?.subtitle ||
+        (requestedSubtitleLang === 'ja' ? (delivery?.subtitles?.ja ?? runtimeResult?.response?.subtitle_ja) : undefined) ||
+        (requestedSubtitleLang === 'en' ? (delivery?.subtitles?.en ?? runtimeResult?.response?.subtitle_en) : undefined);
+    if (subtitle && requestedSubtitleLang) {
+        resolvedSubtitles[requestedSubtitleLang] = subtitle;
+    }
+    const rawCitations = runtimeResult?.metadata?.citations ?? runtimeResult?.response?.citations ?? [];
+    const normalizedCitations = (Array.isArray(rawCitations) ? rawCitations : []).map((c) => ({
+        evidence_id: c.evidence_id || c.evidenceId,
+        evidenceId: c.evidenceId || c.evidence_id,
+        source_id: c.source_id || c.sourceId,
+        sourceId: c.sourceId || c.source_id,
+        document_id: c.document_id || c.documentId,
+        documentId: c.documentId || c.document_id,
+        chunk_id: c.chunk_id || c.chunkId,
+        chunkId: c.chunkId || c.chunk_id,
+        revision: c.revision,
+        provenance: c.provenance || c.sourceId || c.source_id,
+        preview: c.preview,
+        locator: c.locator,
+    }));
+    // Ensure both spoken_ja and subtitle_en are accessible alongside speech_id and evidence_ids
+    const responsePlan = {
+        speech_id: runtimeResult?.response?.speech_id,
+        audio_url: audioUrl,
+        subtitle_ja: delivery?.subtitles?.ja ?? runtimeResult?.response?.subtitle_ja ?? speech,
+        subtitle_en: delivery?.subtitles?.en ?? runtimeResult?.response?.subtitle_en ?? speech,
+        spoken_ja: delivery?.subtitles?.spoken ?? runtimeResult?.response?.spoken_ja ?? runtimeResult?.response?.subtitle_ja ?? speech,
+        subtitle,
+        subtitle_language: requestedSubtitleLang,
+        subtitles: resolvedSubtitles,
+        evidence_ids: runtimeResult?.metadata?.evidence_ids ?? runtimeResult?.response?.evidence_ids ?? (normalizedCitations.map((c) => c.evidence_id).filter(Boolean)),
+        citations: normalizedCitations,
+        gate: runtimeResult?.response?.gate ?? runtimeResult?.metadata?.gate,
+    };
+    const metadata = {
+        ...(runtimeResult?.metadata || {}),
+        citations: normalizedCitations,
+    };
+    delete metadata.internal_monologue;
+    delete metadata.internalMonologue;
+    return {
+        status: runtimeResult?.status || 'APPROVED',
+        response_id: runtimeResult?.response_id,
+        correlation_id: runtimeResult?.correlation_id,
+        response: responsePlan,
+        delivery,
+        metadata,
+        // Convenience fields for legacy/simple consumers
+        reply: speech,
+        text: speech,
+        audioUrl,
+        expression,
+    };
+}

package/dist/cognition-planner.d.ts

@@ -0,0 +1,15 @@
+import { BrainOrgan, Message, ResponsePlan, MemoryScope } from './index';
+export interface CognitionPlanningParams {
+    companionName: string;
+    brain?: BrainOrgan;
+    systemPrompt: string;
+    contextPrompt: string;
+    recentMessages: Message[];
+    recipient?: MemoryScope;
+    perceivedText: string;
+}
+/**
+ * Invokes BrainOrgan to generate a structured ResponsePlan, or provides
+ * a graceful baseline response if Brain is absent or in headless passive mode.
+ */
+export declare function generateCognitionPlan(params: CognitionPlanningParams): Promise<ResponsePlan>;

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: `[Companion] Acknowledged: ${perceivedText}`,
+        language: 'en',
+    };
+}

package/dist/container.d.ts

@@ -0,0 +1,74 @@
+import { BrainOrgan, MemoryOrgan, VoiceOrgan, KnowledgeOrgan, VisionOrgan, BehaviorOrgan, BodyOrgan, HandsOrgan, EarOrgan, ObservationOrgan, MouthOrgan, SelfRepository, EKnowledgeOrgan, OrganConfig, ActionStore, ActionPolicyEngine, ResponseGatingEngine, ExperienceDispatcher, ExperienceAdapter } from './index';
+import { SessionHistoryManager } from './session-history';
+import { SiduriRuntime } from './runtime';
+export interface SiduriRuntimeConfig {
+    name: string;
+    brain?: OrganConfig | Record<string, unknown>;
+    voice?: OrganConfig | Record<string, unknown>;
+    memory?: OrganConfig | Record<string, unknown>;
+    knowledge?: OrganConfig | Record<string, unknown>;
+    behavior?: OrganConfig | Record<string, unknown>;
+    body?: OrganConfig | Record<string, unknown>;
+    vision?: OrganConfig | Record<string, unknown>;
+    hands?: OrganConfig | Record<string, unknown>;
+    ear?: OrganConfig | Record<string, unknown>;
+    observation?: OrganConfig | Record<string, unknown>;
+    mouth?: OrganConfig | Record<string, unknown>;
+    self?: OrganConfig | Record<string, unknown>;
+    externalKnowledge?: OrganConfig | Record<string, unknown>;
+    actionPolicy?: Record<string, unknown>;
+    actionStore?: 'in-memory' | 'sqlite' | {
+        type: 'sqlite' | 'in-memory';
+        dbPath?: string;
+    };
+    actionStorePath?: string;
+    [key: string]: unknown;
+}
+export interface RuntimeOrgans {
+    brain?: BrainOrgan;
+    memory?: MemoryOrgan;
+    voice?: VoiceOrgan | ExperienceAdapter;
+    knowledge?: KnowledgeOrgan;
+    vision?: VisionOrgan;
+    behavior?: BehaviorOrgan;
+    body?: BodyOrgan | ExperienceAdapter;
+    hands?: HandsOrgan;
+    ear?: EarOrgan;
+    observation?: ObservationOrgan;
+    mouth?: MouthOrgan;
+    self?: SelfRepository;
+    externalKnowledge?: EKnowledgeOrgan;
+    actionStore?: ActionStore;
+    actionPolicy?: ActionPolicyEngine;
+}
+/**
+ * CompanionContainer manages the lifecycle, discovery, wiring, and dependency injection
+ * of organs and infrastructure for a companion instance.
+ */
+export declare class CompanionContainer {
+    readonly id: string;
+    readonly config: SiduriRuntimeConfig;
+    readonly organs: RuntimeOrgans;
+    readonly gating: ResponseGatingEngine;
+    readonly actionPolicy: ActionPolicyEngine;
+    readonly dispatcher: ExperienceDispatcher;
+    readonly sessionHistory: SessionHistoryManager;
+    private _runtime?;
+    constructor(id: string, config: SiduriRuntimeConfig, organs?: RuntimeOrgans);
+    get brain(): BrainOrgan | undefined;
+    get memory(): MemoryOrgan | undefined;
+    get voice(): ExperienceAdapter | VoiceOrgan | undefined;
+    get knowledge(): KnowledgeOrgan | undefined;
+    get vision(): VisionOrgan | undefined;
+    get behavior(): BehaviorOrgan | undefined;
+    get body(): ExperienceAdapter | BodyOrgan | undefined;
+    get hands(): HandsOrgan | undefined;
+    get ear(): EarOrgan | undefined;
+    get observation(): ObservationOrgan | undefined;
+    set observation(org: ObservationOrgan | undefined);
+    get mouth(): MouthOrgan | undefined;
+    get self(): SelfRepository | undefined;
+    get externalKnowledge(): EKnowledgeOrgan | undefined;
+    initialize(): Promise<void>;
+    get runtime(): SiduriRuntime;
+}

package/dist/container.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompanionContainer = void 0;
+const index_1 = require("./index");
+const session_history_1 = require("./session-history");
+const runtime_1 = require("./runtime");
+/**
+ * CompanionContainer manages the lifecycle, discovery, wiring, and dependency injection
+ * of organs and infrastructure for a companion instance.
+ */
+class CompanionContainer {
+    id;
+    config;
+    organs;
+    gating;
+    actionPolicy;
+    dispatcher;
+    sessionHistory;
+    _runtime;
+    constructor(id, config, organs = {}) {
+        this.id = id;
+        this.config = config;
+        this.organs = organs;
+        this.gating = new index_1.ResponseGatingEngine();
+        let actionStore = organs.actionStore;
+        if (!actionStore) {
+            const storeOpt = config.actionStore;
+            const storePath = config.actionStorePath || (typeof storeOpt === 'object' ? storeOpt.dbPath : undefined);
+            if (storeOpt === 'sqlite' || (typeof storeOpt === 'object' && storeOpt.type === 'sqlite') || storePath) {
+                actionStore = new index_1.SqliteActionStore({ dbPath: storePath });
+            }
+        }
+        this.actionPolicy = organs.actionPolicy || new index_1.ActionPolicyEngine({
+            store: actionStore,
+        });
+        this.dispatcher = new index_1.ExperienceDispatcher();
+        if (this.organs.voice && typeof this.organs.voice.handleEvent === 'function') {
+            this.dispatcher.registerAdapter(this.organs.voice);
+        }
+        if (this.organs.body && typeof this.organs.body.handleEvent === 'function') {
+            this.dispatcher.registerAdapter(this.organs.body);
+        }
+        if (this.organs.mouth && typeof this.organs.mouth.handleEvent === 'function') {
+            this.dispatcher.registerAdapter(this.organs.mouth);
+        }
+        this.sessionHistory = new session_history_1.SessionHistoryManager();
+    }
+    // Direct organ accessors
+    get brain() { return this.organs.brain; }
+    get memory() { return this.organs.memory; }
+    get voice() { return this.organs.voice; }
+    get knowledge() { return this.organs.knowledge; }
+    get vision() { return this.organs.vision; }
+    get behavior() { return this.organs.behavior; }
+    get body() { return this.organs.body; }
+    get hands() { return this.organs.hands; }
+    get ear() { return this.organs.ear; }
+    get observation() { return this.organs.observation; }
+    set observation(org) { this.organs.observation = org; }
+    get mouth() { return this.organs.mouth; }
+    get self() { return this.organs.self; }
+    get externalKnowledge() { return this.organs.externalKnowledge; }
+    async initialize() {
+        if (this.organs.memory && typeof this.organs.memory.initialize === 'function') {
+            await this.organs.memory.initialize(this.id);
+        }
+        if (this.organs.hands && typeof this.organs.hands.listTools === 'function') {
+            const tools = await this.organs.hands.listTools();
+            for (const tool of tools) {
+                this.actionPolicy.registerToolDefinition(tool);
+            }
+        }
+    }
+    get runtime() {
+        if (!this._runtime) {
+            this._runtime = new runtime_1.SiduriRuntime(this.id, this.config, this);
+        }
+        return this._runtime;
+    }
+}
+exports.CompanionContainer = CompanionContainer;

package/dist/context-retriever.d.ts

@@ -0,0 +1,33 @@
+import { KnowledgeOrgan, MemoryOrgan, KnowledgeItem, Claim, BehaviorDirective, EvidenceRecord, ResponseCitation, RequestContext, SelfRepository, LifeDatabase, EpisodicMemoryStore, EKnowledgeOrgan } from './index';
+export interface ContextRetrievalParams {
+    companionId: string;
+    perceivedText: string;
+    requestContext: RequestContext;
+    role: 'OWNER' | 'VIEWER' | 'OPERATOR';
+    isContextObject: boolean;
+    shouldQueryKnowledge: boolean;
+    knowledgeQueries?: string[];
+    memoryQueries?: string[];
+    isSelfIdentityRequest?: boolean;
+    knowledge?: KnowledgeOrgan | LifeDatabase;
+    memory?: MemoryOrgan | EpisodicMemoryStore;
+    self?: SelfRepository;
+    externalKnowledge?: EKnowledgeOrgan | KnowledgeOrgan;
+}
+export interface RetrievedContext {
+    knowledgeData: KnowledgeItem[];
+    memoryData: Claim[];
+    activeDirectives: BehaviorDirective[];
+    subsystemDiagnostics: Record<string, string>;
+    collectedEvidence: EvidenceRecord[];
+    citations: ResponseCitation[];
+    lifeContext?: string[];
+    selfIdentity?: any;
+    selfRelationship?: any;
+    personality?: any;
+}
+/**
+ * Concurrently queries Self, Knowledge (Life DB), External Knowledge, and Memory
+ * in a single parallel pass with graceful degradation.
+ */
+export declare function retrieveRuntimeContext(params: ContextRetrievalParams): Promise<RetrievedContext>;

package/dist/context-retriever.js

@@ -0,0 +1,260 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retrieveRuntimeContext = retrieveRuntimeContext;
+const intent_classifier_1 = require("./intent-classifier");
+/**
+ * Concurrently queries Self, Knowledge (Life DB), External Knowledge, and Memory
+ * in a single parallel pass with graceful degradation.
+ */
+async function retrieveRuntimeContext(params) {
+    const { companionId, perceivedText, requestContext, role, isContextObject, shouldQueryKnowledge, knowledgeQueries, memoryQueries, isSelfIdentityRequest, knowledge, memory, self, externalKnowledge, } = params;
+    const queryOptions = isContextObject
+        ? {
+            limit: 5,
+        }
+        : role;
+    const subsystemDiagnostics = {};
+    // 1. Resolve External Knowledge organ (either explicitly passed or from legacy knowledge with .search)
+    const extKnowledge = externalKnowledge || (knowledge && typeof knowledge.search === 'function' ? knowledge : undefined);
+    // Formulate queries: combine AI/cognitive queries, entity keywords, and cleaned query variants
+    const keywordQueries = (0, intent_classifier_1.extractSearchKeywords)(perceivedText, companionId, requestContext?.history);
+    const aiQueries = (knowledgeQueries || []).filter(Boolean);
+    // Clean AI queries of conversational filler if present (e.g. 'what is the lore on Sandrone' -> 'Sandrone')
+    const cleanedAiQueries = aiQueries.map((q) => q.replace(/^(?:what(?:\s+is|\s+are)?|who(?:\s+is|\s+are)?|tell(?:\s+me)?(?:\s+about)?|search(?:\s+for)?|information(?:\s+on|\s+about)?|details(?:\s+on|\s+about)?|lore(?:\s+for|\s+on|\s+about)?)\s+/gi, '').trim()).filter((q) => q.length > 0);
+    const queryCandidateSet = new Set();
+    for (const q of [...keywordQueries, ...aiQueries, ...cleanedAiQueries]) {
+        if (q && q.trim()) {
+            queryCandidateSet.add(q.trim());
+        }
+    }
+    if (queryCandidateSet.size === 0 && perceivedText && perceivedText.trim()) {
+        queryCandidateSet.add(perceivedText.trim());
+    }
+    const finalKnowledgeQueries = Array.from(queryCandidateSet);
+    const memoryQueryToRun = (memoryQueries && memoryQueries.length > 0 && memoryQueries[0])
+        ? memoryQueries[0]
+        : (0, intent_classifier_1.extractSearchKeywords)(perceivedText, companionId)[0] || perceivedText;
+    // 2. Query streams in parallel
+    const [knowledgeData, memoryData, selfOrMemoryDirectives, lifeContext, selfIdentity, selfRelationship, personality,] = await Promise.all([
+        // Stream A: External Cited Lore / Documentation
+        extKnowledge && shouldQueryKnowledge && typeof extKnowledge.search === 'function'
+            ? Promise.all(finalKnowledgeQueries.map((q) => extKnowledge.search(q).catch((e) => {
+                console.error(`[SiduriRuntime] Knowledge search failed for "${q}":`, e.message);
+                subsystemDiagnostics['knowledge'] = `UNAVAILABLE: ${e.message}`;
+                return [];
+            }))).then((resultsArray) => {
+                const merged = [];
+                const seen = new Set();
+                for (const list of resultsArray) {
+                    if (!Array.isArray(list))
+                        continue;
+                    for (const item of list) {
+                        const key = item.id || item.content || item.text || JSON.stringify(item.citations);
+                        if (!seen.has(key)) {
+                            seen.add(key);
+                            merged.push(item);
+                        }
+                    }
+                }
+                return merged;
+            })
+            : Promise.resolve([]),
+        // Stream B: Episodic Memory / Verified Claims (SQLite FTS5 with Identity Fallback)
+        memory && typeof memory.searchClaims === 'function'
+            ? (async () => {
+                try {
+                    // Support both (companionId, query, limit) and (query, options, limit)
+                    let result = await memory.searchClaims(memoryQueryToRun, queryOptions, 5);
+                    if ((!result || result.length === 0) && isSelfIdentityRequest) {
+                        if (typeof memory.getApprovedClaims === 'function') {
+                            const approved = await memory.getApprovedClaims(companionId, 10);
+                            const identityClaims = approved.filter((c) => {
+                                const pred = (c.predicate || '').toLowerCase();
+                                const subj = (c.subject || '').toLowerCase();
+                                return (['name', 'role', 'stated_relationship', 'relationship', 'origin', 'created_by', 'preferred_address', 'title', 'identity', 'creator', 'archetype', 'affiliation'].includes(pred) ||
+                                    subj.startsWith('companion') ||
+                                    subj === 'self' ||
+                                    subj === 'siduri' ||
+                                    subj.startsWith('actor:'));
+                            });
+                            result = identityClaims.length > 0 ? identityClaims.slice(0, 5) : approved.slice(0, 5);
+                        }
+                        else if (typeof memory.getClaims === 'function') {
+                            const all = await memory.getClaims(50);
+                            const approved = all.filter((c) => (c.status || '').toLowerCase() === 'approved');
+                            result = approved.slice(0, 5);
+                        }
+                    }
+                    return result || [];
+                }
+                catch (e) {
+                    console.error('[SiduriRuntime] Memory search failed:', e.message);
+                    subsystemDiagnostics['memory_claims'] = `UNAVAILABLE: ${e.message}`;
+                    return [];
+                }
+            })()
+            : Promise.resolve([]),
+        // Stream C: Active Directives from Self (or fallback Memory)
+        self && typeof self.getActiveDirectives === 'function'
+            ? self.getActiveDirectives(companionId).catch((e) => {
+                console.error('[SiduriRuntime] Self directives failed:', e.message);
+                subsystemDiagnostics['self_directives'] = `UNAVAILABLE: ${e.message}`;
+                return [];
+            })
+            : 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([]),
+        // Stream D: Sovereign Life DB Context (Finances, Inventory, Schedule, Preferences)
+        knowledge && typeof knowledge.queryContext === 'function'
+            ? knowledge.queryContext(companionId, perceivedText).catch((e) => {
+                console.error('[SiduriRuntime] Life DB context failed:', e.message);
+                subsystemDiagnostics['life_db'] = `UNAVAILABLE: ${e.message}`;
+                return [];
+            })
+            : Promise.resolve([]),
+        // Stream E: Self Identity
+        self && typeof self.getIdentity === 'function'
+            ? self.getIdentity(companionId).catch((e) => {
+                console.error('[SiduriRuntime] Self identity failed:', e.message);
+                return undefined;
+            })
+            : Promise.resolve(undefined),
+        // Stream F: Self Relationship toward interacting actor
+        self && typeof self.getRelationship === 'function' && requestContext.actor?.actorId
+            ? self.getRelationship(companionId, requestContext.actor.actorId).catch((e) => {
+                console.error('[SiduriRuntime] Self relationship failed:', e.message);
+                return null;
+            })
+            : Promise.resolve(null),
+        // Stream G: Self Personality
+        self && typeof self.getPersonality === 'function'
+            ? self.getPersonality(companionId).catch(() => undefined)
+            : Promise.resolve(undefined),
+    ]);
+    const activeDirectives = (selfOrMemoryDirectives || []);
+    // Build evidence records from retrieved context streams
+    const collectedEvidence = [];
+    const citations = [];
+    // Stream A: External Knowledge
+    if (knowledgeData.length > 0) {
+        for (const k of knowledgeData) {
+            const previewText = k.content || k.text || k.summary || k.preview || '';
+            if (k.evidenceRecord) {
+                const nativeRecord = {
+                    ...k.evidenceRecord,
+                };
+                collectedEvidence.push(nativeRecord);
+                citations.push({
+                    evidenceId: nativeRecord.evidenceId,
+                    provenance: k.provenance || nativeRecord.sourceId || 'knowledge',
+                    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,
+                    preview: previewText.slice(0, 300),
+                });
+            }
+            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({
+                    evidenceId: evId,
+                    provenance: sourceId,
+                    sourceId,
+                    revision: k.revision,
+                    documentId: k.citations?.[0]?.documentId,
+                    chunkId: k.citations?.[0]?.chunkId,
+                    locator: k.citations?.[0]?.locator,
+                    preview: previewText.slice(0, 300),
+                });
+            }
+        }
+    }
+    // Stream B: Episodic Memory Claims
+    if (memoryData.length > 0) {
+        for (const m of memoryData) {
+            const claimId = m.claim_id || m.id || `claim-${Date.now()}`;
+            const sourceId = m.provenance || 'sqlite-memory';
+            const evId = `ev-mem-${claimId}`;
+            const claimPreview = m.content || `${m.subject || 'user'} ${m.predicate || 'claims'}: ${m.value || ''}`;
+            collectedEvidence.push({
+                evidenceId: evId,
+                sourceId,
+                documentId: claimId,
+                chunkId: `${m.subject || 'user'}:${m.predicate || 'claim'}`,
+                origin: 'memory',
+                trust: 'configured',
+                sensitivity: 'private',
+                companionId,
+                correlationId: requestContext.conversation.correlationId,
+                createdAt: new Date().toISOString(),
+            });
+            citations.push({
+                evidenceId: evId,
+                provenance: 'memory',
+                sourceId,
+                documentId: claimId,
+                chunkId: `${m.subject || 'user'}.${m.predicate || 'claim'}`,
+                locator: `claim:${claimId}`,
+                preview: claimPreview.slice(0, 300),
+            });
+        }
+    }
+    // Stream D: Life DB Context Items
+    if (lifeContext && lifeContext.length > 0) {
+        for (let i = 0; i < lifeContext.length; i++) {
+            const item = lifeContext[i];
+            const evId = `ev-life-${Date.now()}-${i}`;
+            const sourceId = 'sqlite-lifedb';
+            const itemPreview = item.title || item.name || item.summary || JSON.stringify(item);
+            collectedEvidence.push({
+                evidenceId: evId,
+                sourceId,
+                documentId: `item-${i}`,
+                origin: 'life',
+                trust: 'configured',
+                sensitivity: 'private',
+                companionId,
+                correlationId: requestContext.conversation.correlationId,
+                createdAt: new Date().toISOString(),
+            });
+            citations.push({
+                evidenceId: evId,
+                provenance: 'life',
+                sourceId,
+                documentId: `item-${i}`,
+                locator: `lifedb:item:${i}`,
+                preview: itemPreview.slice(0, 300),
+            });
+        }
+    }
+    return {
+        knowledgeData,
+        memoryData,
+        activeDirectives,
+        subsystemDiagnostics,
+        collectedEvidence,
+        citations,
+        lifeContext,
+        selfIdentity,
+        selfRelationship,
+        personality,
+    };
+}

package/dist/context.d.ts

@@ -0,0 +1,46 @@
+export interface ActorContext {
+    actorId: string;
+    sessionId: string;
+    authenticated?: boolean;
+    capabilities?: string[];
+    [key: string]: unknown;
+}
+export interface ConversationContext {
+    correlationId: string;
+    sessionId?: string;
+    channel?: string;
+    [key: string]: unknown;
+}
+export type SubjectKind = 'actor' | 'companion' | 'configured';
+export type InteractionMode = 'casual' | 'teach' | 'hybrid';
+export interface SubjectRef {
+    subjectId: string;
+    kind: SubjectKind;
+    ownerActorId?: string;
+}
+export interface RequestContext {
+    companionId: string;
+    actor: ActorContext;
+    conversation: ConversationContext;
+    source?: 'local' | 'external' | string;
+    subject?: SubjectRef;
+    mode?: InteractionMode;
+    metadata?: Record<string, unknown>;
+}
+export type DiagnosticCode = 'legacy_role_removed' | 'anonymous_session_generated' | 'companion_default_mapped_for_bootstrap' | 'actor_scoped_subject_mapped' | 'role_escalation_attempt_suppressed' | 'capability_escalation_attempt_suppressed';
+export type ContextErrorCode = 'MISSING_CONTEXT' | 'INVALID_CONTEXT' | 'FORBIDDEN_CONTEXT' | '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;