evidential-protocol 2.0.0 → 3.1.0

package/dist/provenance.js

@@ -0,0 +1,197 @@
+/**
+ * EP-2: Root Provenance Tracing (Kusunda pre-family lineage)
+ *
+ * Traces any claim back through the full agent chain to its absolute
+ * origin. Supports depth queries, weakest-link analysis, compounding
+ * confidence degradation, and Mermaid diagram rendering.
+ */
+import { CLASS_STRENGTH } from "./types.js";
+/** Generate a compact unique ID. */
+function generateId() {
+    const ts = Date.now().toString(36);
+    const rand = Math.random().toString(36).slice(2, 8);
+    return `prov_${ts}_${rand}`;
+}
+/**
+ * Manages a directed acyclic provenance chain.
+ *
+ * Each node records a claim, its evidence, and a link to its parent.
+ * Root nodes represent original observations; leaves are terminal claims.
+ */
+export class ProvenanceChain {
+    nodes = new Map();
+    childrenIndex = new Map();
+    /** Total number of nodes in the chain. */
+    get size() {
+        return this.nodes.size;
+    }
+    /**
+     * Add a new node to the provenance chain.
+     *
+     * @param claim - The assertion being made.
+     * @param evidence - Evidence supporting the claim.
+     * @param producer - Agent or tool that produced this node.
+     * @param parentId - ID of the parent node (omit for root nodes).
+     * @returns The created ProvenanceNode.
+     * @throws If parentId is provided but does not exist in the chain.
+     */
+    addNode(claim, evidence, producer, parentId) {
+        if (parentId !== undefined && !this.nodes.has(parentId)) {
+            throw new Error(`Parent node not found: ${parentId}`);
+        }
+        const node = {
+            id: generateId(),
+            claim,
+            evidence,
+            producer,
+            timestamp: new Date().toISOString(),
+            parent_id: parentId ?? null,
+        };
+        this.nodes.set(node.id, node);
+        if (parentId !== undefined) {
+            const children = this.childrenIndex.get(parentId);
+            if (children) {
+                children.push(node.id);
+            }
+            else {
+                this.childrenIndex.set(parentId, [node.id]);
+            }
+        }
+        return node;
+    }
+    /** Get a node by ID, or undefined if not found. */
+    getNode(nodeId) {
+        return this.nodes.get(nodeId);
+    }
+    /**
+     * Walk back from a node to the absolute origin.
+     *
+     * @returns Array of nodes from the given node to the root (inclusive).
+     * @throws If nodeId does not exist.
+     */
+    traceToRoot(nodeId) {
+        const path = [];
+        let currentId = nodeId;
+        while (currentId !== null) {
+            const node = this.nodes.get(currentId);
+            if (!node) {
+                throw new Error(`Node not found: ${currentId}`);
+            }
+            path.push(node);
+            currentId = node.parent_id;
+        }
+        return path;
+    }
+    /**
+     * Get the depth (number of hops from the root) for a node.
+     *
+     * Root nodes have depth 0.
+     * @throws If nodeId does not exist.
+     */
+    getDepth(nodeId) {
+        // traceToRoot returns [node, ..., root], depth = length - 1
+        return this.traceToRoot(nodeId).length - 1;
+    }
+    /** Get all root nodes (original observations with no parent). */
+    getRoots() {
+        const roots = [];
+        for (const node of this.nodes.values()) {
+            if (node.parent_id === null) {
+                roots.push(node);
+            }
+        }
+        return roots;
+    }
+    /** Get all leaf nodes (terminal claims with no children). */
+    getLeaves() {
+        const leaves = [];
+        for (const node of this.nodes.values()) {
+            const children = this.childrenIndex.get(node.id);
+            if (!children || children.length === 0) {
+                leaves.push(node);
+            }
+        }
+        return leaves;
+    }
+    /**
+     * Find the weakest evidence class in the chain from a node to its root.
+     *
+     * @returns The lowest evidence class found along the path.
+     * @throws If nodeId does not exist.
+     */
+    weakestLink(nodeId) {
+        const path = this.traceToRoot(nodeId);
+        let weakest = "direct";
+        for (const node of path) {
+            if (CLASS_STRENGTH[node.evidence.class] < CLASS_STRENGTH[weakest]) {
+                weakest = node.evidence.class;
+            }
+        }
+        return weakest;
+    }
+    /**
+     * Compute compounding confidence through the chain to root.
+     *
+     * Each hop multiplies confidence, modeling degradation: the further
+     * from the source, the lower the total confidence.
+     *
+     * @returns Compounded confidence score (0.0 - 1.0).
+     * @throws If nodeId does not exist.
+     */
+    chainConfidence(nodeId) {
+        const path = this.traceToRoot(nodeId);
+        let confidence = 1.0;
+        for (const node of path) {
+            confidence *= node.evidence.confidence;
+        }
+        return Math.round(confidence * 10000) / 10000;
+    }
+    /**
+     * Render the entire provenance chain as a Mermaid flowchart.
+     *
+     * Direction: bottom-to-top (roots at bottom, leaves at top).
+     */
+    toMermaid() {
+        const lines = ["graph BT"];
+        for (const node of this.nodes.values()) {
+            const label = this.escapeMermaid(`${node.claim}\\n[${node.evidence.class} | ${node.evidence.confidence}]\\n${node.producer}`);
+            lines.push(`  ${node.id}["${label}"]`);
+        }
+        for (const node of this.nodes.values()) {
+            if (node.parent_id !== null) {
+                lines.push(`  ${node.parent_id} --> ${node.id}`);
+            }
+        }
+        return lines.join("\n");
+    }
+    /** Serialize the chain to a JSON-safe snapshot. */
+    toJSON() {
+        return {
+            version: "1.0",
+            nodes: Array.from(this.nodes.values()),
+            created_at: new Date().toISOString(),
+        };
+    }
+    /** Restore a chain from a serialized snapshot. */
+    static fromJSON(snapshot) {
+        const chain = new ProvenanceChain();
+        for (const node of snapshot.nodes) {
+            chain.nodes.set(node.id, node);
+            if (node.parent_id !== null) {
+                const children = chain.childrenIndex.get(node.parent_id);
+                if (children) {
+                    children.push(node.id);
+                }
+                else {
+                    chain.childrenIndex.set(node.parent_id, [node.id]);
+                }
+            }
+        }
+        return chain;
+    }
+    // ---- Internal helpers ----
+    escapeMermaid(text) {
+        return text.replace(/"/g, "&quot;");
+    }
+}
+//# sourceMappingURL=provenance.js.map

package/dist/provenance.js.map

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

package/dist/purity.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Content Contamination Detection (Kusunda loanword resistance)
+ *
+ * Kusunda is a language isolate that historically resisted borrowing
+ * from neighbouring Indo-Aryan and Tibeto-Burman languages. This module
+ * mirrors that principle: it detects when external or untrusted data
+ * enters a content pipeline and quantifies contamination.
+ */
+import { type EvidenceClass } from "./types.js";
+/** Where a piece of content originated. */
+export type SourceOrigin = "internal" | "external" | "cached" | "generated" | "unknown";
+/** A discrete segment of content with known provenance. */
+export interface ContentSegment {
+    /** The textual content of this segment. */
+    text: string;
+    /** Origin classification. */
+    origin: SourceOrigin;
+    /** Optional human-readable source identifier. */
+    source?: string;
+    /** Evidence class associated with this segment, if known. */
+    evidence_class?: EvidenceClass;
+}
+/** Result of a purity scan across a set of content segments. */
+export interface PurityAnalysis {
+    /** Total number of segments scanned. */
+    total_segments: number;
+    /** Ratio of internal segments (0–1). */
+    internal_ratio: number;
+    /** Ratio of external segments (0–1). */
+    external_ratio: number;
+    /** Whether the content is considered contaminated. */
+    contaminated: boolean;
+    /** Contamination score (0 = pure, 1 = fully contaminated). */
+    contamination_score: number;
+    /** Segments flagged as external or unknown. */
+    flagged_segments: ContentSegment[];
+}
+/**
+ * Compute a purity score from a set of content segments.
+ * Returns a value between 0 (fully contaminated) and 1 (pure).
+ */
+export declare function computePurityScore(segments: ContentSegment[]): number;
+/**
+ * Scans content segments for contamination from external or unknown
+ * sources. Maintains a registry of known source patterns so that
+ * segments can be classified automatically.
+ */
+export declare class PurityScanner {
+    private readonly knownSources;
+    /**
+     * Register a source pattern and its origin classification.
+     * When a segment's `source` field matches the pattern (simple
+     * `includes` match), it will be classified accordingly.
+     */
+    addKnownSource(pattern: string, origin: SourceOrigin): void;
+    /**
+     * Run a full purity scan. The raw `content` string is accepted for
+     * context but the analysis is driven by the structured `segments`.
+     */
+    scan(_content: string, segments: ContentSegment[]): PurityAnalysis;
+    /**
+     * Convenience check: is the content pure enough?
+     *
+     * @param content  - The raw content string (context).
+     * @param segments - Structured content segments.
+     * @param threshold - Maximum acceptable purity score (default 0.8).
+     *                    A purity score of 0.8 means at most 20% external.
+     */
+    isPure(content: string, segments: ContentSegment[], threshold?: number): boolean;
+    /**
+     * Return only segments whose origin is `external` or `unknown`.
+     */
+    flagExternalContent(segments: ContentSegment[]): ContentSegment[];
+    /**
+     * Wrap external/unknown segments with contamination warnings.
+     * Returns new segment objects; originals are not mutated.
+     */
+    quarantine(segments: ContentSegment[]): ContentSegment[];
+    /**
+     * Attempt to resolve unknown origins using the known-source registry.
+     * Returns a new array; input segments are not mutated.
+     */
+    private resolveOrigins;
+}
+//# sourceMappingURL=purity.d.ts.map

package/dist/purity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"purity.d.ts","sourceRoot":"","sources":["../src/purity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAMhD,2CAA2C;AAC3C,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;AAExF,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,MAAM,EAAE,YAAY,CAAC;IACrB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,cAAc,CAAC,EAAE,aAAa,CAAC;CAChC;AAED,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,YAAY,EAAE,OAAO,CAAC;IACtB,8DAA8D;IAC9D,mBAAmB,EAAE,MAAM,CAAC;IAC5B,+CAA+C;IAC/C,gBAAgB,EAAE,cAAc,EAAE,CAAC;CACpC;AAMD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,MAAM,CAQrE;AAWD;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;IAEvD;;;;OAIG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI;IAI3D;;;OAGG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,cAAc;IAqClE;;;;;;;OAOG;IACH,MAAM,CACJ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,EAAE,EAC1B,SAAS,GAAE,MAAY,GACtB,OAAO;IAMV;;OAEG;IACH,mBAAmB,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,cAAc,EAAE;IAOjE;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,cAAc,EAAE;IAgBxD;;;OAGG;IACH,OAAO,CAAC,cAAc;CAavB"}

package/dist/purity.js

@@ -0,0 +1,124 @@
+/**
+ * Content Contamination Detection (Kusunda loanword resistance)
+ *
+ * Kusunda is a language isolate that historically resisted borrowing
+ * from neighbouring Indo-Aryan and Tibeto-Burman languages. This module
+ * mirrors that principle: it detects when external or untrusted data
+ * enters a content pipeline and quantifies contamination.
+ */
+// ---------------------------------------------------------------------------
+// Standalone utility
+// ---------------------------------------------------------------------------
+/**
+ * Compute a purity score from a set of content segments.
+ * Returns a value between 0 (fully contaminated) and 1 (pure).
+ */
+export function computePurityScore(segments) {
+    if (segments.length === 0)
+        return 1;
+    const internalCount = segments.filter((s) => s.origin === "internal" || s.origin === "generated").length;
+    return internalCount / segments.length;
+}
+/**
+ * Scans content segments for contamination from external or unknown
+ * sources. Maintains a registry of known source patterns so that
+ * segments can be classified automatically.
+ */
+export class PurityScanner {
+    knownSources = [];
+    /**
+     * Register a source pattern and its origin classification.
+     * When a segment's `source` field matches the pattern (simple
+     * `includes` match), it will be classified accordingly.
+     */
+    addKnownSource(pattern, origin) {
+        this.knownSources.push({ pattern, origin });
+    }
+    /**
+     * Run a full purity scan. The raw `content` string is accepted for
+     * context but the analysis is driven by the structured `segments`.
+     */
+    scan(_content, segments) {
+        const resolved = this.resolveOrigins(segments);
+        const total = resolved.length;
+        if (total === 0) {
+            return {
+                total_segments: 0,
+                internal_ratio: 1,
+                external_ratio: 0,
+                contaminated: false,
+                contamination_score: 0,
+                flagged_segments: [],
+            };
+        }
+        const flagged = this.flagExternalContent(resolved);
+        const internalCount = resolved.filter((s) => s.origin === "internal" || s.origin === "generated" || s.origin === "cached").length;
+        const externalCount = resolved.filter((s) => s.origin === "external" || s.origin === "unknown").length;
+        const internalRatio = internalCount / total;
+        const externalRatio = externalCount / total;
+        const contaminationScore = externalRatio;
+        return {
+            total_segments: total,
+            internal_ratio: internalRatio,
+            external_ratio: externalRatio,
+            contaminated: contaminationScore > 0.2,
+            contamination_score: contaminationScore,
+            flagged_segments: flagged,
+        };
+    }
+    /**
+     * Convenience check: is the content pure enough?
+     *
+     * @param content  - The raw content string (context).
+     * @param segments - Structured content segments.
+     * @param threshold - Maximum acceptable purity score (default 0.8).
+     *                    A purity score of 0.8 means at most 20% external.
+     */
+    isPure(content, segments, threshold = 0.8) {
+        const resolved = this.resolveOrigins(segments);
+        const score = computePurityScore(resolved);
+        return score >= threshold;
+    }
+    /**
+     * Return only segments whose origin is `external` or `unknown`.
+     */
+    flagExternalContent(segments) {
+        const resolved = this.resolveOrigins(segments);
+        return resolved.filter((s) => s.origin === "external" || s.origin === "unknown");
+    }
+    /**
+     * Wrap external/unknown segments with contamination warnings.
+     * Returns new segment objects; originals are not mutated.
+     */
+    quarantine(segments) {
+        return segments.map((seg) => {
+            if (seg.origin === "external" || seg.origin === "unknown") {
+                return {
+                    ...seg,
+                    text: `[QUARANTINED: ${seg.origin} content] ${seg.text} [/QUARANTINED]`,
+                };
+            }
+            return { ...seg };
+        });
+    }
+    // -----------------------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Attempt to resolve unknown origins using the known-source registry.
+     * Returns a new array; input segments are not mutated.
+     */
+    resolveOrigins(segments) {
+        return segments.map((seg) => {
+            if (seg.origin !== "unknown" || !seg.source)
+                return seg;
+            for (const entry of this.knownSources) {
+                if (seg.source.includes(entry.pattern)) {
+                    return { ...seg, origin: entry.origin };
+                }
+            }
+            return seg;
+        });
+    }
+}
+//# sourceMappingURL=purity.js.map

package/dist/purity.js.map

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

package/dist/resilience.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Resilience Module — Bus Factor / SPOF Detection
+ *
+ * Inspired by the Kusunda last-speaker problem: when knowledge
+ * lives in a single person, language death is one heartbeat away.
+ * This module identifies single points of failure across any system.
+ */
+/** A component within the system under analysis. */
+export interface SystemComponent {
+    id: string;
+    name: string;
+    category: "service" | "credential" | "process" | "knowledge" | "infrastructure";
+    operators: string[];
+    documentation_level: "none" | "minimal" | "adequate" | "comprehensive";
+    last_verified?: string;
+    restart_method?: "automatic" | "manual" | "unknown";
+    criticality: "low" | "medium" | "high" | "critical";
+}
+/** Results of a resilience analysis. */
+export interface ResilienceReport {
+    total_components: number;
+    spof_count: number;
+    at_risk_count: number;
+    healthy_count: number;
+    overall_score: number;
+    spofs: SystemComponent[];
+    recommendations: string[];
+}
+/**
+ * Analyzes a collection of system components for single points of failure,
+ * documentation gaps, and manual-restart risks.
+ */
+export declare class ResilienceAnalyzer {
+    private components;
+    /** Register a component for analysis. */
+    addComponent(component: SystemComponent): void;
+    /** Get the bus factor (number of operators) for a component. */
+    getBusFactor(componentId: string): number;
+    /** Return all components with no documentation. */
+    getUndocumented(): SystemComponent[];
+    /** Return all components requiring manual restart. */
+    getManualRestarts(): SystemComponent[];
+    /** Return critical components with only one operator (bus factor = 1). */
+    getCriticalSpofs(): SystemComponent[];
+    /** Run the full resilience analysis. */
+    analyze(): ResilienceReport;
+    /**
+     * Generate a continuity document in Markdown covering every SPOF
+     * and concrete remediation steps.
+     */
+    generateContinuityDoc(): string;
+    /**
+     * Compute an overall resilience score from 0 (fragile) to 1 (robust).
+     * Weights each component by criticality, penalizes low bus factor
+     * and poor documentation.
+     */
+    private computeOverallScore;
+    /** Build actionable recommendations from the analysis. */
+    private buildRecommendations;
+    /** Generate remediation advice for a single SPOF. */
+    private remediationFor;
+}
+//# sourceMappingURL=resilience.d.ts.map

package/dist/resilience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilience.d.ts","sourceRoot":"","sources":["../src/resilience.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,gBAAgB,CAAC;IAChF,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,mBAAmB,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,eAAe,CAAC;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;IACpD,WAAW,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;CACrD;AAED,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAkBD;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,UAAU,CAA2C;IAE7D,yCAAyC;IACzC,YAAY,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI;IAI9C,gEAAgE;IAChE,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAMzC,mDAAmD;IACnD,eAAe,IAAI,eAAe,EAAE;IAMpC,sDAAsD;IACtD,iBAAiB,IAAI,eAAe,EAAE;IAMtC,0EAA0E;IAC1E,gBAAgB,IAAI,eAAe,EAAE;IAMrC,wCAAwC;IACxC,OAAO,IAAI,gBAAgB;IAoC3B;;;OAGG;IACH,qBAAqB,IAAI,MAAM;IA2E/B;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IA+B3B,0DAA0D;IAC1D,OAAO,CAAC,oBAAoB;IA+D5B,qDAAqD;IACrD,OAAO,CAAC,cAAc;CAiCvB"}