limen-ai 1.0.0

package/dist/api/enforcement/cost_tracker.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Cost scaling verification tracker.
+ * S ref: I-15 (Linear Cost Scaling), §4 (Performance Invariants)
+ *
+ * Phase: Sprint 5 (Performance & Events)
+ * Implements: Per-session overhead tracking and linear scaling verification.
+ *
+ * I-15: "Engine overhead per agent-session scales linearly, not quadratically."
+ *
+ * Overhead = total tokens consumed - raw LLM I/O tokens.
+ * This captures the pipeline skeleton cost (system prompts, context assembly)
+ * and injected technique cost.
+ *
+ * Linear scaling is verified via R-squared (R^2) of linear regression on
+ * overhead vs session index. R^2 > 0.95 = linear. If <= 2 sessions exist,
+ * isLinear defaults to true (insufficient data for statistical verification).
+ *
+ * Design decisions:
+ *   - `recordSessionOverhead`: Queries `core_interactions` for session token
+ *     totals, computes overhead from ResponseMetadata technique cost.
+ *   - `evaluateCostScaling`: Queries all sessions for a mission, runs linear
+ *     regression, returns R^2 and verdict.
+ *   - No new tables required: reads from existing `core_interactions`.
+ *
+ * Invariants enforced: I-15
+ * Failure modes defended: FM-02 (cost explosion detection)
+ */
+import type { DatabaseConnection } from '../../kernel/interfaces/index.js';
+import type { ResponseMetadata } from '../interfaces/api.js';
+/**
+ * Per-session overhead snapshot.
+ */
+export interface SessionOverhead {
+    readonly sessionId: string;
+    readonly missionId: string;
+    readonly fixedOverhead: number;
+    readonly techniqueOverhead: number;
+    readonly totalOverhead: number;
+}
+/**
+ * Cost scaling evaluation report.
+ */
+export interface CostScalingReport {
+    readonly sessionCount: number;
+    readonly overheads: readonly SessionOverhead[];
+    readonly linearityR2: number;
+    readonly isLinear: boolean;
+    readonly averageOverhead: number;
+    readonly maxOverhead: number;
+}
+/**
+ * I-15: Record per-session overhead from pipeline metadata.
+ *
+ * Computes overhead as the difference between total tokens consumed and the
+ * raw LLM I/O (which scales with user content, not engine complexity).
+ *
+ * The technique overhead comes from ResponseMetadata.techniqueTokenCost,
+ * which tracks the token cost of injected prompt fragments (I-54).
+ *
+ * Fixed overhead is the pipeline skeleton cost: context assembly, system
+ * prompts, safety gates, evaluation, and audit instrumentation. This is
+ * estimated as (total tokens - user content tokens - technique tokens).
+ *
+ * Since this data is derived at pipeline time and stored implicitly in
+ * core_interactions, we return the computed overhead for the caller to
+ * use (e.g., emit as a warning event or store in metrics).
+ *
+ * @param conn - Database connection for querying core_interactions
+ * @param sessionId - Session identifier
+ * @param missionId - Mission identifier (may be empty for sessionless chat)
+ * @param metadata - ResponseMetadata from the completed pipeline
+ * @returns SessionOverhead snapshot
+ */
+export declare function computeSessionOverhead(sessionId: string, missionId: string, metadata: ResponseMetadata): SessionOverhead;
+/**
+ * I-15: Evaluate cost scaling linearity across sessions within a mission.
+ *
+ * Queries core_interactions for all sessions associated with a mission,
+ * computes per-session token totals, and runs linear regression on the
+ * overhead sequence to verify R^2 > 0.95 (linear scaling).
+ *
+ * If <= 2 sessions exist, isLinear defaults to true (insufficient data
+ * for meaningful statistical analysis).
+ *
+ * @param conn - Database connection
+ * @param missionId - Mission to evaluate
+ * @returns CostScalingReport with R^2, verdict, and per-session details
+ */
+export declare function evaluateCostScaling(conn: DatabaseConnection, missionId: string): CostScalingReport;
+/**
+ * Compute R^2 (coefficient of determination) for a sequence of values
+ * against their index (0, 1, 2, ..., n-1).
+ *
+ * R^2 = 1 - (SS_res / SS_tot)
+ * where:
+ *   SS_res = sum of (actual - predicted)^2
+ *   SS_tot = sum of (actual - mean)^2
+ *
+ * predicted = a + b * i (least squares linear fit)
+ *
+ * @param values - Array of numeric values ordered by index
+ * @returns R^2 value between 0 and 1 (1 = perfectly linear)
+ */
+export declare function computeLinearR2(values: readonly number[]): number;
+//# sourceMappingURL=cost_tracker.d.ts.map

