evidential-protocol 1.0.0

package/dist/validate.js

@@ -0,0 +1,184 @@
+/**
+ * EP-1 Validation — enforces protocol rules on evidential responses.
+ */
+import { CONFIDENCE_FLOORS, CLASS_STRENGTH, } from "./types.js";
+/** Validate a single Evidence object. */
+export function validateEvidence(evidence, path = "evidence") {
+    const errors = [];
+    // Class must be valid
+    if (!CONFIDENCE_FLOORS[evidence.class]) {
+        errors.push({
+            rule: "valid-class",
+            message: `Invalid evidence class: "${evidence.class}"`,
+            path,
+            severity: "error",
+        });
+        return errors;
+    }
+    // Confidence must meet class floor
+    const floor = CONFIDENCE_FLOORS[evidence.class];
+    if (evidence.confidence < floor) {
+        errors.push({
+            rule: "confidence-floor",
+            message: `Confidence ${evidence.confidence} below floor ${floor} for class "${evidence.class}"`,
+            path: `${path}.confidence`,
+            severity: "error",
+        });
+    }
+    // Confidence must be 0.0–1.0
+    if (evidence.confidence < 0 || evidence.confidence > 1) {
+        errors.push({
+            rule: "confidence-range",
+            message: `Confidence must be 0.0–1.0, got ${evidence.confidence}`,
+            path: `${path}.confidence`,
+            severity: "error",
+        });
+    }
+    // Source is required
+    if (!evidence.source || evidence.source.trim() === "") {
+        errors.push({
+            rule: "source-required",
+            message: "Evidence must have a source",
+            path: `${path}.source`,
+            severity: "error",
+        });
+    }
+    // Timestamp is required
+    if (!evidence.timestamp) {
+        errors.push({
+            rule: "timestamp-required",
+            message: "Evidence must have a timestamp",
+            path: `${path}.timestamp`,
+            severity: "error",
+        });
+    }
+    // Conjecture MUST have reasoning
+    if (evidence.class === "conjecture" && !evidence.reasoning) {
+        errors.push({
+            rule: "conjecture-reasoning",
+            message: "Conjecture class requires a reasoning field",
+            path: `${path}.reasoning`,
+            severity: "error",
+        });
+    }
+    // Direct evidence SHOULD have TTL
+    if (evidence.class === "direct" && !evidence.ttl) {
+        errors.push({
+            rule: "direct-ttl",
+            message: "Direct evidence should include TTL for degradation tracking",
+            path: `${path}.ttl`,
+            severity: "warning",
+        });
+    }
+    return errors;
+}
+/** Validate a single EvidentialClaim. */
+export function validateClaim(claim, index) {
+    const errors = [];
+    const path = `claims[${index}]`;
+    if (!claim.claim || claim.claim.trim() === "") {
+        errors.push({
+            rule: "claim-text-required",
+            message: "Claim must have text",
+            path: `${path}.claim`,
+            severity: "error",
+        });
+    }
+    if (!claim.evidence) {
+        errors.push({
+            rule: "evidence-required",
+            message: "Every claim must have an evidence object",
+            path: `${path}.evidence`,
+            severity: "error",
+        });
+        return errors;
+    }
+    errors.push(...validateEvidence(claim.evidence, `${path}.evidence`));
+    return errors;
+}
+/** Validate a full EvidentialResponse. */
+export function validateResponse(response) {
+    const all = [];
+    // Must have ep_version
+    if (response.ep_version !== "1.0") {
+        all.push({
+            rule: "version",
+            message: `Unsupported protocol version: "${response.ep_version}"`,
+            severity: "error",
+        });
+    }
+    // Must have producer
+    if (!response.producer || response.producer.trim() === "") {
+        all.push({
+            rule: "producer-required",
+            message: "Response must identify its producer",
+            path: "producer",
+            severity: "error",
+        });
+    }
+    // Must have at least one claim
+    if (!response.claims || response.claims.length === 0) {
+        all.push({
+            rule: "claims-required",
+            message: "Response must contain at least one claim",
+            path: "claims",
+            severity: "error",
+        });
+    }
+    else {
+        // Validate each claim
+        for (let i = 0; i < response.claims.length; i++) {
+            all.push(...validateClaim(response.claims[i], i));
+        }
+        // Verify aggregate_class is the lowest class
+        const lowestStrength = Math.min(...response.claims.map((c) => CLASS_STRENGTH[c.evidence.class]));
+        const expectedClass = Object.entries(CLASS_STRENGTH).find(([, v]) => v === lowestStrength)?.[0];
+        if (expectedClass && response.aggregate_class !== expectedClass) {
+            all.push({
+                rule: "aggregate-class-consistency",
+                message: `Aggregate class should be "${expectedClass}" (lowest), got "${response.aggregate_class}"`,
+                path: "aggregate_class",
+                severity: "error",
+            });
+        }
+    }
+    // Must have produced_at
+    if (!response.produced_at) {
+        all.push({
+            rule: "produced-at-required",
+            message: "Response must have produced_at timestamp",
+            path: "produced_at",
+            severity: "error",
+        });
+    }
+    const errors = all.filter((e) => e.severity === "error");
+    const warnings = all.filter((e) => e.severity === "warning");
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+/** Validate an MCP evidence tag. */
+export function validateMcpTag(tag) {
+    const all = [];
+    if (tag.ep_version !== "1.0") {
+        all.push({
+            rule: "version",
+            message: `Unsupported version: "${tag.ep_version}"`,
+            severity: "error",
+        });
+    }
+    all.push(...validateEvidence({
+        class: tag.class,
+        confidence: tag.confidence,
+        source: tag.source,
+        timestamp: tag.timestamp,
+        ttl: tag.ttl,
+        reasoning: tag.reasoning,
+    }, "_evidence"));
+    const errors = all.filter((e) => e.severity === "error");
+    const warnings = all.filter((e) => e.severity === "warning");
+    return { valid: errors.length === 0, errors, warnings };
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAKL,iBAAiB,EACjB,cAAc,GACf,MAAM,YAAY,CAAC;AAiBpB,yCAAyC;AACzC,MAAM,UAAU,gBAAgB,CAC9B,QAAkB,EAClB,IAAI,GAAG,UAAU;IAEjB,MAAM,MAAM,GAAsB,EAAE,CAAC;IAErC,sBAAsB;IACtB,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,aAAa;YACnB,OAAO,EAAE,4BAA4B,QAAQ,CAAC,KAAK,GAAG;YACtD,IAAI;YACJ,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,mCAAmC;IACnC,MAAM,KAAK,GAAG,iBAAiB,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAChD,IAAI,QAAQ,CAAC,UAAU,GAAG,KAAK,EAAE,CAAC;QAChC,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,kBAAkB;YACxB,OAAO,EAAE,cAAc,QAAQ,CAAC,UAAU,gBAAgB,KAAK,eAAe,QAAQ,CAAC,KAAK,GAAG;YAC/F,IAAI,EAAE,GAAG,IAAI,aAAa;YAC1B,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC;IACL,CAAC;IAED,6BAA6B;IAC7B,IAAI,QAAQ,CAAC,UAAU,GAAG,CAAC,IAAI,QAAQ,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;QACvD,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,kBAAkB;YACxB,OAAO,EAAE,mCAAmC,QAAQ,CAAC,UAAU,EAAE;YACjE,IAAI,EAAE,GAAG,IAAI,aAAa;YAC1B,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC;IACL,CAAC;IAED,qBAAqB;IACrB,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACtD,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,iBAAiB;YACvB,OAAO,EAAE,6BAA6B;YACtC,IAAI,EAAE,GAAG,IAAI,SAAS;YACtB,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC;IACL,CAAC;IAED,wBAAwB;IACxB,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,oBAAoB;YAC1B,OAAO,EAAE,gCAAgC;YACzC,IAAI,EAAE,GAAG,IAAI,YAAY;YACzB,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC;IACL,CAAC;IAED,iCAAiC;IACjC,IAAI,QAAQ,CAAC,KAAK,KAAK,YAAY,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;QAC3D,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,sBAAsB;YAC5B,OAAO,EAAE,6CAA6C;YACtD,IAAI,EAAE,GAAG,IAAI,YAAY;YACzB,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC;IACL,CAAC;IAED,kCAAkC;IAClC,IAAI,QAAQ,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC;QACjD,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,YAAY;YAClB,OAAO,EAAE,6DAA6D;YACtE,IAAI,EAAE,GAAG,IAAI,MAAM;YACnB,QAAQ,EAAE,SAAS;SACpB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,aAAa,CAC3B,KAAsB,EACtB,KAAa;IAEb,MAAM,MAAM,GAAsB,EAAE,CAAC;IACrC,MAAM,IAAI,GAAG,UAAU,KAAK,GAAG,CAAC;IAEhC,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC9C,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,qBAAqB;YAC3B,OAAO,EAAE,sBAAsB;YAC/B,IAAI,EAAE,GAAG,IAAI,QAAQ;YACrB,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QACpB,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,mBAAmB;YACzB,OAAO,EAAE,0CAA0C;YACnD,IAAI,EAAE,GAAG,IAAI,WAAW;YACxB,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC;IACrE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,gBAAgB,CAC9B,QAA4B;IAE5B,MAAM,GAAG,GAAsB,EAAE,CAAC;IAElC,uBAAuB;IACvB,IAAI,QAAQ,CAAC,UAAU,KAAK,KAAK,EAAE,CAAC;QAClC,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,kCAAkC,QAAQ,CAAC,UAAU,GAAG;YACjE,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC;IACL,CAAC;IAED,qBAAqB;IACrB,IAAI,CAAC,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC1D,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,mBAAmB;YACzB,OAAO,EAAE,qCAAqC;YAC9C,IAAI,EAAE,UAAU;YAChB,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC;IACL,CAAC;IAED,+BAA+B;IAC/B,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrD,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,iBAAiB;YACvB,OAAO,EAAE,0CAA0C;YACnD,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC;IACL,CAAC;SAAM,CAAC;QACN,sBAAsB;QACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAChD,GAAG,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACpD,CAAC;QAED,6CAA6C;QAC7C,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAC7B,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAChE,CAAC;QACF,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,IAAI,CACvD,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,cAAc,CAChC,EAAE,CAAC,CAAC,CAAC,CAAC;QAEP,IAAI,aAAa,IAAI,QAAQ,CAAC,eAAe,KAAK,aAAa,EAAE,CAAC;YAChE,GAAG,CAAC,IAAI,CAAC;gBACP,IAAI,EAAE,6BAA6B;gBACnC,OAAO,EAAE,8BAA8B,aAAa,oBAAoB,QAAQ,CAAC,eAAe,GAAG;gBACnG,IAAI,EAAE,iBAAiB;gBACvB,QAAQ,EAAE,OAAO;aAClB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,wBAAwB;IACxB,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;QAC1B,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,sBAAsB;YAC5B,OAAO,EAAE,0CAA0C;YACnD,IAAI,EAAE,aAAa;YACnB,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC;IAE7D,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;QAC1B,MAAM;QACN,QAAQ;KACT,CAAC;AACJ,CAAC;AAED,oCAAoC;AACpC,MAAM,UAAU,cAAc,CAAC,GAAmB;IAChD,MAAM,GAAG,GAAsB,EAAE,CAAC;IAElC,IAAI,GAAG,CAAC,UAAU,KAAK,KAAK,EAAE,CAAC;QAC7B,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,yBAAyB,GAAG,CAAC,UAAU,GAAG;YACnD,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC;IACL,CAAC;IAED,GAAG,CAAC,IAAI,CACN,GAAG,gBAAgB,CACjB;QACE,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,GAAG,EAAE,GAAG,CAAC,GAAG;QACZ,SAAS,EAAE,GAAG,CAAC,SAAS;KACzB,EACD,WAAW,CACZ,CACF,CAAC;IAEF,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC;IAE7D,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC1D,CAAC"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "evidential-protocol",
+  "version": "1.0.0",
+  "description": "Matsés-inspired evidential metadata for AI agent outputs. Every claim declares how it knows.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test dist/tests/",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "evidential",
+    "ai-agents",
+    "mcp",
+    "trust",
+    "provenance",
+    "epistemic",
+    "matses"
+  ],
+  "author": "Matthew Karsten <MatthewKarstenConnects@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ExpertVagabond/evidential-protocol.git"
+  },
+  "files": [
+    "dist",
+    "schema"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "import": "./dist/schema.js"
+    },
+    "./validate": {
+      "types": "./dist/validate.d.ts",
+      "import": "./dist/validate.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware.d.ts",
+      "import": "./dist/middleware.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3"
+  }
+}

