@sidurijs/core 1.0.0

package/dist/gating.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResponseGatingEngine = void 0;
+const evidence_1 = require("./evidence");
+function generateId(prefix) {
+    return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+class ResponseGatingEngine {
+    stagedPlans = new Map();
+    consumedApprovals = new Set();
+    stageResponse(options) {
+        const { requestContext } = options;
+        const nowTime = options.now ? new Date(options.now).getTime() : Date.now();
+        const ttlMs = options.ttlMs ?? 60_000;
+        const expiresAt = new Date(nowTime + ttlMs).toISOString();
+        const evidenceRecords = options.evidenceRecords ?? [];
+        const evidenceIds = evidenceRecords.map((e) => e.evidenceId);
+        // Calculate aggregate confidence from evidence records if present
+        let confidenceSummary = 1.0;
+        let uncertaintySummary;
+        if (evidenceRecords.length > 0) {
+            const confidences = evidenceRecords
+                .map((e) => e.confidence)
+                .filter((c) => typeof c === 'number' && !isNaN(c));
+            if (confidences.length > 0) {
+                confidenceSummary = confidences.reduce((sum, c) => sum + c, 0) / confidences.length;
+            }
+            const uncertainties = evidenceRecords
+                .map((e) => e.uncertainty)
+                .filter((u) => typeof u === 'string' && u.trim() !== '');
+            if (uncertainties.length > 0) {
+                uncertaintySummary = uncertainties.join('; ');
+            }
+        }
+        const requiresApproval = options.requiresApproval !== undefined
+            ? options.requiresApproval
+            : evidenceRecords.some((e) => e.origin === 'ocr' || e.trust === 'untrusted');
+        const staged = {
+            responseId: generateId('resp'),
+            companionId: requestContext.companionId,
+            correlationId: requestContext.conversation.correlationId,
+            channel: requestContext.conversation?.channel,
+            speech: options.candidateSpeech,
+            language: options.candidateLanguage,
+            evidenceIds,
+            citations: options.citations ?? [],
+            confidenceSummary,
+            uncertaintySummary,
+            requiresApproval,
+            status: 'STAGED',
+            createdAt: new Date(nowTime).toISOString(),
+            expiresAt,
+            memoryProposals: options.memoryProposals,
+            behaviorProposals: options.behaviorProposals,
+            internalMonologue: options.internalMonologue,
+        };
+        this.stagedPlans.set(staged.responseId, staged);
+        return staged;
+    }
+    evaluateGate(staged, allEvidence = [], now = new Date()) {
+        const nowTime = new Date(now).getTime();
+        // 1. Check if empty speech
+        if (!staged.speech || staged.speech.trim() === '') {
+            return {
+                admissible: false,
+                disposition: 'REJECTED',
+                reasonCode: 'EMPTY_SPEECH',
+                stagedPlan: staged,
+                filteredEvidenceIds: [],
+                filteredCitations: [],
+                diagnostics: { detail: 'Speech content is empty' },
+            };
+        }
+        // 2. Check if expired
+        if (staged.expiresAt && new Date(staged.expiresAt).getTime() <= nowTime) {
+            staged.status = 'EXPIRED';
+            return {
+                admissible: false,
+                disposition: 'EXPIRED',
+                reasonCode: 'EVIDENCE_EXPIRED',
+                stagedPlan: staged,
+                filteredEvidenceIds: [],
+                filteredCitations: [],
+                diagnostics: { detail: 'Staged response plan expired' },
+            };
+        }
+        // 3. Disclosure filter on attached evidence
+        const attachedEvidence = allEvidence.filter((e) => staged.evidenceIds.includes(e.evidenceId));
+        const { admitted, excluded } = (0, evidence_1.filterEvidenceRecords)(attachedEvidence, {
+            companionId: staged.companionId,
+            channel: staged.channel,
+            now,
+        });
+        // If any evidence attached to this plan violated disclosure in this channel, exclude it
+        const admittedEvidenceIds = admitted.map((e) => e.evidenceId);
+        const filteredCitations = staged.citations.filter((c) => admitted.some((e) => (c.evidenceId && e.evidenceId === c.evidenceId) ||
+            e.sourceId === c.sourceId ||
+            (e.documentId && e.documentId === c.documentId)));
+        // 4. Explicitly rejected or status check
+        if (staged.status === 'REJECTED') {
+            return {
+                admissible: false,
+                disposition: 'REJECTED',
+                reasonCode: 'EXPLICITLY_REJECTED',
+                stagedPlan: staged,
+                filteredEvidenceIds: admittedEvidenceIds,
+                filteredCitations,
+            };
+        }
+        // 5. Staged approval check
+        if (staged.requiresApproval && staged.status !== 'APPROVED') {
+            return {
+                admissible: false,
+                disposition: staged.status,
+                reasonCode: 'APPROVAL_REQUIRED',
+                stagedPlan: staged,
+                filteredEvidenceIds: admittedEvidenceIds,
+                filteredCitations,
+                diagnostics: {
+                    detail: 'Response plan requires approval before external emission',
+                    excludedEvidenceCount: String(excluded.length),
+                },
+            };
+        }
+        // 6. Direct approval / Admissible
+        return {
+            admissible: true,
+            disposition: staged.status === 'APPROVED' ? 'APPROVED' : 'APPROVED',
+            reasonCode: 'APPROVED_DIRECT',
+            stagedPlan: staged,
+            filteredEvidenceIds: admittedEvidenceIds,
+            filteredCitations,
+        };
+    }
+    approveResponse(options) {
+        const plan = this.stagedPlans.get(options.responseId);
+        if (!plan) {
+            return { success: false, reason: 'UNKNOWN_APPROVAL_ID' };
+        }
+        if (this.consumedApprovals.has(options.responseId) || plan.status === 'APPROVED') {
+            return { success: false, reason: 'APPROVAL_ALREADY_CONSUMED' };
+        }
+        if (plan.companionId !== options.companionId) {
+            return { success: false, reason: 'COMPANION_MISMATCH' };
+        }
+        if (plan.correlationId !== options.correlationId) {
+            return { success: false, reason: 'APPROVAL_ID_MISMATCH' };
+        }
+        if (plan.status === 'EXPIRED') {
+            return { success: false, reason: 'EVIDENCE_EXPIRED' };
+        }
+        if (plan.status === 'REJECTED') {
+            return { success: false, reason: 'EXPLICITLY_REJECTED' };
+        }
+        plan.status = 'APPROVED';
+        this.consumedApprovals.add(options.responseId);
+        return { success: true, plan };
+    }
+    rejectResponse(options) {
+        const plan = this.stagedPlans.get(options.responseId);
+        if (!plan) {
+            return { success: false, reason: 'UNKNOWN_APPROVAL_ID' };
+        }
+        if (plan.companionId !== options.companionId) {
+            return { success: false, reason: 'COMPANION_MISMATCH' };
+        }
+        if (plan.correlationId !== options.correlationId) {
+            return { success: false, reason: 'APPROVAL_ID_MISMATCH' };
+        }
+        plan.status = 'REJECTED';
+        return { success: true, plan };
+    }
+    getStagedPlan(responseId) {
+        return this.stagedPlans.get(responseId);
+    }
+    findStagedPlanByCorrelation(companionId, correlationId) {
+        for (const plan of this.stagedPlans.values()) {
+            if (plan.companionId === companionId && plan.correlationId === correlationId) {
+                return plan;
+            }
+        }
+        return undefined;
+    }
+}
+exports.ResponseGatingEngine = ResponseGatingEngine;

package/dist/gating.test.d.ts

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

package/dist/gating.test.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const gating_1 = require("./gating");
+describe('T4 Response Gating & Staged Approval Suite', () => {
+    let engine;
+    const validPublicContext = {
+        companionId: 'companion-a',
+        actor: {
+            actorId: 'actor-a',
+            sessionId: 'session-a',
+            authorizationRole: 'viewer',
+            capabilities: ['chat:public'],
+            authenticated: false,
+        },
+        conversation: {
+            channel: 'public',
+            correlationId: 'corr-gate-1',
+        },
+    };
+    beforeEach(() => {
+        engine = new gating_1.ResponseGatingEngine();
+    });
+    test('valid grounded response without special approval requirement is approved/admissible directly', () => {
+        const evidence = {
+            evidenceId: 'ev-pub-1',
+            sourceId: 'src-wiki',
+            origin: 'knowledge',
+            trust: 'configured',
+            sensitivity: 'public',
+            companionId: 'companion-a',
+            correlationId: 'corr-gate-1',
+            createdAt: new Date().toISOString(),
+        };
+        const staged = engine.stageResponse({
+            requestContext: validPublicContext,
+            candidateSpeech: 'Here is grounded public knowledge.',
+            candidateLanguage: 'en',
+            evidenceRecords: [evidence],
+            citations: [{ sourceId: 'src-wiki', revision: 'r1' }],
+        });
+        expect(staged.requiresApproval).toBe(false);
+        expect(staged.status).toBe('STAGED');
+        const evaluation = engine.evaluateGate(staged, [evidence]);
+        expect(evaluation.admissible).toBe(true);
+        expect(evaluation.disposition).toBe('APPROVED');
+        expect(evaluation.reasonCode).toBe('APPROVED_DIRECT');
+        expect(evaluation.filteredEvidenceIds).toEqual(['ev-pub-1']);
+        expect(evaluation.filteredCitations.length).toBe(1);
+    });
+    test('response containing untrusted OCR evidence requires approval and remains staged until approved', () => {
+        const ocrEvidence = {
+            evidenceId: 'ev-ocr-1',
+            sourceId: 'vision-ocr',
+            origin: 'ocr',
+            trust: 'untrusted',
+            sensitivity: 'public',
+            companionId: 'companion-a',
+            correlationId: 'corr-gate-2',
+            createdAt: new Date().toISOString(),
+            uncertainty: 'OCR detected prompt injection text',
+        };
+        const staged = engine.stageResponse({
+            requestContext: {
+                ...validPublicContext,
+                conversation: { ...validPublicContext.conversation, correlationId: 'corr-gate-2' },
+            },
+            candidateSpeech: 'Text extracted from image.',
+            candidateLanguage: 'en',
+            evidenceRecords: [ocrEvidence],
+        });
+        expect(staged.requiresApproval).toBe(true);
+        expect(staged.status).toBe('STAGED');
+        // Before approval -> gating holds it
+        const beforeApproval = engine.evaluateGate(staged, [ocrEvidence]);
+        expect(beforeApproval.admissible).toBe(false);
+        expect(beforeApproval.disposition).toBe('STAGED');
+        expect(beforeApproval.reasonCode).toBe('APPROVAL_REQUIRED');
+        // Operator approves the response
+        const approveResult = engine.approveResponse({
+            responseId: staged.responseId,
+            companionId: 'companion-a',
+            correlationId: 'corr-gate-2',
+        });
+        expect(approveResult.success).toBe(true);
+        // After approval -> gating allows it
+        const afterApproval = engine.evaluateGate(staged, [ocrEvidence]);
+        expect(afterApproval.admissible).toBe(true);
+        expect(afterApproval.disposition).toBe('APPROVED');
+        expect(afterApproval.reasonCode).toBe('APPROVED_DIRECT');
+    });
+    test('unknown or mismatched approval ID is rejected', () => {
+        const staged = engine.stageResponse({
+            requestContext: validPublicContext,
+            candidateSpeech: 'Requires approval',
+            candidateLanguage: 'en',
+            requiresApproval: true,
+        });
+        // Unknown response ID
+        const unknownRes = engine.approveResponse({
+            responseId: 'non-existent-resp',
+            companionId: 'companion-a',
+            correlationId: 'corr-gate-1',
+        });
+        expect(unknownRes.success).toBe(false);
+        expect(unknownRes.reason).toBe('UNKNOWN_APPROVAL_ID');
+        // Companion mismatch
+        const companionMismatch = engine.approveResponse({
+            responseId: staged.responseId,
+            companionId: 'companion-other',
+            correlationId: 'corr-gate-1',
+        });
+        expect(companionMismatch.success).toBe(false);
+        expect(companionMismatch.reason).toBe('COMPANION_MISMATCH');
+        // Correlation ID mismatch
+        const correlationMismatch = engine.approveResponse({
+            responseId: staged.responseId,
+            companionId: 'companion-a',
+            correlationId: 'corr-mismatch',
+        });
+        expect(correlationMismatch.success).toBe(false);
+        expect(correlationMismatch.reason).toBe('APPROVAL_ID_MISMATCH');
+    });
+    test('rejection prevents response from ever reaching emission', () => {
+        const staged = engine.stageResponse({
+            requestContext: validPublicContext,
+            candidateSpeech: 'Potentially unsafe response',
+            candidateLanguage: 'en',
+            requiresApproval: true,
+        });
+        const rejectRes = engine.rejectResponse({
+            responseId: staged.responseId,
+            companionId: 'companion-a',
+            correlationId: 'corr-gate-1',
+        });
+        expect(rejectRes.success).toBe(true);
+        const evalRes = engine.evaluateGate(staged);
+        expect(evalRes.admissible).toBe(false);
+        expect(evalRes.disposition).toBe('REJECTED');
+        expect(evalRes.reasonCode).toBe('EXPLICITLY_REJECTED');
+    });
+    test('expired staged response plan cannot be approved or emitted', () => {
+        const staged = engine.stageResponse({
+            requestContext: validPublicContext,
+            candidateSpeech: 'Expired response',
+            candidateLanguage: 'en',
+            requiresApproval: true,
+            ttlMs: 100,
+            now: new Date(Date.now() - 500),
+        });
+        const evalRes = engine.evaluateGate(staged, [], new Date());
+        expect(evalRes.admissible).toBe(false);
+        expect(evalRes.disposition).toBe('EXPIRED');
+        expect(evalRes.reasonCode).toBe('EVIDENCE_EXPIRED');
+        const approveRes = engine.approveResponse({
+            responseId: staged.responseId,
+            companionId: 'companion-a',
+            correlationId: 'corr-gate-1',
+        });
+        expect(approveRes.success).toBe(false);
+        expect(approveRes.reason).toBe('EVIDENCE_EXPIRED');
+    });
+    test('foreign companion evidence is filtered out and absent from citations/evidence list', () => {
+        const foreignEvidence = {
+            evidenceId: 'ev-foreign-1',
+            sourceId: 'src-secret',
+            origin: 'knowledge',
+            trust: 'configured',
+            sensitivity: 'private',
+            companionId: 'companion-b',
+            correlationId: 'corr-gate-1',
+            createdAt: new Date().toISOString(),
+        };
+        const staged = engine.stageResponse({
+            requestContext: validPublicContext, // companion-a
+            candidateSpeech: 'Response text',
+            candidateLanguage: 'en',
+            evidenceRecords: [foreignEvidence],
+            citations: [{ sourceId: 'src-secret' }],
+        });
+        const evalRes = engine.evaluateGate(staged, [foreignEvidence]);
+        expect(evalRes.admissible).toBe(true);
+        // Foreign companion evidence and its citation must be stripped due to companion isolation
+        expect(evalRes.filteredEvidenceIds).toEqual([]);
+        expect(evalRes.filteredCitations).toEqual([]);
+    });
+});