agentic-qe 3.7.21 → 3.8.0

package/dist/governance/witness-chain.d.ts

@@ -0,0 +1,311 @@
+/**
+ * Witness Chain - Hash-Linked Audit Trail for Quality Gate Decisions
+ *
+ * Implements an append-only, hash-linked witness log for quality gate decisions.
+ * Each receipt is cryptographically chained to its predecessor using SHA-256,
+ * creating a tamper-evident audit trail.
+ *
+ * Features:
+ * - Append-only witness log with SHA-256 hash linking
+ * - Chain integrity verification with tamper detection
+ * - SPRT (Sequential Probability Ratio Test) evidence accumulation
+ * - Export/import for brain transfer
+ * - Feature-flag gated via useWitnessChain
+ *
+ * @module governance/witness-chain
+ * @see ADR-083-coherence-gated-agent-actions.md
+ */
+/**
+ * A decision to be witnessed and recorded in the chain.
+ */
+export interface WitnessDecision {
+    /** Gate type that produced this decision */
+    type: string;
+    /** Decision outcome */
+    decision: 'PASS' | 'FAIL' | 'INCONCLUSIVE' | 'PERMIT' | 'DEFER' | 'DENY';
+    /** Contextual data for the decision */
+    context: Record<string, unknown>;
+    /** Accumulated SPRT evidence value (optional) */
+    evidence?: number;
+}
+/**
+ * An immutable receipt in the witness chain.
+ * Each receipt is hash-linked to the previous receipt.
+ */
+export interface WitnessReceipt {
+    /** Unique receipt identifier */
+    id: string;
+    /** Timestamp (ms since epoch) */
+    timestamp: number;
+    /** SHA-256 hash of the previous receipt (genesis uses '0' x 64) */
+    previousHash: string;
+    /** SHA-256 hash of this receipt: hash(previousHash + JSON(decision) + timestamp) */
+    hash: string;
+    /** The decision that was witnessed */
+    decision: WitnessDecision;
+    /** Position in the chain (0-indexed) */
+    chainIndex: number;
+}
+/**
+ * Result of verifying the witness chain integrity.
+ */
+export interface ChainVerificationResult {
+    /** Whether the entire chain is valid */
+    valid: boolean;
+    /** Total number of receipts checked */
+    length: number;
+    /** Index of the first invalid receipt (-1 if all valid) */
+    brokenAt: number;
+    /** Human-readable description of the verification outcome */
+    message: string;
+    /** Hash of the last receipt in the chain */
+    lastHash: string;
+}
+/**
+ * Serialized chain format for export/import.
+ */
+export interface WitnessChainExport {
+    /** Format version */
+    version: '1.0.0';
+    /** Export timestamp */
+    exportedAt: number;
+    /** Number of receipts */
+    length: number;
+    /** The receipt chain */
+    receipts: WitnessReceipt[];
+}
+/**
+ * Sequential Probability Ratio Test accumulator for Pass/Fail decisions.
+ *
+ * Simplified sequential decision rule with configurable evidence strength.
+ * For production use, strength should reflect log-likelihood ratio of the
+ * observation under the alternative vs null hypothesis.
+ *
+ * Accumulates evidence over a sequence of observations to decide between
+ * two hypotheses (Pass vs Fail) with controlled error rates.
+ *
+ * Boundaries:
+ * - Upper bound (accept H1 / PASS): ln(1/alpha)
+ * - Lower bound (accept H0 / FAIL): ln(beta)
+ *
+ * Default evidence step: +0.5 for positive, -0.5 for negative.
+ * Use addWeightedEvidence() for variable-strength observations.
+ */
+export declare class SPRTAccumulator {
+    private logLikelihoodRatio;
+    private readonly upperBound;
+    private readonly lowerBound;
+    private observations;
+    /**
+     * @param alpha - Type I error rate (false positive). Default: 0.05
+     * @param beta - Type II error rate (false negative). Default: 0.05
+     */
+    constructor(alpha?: number, beta?: number);
+    /**
+     * Add a weighted observation and return the current decision.
+     *
+     * The strength parameter controls the log-likelihood step size.
+     * For production use, strength should reflect the log-likelihood ratio
+     * of the observation under the alternative vs null hypothesis.
+     *
+     * @param positive - Whether this observation is positive evidence
+     * @param strength - Evidence strength (step size). Default 0.5 for backward compat.
+     * @returns Current decision: PASS, FAIL, or INCONCLUSIVE
+     */
+    addWeightedEvidence(positive: boolean, strength: number): 'PASS' | 'FAIL' | 'INCONCLUSIVE';
+    /**
+     * Add an observation with default strength (0.5) and return the current decision.
+     *
+     * @param positive - Whether this observation is positive evidence
+     * @returns Current decision: PASS, FAIL, or INCONCLUSIVE
+     */
+    addEvidence(positive: boolean): 'PASS' | 'FAIL' | 'INCONCLUSIVE';
+    /**
+     * Get the current log-likelihood ratio.
+     */
+    getRatio(): number;
+    /**
+     * Get the total number of observations.
+     */
+    getObservations(): number;
+    /**
+     * Get the SPRT boundaries.
+     */
+    getBounds(): {
+        upper: number;
+        lower: number;
+    };
+    /**
+     * Reset the accumulator to its initial state.
+     */
+    reset(): void;
+}
+/**
+ * Append-only, hash-linked witness chain for quality gate decisions.
+ *
+ * Maintains an ordered sequence of witness receipts where each receipt
+ * references the hash of its predecessor, forming a tamper-evident chain.
+ *
+ * @example
+ * ```typescript
+ * const chain = new WitnessChain();
+ * const receipt = chain.appendWitness({
+ *   type: 'coherence-gate',
+ *   decision: 'PASS',
+ *   context: { energy: 0.23, threshold: 0.4 },
+ * });
+ * const result = chain.verifyChain();
+ * console.log(result.valid); // true
+ * ```
+ */
+export declare class WitnessChain {
+    private receipts;
+    private lastHash;
+    private readonly sprtAccumulators;
+    /**
+     * Append a witness decision to the chain.
+     *
+     * Creates a new receipt hash-linked to the previous receipt and appends
+     * it to the chain. Optionally updates the SPRT accumulator for the
+     * decision type.
+     *
+     * @param decision - The decision to witness
+     * @returns The new witness receipt with its chain hash
+     */
+    appendWitness(decision: WitnessDecision): WitnessReceipt;
+    /**
+     * Verify the integrity of the entire witness chain.
+     *
+     * Walks the chain from genesis to tip, recomputing each receipt's hash
+     * and checking it against the stored value. Reports the first breakage.
+     *
+     * @returns Verification result with validity, length, and break point
+     */
+    verifyChain(): ChainVerificationResult;
+    /**
+     * Get receipts from the chain.
+     *
+     * @param limit - Maximum number of receipts to return (from most recent).
+     *                If omitted, returns the entire chain.
+     * @returns Array of witness receipts
+     */
+    getChain(limit?: number): WitnessReceipt[];
+    /**
+     * Get the total number of receipts in the chain.
+     */
+    getChainLength(): number;
+    /**
+     * Get the hash of the most recent receipt (chain tip).
+     */
+    getLastHash(): string;
+    /**
+     * Export the chain as a JSON string for brain transfer.
+     *
+     * @returns JSON string containing the full chain
+     */
+    exportChain(): string;
+    /**
+     * Import a chain from a JSON string.
+     *
+     * Validates the imported chain integrity before accepting it.
+     * Replaces the current chain if valid.
+     *
+     * @param data - JSON string from exportChain()
+     * @returns true if import was successful, false if data was invalid
+     */
+    importChain(data: string): boolean;
+    /**
+     * Get or create an SPRT accumulator for a decision type.
+     *
+     * @param type - The decision type (e.g., 'coherence-gate')
+     * @param alpha - Type I error rate (default: 0.05)
+     * @param beta - Type II error rate (default: 0.05)
+     * @returns The SPRT accumulator for the given type
+     */
+    getSPRT(type: string, alpha?: number, beta?: number): SPRTAccumulator;
+    /**
+     * Get a receipt by chain index.
+     *
+     * @param index - The chain index (0-based)
+     * @returns The receipt at the given index, or undefined if out of range
+     */
+    getReceipt(index: number): WitnessReceipt | undefined;
+    /**
+     * Update the SPRT accumulator based on the decision.
+     */
+    private updateSPRT;
+}
+/**
+ * Persistence interface for witness chain SQLite backing.
+ *
+ * Implementations must provide methods to store and retrieve receipts
+ * from the unified SQLite database. This keeps WitnessChain decoupled
+ * from the database layer.
+ */
+export interface IWitnessChainPersistence {
+    /** Store a receipt in SQLite. Called after each appendWitness(). */
+    insertReceipt(receipt: WitnessReceipt): void;
+    /** Load all receipts from SQLite, ordered by chainIndex. */
+    loadAllReceipts(): WitnessReceipt[];
+    /** Get the total count of persisted receipts. */
+    getReceiptCount(): number;
+}
+/**
+ * SQLite-backed WitnessChain that persists receipts to the unified database.
+ *
+ * Extends WitnessChain with optional SQLite persistence. When a persistence
+ * backend is provided, each witness receipt is written to SQLite on append,
+ * and the chain can be restored from SQLite on startup.
+ *
+ * @example
+ * ```typescript
+ * const persistence = createWitnessChainSQLitePersistence(db);
+ * const chain = createPersistentWitnessChain(persistence);
+ * // Chain is automatically loaded from SQLite on creation
+ * ```
+ */
+export declare class PersistentWitnessChain extends WitnessChain {
+    private readonly persistence;
+    constructor(persistence: IWitnessChainPersistence);
+    /**
+     * Append a witness and persist it to SQLite.
+     */
+    appendWitness(decision: WitnessDecision): WitnessReceipt;
+}
+/**
+ * Create a SQLite persistence backend using better-sqlite3.
+ *
+ * Creates the `witness_chain_receipts` table if it doesn't exist
+ * and provides insert/load methods.
+ *
+ * @param db - better-sqlite3 Database instance (from unified persistence)
+ * @returns IWitnessChainPersistence implementation
+ */
+export declare function createWitnessChainSQLitePersistence(db: {
+    prepare: (sql: string) => {
+        run: (...args: unknown[]) => unknown;
+        all: (...args: unknown[]) => unknown[];
+        get: (...args: unknown[]) => unknown;
+    };
+    exec: (sql: string) => void;
+}): IWitnessChainPersistence;
+/**
+ * Create a new WitnessChain instance (in-memory).
+ *
+ * @returns A new empty WitnessChain
+ */
+export declare function createWitnessChain(): WitnessChain;
+/**
+ * Create a SQLite-backed WitnessChain that persists receipts.
+ *
+ * @param persistence - SQLite persistence backend
+ * @returns A PersistentWitnessChain loaded from SQLite
+ */
+export declare function createPersistentWitnessChain(persistence: IWitnessChainPersistence): PersistentWitnessChain;
+/**
+ * Check if the witness chain feature is enabled.
+ *
+ * @returns true if the useWitnessChain feature flag is on
+ */
+export declare function isWitnessChainFeatureEnabled(): boolean;
+//# sourceMappingURL=witness-chain.d.ts.map