@principles/core 1.73.0 → 1.74.0

package/dist/runtime-v2/nocturnal/nocturnal-compliance.d.ts

@@ -1,185 +0,0 @@
-/**
- * Nocturnal Compliance Engine — Opportunity-Based Principle Evaluation
- * =====================================================================
- *
- * Replaces session-average compliance with opportunity-based compliance.
- *
- * CORE CONCEPTS:
- *
- * Opportunity — a session context where a principle COULD have been applied.
- *                An opportunity exists when the agent's action (or planned action)
- *                falls within the principle's applicability scope.
- *
- * Compliance   — the principle was followed in an opportunity.
- *                Determined by absence of violation signals, not presence of
- *                positive confirmation (avoids LLM scoring).
- *
- * Violation   — strong evidence the principle was NOT followed.
- *                Detected through deterministic event signals (pain, tool failures,
- *                gate blocks) — no LLM involved.
- *
- * Dilution prevention — compliance is computed ONLY over sessions where the
- *                         principle had an opportunity. Unrelated sessions
- *                         (where T-05's risky operations never occurred) do NOT
- *                         dilute the compliance rate.
- *
- * DESIGN CONSTRAINTS (Phase 1):
- * - T-xx principles only (deterministic / weak-heuristic evaluability)
- * - No P_xxx automation (requires detector metadata — Task 1.3 scope)
- * - No LLM-based scoring
- * - No training logic
- *
- * FILE: No file persistence — stateless computation over event stream.
- *       Caller is responsible for writing results to principle-training-state.ts.
- */
-/**
- * Session events extracted from the event log.
- * Compatible with EventLogEntry from event-types.ts.
- */
-export interface SessionEvents {
-    sessionId: string;
-    toolCalls: ToolCallRecord[];
-    painSignals: PainSignalRecord[];
-    gateBlocks: GateBlockRecord[];
-    userCorrections: UserCorrectionRecord[];
-    planApprovals: PlanApprovalRecord[];
-}
-export interface ToolCallRecord {
-    toolName: string;
-    filePath?: string;
-    outcome: 'success' | 'failure' | 'blocked';
-    errorType?: string;
-    errorMessage?: string;
-}
-export interface PainSignalRecord {
-    source: string;
-    score: number;
-    severity?: 'mild' | 'moderate' | 'severe';
-    reason?: string;
-}
-export interface GateBlockRecord {
-    toolName: string;
-    filePath?: string;
-    reason: string;
-}
-export interface UserCorrectionRecord {
-    correctionCue?: string;
-}
-export interface PlanApprovalRecord {
-    toolName: string;
-    filePath?: string;
-}
-/**
- * The result of compliance computation for one principle.
- */
-export interface ComplianceResult {
-    principleId: string;
-    /** Number of sessions/events where this principle had an applicable opportunity */
-    applicableOpportunityCount: number;
-    /** Number of opportunities where violation signals were detected */
-    observedViolationCount: number;
-    /** complianceRate = (opportunities - violations) / opportunities; 0 if none */
-    complianceRate: number;
-    /**
-     * Violation trend:
-     *   +1 = violations increasing (worsening)
-     *    0 = stable
-     *   -1 = violations decreasing (improving)
-     */
-    violationTrend: number;
-    /**
-     * Explanation of why the result is what it is.
-     * For debugging, observability, and reviewer verification.
-     */
-    explanation: string;
-}
-/**
- * Opportunity detection result for a single session.
- */
-interface OpportunityMatch {
-    applicable: boolean;
-    reason: string;
-}
-/**
- * Violation detection result for a session with applicable opportunity.
- */
-interface ViolationMatch {
-    violated: boolean;
-    reason: string;
-}
-/**
- * Detects whether a given session presents an APPLICABLE OPPORTUNITY
- * for a specific principle.
- *
- * An opportunity exists when the session context falls within the
- * principle's applicability scope — regardless of whether the agent
- * followed the principle.
- *
- * IMPORTANT: This does NOT assess compliance. It only answers:
- *   "Could the principle have applied here?"
- *
- * #216: For P_* principles (not T-xx), uses generic detection based on
- * pain events and tool calls — any session with a pain signal is considered
- * an opportunity for a pain-derived principle.
- */
-export declare function detectOpportunity(principleId: string, session: SessionEvents): OpportunityMatch;
-/**
- * Detects whether a principle was VIOLATED in a session where an
- * opportunity was applicable.
- *
- * Returns a ViolationMatch with violated=true if violation signals are present.
- *
- * #216: For P_* principles (pain-derived), violation is detected when the session
- * has pain signals, tool failures, or gate blocks that match the principle's
- * trigger pattern. Since P_* principles don't have T-xx specific detectors,
- * we use the presence of negative signals as violation evidence.
- */
-export declare function detectViolation(principleId: string, session: SessionEvents): ViolationMatch;
-/**
- * Computes compliance metrics for a single T-xx principle across a batch of sessions.
- *
- * DILUTION PREVENTION:
- * - Sessions where the principle had NO opportunity are EXCLUDED from
- *   applicableOpportunityCount and do not affect complianceRate.
- * - Example: T-05 sessions with no risky operations do not dilute
- *   the compliance rate computed from T-05 sessions with gate blocks.
- *
- * TREND COMPUTATION:
- * - Sessions are ordered chronologically (most recent first).
- * - Current window: last 3 applicable sessions.
- * - Previous window: sessions 4-6 (if available).
- * - If either window has < 1 applicable session, trend = 0 (insufficient data).
- * - Otherwise: trend = prevViolationRate - currentViolationRate
- *   (+1 = improving, 0 = stable, -1 = worsening).
- */
-export declare function computeCompliance(principleId: string, sessions: SessionEvents[], options?: {
-    trendWindowSize?: number;
-}): ComplianceResult;
-/**
- * Computes compliance results for all T-01 through T-09 principles
- * across the provided sessions.
- *
- * Sessions are assumed to be ordered most-recent-first.
- */
-export declare function computeAllCompliance(sessions: SessionEvents[], options?: {
-    trendWindowSize?: number;
-}): ComplianceResult[];
-/**
- * Converts raw EventLogEntry[] from event-types.ts into SessionEvents.
- *
- * Groups events by sessionId and maps to the SessionEvents interface.
- * Events with no sessionId are grouped under sessionId = 'unknown'.
- */
-export declare function groupEventsIntoSessions(events: RawEventEntry[]): Map<string, SessionEvents>;
-/**
- * Raw event entry from the events.jsonl log.
- * Compatible with EventLogEntry from event-types.ts.
- */
-export interface RawEventEntry {
-    ts: string;
-    type: string;
-    sessionId?: string;
-    data: Record<string, unknown>;
-}
-export {};
-//# sourceMappingURL=nocturnal-compliance.d.ts.map

package/dist/runtime-v2/nocturnal/nocturnal-compliance.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"nocturnal-compliance.d.ts","sourceRoot":"","sources":["../../../src/runtime-v2/nocturnal/nocturnal-compliance.ts"],"names":[],"mappings":"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"}