instar 0.28.109 → 0.28.111

package/dist/remediation/NovelFailureReviewer.d.ts

@@ -0,0 +1,212 @@
+/**
+ * NovelFailureReviewer — bottom-up signature discovery for `no-matching-runbook`
+ * degradation events.
+ *
+ * Tier-3 S-1 of the Self-Healing Remediator v2 rollout.
+ *
+ * NOT a `CoherenceReviewer` subclass and NOT under `src/core/reviewers/`
+ * (§A50). NOT the same as `src/monitoring/SystemReviewer.ts` (the probe
+ * runner — see §A18 for the rename history). This module lives at
+ * `src/remediation/NovelFailureReviewer.ts` and is structurally distinct
+ * from both.
+ *
+ * Spec anchor: docs/specs/SELF-HEALING-REMEDIATOR-V2-SPEC.md
+ *   §A10  caps / batching / structured rendering / schema constraints
+ *   §A18  module rename (SystemReviewer → NovelFailureReviewer)
+ *   §A26  additional guardrails (dismiss-trust, no-slot-for-collisions,
+ *         model allowlist, raw-response redaction)
+ *   §A32  signed `producingAgentId` on every proposal
+ *   §A47  per-signature counter persistence at
+ *         `.instar/remediation/cluster-counters-<machineId>.json`
+ *   §A50  naming clarity (this comment)
+ *   §A57  Tier-3 placement
+ *   §A60  deterministic proposalId = sha256(clusterSignature || windowStartMs || fleetScope)
+ *   §A65  LLM monthly budget circuit-breaker + per-call cost cap
+ *
+ * Pipeline per `runTick()`:
+ *   1. Read `auditProjection.unmatched()` — `no-matching-runbook` entries.
+ *   2. Cluster by signature: `(subsystem, errorCode-token-classed,
+ *      reason-prefix-hashed)` (§A10).
+ *   3. Persist per-signature counters with HMAC (§A47).
+ *   4. For clusters crossing thresholds (≥3 occurrences × ≥2 process
+ *      lifetimes within `windowDays`):
+ *       - If outstanding-proposal cap reached → silently queue (no LLM
+ *         call, no slot consumed).
+ *       - Else: call `llmCaller()` with a fixed safety frame; validate
+ *         schema (§A10), strip injection artifacts, check collision
+ *         against active runbook errorCodes (§A26 — collision rejection
+ *         does NOT consume an outstanding slot), persist the signed
+ *         proposal, and emit observability events.
+ *
+ * Out of scope for S-1 (handled by S-2 Dashboard / S-3 promotion-gate):
+ *   - Batched Telegram notification rendering — S-1 emits structured
+ *     events; S-2 owns UI.
+ *   - Primary-aggregator lease + fencing tokens — A47 / A60 cross-machine
+ *     coordination ships alongside S-2 / S-3.
+ */
+import { AuditProjection } from './audit/AuditProjection.js';
+import type { AuditEntry } from './audit/AuditWriter.js';
+import type { RemediationKeyVault } from './RemediationKeyVault.js';
+import type { TrustElevationSource } from './TrustElevationSource.js';
+export interface NovelFailureReviewerConfig {
+    /** Minimum occurrences to qualify a cluster for proposal (§A10/§A17). */
+    clusterThresholdOccurrences: number;
+    /** Minimum distinct process lifetimes spanned (§A10/§A17). */
+    clusterThresholdLifetimes: number;
+    /** Sliding window in days for occurrence / lifetime counting. */
+    windowDays: number;
+    /** Max outstanding proposals per agent at any time (§A10). */
+    outstandingProposalCap: number;
+    /** Cluster LRU bound (§A10). */
+    clusterLruCap: number;
+    /** LLM model id (allowlisted in production via §A26). */
+    llmModel: string;
+    /** Monthly cumulative LLM spend ceiling in USD (§A65). */
+    llmMonthlyBudgetUsd: number;
+    /** Per-call estimated cost ceiling in USD (§A65). */
+    llmPerCallCostCapUsd?: number;
+    /** Estimated USD cost per LLM call. Default fits Haiku-class pricing. */
+    llmEstimatedCostPerCallUsd?: number;
+}
+export declare const DEFAULT_NOVEL_FAILURE_REVIEWER_CONFIG: NovelFailureReviewerConfig;
+/** §A10 — small, fixed allowlist enforced at config-load (per §A26). */
+export declare const LLM_MODEL_ALLOWLIST: ReadonlySet<string>;
+export interface SampleEvent {
+    subsystem: string;
+    errorCode: string;
+    reason: {
+        redacted: string;
+    };
+    timestamp: number;
+}
+export interface NovelFailureProposal {
+    /** §A60: sha256(clusterSignature || windowStartMs || fleetScope). */
+    proposalId: string;
+    clusterSignature: string;
+    occurrencesObserved: number;
+    processLifetimes: number;
+    /** ≤ 3 redacted entries — §A26 raw-response redaction handled by writer. */
+    sampleEvents: SampleEvent[];
+    llmSummary: string;
+    suggestedErrorCode: string;
+    hypothesis: string;
+    /** §A32 — signed agent identity stamped on every proposal. */
+    producingAgentId: string;
+    producingAgentSignature: string;
+    generatedAt: number;
+    status: 'outstanding' | 'dismissed' | 'promoted';
+    /** §A10 forensic fields (prompt-hash, raw-response, model, generated-at). */
+    forensic: {
+        promptHash: string;
+        llmModel: string;
+        /** Redacted raw response. Pre-redaction copy lives in `llm-raw-*.jsonl`. */
+        rawResponse: string;
+    };
+}
+export type LlmCaller = (prompt: string) => Promise<string>;
+export interface ObservabilityEvent {
+    event: string;
+    payload?: Record<string, unknown>;
+}
+export interface NovelFailureReviewerOpts {
+    stateDir: string;
+    auditProjection: AuditProjection;
+    llmCaller: LlmCaller;
+    keyVault: RemediationKeyVault;
+    /** Agent identity stamped on every proposal (§A32). */
+    agentId: string;
+    /** Machine id — disambiguates persistence files (§A47). */
+    machineId: string;
+    /** Fleet scope identifier for §A60 proposalId derivation. */
+    fleetScope?: string;
+    /** §A26 dismiss gate — when present, dismiss requires `collaborative`. */
+    trustSource?: TrustElevationSource;
+    /** Active runbook errorCodes for §A10 / §A26 collision rejection. */
+    getActiveRunbookErrorCodes?: () => ReadonlySet<string>;
+    /**
+     * Receives observability events synchronously. Production wires to the
+     * server's metrics sink; tests collect events for assertion.
+     */
+    onEvent?: (e: ObservabilityEvent) => void;
+    /** Optional `Date.now`-equivalent for deterministic tests. */
+    now?: () => number;
+    /** Process lifetime token — distinct restarts must use distinct values. */
+    processLifetimeToken?: string;
+    config?: Partial<NovelFailureReviewerConfig>;
+}
+export declare class NovelFailureReviewer {
+    private readonly opts;
+    private readonly cfg;
+    private readonly proposalDir;
+    private readonly countersPath;
+    private readonly spendPath;
+    private readonly rawLlmPath;
+    private readonly hmacKey;
+    private readonly proposalSigningKey;
+    /** In-memory mirror of the counters file. */
+    private counters;
+    /** LRU touch order — oldest first; mirrors `counters` membership. */
+    private lru;
+    constructor(opts: NovelFailureReviewerOpts);
+    /**
+     * Run one hourly tick. Reads unmatched audit entries, updates per-signature
+     * counters, and emits proposals for clusters crossing thresholds.
+     */
+    runTick(): Promise<{
+        clusters: number;
+        proposals: number;
+    }>;
+    /** Returns currently persisted proposals, sorted oldest-first. */
+    listProposals(): Promise<NovelFailureProposal[]>;
+    /**
+     * Mark a proposal dismissed. Requires `collaborative` trust via the
+     * injected TrustElevationSource (§A26).
+     */
+    dismissProposal(proposalId: string, principal: {
+        userId: string;
+    }): Promise<void>;
+    private emit;
+    /** Update an in-memory cluster counter; touches LRU. */
+    private touch;
+    private evictExpired;
+    private loadCounters;
+    private persistCounters;
+    private signCounters;
+    private computeProposalId;
+    private buildPrompt;
+    private buildProposal;
+    private persistProposal;
+    private canSpendLlm;
+    private recordLlmSpend;
+    private readMonthlySpend;
+    private appendRawLlmLog;
+    private gcRawLlmLog;
+}
+/**
+ * §A10 token-classed signature: paths → `<path>`, hex → `<hex>`,
+ * numbers → `<num>`. Collapses cardinality.
+ */
+export declare function tokenClassify(s: string): string;
+export declare function computeClusterSignature(e: AuditEntry): string;
+interface ParsedLlmOutput {
+    summary: string;
+    suggestedErrorCode: string;
+    hypothesis: string;
+}
+/**
+ * Parse + sanitize LLM JSON output. Returns null when:
+ *   - JSON parse fails
+ *   - fields missing / wrong types
+ *   - schema constraints violated AFTER sanitization
+ *
+ * Per §A10: URLs, code fences, and imperative-verb markers are stripped
+ * BEFORE schema enforcement. Length / regex constraints then enforced.
+ */
+export declare function parseAndSanitizeLlmOutput(raw: string): ParsedLlmOutput | null;
+/**
+ * §A10 — strip URLs, code fences, and imperative-verb markers from
+ * LLM-emitted free-text before persistence.
+ */
+export declare function redactInjectionArtifacts(s: string): string;
+export {};
+//# sourceMappingURL=NovelFailureReviewer.d.ts.map