package/dist/api/enforcement/cost_tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost_tracker.d.ts","sourceRoot":"","sources":["../../../src/api/enforcement/cost_tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAM7D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,gBAAgB,GACzB,eAAe,CA2BjB;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,kBAAkB,EACxB,SAAS,EAAE,MAAM,GAChB,iBAAiB,CAkFnB;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAgDjE"}

package/dist/api/enforcement/cost_tracker.js

@@ -0,0 +1,227 @@
+/**
+ * Cost scaling verification tracker.
+ * S ref: I-15 (Linear Cost Scaling), §4 (Performance Invariants)
+ *
+ * Phase: Sprint 5 (Performance & Events)
+ * Implements: Per-session overhead tracking and linear scaling verification.
+ *
+ * I-15: "Engine overhead per agent-session scales linearly, not quadratically."
+ *
+ * Overhead = total tokens consumed - raw LLM I/O tokens.
+ * This captures the pipeline skeleton cost (system prompts, context assembly)
+ * and injected technique cost.
+ *
+ * Linear scaling is verified via R-squared (R^2) of linear regression on
+ * overhead vs session index. R^2 > 0.95 = linear. If <= 2 sessions exist,
+ * isLinear defaults to true (insufficient data for statistical verification).
+ *
+ * Design decisions:
+ *   - `recordSessionOverhead`: Queries `core_interactions` for session token
+ *     totals, computes overhead from ResponseMetadata technique cost.
+ *   - `evaluateCostScaling`: Queries all sessions for a mission, runs linear
+ *     regression, returns R^2 and verdict.
+ *   - No new tables required: reads from existing `core_interactions`.
+ *
+ * Invariants enforced: I-15
+ * Failure modes defended: FM-02 (cost explosion detection)
+ */
+// ============================================================================
+// Overhead Recording
+// ============================================================================
+/**
+ * I-15: Record per-session overhead from pipeline metadata.
+ *
+ * Computes overhead as the difference between total tokens consumed and the
+ * raw LLM I/O (which scales with user content, not engine complexity).
+ *
+ * The technique overhead comes from ResponseMetadata.techniqueTokenCost,
+ * which tracks the token cost of injected prompt fragments (I-54).
+ *
+ * Fixed overhead is the pipeline skeleton cost: context assembly, system
+ * prompts, safety gates, evaluation, and audit instrumentation. This is
+ * estimated as (total tokens - user content tokens - technique tokens).
+ *
+ * Since this data is derived at pipeline time and stored implicitly in
+ * core_interactions, we return the computed overhead for the caller to
+ * use (e.g., emit as a warning event or store in metrics).
+ *
+ * @param conn - Database connection for querying core_interactions
+ * @param sessionId - Session identifier
+ * @param missionId - Mission identifier (may be empty for sessionless chat)
+ * @param metadata - ResponseMetadata from the completed pipeline
+ * @returns SessionOverhead snapshot
+ */
+export function computeSessionOverhead(sessionId, missionId, metadata) {
+    // Technique overhead comes from the pipeline's technique injection
+    const techniqueOverhead = metadata.techniqueTokenCost;
+    // Fixed overhead: pipeline skeleton cost beyond raw LLM I/O
+    // The total tokens includes everything; the raw I/O is input + output tokens
+    // that the user's content required. Fixed overhead is everything else.
+    // Since we cannot perfectly separate user-content tokens from system-prompt
+    // tokens at this level, we estimate fixed overhead as a constant per pipeline
+    // execution. The key invariant (I-15) is that this does NOT grow quadratically
+    // with session count.
+    //
+    // For now, fixed overhead = 0 (baseline). The actual pipeline skeleton tokens
+    // are accounted within input_tokens by the LLM provider. What matters for I-15
+    // is that technique overhead (which grows with technique count, not session
+    // count) is tracked and the total overhead per session stays bounded.
+    const fixedOverhead = 0;
+    const totalOverhead = fixedOverhead + techniqueOverhead;
+    return {
+        sessionId,
+        missionId,
+        fixedOverhead,
+        techniqueOverhead,
+        totalOverhead,
+    };
+}
+// ============================================================================
+// Cost Scaling Evaluation
+// ============================================================================
+/**
+ * I-15: Evaluate cost scaling linearity across sessions within a mission.
+ *
+ * Queries core_interactions for all sessions associated with a mission,
+ * computes per-session token totals, and runs linear regression on the
+ * overhead sequence to verify R^2 > 0.95 (linear scaling).
+ *
+ * If <= 2 sessions exist, isLinear defaults to true (insufficient data
+ * for meaningful statistical analysis).
+ *
+ * @param conn - Database connection
+ * @param missionId - Mission to evaluate
+ * @returns CostScalingReport with R^2, verdict, and per-session details
+ */
+export function evaluateCostScaling(conn, missionId) {
+    // Query per-session token totals from core_interactions.
+    // Sessions are ordered by first interaction time (proxy for session index).
+    // Note: No core_sessions table exists yet. When it does (with mission_id FK),
+    // the missionId parameter can be used for scoped queries. Currently we query
+    // all sessions in core_interactions. The missionId filter is a forward
+    // obligation for when session-mission linking is implemented.
+    const effectiveSessions = conn.query(`SELECT
+       session_id,
+       SUM(input_tokens) as total_input,
+       SUM(output_tokens) as total_output,
+       COUNT(*) as interaction_count
+     FROM core_interactions
+     WHERE session_id IS NOT NULL
+     GROUP BY session_id
+     ORDER BY MIN(created_at) ASC`);
+    if (effectiveSessions.length === 0) {
+        return {
+            sessionCount: 0,
+            overheads: [],
+            linearityR2: 1.0,
+            isLinear: true,
+            averageOverhead: 0,
+            maxOverhead: 0,
+        };
+    }
+    // Compute per-session overhead
+    // For I-15 verification: overhead = total tokens per session.
+    // The invariant states overhead scales linearly with session count,
+    // meaning each new session adds a roughly constant cost, not a
+    // cost proportional to the number of existing sessions.
+    const overheads = effectiveSessions.map((s) => {
+        const totalTokens = s.total_input + s.total_output;
+        return {
+            sessionId: s.session_id,
+            missionId,
+            fixedOverhead: totalTokens,
+            techniqueOverhead: 0, // Computed at pipeline time, not queryable after the fact
+            totalOverhead: totalTokens,
+        };
+    });
+    // If <= 2 sessions, insufficient data for regression
+    if (overheads.length <= 2) {
+        const avg = overheads.reduce((sum, o) => sum + o.totalOverhead, 0) / overheads.length;
+        const maxOh = Math.max(...overheads.map(o => o.totalOverhead));
+        return {
+            sessionCount: overheads.length,
+            overheads,
+            linearityR2: 1.0,
+            isLinear: true,
+            averageOverhead: avg,
+            maxOverhead: maxOh,
+        };
+    }
+    // Linear regression: fit overhead[i] = a + b * i
+    // R^2 = 1 - (SS_res / SS_tot)
+    const n = overheads.length;
+    const values = overheads.map(o => o.totalOverhead);
+    const r2 = computeLinearR2(values);
+    const avg = values.reduce((sum, v) => sum + v, 0) / n;
+    const maxOh = Math.max(...values);
+    return {
+        sessionCount: n,
+        overheads,
+        linearityR2: r2,
+        isLinear: r2 > 0.95,
+        averageOverhead: avg,
+        maxOverhead: maxOh,
+    };
+}
+// ============================================================================
+// Linear Regression Helper
+// ============================================================================
+/**
+ * Compute R^2 (coefficient of determination) for a sequence of values
+ * against their index (0, 1, 2, ..., n-1).
+ *
+ * R^2 = 1 - (SS_res / SS_tot)
+ * where:
+ *   SS_res = sum of (actual - predicted)^2
+ *   SS_tot = sum of (actual - mean)^2
+ *
+ * predicted = a + b * i (least squares linear fit)
+ *
+ * @param values - Array of numeric values ordered by index
+ * @returns R^2 value between 0 and 1 (1 = perfectly linear)
+ */
+export function computeLinearR2(values) {
+    const n = values.length;
+    if (n <= 1)
+        return 1.0;
+    // Compute means
+    let sumX = 0;
+    let sumY = 0;
+    for (let i = 0; i < n; i++) {
+        sumX += i;
+        sumY += (values[i] ?? 0);
+    }
+    const meanX = sumX / n;
+    const meanY = sumY / n;
+    // Compute slope (b) and intercept (a) via least squares
+    let numerator = 0;
+    let denominator = 0;
+    for (let i = 0; i < n; i++) {
+        const dx = i - meanX;
+        numerator += dx * ((values[i] ?? 0) - meanY);
+        denominator += dx * dx;
+    }
+    // If all x values are identical (impossible for index sequence but handle gracefully)
+    if (denominator === 0)
+        return 1.0;
+    const b = numerator / denominator;
+    const a = meanY - b * meanX;
+    // Compute SS_res and SS_tot
+    let ssRes = 0;
+    let ssTot = 0;
+    for (let i = 0; i < n; i++) {
+        const val = values[i] ?? 0;
+        const predicted = a + b * i;
+        const residual = val - predicted;
+        ssRes += residual * residual;
+        const deviation = val - meanY;
+        ssTot += deviation * deviation;
+    }
+    // If SS_tot is 0 (all values identical), perfect linear fit
+    if (ssTot === 0)
+        return 1.0;
+    const r2 = 1 - (ssRes / ssTot);
+    // Clamp to [0, 1] to handle floating point imprecision
+    return Math.max(0, Math.min(1, r2));
+}
+//# sourceMappingURL=cost_tracker.js.map

