@mnemom/agent-alignment-protocol 0.5.0 → 0.6.1

package/dist/index.mjs

@@ -655,6 +655,297 @@ function detectDrift(card, traces, similarityThreshold = DEFAULT_SIMILARITY_THRE
   }
   return alerts;
 }
+function deterministicHex(input, length) {
+  let hash = 0;
+  for (let i = 0; i < input.length; i++) {
+    const char = input.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash).toString(16).padStart(length, "0").slice(0, length);
+}
+function jaccardSimilarity(a, b) {
+  const setA = new Set(a);
+  const setB = new Set(b);
+  const intersection = [...setA].filter((x) => setB.has(x)).length;
+  const union = (/* @__PURE__ */ new Set([...setA, ...setB])).size;
+  return union === 0 ? 0 : intersection / union;
+}
+var ROLE_KEYWORDS = [
+  "safety",
+  "executive",
+  "cfo",
+  "analyst",
+  "compliance",
+  "legal",
+  "risk",
+  "finance",
+  "security",
+  "ethics",
+  "audit",
+  "ops",
+  "operations"
+];
+function hasRoleKeyword(agentId) {
+  const lower = agentId.toLowerCase();
+  return ROLE_KEYWORDS.some((kw) => lower.includes(kw));
+}
+function getClpiRole(card) {
+  const ext = card.extensions;
+  if (!ext) return null;
+  const clpi = ext["clpi"];
+  if (!clpi || typeof clpi["role"] !== "string") return null;
+  return clpi["role"] || null;
+}
+function analyzeFaultLines(coherenceResult, cards, options) {
+  const reputationScores = options?.reputationScores;
+  const agentBoundedActions = /* @__PURE__ */ new Map();
+  for (const { agentId, card } of cards) {
+    agentBoundedActions.set(agentId, card.autonomy_envelope?.bounded_actions ?? []);
+  }
+  const agentConflictMap = /* @__PURE__ */ new Map();
+  for (const { agentId, card } of cards) {
+    agentConflictMap.set(agentId, new Set(card.values.conflicts_with ?? []));
+  }
+  const agentRoleMap = /* @__PURE__ */ new Map();
+  for (const { agentId, card } of cards) {
+    agentRoleMap.set(agentId, getClpiRole(card));
+  }
+  const faultLines = [];
+  for (const divergence of coherenceResult.divergence_report) {
+    const {
+      value,
+      agents_declaring,
+      agents_missing,
+      agents_conflicting,
+      impact_on_fleet_score
+    } = divergence;
+    const involvedAgents = [
+      .../* @__PURE__ */ new Set([...agents_declaring, ...agents_missing, ...agents_conflicting])
+    ];
+    let classification;
+    if (agents_conflicting.length > 0) {
+      classification = "incompatible";
+    } else if (agents_declaring.length >= 2 && (() => {
+      for (let i = 0; i < agents_declaring.length; i++) {
+        for (let j = i + 1; j < agents_declaring.length; j++) {
+          const idA = agents_declaring[i];
+          const idB = agents_declaring[j];
+          const entry = coherenceResult.pairwise_matrix.find(
+            (p) => p.agent_a === idA && p.agent_b === idB || p.agent_a === idB && p.agent_b === idA
+          );
+          if (entry && entry.result.score < 0.5) {
+            return true;
+          }
+        }
+      }
+      return false;
+    })()) {
+      classification = "priority_mismatch";
+    } else if (agents_declaring.length >= 1 && agents_missing.length >= 1 && (() => {
+      const declaringRoles = new Set(agents_declaring.map((id2) => agentRoleMap.get(id2) ?? null).filter(Boolean));
+      const missingRoles = new Set(agents_missing.map((id2) => agentRoleMap.get(id2) ?? null).filter(Boolean));
+      if (declaringRoles.size > 0) {
+        const declaringRoleArr = [...declaringRoles];
+        const isRoleExclusive = declaringRoleArr.every((role) => !missingRoles.has(role));
+        if (isRoleExclusive) return true;
+      }
+      const allInvolved = [...agents_declaring, ...agents_missing];
+      return allInvolved.some((id2) => hasRoleKeyword(id2));
+    })()) {
+      classification = "complementary";
+    } else {
+      classification = "resolvable";
+    }
+    let coordinationOverlap;
+    if (involvedAgents.length < 2) {
+      coordinationOverlap = 0.5;
+    } else {
+      const actionSets = involvedAgents.map((id2) => agentBoundedActions.get(id2) ?? []);
+      const nonEmpty = actionSets.filter((s) => s.length > 0);
+      if (nonEmpty.length < 2) {
+        coordinationOverlap = 0.5;
+      } else {
+        let total = 0;
+        let count = 0;
+        for (let i = 0; i < nonEmpty.length; i++) {
+          for (let j = i + 1; j < nonEmpty.length; j++) {
+            total += jaccardSimilarity(nonEmpty[i], nonEmpty[j]);
+            count++;
+          }
+        }
+        coordinationOverlap = count > 0 ? total / count : 0.5;
+      }
+    }
+    let impactScore = impact_on_fleet_score * coordinationOverlap;
+    if (reputationScores && involvedAgents.length > 0) {
+      const repValues = involvedAgents.map((id2) => (reputationScores[id2] ?? 500) / 1e3).map((r) => Math.max(1e-3, r));
+      const logSum = repValues.reduce((sum, r) => sum + Math.log(r), 0);
+      const geoMean = Math.exp(logSum / repValues.length);
+      impactScore *= geoMean;
+    }
+    impactScore = Math.min(1, Math.max(0, impactScore));
+    let severity;
+    if (impactScore >= 0.7) {
+      severity = "critical";
+    } else if (impactScore >= 0.4) {
+      severity = "high";
+    } else if (impactScore >= 0.2) {
+      severity = "medium";
+    } else {
+      severity = "low";
+    }
+    let resolutionHint;
+    switch (classification) {
+      case "resolvable":
+        resolutionHint = `Add value '${value}' to ${agents_missing.join(", ")} alignment card(s).`;
+        break;
+      case "priority_mismatch":
+        resolutionHint = `Align priority/definition of '${value}' across all declaring agents.`;
+        break;
+      case "incompatible":
+        resolutionHint = `Value '${value}' conflicts with ${agents_conflicting.join(", ")}. Requires human review.`;
+        break;
+      case "complementary":
+        resolutionHint = `Value '${value}' divergence appears intentional given agent specializations.`;
+        break;
+    }
+    let affectsCapabilities = [];
+    if (involvedAgents.length > 0) {
+      const firstActions = agentBoundedActions.get(involvedAgents[0]) ?? [];
+      affectsCapabilities = firstActions.filter(
+        (action) => involvedAgents.every((id2) => (agentBoundedActions.get(id2) ?? []).includes(action))
+      );
+    }
+    const idInput = [value, ...involvedAgents.sort()].join("|");
+    const id = deterministicHex(idInput, 12);
+    faultLines.push({
+      id,
+      value,
+      classification,
+      severity,
+      agents_declaring,
+      agents_missing,
+      agents_conflicting,
+      impact_score: Math.round(impactScore * 1e4) / 1e4,
+      resolution_hint: resolutionHint,
+      affects_capabilities: affectsCapabilities
+    });
+  }
+  const severityOrder = {
+    critical: 0,
+    high: 1,
+    medium: 2,
+    low: 3
+  };
+  faultLines.sort((a, b) => {
+    const sev = severityOrder[a.severity] - severityOrder[b.severity];
+    if (sev !== 0) return sev;
+    return b.impact_score - a.impact_score;
+  });
+  const alignments = [];
+  const grouped = /* @__PURE__ */ new Map();
+  const groupAssignment = /* @__PURE__ */ new Map();
+  let nextGroupId = 0;
+  for (let i = 0; i < faultLines.length; i++) {
+    for (let j = i + 1; j < faultLines.length; j++) {
+      const sim = jaccardSimilarity(faultLines[i].agents_missing, faultLines[j].agents_missing);
+      if (sim > 0.6) {
+        const gi = groupAssignment.get(i);
+        const gj = groupAssignment.get(j);
+        if (gi === void 0 && gj === void 0) {
+          const gid = nextGroupId++;
+          grouped.set(gid, [i, j]);
+          groupAssignment.set(i, gid);
+          groupAssignment.set(j, gid);
+        } else if (gi !== void 0 && gj === void 0) {
+          grouped.get(gi).push(j);
+          groupAssignment.set(j, gi);
+        } else if (gi === void 0 && gj !== void 0) {
+          grouped.get(gj).push(i);
+          groupAssignment.set(i, gj);
+        } else if (gi !== gj) {
+          const smaller = gi < gj ? gj : gi;
+          const larger = gi < gj ? gi : gj;
+          const smallerMembers = grouped.get(smaller) ?? [];
+          const largerMembers = grouped.get(larger) ?? [];
+          const merged = [.../* @__PURE__ */ new Set([...largerMembers, ...smallerMembers])];
+          grouped.set(larger, merged);
+          grouped.delete(smaller);
+          for (const idx of smallerMembers) {
+            groupAssignment.set(idx, larger);
+          }
+        }
+      }
+    }
+  }
+  for (const [, members] of grouped) {
+    if (members.length < 2) continue;
+    const unique = [...new Set(members)];
+    const groupFaultLines = unique.map((i) => faultLines[i]);
+    const minorityAgents = [
+      ...new Set(groupFaultLines.flatMap((fl) => fl.agents_missing))
+    ];
+    const majorityAgents = [
+      ...new Set(groupFaultLines.flatMap((fl) => fl.agents_declaring))
+    ];
+    let jaccardSum = 0;
+    let jaccardCount = 0;
+    for (let i = 0; i < unique.length; i++) {
+      for (let j = i + 1; j < unique.length; j++) {
+        jaccardSum += jaccardSimilarity(
+          groupFaultLines[i].agents_missing,
+          groupFaultLines[j].agents_missing
+        );
+        jaccardCount++;
+      }
+    }
+    const alignmentScore = jaccardCount > 0 ? jaccardSum / jaccardCount : 0;
+    const hasHigherSeverity = groupFaultLines.some(
+      (fl) => fl.severity === "critical" || fl.severity === "high"
+    );
+    let severity = unique.length >= 3 ? "high" : "medium";
+    if (hasHigherSeverity && severity === "medium") {
+      severity = "high";
+    }
+    const sortedFaultLineIds = groupFaultLines.map((fl) => fl.id).sort();
+    const alignmentId = deterministicHex(sortedFaultLineIds.join("|"), 12);
+    alignments.push({
+      id: alignmentId,
+      fault_line_ids: sortedFaultLineIds,
+      minority_agents: minorityAgents,
+      majority_agents: majorityAgents,
+      alignment_score: Math.round(alignmentScore * 1e4) / 1e4,
+      severity,
+      description: `${groupFaultLines.length} fault lines consistently isolate ${minorityAgents.join(", ")} from the team`
+    });
+  }
+  const summary = {
+    total: faultLines.length,
+    resolvable: faultLines.filter((fl) => fl.classification === "resolvable").length,
+    priority_mismatch: faultLines.filter((fl) => fl.classification === "priority_mismatch").length,
+    incompatible: faultLines.filter((fl) => fl.classification === "incompatible").length,
+    complementary: faultLines.filter((fl) => fl.classification === "complementary").length,
+    critical_count: faultLines.filter((fl) => fl.severity === "critical").length
+  };
+  const analysisIdInput = [
+    String(coherenceResult.fleet_score),
+    ...faultLines.map((fl) => fl.id).sort()
+  ].join("|");
+  const analysisId = deterministicHex(analysisIdInput, 16);
+  return {
+    analysis_id: analysisId,
+    fleet_score: coherenceResult.fleet_score,
+    fault_lines: faultLines,
+    alignments,
+    summary
+  };
+}
+function checkFleetFaultLines(cards, options) {
+  const coherence = checkFleetCoherence(cards);
+  const analysis = analyzeFaultLines(coherence, cards, options);
+  return { coherence, analysis };
+}
 function evaluateCondition(condition, trace) {
   if (!condition) {
     return false;
@@ -665,7 +956,7 @@ function evaluateCondition(condition, trace) {
     const actual = trace.action.type ?? "";
     return actual === expected;
   }
-  const numericMatch = condition.match(/(\w+)\s*([><=!]+)\s*(\d+(?:\.\d+)?)/);
+  const numericMatch = condition.match(/^\s*(\w+)\s*([><=!]+)\s*(\d+(?:\.\d+)?)\s*$/);
   if (numericMatch) {
     const [, field, op, valueStr] = numericMatch;
     const value = parseFloat(valueStr);
@@ -830,8 +1121,10 @@ export {
   NEAR_BOUNDARY_THRESHOLD,
   OUTLIER_STD_DEV_THRESHOLD,
   VIOLATION_SEVERITY,
+  analyzeFaultLines,
   checkCoherence,
   checkFleetCoherence,
+  checkFleetFaultLines,
   computeCentroid,
   cosineSimilarity,
   createViolation,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/agent-alignment-protocol",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Agent Alignment Protocol (AAP) - Verification and drift detection for AI agents",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -23,7 +23,6 @@
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "test": "vitest run",
     "test:watch": "vitest",
-
     "typecheck": "tsc --noEmit"
   },
   "keywords": [
@@ -47,7 +46,7 @@
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-
+    "@vitest/coverage-v8": "^1.6.1",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
     "vitest": "^1.0.0"
@@ -55,4 +54,4 @@
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}

package/src/index.ts

@@ -35,7 +35,7 @@
  */
 
 // Main API exports
-export { verifyTrace, checkCoherence, checkFleetCoherence, detectDrift } from "./verification/api";
+export { verifyTrace, checkCoherence, checkFleetCoherence, detectDrift, analyzeFaultLines, checkFleetFaultLines } from "./verification/api";
 
 // Schema types
 export type {
@@ -114,6 +114,12 @@ export type {
   FleetCluster,
   ValueDivergence,
   AgentCoherenceSummary,
+  // Fault Line Analysis (E-06)
+  FaultLineClassification,
+  FaultLine,
+  FaultLineSummary,
+  FaultLineAlignment,
+  FaultLineAnalysis,
 } from "./verification/models";
 
 // Utility exports