package/dist/remediation/NovelFailureReviewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NovelFailureReviewer.d.ts","sourceRoot":"","sources":["../../src/remediation/NovelFailureReviewer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAKH,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAKtE,MAAM,WAAW,0BAA0B;IACzC,yEAAyE;IACzE,2BAA2B,EAAE,MAAM,CAAC;IACpC,8DAA8D;IAC9D,yBAAyB,EAAE,MAAM,CAAC;IAClC,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,sBAAsB,EAAE,MAAM,CAAC;IAC/B,gCAAgC;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,mBAAmB,EAAE,MAAM,CAAC;IAC5B,qDAAqD;IACrD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,yEAAyE;IACzE,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,eAAO,MAAM,qCAAqC,EAAE,0BAUnD,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAIlD,CAAC;AAEH,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB,uBAAuB,EAAE,MAAM,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;IACjD,6EAA6E;IAC7E,QAAQ,EAAE;QACR,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,4EAA4E;QAC5E,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE5D,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,eAAe,CAAC;IACjC,SAAS,EAAE,SAAS,CAAC;IACrB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,oBAAoB,CAAC;IACnC,qEAAqE;IACrE,0BAA0B,CAAC,EAAE,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC;IACvD;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAC1C,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,2EAA2E;IAC3E,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC,0BAA0B,CAAC,CAAC;CAC9C;AA8CD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA2B;IAChD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA6B;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAE5C,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,CAA0C;IAC1D,qEAAqE;IACrE,OAAO,CAAC,GAAG,CAAgB;gBAEf,IAAI,EAAE,wBAAwB;IA8C1C;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IA2GjE,kEAAkE;IAC5D,aAAa,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAmBtD;;;OAGG;IACG,eAAe,CACnB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAC5B,OAAO,CAAC,IAAI,CAAC;IA8BhB,OAAO,CAAC,IAAI;IAQZ,wDAAwD;IACxD,OAAO,CAAC,KAAK;IAwCb,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,YAAY;IAoBpB,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,aAAa;IA6CrB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,WAAW;CAepB;AAID;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAU/C;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAU7D;AAED,UAAU,eAAe;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CA+B7E;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAgB1D"}