package/schema/evidential-response.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://psm.dev/schemas/evidential-response.schema.json",
+  "title": "EvidentialResponse",
+  "description": "EP-1 Evidential Protocol response. Every AI agent output must conform to this schema.",
+  "type": "object",
+  "required": ["ep_version", "data", "claims", "aggregate_class", "aggregate_confidence", "producer", "produced_at"],
+  "properties": {
+    "ep_version": {
+      "type": "string",
+      "const": "1.0",
+      "description": "Protocol version."
+    },
+    "data": {
+      "description": "The output payload (any shape)."
+    },
+    "claims": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/EvidentialClaim" },
+      "description": "All claims made in this response."
+    },
+    "aggregate_class": {
+      "$ref": "#/$defs/EvidenceClass",
+      "description": "Lowest evidence class among all claims."
+    },
+    "aggregate_confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Weighted mean confidence across claims."
+    },
+    "producer": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Agent or tool that produced this response."
+    },
+    "produced_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp."
+    }
+  },
+  "$defs": {
+    "EvidenceClass": {
+      "type": "string",
+      "enum": ["direct", "inferred", "reported", "conjecture"]
+    },
+    "EvidenceSource": {
+      "type": "object",
+      "required": ["class", "source", "detail"],
+      "properties": {
+        "class": { "$ref": "#/$defs/EvidenceClass" },
+        "source": { "type": "string", "minLength": 1 },
+        "detail": { "type": "string" },
+        "timestamp": { "type": "string", "format": "date-time" }
+      }
+    },
+    "Evidence": {
+      "type": "object",
+      "required": ["class", "confidence", "source", "timestamp"],
+      "properties": {
+        "class": { "$ref": "#/$defs/EvidenceClass" },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "reasoning": { "type": "string" },
+        "timestamp": { "type": "string", "format": "date-time" },
+        "ttl": { "type": "integer", "minimum": 0 },
+        "sources": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/EvidenceSource" }
+        }
+      },
+      "if": {
+        "properties": { "class": { "const": "conjecture" } }
+      },
+      "then": {
+        "required": ["reasoning"]
+      }
+    },
+    "EvidentialClaim": {
+      "type": "object",
+      "required": ["claim", "evidence"],
+      "properties": {
+        "claim": { "type": "string", "minLength": 1 },
+        "evidence": { "$ref": "#/$defs/Evidence" },
+        "refs": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}