package/dist/api/enforcement/cost_tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost_tracker.js","sourceRoot":"","sources":["../../../src/api/enforcement/cost_tracker.ts"],"names":[],"mappings":"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"}

package/dist/api/enforcement/latency_harness.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Latency budget enforcement harness.
+ * S ref: I-14 (Predictable Latency), §4 (Performance Invariants)
+ *
+ * Phase: Sprint 5 (Performance & Events)
+ * Implements: Per-phase latency budget verification for the 9-phase chat pipeline.
+ *
+ * I-14: "Memory retrieval: < 50ms for up to 100K memories. Perception: < 5ms.
+ *        Mutation-audit: < 1ms (same SQLite transaction). Hot-path total
+ *        (excl. LLM): <= 103ms."
+ *
+ * This module is a VERIFICATION function, not middleware. It takes phase timings
+ * from ResponseMetadata.phases (produced by the pipeline) and returns a report
+ * indicating whether budgets were met or violated.
+ *
+ * Design decisions:
+ *   - Pure function: no side effects, no database access, no state mutation.
+ *   - Does NOT throw on violation: returns violations in report (degraded mode).
+ *   - WARNING when phase exceeds budget by < 2x; CRITICAL when >= 2x.
+ *   - 'generation' phase excluded from hot-path total (LLM latency is external).
+ *
+ * Invariants enforced: I-14
+ * Failure modes defended: FM-11 (observability overhead < 2%)
+ */
+import type { PipelinePhase } from '../interfaces/api.js';
+/**
+ * I-14: Per-phase latency budgets in milliseconds.
+ * Defaults derived from spec:
+ *   - perception: 5ms
+ *   - retrieval: 50ms (100K memories)
+ *   - contextAssembly: 15ms
+ *   - preSafety: 5ms
+ *   - postSafety: 5ms
+ *   - learning: 10ms
+ *   - evaluation: 5ms
+ *   - audit: 1ms (mutation-audit, same SQLite transaction)
+ *   - hotPathTotal: 103ms (sum excl. generation)
+ */
+export interface LatencyBudget {
+    readonly perception: number;
+    readonly retrieval: number;
+    readonly contextAssembly: number;
+    readonly preSafety: number;
+    readonly postSafety: number;
+    readonly learning: number;
+    readonly evaluation: number;
+    readonly audit: number;
+    readonly hotPathTotal: number;
+}
+/**
+ * A single latency budget violation detected during evaluation.
+ */
+export interface LatencyViolation {
+    readonly phase: PipelinePhase;
+    readonly budgetMs: number;
+    readonly actualMs: number;
+    readonly severity: 'warning' | 'critical';
+}
+/**
+ * Latency evaluation report produced by evaluateLatency().
+ */
+export interface LatencyReport {
+    readonly violations: readonly LatencyViolation[];
+    readonly hotPathMs: number;
+    readonly hotPathBudgetMs: number;
+    readonly withinBudget: boolean;
+}
+/**
+ * I-14: Default latency budgets derived from the spec.
+ * All values in milliseconds.
+ */
+export declare const DEFAULT_LATENCY_BUDGET: LatencyBudget;
+/**
+ * I-14: Evaluate phase timings against latency budgets.
+ *
+ * Pure function. Takes phase timings from ResponseMetadata.phases and returns
+ * a LatencyReport with any violations found.
+ *
+ * Severity classification:
+ *   - WARNING: phase exceeds budget but by less than 2x
+ *   - CRITICAL: phase exceeds budget by 2x or more
+ *
+ * The 'generation' phase is excluded from hot-path total calculation because
+ * LLM inference latency is external and unbounded by design.
+ *
+ * @param phases - Array of { phase, durationMs } from ResponseMetadata
+ * @param budget - Optional partial budget overrides (merged with defaults)
+ * @returns LatencyReport with violations, hot-path total, and overall verdict
+ */
+export declare function evaluateLatency(phases: ReadonlyArray<{
+    readonly phase: PipelinePhase;
+    readonly durationMs: number;
+}>, budget?: Partial<LatencyBudget>): LatencyReport;
+//# sourceMappingURL=latency_harness.d.ts.map

