evidential-protocol 2.0.0 → 3.0.0

package/dist/resilience.js

@@ -0,0 +1,241 @@
+/**
+ * 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.
+ */
+/** Documentation level numeric mapping for scoring. */
+const DOC_SCORES = {
+    none: 0,
+    minimal: 0.25,
+    adequate: 0.6,
+    comprehensive: 1.0,
+};
+/** Criticality numeric mapping for weighting. */
+const CRITICALITY_WEIGHTS = {
+    low: 1,
+    medium: 2,
+    high: 3,
+    critical: 4,
+};
+/**
+ * Analyzes a collection of system components for single points of failure,
+ * documentation gaps, and manual-restart risks.
+ */
+export class ResilienceAnalyzer {
+    components = new Map();
+    /** Register a component for analysis. */
+    addComponent(component) {
+        this.components.set(component.id, component);
+    }
+    /** Get the bus factor (number of operators) for a component. */
+    getBusFactor(componentId) {
+        const component = this.components.get(componentId);
+        if (!component)
+            return 0;
+        return component.operators.length;
+    }
+    /** Return all components with no documentation. */
+    getUndocumented() {
+        return [...this.components.values()].filter((c) => c.documentation_level === "none");
+    }
+    /** Return all components requiring manual restart. */
+    getManualRestarts() {
+        return [...this.components.values()].filter((c) => c.restart_method === "manual");
+    }
+    /** Return critical components with only one operator (bus factor = 1). */
+    getCriticalSpofs() {
+        return [...this.components.values()].filter((c) => c.criticality === "critical" && c.operators.length === 1);
+    }
+    /** Run the full resilience analysis. */
+    analyze() {
+        const all = [...this.components.values()];
+        const total = all.length;
+        if (total === 0) {
+            return {
+                total_components: 0,
+                spof_count: 0,
+                at_risk_count: 0,
+                healthy_count: 0,
+                overall_score: 1,
+                spofs: [],
+                recommendations: [],
+            };
+        }
+        const spofs = all.filter((c) => c.operators.length === 1);
+        const atRisk = all.filter((c) => c.operators.length === 2);
+        const healthy = all.filter((c) => c.operators.length > 2);
+        const score = this.computeOverallScore(all);
+        const recommendations = this.buildRecommendations(all, spofs);
+        return {
+            total_components: total,
+            spof_count: spofs.length,
+            at_risk_count: atRisk.length,
+            healthy_count: healthy.length,
+            overall_score: score,
+            spofs,
+            recommendations,
+        };
+    }
+    /**
+     * Generate a continuity document in Markdown covering every SPOF
+     * and concrete remediation steps.
+     */
+    generateContinuityDoc() {
+        const report = this.analyze();
+        const lines = [];
+        lines.push("# System Continuity Document");
+        lines.push("");
+        lines.push(`Generated: ${new Date().toISOString()}`);
+        lines.push("");
+        lines.push("## Summary");
+        lines.push("");
+        lines.push(`| Metric | Value |`);
+        lines.push(`|--------|-------|`);
+        lines.push(`| Total Components | ${report.total_components} |`);
+        lines.push(`| SPOFs (bus factor = 1) | ${report.spof_count} |`);
+        lines.push(`| At Risk (bus factor <= 2) | ${report.at_risk_count} |`);
+        lines.push(`| Healthy (bus factor > 2) | ${report.healthy_count} |`);
+        lines.push(`| Overall Score | ${(report.overall_score * 100).toFixed(1)}% |`);
+        lines.push("");
+        if (report.spofs.length > 0) {
+            lines.push("## Single Points of Failure");
+            lines.push("");
+            for (const spof of report.spofs) {
+                lines.push(`### ${spof.name}`);
+                lines.push("");
+                lines.push(`- **ID:** ${spof.id}`);
+                lines.push(`- **Category:** ${spof.category}`);
+                lines.push(`- **Criticality:** ${spof.criticality}`);
+                lines.push(`- **Sole Operator:** ${spof.operators[0] ?? "unknown"}`);
+                lines.push(`- **Documentation:** ${spof.documentation_level}`);
+                lines.push(`- **Restart Method:** ${spof.restart_method ?? "unknown"}`);
+                if (spof.last_verified) {
+                    lines.push(`- **Last Verified:** ${spof.last_verified}`);
+                }
+                lines.push("");
+                lines.push("**Remediation:**");
+                lines.push("");
+                lines.push(this.remediationFor(spof));
+                lines.push("");
+            }
+        }
+        const undocumented = this.getUndocumented();
+        if (undocumented.length > 0) {
+            lines.push("## Undocumented Components");
+            lines.push("");
+            for (const c of undocumented) {
+                lines.push(`- **${c.name}** (${c.id}) — ${c.category}, criticality: ${c.criticality}`);
+            }
+            lines.push("");
+        }
+        const manualRestarts = this.getManualRestarts();
+        if (manualRestarts.length > 0) {
+            lines.push("## Manual Restart Required");
+            lines.push("");
+            for (const c of manualRestarts) {
+                lines.push(`- **${c.name}** (${c.id}) — operators: ${c.operators.join(", ")}`);
+            }
+            lines.push("");
+        }
+        if (report.recommendations.length > 0) {
+            lines.push("## Recommendations");
+            lines.push("");
+            for (const rec of report.recommendations) {
+                lines.push(`- ${rec}`);
+            }
+            lines.push("");
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Compute an overall resilience score from 0 (fragile) to 1 (robust).
+     * Weights each component by criticality, penalizes low bus factor
+     * and poor documentation.
+     */
+    computeOverallScore(components) {
+        if (components.length === 0)
+            return 1;
+        let totalWeight = 0;
+        let weightedScore = 0;
+        for (const c of components) {
+            const weight = CRITICALITY_WEIGHTS[c.criticality];
+            totalWeight += weight;
+            // Bus factor score: 0 ops = 0, 1 = 0.2, 2 = 0.6, 3+ = 1.0
+            const ops = c.operators.length;
+            const busScore = ops === 0 ? 0 : ops === 1 ? 0.2 : ops === 2 ? 0.6 : 1.0;
+            // Documentation score
+            const docScore = DOC_SCORES[c.documentation_level];
+            // Restart automation score
+            const restartScore = c.restart_method === "automatic" ? 1.0 :
+                c.restart_method === "manual" ? 0.3 :
+                    0.1;
+            // Component resilience is weighted average of factors
+            const componentScore = busScore * 0.5 + docScore * 0.3 + restartScore * 0.2;
+            weightedScore += componentScore * weight;
+        }
+        return Math.round((weightedScore / totalWeight) * 1000) / 1000;
+    }
+    /** Build actionable recommendations from the analysis. */
+    buildRecommendations(all, spofs) {
+        const recs = [];
+        const criticalSpofs = spofs.filter((c) => c.criticality === "critical");
+        if (criticalSpofs.length > 0) {
+            recs.push(`URGENT: ${criticalSpofs.length} critical component(s) have bus factor of 1. ` +
+                `Cross-train immediately: ${criticalSpofs.map((c) => c.name).join(", ")}.`);
+        }
+        const highSpofs = spofs.filter((c) => c.criticality === "high");
+        if (highSpofs.length > 0) {
+            recs.push(`HIGH: ${highSpofs.length} high-criticality SPOF(s) need additional operators: ` +
+                `${highSpofs.map((c) => c.name).join(", ")}.`);
+        }
+        const undocumented = all.filter((c) => c.documentation_level === "none");
+        if (undocumented.length > 0) {
+            recs.push(`Document ${undocumented.length} component(s) with no documentation: ` +
+                `${undocumented.map((c) => c.name).join(", ")}.`);
+        }
+        const manualCritical = all.filter((c) => c.restart_method === "manual" && (c.criticality === "critical" || c.criticality === "high"));
+        if (manualCritical.length > 0) {
+            recs.push(`Automate restart for ${manualCritical.length} high/critical component(s) ` +
+                `still requiring manual intervention: ${manualCritical.map((c) => c.name).join(", ")}.`);
+        }
+        const unknownRestart = all.filter((c) => c.restart_method === "unknown");
+        if (unknownRestart.length > 0) {
+            recs.push(`Determine restart method for ${unknownRestart.length} component(s) with unknown procedures: ` +
+                `${unknownRestart.map((c) => c.name).join(", ")}.`);
+        }
+        const stale = all.filter((c) => {
+            if (!c.last_verified)
+                return true;
+            const verified = new Date(c.last_verified).getTime();
+            const ninetyDays = 90 * 24 * 60 * 60 * 1000;
+            return Date.now() - verified > ninetyDays;
+        });
+        if (stale.length > 0) {
+            recs.push(`Verify ${stale.length} component(s) not checked in 90+ days or never verified.`);
+        }
+        return recs;
+    }
+    /** Generate remediation advice for a single SPOF. */
+    remediationFor(component) {
+        const steps = [];
+        const operator = component.operators[0] ?? "the sole operator";
+        steps.push(`1. Cross-train at least one additional person on ${component.name}.`);
+        if (component.documentation_level === "none" || component.documentation_level === "minimal") {
+            steps.push(`2. Create comprehensive documentation. Current level: ${component.documentation_level}.`);
+        }
+        if (component.restart_method === "manual" || component.restart_method === "unknown") {
+            steps.push(`3. Automate the restart procedure (currently: ${component.restart_method ?? "unknown"}).`);
+        }
+        if (component.category === "credential") {
+            steps.push(`4. Store credentials in a shared vault accessible to the team, not just ${operator}.`);
+        }
+        if (component.category === "knowledge") {
+            steps.push(`4. Record a knowledge transfer session with ${operator}. ` +
+                `This is the most fragile SPOF type — undocumented knowledge disappears instantly.`);
+        }
+        return steps.join("\n");
+    }
+}
+//# sourceMappingURL=resilience.js.map

package/dist/resilience.js.map

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

package/dist/scoring.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Continuous Scoring / Bias-Free Classification — Kusunda No-Gender
+ *
+ * Kusunda has no grammatical gender — it doesn't force nouns into
+ * arbitrary masculine/feminine buckets. This module follows the same
+ * philosophy: no forced binary categories. Everything is a spectrum,
+ * scored across continuous multi-axis dimensions.
+ */
+import type { EvidenceClass } from "./types.js";
+/** A single scoring dimension with weight and value. */
+export interface ScoringAxis {
+    name: string;
+    weight: number;
+    value: number;
+    evidence_class?: EvidenceClass;
+    source?: string;
+}
+/** A multi-axis continuous score for an entity. */
+export interface ContinuousScore {
+    entity_id: string;
+    axes: ScoringAxis[];
+    composite_score: number;
+    confidence: number;
+    assessed_at: string;
+}
+/** Axis-by-axis comparison between two scored entities. */
+export interface AxisComparison {
+    axis: string;
+    entity_a_value: number;
+    entity_b_value: number;
+    delta: number;
+}
+/** Result of comparing two entities. */
+export interface ComparisonResult {
+    entity_a: string;
+    entity_b: string;
+    comparisons: AxisComparison[];
+    composite_delta: number;
+}
+/** A cluster of similar entities. */
+export interface Cluster {
+    centroid: number;
+    members: ContinuousScore[];
+}
+/**
+ * Scores entities across user-defined continuous axes.
+ * No forced categories — only weighted spectra.
+ */
+export declare class ScoringEngine {
+    private axisDefinitions;
+    private scores;
+    /** Define the scoring axes. Weights are normalized internally. */
+    defineAxes(axes: Array<{
+        name: string;
+        weight: number;
+    }>): void;
+    /**
+     * Score an entity across the defined axes.
+     * Values should be keyed by axis name, each in range 0-1.
+     */
+    score(entityId: string, values: Record<string, number>): ContinuousScore;
+    /** Compare two previously scored entities axis by axis. */
+    compare(entityA: string, entityB: string): ComparisonResult;
+    /** Rank entities by composite score, highest first. */
+    rank(entities: ContinuousScore[]): ContinuousScore[];
+    /**
+     * Simple k-means clustering by composite score.
+     * Groups entities into k clusters based on score similarity.
+     */
+    cluster(entities: ContinuousScore[], k: number): Cluster[];
+    /**
+     * Identify entities whose composite score deviates significantly
+     * from the mean. Default threshold: 1.5 standard deviations.
+     */
+    getOutliers(entities: ContinuousScore[], threshold?: number): ContinuousScore[];
+    /**
+     * Compute the weighted composite score.
+     * Uses normalized weights so they sum to 1.
+     */
+    private computeComposite;
+    /**
+     * Estimate confidence based on how many axes have explicit values.
+     * Missing axes (defaulting to 0) reduce confidence.
+     */
+    private computeConfidence;
+}
+//# sourceMappingURL=scoring.d.ts.map

package/dist/scoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoring.d.ts","sourceRoot":"","sources":["../src/scoring.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,qCAAqC;AACrC,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,eAAe,CAA+C;IACtE,OAAO,CAAC,MAAM,CAA2C;IAEzD,kEAAkE;IAClE,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI;IAO/D;;;OAGG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,eAAe;IA0BxE,2DAA2D;IAC3D,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB;IA0B3D,uDAAuD;IACvD,IAAI,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE;IAIpD;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,eAAe,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE;IAsE1D;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,eAAe,EAAE,EAAE,SAAS,SAAM,GAAG,eAAe,EAAE;IAiB5E;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAOxB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;CAqB1B"}

package/dist/scoring.js

@@ -0,0 +1,202 @@
+/**
+ * Continuous Scoring / Bias-Free Classification — Kusunda No-Gender
+ *
+ * Kusunda has no grammatical gender — it doesn't force nouns into
+ * arbitrary masculine/feminine buckets. This module follows the same
+ * philosophy: no forced binary categories. Everything is a spectrum,
+ * scored across continuous multi-axis dimensions.
+ */
+/**
+ * Scores entities across user-defined continuous axes.
+ * No forced categories — only weighted spectra.
+ */
+export class ScoringEngine {
+    axisDefinitions = [];
+    scores = new Map();
+    /** Define the scoring axes. Weights are normalized internally. */
+    defineAxes(axes) {
+        this.axisDefinitions = axes.map((a) => ({
+            name: a.name,
+            weight: clamp(a.weight, 0, 1),
+        }));
+    }
+    /**
+     * Score an entity across the defined axes.
+     * Values should be keyed by axis name, each in range 0-1.
+     */
+    score(entityId, values) {
+        if (this.axisDefinitions.length === 0) {
+            throw new Error("No axes defined. Call defineAxes() first.");
+        }
+        const axes = this.axisDefinitions.map((def) => ({
+            name: def.name,
+            weight: def.weight,
+            value: clamp(values[def.name] ?? 0, 0, 1),
+        }));
+        const composite = this.computeComposite(axes);
+        const confidence = this.computeConfidence(axes, values);
+        const result = {
+            entity_id: entityId,
+            axes,
+            composite_score: round4(composite),
+            confidence: round4(confidence),
+            assessed_at: new Date().toISOString(),
+        };
+        this.scores.set(entityId, result);
+        return result;
+    }
+    /** Compare two previously scored entities axis by axis. */
+    compare(entityA, entityB) {
+        const a = this.scores.get(entityA);
+        const b = this.scores.get(entityB);
+        if (!a)
+            throw new Error(`Entity "${entityA}" has not been scored.`);
+        if (!b)
+            throw new Error(`Entity "${entityB}" has not been scored.`);
+        const comparisons = a.axes.map((axisA) => {
+            const axisB = b.axes.find((ab) => ab.name === axisA.name);
+            const bVal = axisB?.value ?? 0;
+            return {
+                axis: axisA.name,
+                entity_a_value: axisA.value,
+                entity_b_value: bVal,
+                delta: round4(axisA.value - bVal),
+            };
+        });
+        return {
+            entity_a: entityA,
+            entity_b: entityB,
+            comparisons,
+            composite_delta: round4(a.composite_score - b.composite_score),
+        };
+    }
+    /** Rank entities by composite score, highest first. */
+    rank(entities) {
+        return [...entities].sort((a, b) => b.composite_score - a.composite_score);
+    }
+    /**
+     * Simple k-means clustering by composite score.
+     * Groups entities into k clusters based on score similarity.
+     */
+    cluster(entities, k) {
+        if (entities.length === 0)
+            return [];
+        if (k <= 0)
+            throw new Error("k must be positive.");
+        if (k >= entities.length) {
+            // Each entity is its own cluster
+            return entities.map((e) => ({
+                centroid: e.composite_score,
+                members: [e],
+            }));
+        }
+        // Initialize centroids evenly spaced
+        let centroids = [];
+        for (let i = 0; i < k; i++) {
+            centroids.push((i + 0.5) / k);
+        }
+        const maxIterations = 50;
+        let assignments = new Array(entities.length).fill(0);
+        for (let iter = 0; iter < maxIterations; iter++) {
+            // Assign each entity to nearest centroid
+            const newAssignments = entities.map((e) => {
+                let bestIdx = 0;
+                let bestDist = Infinity;
+                for (let c = 0; c < centroids.length; c++) {
+                    const dist = Math.abs(e.composite_score - centroids[c]);
+                    if (dist < bestDist) {
+                        bestDist = dist;
+                        bestIdx = c;
+                    }
+                }
+                return bestIdx;
+            });
+            // Check convergence
+            const converged = newAssignments.every((a, i) => a === assignments[i]);
+            assignments = newAssignments;
+            // Update centroids
+            const newCentroids = centroids.map((_, c) => {
+                const members = entities.filter((_, i) => assignments[i] === c);
+                if (members.length === 0)
+                    return centroids[c];
+                return members.reduce((sum, m) => sum + m.composite_score, 0) / members.length;
+            });
+            centroids = newCentroids;
+            if (converged)
+                break;
+        }
+        // Build cluster results
+        const clusterMap = new Map();
+        for (let i = 0; i < entities.length; i++) {
+            const c = assignments[i];
+            if (!clusterMap.has(c))
+                clusterMap.set(c, []);
+            clusterMap.get(c).push(entities[i]);
+        }
+        const results = [];
+        for (const [c, members] of clusterMap) {
+            results.push({
+                centroid: round4(centroids[c]),
+                members,
+            });
+        }
+        return results.sort((a, b) => b.centroid - a.centroid);
+    }
+    /**
+     * Identify entities whose composite score deviates significantly
+     * from the mean. Default threshold: 1.5 standard deviations.
+     */
+    getOutliers(entities, threshold = 1.5) {
+        if (entities.length < 2)
+            return [];
+        const scores = entities.map((e) => e.composite_score);
+        const mean = scores.reduce((a, b) => a + b, 0) / scores.length;
+        const variance = scores.reduce((sum, s) => sum + (s - mean) ** 2, 0) / scores.length;
+        const stddev = Math.sqrt(variance);
+        if (stddev === 0)
+            return [];
+        return entities.filter((e) => {
+            const zScore = Math.abs(e.composite_score - mean) / stddev;
+            return zScore > threshold;
+        });
+    }
+    /**
+     * Compute the weighted composite score.
+     * Uses normalized weights so they sum to 1.
+     */
+    computeComposite(axes) {
+        const totalWeight = axes.reduce((sum, a) => sum + a.weight, 0);
+        if (totalWeight === 0)
+            return 0;
+        return axes.reduce((sum, a) => sum + (a.value * a.weight) / totalWeight, 0);
+    }
+    /**
+     * Estimate confidence based on how many axes have explicit values.
+     * Missing axes (defaulting to 0) reduce confidence.
+     */
+    computeConfidence(axes, providedValues) {
+        if (axes.length === 0)
+            return 0;
+        let provided = 0;
+        for (const axis of axes) {
+            if (axis.name in providedValues) {
+                provided++;
+            }
+        }
+        // Base confidence from coverage
+        const coverage = provided / axes.length;
+        // Penalize heavily if fewer than half the axes are provided
+        if (coverage < 0.5)
+            return coverage * 0.6;
+        return 0.3 + coverage * 0.7;
+    }
+}
+/** Clamp a number between min and max. */
+function clamp(n, min, max) {
+    return Math.max(min, Math.min(max, n));
+}
+/** Round to 4 decimal places. */
+function round4(n) {
+    return Math.round(n * 10000) / 10000;
+}
+//# sourceMappingURL=scoring.js.map

package/dist/scoring.js.map

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

package/dist/self-describing.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Self-Describing Payloads — Kusunda Verb Morphology
+ *
+ * In Kusunda, verbs carry so much morphological information that
+ * a single verb can function as a complete sentence. Every payload
+ * in this module carries everything needed to understand it:
+ * who produced it, what schema it follows, what permissions it
+ * requires, and when it expires.
+ */
+import type { EvidenceClass } from "./types.js";
+/** Metadata envelope for a self-describing payload. */
+export interface PayloadMeta {
+    producer: string;
+    tool: string;
+    schema_id: string;
+    version: string;
+    permissions_required: string[];
+    evidence_class: EvidenceClass;
+    timestamp: string;
+    ttl?: number;
+}
+/** A payload that carries its own context — no external lookup needed. */
+export interface SelfDescribingPayload<T> {
+    meta: PayloadMeta;
+    data: T;
+    description: string;
+    validate?: () => boolean;
+}
+/**
+ * Fluent builder for constructing self-describing payloads.
+ * Enforces that required fields are set before building.
+ */
+export declare class PayloadBuilder {
+    private producer;
+    private tool;
+    private schemaId;
+    private version;
+    private permissions;
+    private evidenceClass;
+    private desc;
+    private ttl;
+    constructor(producer: string, tool: string);
+    /** Set the schema identifier and version. */
+    setSchema(schemaId: string, version: string): PayloadBuilder;
+    /** Declare permissions required to consume this payload. */
+    setPermissions(perms: string[]): PayloadBuilder;
+    /** Set the evidence class for this payload's data. */
+    setEvidence(cls: EvidenceClass): PayloadBuilder;
+    /** Set a human-readable description of what this payload contains. */
+    setDescription(desc: string): PayloadBuilder;
+    /** Set the time-to-live in seconds. After expiry the payload is stale. */
+    setTtl(seconds: number): PayloadBuilder;
+    /**
+     * Build the self-describing payload.
+     * Attaches a validate function that checks required fields at runtime.
+     */
+    build<T>(data: T): SelfDescribingPayload<T>;
+}
+/**
+ * Check whether a payload has expired based on its TTL.
+ * Returns false if no TTL is set (never expires).
+ */
+export declare function isExpired(payload: SelfDescribingPayload<unknown>): boolean;
+/** Generate a human-readable summary of a payload. */
+export declare function describe(payload: SelfDescribingPayload<unknown>): string;
+/**
+ * Validate that a payload has all required fields populated.
+ * Returns true if valid, false if any required field is missing or empty.
+ */
+export declare function validate(payload: SelfDescribingPayload<unknown>): boolean;
+//# sourceMappingURL=self-describing.d.ts.map

package/dist/self-describing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-describing.d.ts","sourceRoot":"","sources":["../src/self-describing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,cAAc,EAAE,aAAa,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,CAAC,CAAC;IACR,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,OAAO,CAAM;IACrB,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,IAAI,CAAM;IAClB,OAAO,CAAC,GAAG,CAAqB;gBAEpB,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAK1C,6CAA6C;IAC7C,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc;IAM5D,4DAA4D;IAC5D,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,cAAc;IAK/C,sDAAsD;IACtD,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,cAAc;IAK/C,sEAAsE;IACtE,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc;IAK5C,0EAA0E;IAC1E,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc;IAKvC;;;OAGG;IACH,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,qBAAqB,CAAC,CAAC,CAAC;CAqB5C;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,qBAAqB,CAAC,OAAO,CAAC,GAAG,OAAO,CAQ1E;AAED,sDAAsD;AACtD,wBAAgB,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC,OAAO,CAAC,GAAG,MAAM,CA0BxE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC,OAAO,CAAC,GAAG,OAAO,CAEzE"}