vigiles 2.0.0

package/dist/proofs.d.ts

@@ -0,0 +1,272 @@
+/**
+ * vigiles — Deterministic proof system for self-evolving specifications.
+ *
+ * Six algorithms that verify spec mutations without any LLM dependency:
+ *
+ *   1. MonotonicityLattice — rules can only strengthen over time
+ *   2. ncd()              — information-theoretic duplicate detection
+ *   3. BloomFilter        — fast approximate set membership
+ *   4. fixedPoint()       — compilation convergence detection
+ *   5. MerkleHistory      — tamper-evident spec evolution audit trail
+ *   6. propertyTest()     — random mutation + invariant checking
+ */
+import type { Rule, ClaudeSpec } from "./spec.js";
+export interface MonotonicityViolation {
+    ruleId: string;
+    from: Rule["_kind"];
+    to: Rule["_kind"];
+    fromStrength: number;
+    toStrength: number;
+}
+export interface MonotonicityResult {
+    valid: boolean;
+    violations: MonotonicityViolation[];
+    added: string[];
+    removed: string[];
+    strengthened: string[];
+    unchanged: string[];
+}
+/**
+ * Check that a spec mutation is monotonic: existing rules only strengthen.
+ *
+ * - Adding rules: always allowed
+ * - Removing rules: flagged (informational, not a violation by default)
+ * - Strengthening (guidance → check → enforce): allowed
+ * - Weakening (enforce → guidance): violation unless allowWeaken includes the rule ID
+ */
+export declare function checkMonotonicity(before: Record<string, Rule>, after: Record<string, Rule>, options?: {
+    allowWeaken?: Set<string>;
+}): MonotonicityResult;
+/**
+ * Compute the join (least upper bound) of two rule kinds in the lattice.
+ * join(guidance, enforce) = enforce
+ */
+export declare function latticeJoin(a: Rule["_kind"], b: Rule["_kind"]): Rule["_kind"];
+/**
+ * Compute the meet (greatest lower bound) of two rule kinds in the lattice.
+ * meet(guidance, enforce) = guidance
+ */
+export declare function latticeMeet(a: Rule["_kind"], b: Rule["_kind"]): Rule["_kind"];
+/** Get the numeric strength of a rule kind. */
+export declare function ruleStrength(kind: Rule["_kind"]): number;
+/**
+ * Normalized Compression Distance — information-theoretic similarity.
+ *
+ *   NCD(x, y) = (C(xy) - min(C(x), C(y))) / max(C(x), C(y))
+ *
+ * Range: [0, 1+ε] where 0 = identical information content.
+ * Deterministic. No model dependency. Approximates the universal distance metric.
+ *
+ * Reference: Li, Chen, Li, Ma, Vitányi (2004) "The Similarity Metric"
+ */
+export declare function ncd(a: string, b: string): number;
+export interface NCDPair {
+    idA: string;
+    idB: string;
+    distance: number;
+}
+/**
+ * Find all rule pairs with NCD below a similarity threshold.
+ * Returns pairs sorted by distance (most similar first).
+ */
+export declare function findSimilarRules(rules: Record<string, Rule>, threshold?: number): NCDPair[];
+/**
+ * Bloom filter — space-efficient probabilistic set membership.
+ *
+ * Insert elements, then query "is X possibly in the set?"
+ * False positives possible. False negatives impossible.
+ *
+ * Optimal parameters:
+ *   m = -(n × ln(p)) / (ln2)²     (bit array size)
+ *   k = (m / n) × ln2              (hash function count)
+ *
+ * Reference: Bloom (1970) "Space/Time Trade-offs in Hash Coding"
+ */
+export declare class BloomFilter {
+    private readonly bits;
+    private readonly numHashes;
+    readonly size: number;
+    private _count;
+    /**
+     * Create a Bloom filter.
+     * @param expectedItems Expected number of items to insert
+     * @param falsePositiveRate Desired false positive rate (0-1)
+     */
+    constructor(expectedItems: number, falsePositiveRate?: number);
+    /** Number of items inserted. */
+    get count(): number;
+    /** Theoretical false positive rate given current fill. */
+    get estimatedFPR(): number;
+    /** Insert an element. */
+    add(item: string): void;
+    /** Query membership. Returns true if the item MIGHT be in the set. */
+    has(item: string): boolean;
+    /**
+     * Estimate the Jaccard similarity between two Bloom filters.
+     * Uses bit-level comparison — no need to know the original elements.
+     */
+    static jaccardSimilarity(a: BloomFilter, b: BloomFilter): number;
+}
+/**
+ * Build a Bloom filter from a rule's tokens.
+ * Tokenizes rule text into words and n-grams for fuzzy matching.
+ */
+export declare function ruleToBloomFilter(rule: Rule, expectedTokens?: number): BloomFilter;
+export interface FixedPointResult {
+    converged: boolean;
+    iterations: number;
+    /** Hash at each iteration. */
+    hashes: string[];
+    /** If not converged, the cycle length (0 = no cycle detected within maxIterations). */
+    cycleLength: number;
+}
+/**
+ * Detect whether a compile function reaches a fixed point.
+ *
+ * A fixed point means: applying the function again produces the same output.
+ * compile(compile(spec)) === compile(spec)
+ *
+ * If the function doesn't converge, detects cycles using Floyd's
+ * tortoise-and-hare algorithm adapted for hash sequences.
+ *
+ * @param compileFn A function that takes content and returns new content
+ * @param initialContent Starting content
+ * @param maxIterations Maximum iterations before declaring divergence
+ */
+export declare function fixedPoint(compileFn: (content: string) => string, initialContent: string, maxIterations?: number): FixedPointResult;
+export interface Mutation {
+    type: "add" | "remove" | "strengthen" | "weaken" | "merge" | "reword";
+    ruleIds: string[];
+    description: string;
+}
+export interface ProofReceipt {
+    name: string;
+    passed: boolean;
+    detail?: string;
+}
+export interface HistoryNode {
+    /** SHA-256 hash of this node (covers all fields except `hash` itself). */
+    hash: string;
+    /** Hash of the parent node ("genesis" for the first node). */
+    parentHash: string;
+    /** Hash of the compiled spec content at this version. */
+    specHash: string;
+    /** What mutation was applied. */
+    mutation: Mutation;
+    /** Proof receipts — which proofs ran and their results. */
+    proofs: ProofReceipt[];
+    /** Unix timestamp (ms). */
+    timestamp: number;
+}
+/**
+ * Merkle history — append-only, tamper-evident spec evolution log.
+ *
+ * Each node's hash covers its parent hash, creating a chain where
+ * tampering with any node invalidates all descendants.
+ */
+/**
+ * Read-only view of a MerkleHistory — exposes inspection methods but no
+ * append/mutation surface. Callers that only need to read the audit trail
+ * should depend on this instead of MerkleHistory to prevent bypassing the
+ * engine's validation gates.
+ */
+export interface ReadonlyMerkleHistory {
+    readonly length: number;
+    head(): HistoryNode | null;
+    getNodes(): readonly HistoryNode[];
+    verify(): {
+        valid: boolean;
+        invalidAt: number;
+    };
+    toJSON(): string;
+}
+export declare class MerkleHistory implements ReadonlyMerkleHistory {
+    private nodes;
+    /** Number of versions in the history. */
+    get length(): number;
+    /**
+     * Get all nodes as a deep defensive copy. Callers cannot mutate node
+     * fields (specHash, mutation, proofs) through this API — that would
+     * bypass append/proof gates and weaken the tamper-evident guarantees.
+     */
+    getNodes(): readonly HistoryNode[];
+    /**
+     * Get the latest node, or null if empty. Returned as a deep defensive
+     * copy — see getNodes() for rationale.
+     */
+    head(): HistoryNode | null;
+    /**
+     * Append a new version to the history.
+     * Returns the hash of the new node.
+     */
+    append(specHash: string, mutation: Mutation, proofs: ProofReceipt[]): string;
+    /**
+     * Verify the entire chain — every node's hash must be correct,
+     * and every parent pointer must match the previous node.
+     *
+     * Returns the index of the first invalid node, or -1 if valid.
+     */
+    verify(): {
+        valid: boolean;
+        invalidAt: number;
+    };
+    /**
+     * Serialize the history to JSON for persistence.
+     */
+    toJSON(): string;
+    /**
+     * Deserialize a history from JSON. Rejects non-array payloads and
+     * validates that each entry has the required HistoryNode shape so
+     * malformed persisted data can't produce a "valid" history that
+     * later crashes on append/verify.
+     */
+    static fromJSON(json: string): MerkleHistory;
+}
+export type MutationGenerator<T> = (value: T, seed: number) => T;
+export type Invariant<T> = (value: T) => boolean;
+export interface PropertyTestResult<T> {
+    passed: boolean;
+    iterations: number;
+    /** If failed, the mutation sequence that caused the failure. */
+    failingSequence?: T[];
+    /** If failed, the minimal shrunk counterexample. */
+    shrunk?: T;
+    /** Name of the invariant that failed. */
+    failedInvariant?: string;
+}
+/**
+ * Property-based testing: generate random mutations, check invariants hold.
+ *
+ * Inspired by QuickCheck/fast-check. Uses a deterministic PRNG for
+ * reproducible failures.
+ *
+ * @param initial Starting value
+ * @param mutate Function that produces a random mutation
+ * @param invariants Named invariant functions that must all return true
+ * @param options Test parameters
+ */
+export declare function propertyTest<T>(initial: T, mutate: MutationGenerator<T>, invariants: Record<string, Invariant<T>>, options?: {
+    iterations?: number;
+    seed?: number;
+    sequenceLength?: number;
+}): PropertyTestResult<T>;
+export interface FitnessResult {
+    score: number;
+    coverage: number;
+    redundancy: number;
+    budgetPressure: number;
+}
+/**
+ * Compute the fitness of a spec. Higher is better.
+ *
+ *   fitness = coverage × (1 - redundancy) × (1 - budgetPressure)
+ *
+ * - coverage: fraction of rules with enforcement (check or enforce)
+ * - redundancy: fraction of rule pairs that are near-duplicates (NCD < threshold)
+ * - budgetPressure: tokens used / max tokens
+ */
+export declare function fitness(spec: ClaudeSpec, options?: {
+    maxTokens?: number;
+    ncdThreshold?: number;
+}): FitnessResult;
+//# sourceMappingURL=proofs.d.ts.map

package/dist/proofs.d.ts.map

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