package/dist/api/enforcement/latency_harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"latency_harness.d.ts","sourceRoot":"","sources":["../../../src/api/enforcement/latency_harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAM1D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,UAAU,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAMD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAUnC,CAAC;AAyBH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,EACrF,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC9B,aAAa,CA6Cf"}

package/dist/api/enforcement/latency_harness.js

@@ -0,0 +1,120 @@
+/**
+ * Latency budget enforcement harness.
+ * S ref: I-14 (Predictable Latency), §4 (Performance Invariants)
+ *
+ * Phase: Sprint 5 (Performance & Events)
+ * Implements: Per-phase latency budget verification for the 9-phase chat pipeline.
+ *
+ * I-14: "Memory retrieval: < 50ms for up to 100K memories. Perception: < 5ms.
+ *        Mutation-audit: < 1ms (same SQLite transaction). Hot-path total
+ *        (excl. LLM): <= 103ms."
+ *
+ * This module is a VERIFICATION function, not middleware. It takes phase timings
+ * from ResponseMetadata.phases (produced by the pipeline) and returns a report
+ * indicating whether budgets were met or violated.
+ *
+ * Design decisions:
+ *   - Pure function: no side effects, no database access, no state mutation.
+ *   - Does NOT throw on violation: returns violations in report (degraded mode).
+ *   - WARNING when phase exceeds budget by < 2x; CRITICAL when >= 2x.
+ *   - 'generation' phase excluded from hot-path total (LLM latency is external).
+ *
+ * Invariants enforced: I-14
+ * Failure modes defended: FM-11 (observability overhead < 2%)
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * I-14: Default latency budgets derived from the spec.
+ * All values in milliseconds.
+ */
+export const DEFAULT_LATENCY_BUDGET = Object.freeze({
+    perception: 5,
+    retrieval: 50,
+    contextAssembly: 15,
+    preSafety: 5,
+    postSafety: 5,
+    learning: 10,
+    evaluation: 5,
+    audit: 1,
+    hotPathTotal: 103,
+});
+// ============================================================================
+// Phase-to-Budget Mapping
+// ============================================================================
+/**
+ * Maps PipelinePhase names to LatencyBudget keys.
+ * 'generation' has no budget entry because it is excluded from hot-path totals.
+ */
+const PHASE_BUDGET_MAP = new Map([
+    ['perception', 'perception'],
+    ['retrieval', 'retrieval'],
+    ['context_assembly', 'contextAssembly'],
+    ['pre_safety', 'preSafety'],
+    ['post_safety', 'postSafety'],
+    ['learning', 'learning'],
+    ['evaluation', 'evaluation'],
+    ['audit', 'audit'],
+]);
+// ============================================================================
+// Evaluation Function
+// ============================================================================
+/**
+ * I-14: Evaluate phase timings against latency budgets.
+ *
+ * Pure function. Takes phase timings from ResponseMetadata.phases and returns
+ * a LatencyReport with any violations found.
+ *
+ * Severity classification:
+ *   - WARNING: phase exceeds budget but by less than 2x
+ *   - CRITICAL: phase exceeds budget by 2x or more
+ *
+ * The 'generation' phase is excluded from hot-path total calculation because
+ * LLM inference latency is external and unbounded by design.
+ *
+ * @param phases - Array of { phase, durationMs } from ResponseMetadata
+ * @param budget - Optional partial budget overrides (merged with defaults)
+ * @returns LatencyReport with violations, hot-path total, and overall verdict
+ */
+export function evaluateLatency(phases, budget) {
+    // Merge custom budget overrides with defaults
+    const effectiveBudget = {
+        ...DEFAULT_LATENCY_BUDGET,
+        ...budget,
+    };
+    const violations = [];
+    let hotPathMs = 0;
+    for (const entry of phases) {
+        // Exclude 'generation' from hot-path total
+        if (entry.phase !== 'generation') {
+            hotPathMs += entry.durationMs;
+        }
+        // Check per-phase budget
+        const budgetKey = PHASE_BUDGET_MAP.get(entry.phase);
+        if (budgetKey !== undefined) {
+            const phaseBudget = effectiveBudget[budgetKey];
+            if (entry.durationMs > phaseBudget) {
+                // Severity: CRITICAL if >= 2x budget, WARNING if < 2x
+                const severity = entry.durationMs >= phaseBudget * 2
+                    ? 'critical'
+                    : 'warning';
+                violations.push({
+                    phase: entry.phase,
+                    budgetMs: phaseBudget,
+                    actualMs: entry.durationMs,
+                    severity,
+                });
+            }
+        }
+    }
+    // Check hot-path total budget
+    const withinHotPath = hotPathMs <= effectiveBudget.hotPathTotal;
+    return {
+        violations,
+        hotPathMs,
+        hotPathBudgetMs: effectiveBudget.hotPathTotal,
+        withinBudget: violations.length === 0 && withinHotPath,
+    };
+}
+//# sourceMappingURL=latency_harness.js.map

package/dist/api/enforcement/latency_harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"latency_harness.js","sourceRoot":"","sources":["../../../src/api/enforcement/latency_harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAqDH,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAkB,MAAM,CAAC,MAAM,CAAC;IACjE,UAAU,EAAE,CAAC;IACb,SAAS,EAAE,EAAE;IACb,eAAe,EAAE,EAAE;IACnB,SAAS,EAAE,CAAC;IACZ,UAAU,EAAE,CAAC;IACb,QAAQ,EAAE,EAAE;IACZ,UAAU,EAAE,CAAC;IACb,KAAK,EAAE,CAAC;IACR,YAAY,EAAE,GAAG;CAClB,CAAC,CAAC;AAEH,+EAA+E;AAC/E,0BAA0B;AAC1B,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,gBAAgB,GAA0E,IAAI,GAAG,CAAC;IACtG,CAAC,YAAY,EAAE,YAAY,CAAC;IAC5B,CAAC,WAAW,EAAE,WAAW,CAAC;IAC1B,CAAC,kBAAkB,EAAE,iBAAiB,CAAC;IACvC,CAAC,YAAY,EAAE,WAAW,CAAC;IAC3B,CAAC,aAAa,EAAE,YAAY,CAAC;IAC7B,CAAC,UAAU,EAAE,UAAU,CAAC;IACxB,CAAC,YAAY,EAAE,YAAY,CAAC;IAC5B,CAAC,OAAO,EAAE,OAAO,CAAC;CACnB,CAAC,CAAC;AAEH,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAqF,EACrF,MAA+B;IAE/B,8CAA8C;IAC9C,MAAM,eAAe,GAAkB;QACrC,GAAG,sBAAsB;QACzB,GAAG,MAAM;KACV,CAAC;IAEF,MAAM,UAAU,GAAuB,EAAE,CAAC;IAC1C,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,2CAA2C;QAC3C,IAAI,KAAK,CAAC,KAAK,KAAK,YAAY,EAAE,CAAC;YACjC,SAAS,IAAI,KAAK,CAAC,UAAU,CAAC;QAChC,CAAC;QAED,yBAAyB;QACzB,MAAM,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACpD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,MAAM,WAAW,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;YAC/C,IAAI,KAAK,CAAC,UAAU,GAAG,WAAW,EAAE,CAAC;gBACnC,sDAAsD;gBACtD,MAAM,QAAQ,GAA2B,KAAK,CAAC,UAAU,IAAI,WAAW,GAAG,CAAC;oBAC1E,CAAC,CAAC,UAAU;oBACZ,CAAC,CAAC,SAAS,CAAC;gBAEd,UAAU,CAAC,IAAI,CAAC;oBACd,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,QAAQ,EAAE,WAAW;oBACrB,QAAQ,EAAE,KAAK,CAAC,UAAU;oBAC1B,QAAQ;iBACT,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,8BAA8B;IAC9B,MAAM,aAAa,GAAG,SAAS,IAAI,eAAe,CAAC,YAAY,CAAC;IAEhE,OAAO;QACL,UAAU;QACV,SAAS;QACT,eAAe,EAAE,eAAe,CAAC,YAAY;QAC7C,YAAY,EAAE,UAAU,CAAC,MAAM,KAAK,CAAC,IAAI,aAAa;KACvD,CAAC;AACJ,CAAC"}

package/dist/api/enforcement/rate_guard.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Rate limit enforcement guard for the API surface.
+ * S ref: §36 (rate limiting), SD-14 (RBAC -> Rate Limit -> Execute ordering),
+ *        FM-02 (cost explosion defense)
+ *
+ * Phase: 4 (API Surface)
+ * Implements: SDD §7 build order item 4
+ *
+ * After RBAC passes (FPD-5), rate limiting checks the token-bucket
+ * before allowing the operation to proceed. The kernel's RateLimiter
+ * handles the token-bucket state in SQLite.
+ *
+ * Three bucket types per §36:
+ *   - api_calls: General API call rate (default 100/min)
+ *   - emit_event: Event emission rate (default 10/min)
+ *   - propose_rejections: Rejection tracking
+ *
+ * Invariants enforced: I-13 (enforcement ordering via SD-14)
+ * Failure modes defended: FM-02 (cost explosion via call frequency capping)
+ */
+import type { OperationContext, RateLimiter, BucketType, DatabaseConnection } from '../../kernel/interfaces/index.js';
+/**
+ * §36, SD-14: Require rate limit allowance for the current operation.
+ *
+ * This function MUST be called AFTER RBAC check (FPD-5) and BEFORE
+ * delegation to orchestration.
+ *
+ * The kernel's RateLimiter.checkAndConsume() atomically checks and
+ * consumes a token from the specified bucket. If no tokens remain,
+ * this function throws RATE_LIMITED with cooldownMs indicating when
+ * the bucket will refill.
+ *
+ * @param rateLimiter - The kernel's RateLimiter instance
+ * @param conn - Database connection for atomic token-bucket operations
+ * @param ctx - The operation context (scopes the bucket to tenant/agent)
+ * @param bucketType - Which rate limit bucket to check
+ * @throws LimenError with code RATE_LIMITED if bucket is exhausted
+ */
+export declare function requireRateLimit(rateLimiter: RateLimiter, conn: DatabaseConnection, ctx: OperationContext, bucketType: BucketType): void;
+/**
+ * §36: Check concurrent stream count against per-tenant limit.
+ *
+ * S36 specifies a default of 50 concurrent streams per tenant.
+ * This is separate from the token-bucket rate limiter -- it tracks
+ * active stream count in memory (not in SQLite).
+ *
+ * @param activeStreamCount - Current number of active streams for this tenant
+ * @param maxConcurrentStreams - Configured maximum (default 50 per S36)
+ * @throws LimenError with code RATE_LIMITED if stream limit reached
+ */
+export declare function requireStreamCapacity(activeStreamCount: number, maxConcurrentStreams: number): void;
+//# sourceMappingURL=rate_guard.d.ts.map

package/dist/api/enforcement/rate_guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate_guard.d.ts","sourceRoot":"","sources":["../../../src/api/enforcement/rate_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAAE,WAAW,EAAE,UAAU,EAAE,kBAAkB,EAC9D,MAAM,kCAAkC,CAAC;AAG1C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,WAAW,EACxB,IAAI,EAAE,kBAAkB,EACxB,GAAG,EAAE,gBAAgB,EACrB,UAAU,EAAE,UAAU,GACrB,IAAI,CA8BN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,iBAAiB,EAAE,MAAM,EACzB,oBAAoB,EAAE,MAAM,GAC3B,IAAI,CAQN"}