@mnemom/agent-alignment-protocol 0.6.1 → 0.6.2

package/dist/index.d.mts

@@ -40,7 +40,24 @@ interface ValueDefinition {
 }
 /** Value declarations (SPEC Section 4.4). */
 interface Values {
-    /** List of value identifiers */
+    /**
+     * Behavioral and ethical values the agent applies in its decision-making.
+     *
+     * This field is actively monitored by AIP at runtime: every value listed here
+     * is expected to appear in AP-Trace `values_applied` fields when it influences
+     * a decision. Declaring a value the agent never applies produces verification
+     * warnings and degrades trust scoring.
+     *
+     * **Include**: Ethical and behavioral commitments — e.g. `transparency`,
+     * `honesty`, `accuracy`, `safety`, `accountability`, `helpfulness`,
+     * `deliberation_before_action`. These describe HOW the agent reasons.
+     *
+     * **Do not include**: Role capabilities, operational principles, or job-function
+     * descriptors — e.g. `fiduciary_precision`, `organizational_clarity`. These
+     * describe WHAT the agent is in its role and belong in `extensions.clpi.role`
+     * or other `extensions` metadata. Capability names (e.g. `read_documents`)
+     * belong in `autonomy_envelope.bounded_actions`.
+     */
     declared: string[];
     /** Definitions for non-standard values */
     definitions?: Record<string, ValueDefinition> | null;

package/dist/index.d.ts

@@ -40,7 +40,24 @@ interface ValueDefinition {
 }
 /** Value declarations (SPEC Section 4.4). */
 interface Values {
-    /** List of value identifiers */
+    /**
+     * Behavioral and ethical values the agent applies in its decision-making.
+     *
+     * This field is actively monitored by AIP at runtime: every value listed here
+     * is expected to appear in AP-Trace `values_applied` fields when it influences
+     * a decision. Declaring a value the agent never applies produces verification
+     * warnings and degrades trust scoring.
+     *
+     * **Include**: Ethical and behavioral commitments — e.g. `transparency`,
+     * `honesty`, `accuracy`, `safety`, `accountability`, `helpfulness`,
+     * `deliberation_before_action`. These describe HOW the agent reasons.
+     *
+     * **Do not include**: Role capabilities, operational principles, or job-function
+     * descriptors — e.g. `fiduciary_precision`, `organizational_clarity`. These
+     * describe WHAT the agent is in its role and belong in `extensions.clpi.role`
+     * or other `extensions` metadata. Capability names (e.g. `read_documents`)
+     * belong in `autonomy_envelope.bounded_actions`.
+     */
     declared: string[];
     /** Definitions for non-standard values */
     definitions?: Record<string, ValueDefinition> | null;

package/dist/index.js

@@ -834,23 +834,29 @@ function analyzeFaultLines(coherenceResult, cards, options) {
         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 impactScore;
     let severity;
-    if (impactScore >= 0.7) {
-      severity = "critical";
-    } else if (impactScore >= 0.4) {
-      severity = "high";
-    } else if (impactScore >= 0.2) {
-      severity = "medium";
-    } else {
+    if (classification === "complementary") {
+      impactScore = 0;
       severity = "low";
+    } else {
+      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));
+      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) {
@@ -901,12 +907,15 @@ function analyzeFaultLines(coherenceResult, cards, options) {
     return b.impact_score - a.impact_score;
   });
   const alignments = [];
+  const actionableFaultLines = faultLines.filter(
+    (fl) => fl.classification === "resolvable" || fl.classification === "incompatible"
+  );
   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);
+  for (let i = 0; i < actionableFaultLines.length; i++) {
+    for (let j = i + 1; j < actionableFaultLines.length; j++) {
+      const sim = jaccardSimilarity(actionableFaultLines[i].agents_missing, actionableFaultLines[j].agents_missing);
       if (sim > 0.6) {
         const gi = groupAssignment.get(i);
         const gj = groupAssignment.get(j);
@@ -939,7 +948,7 @@ function analyzeFaultLines(coherenceResult, cards, options) {
   for (const [, members] of grouped) {
     if (members.length < 2) continue;
     const unique = [...new Set(members)];
-    const groupFaultLines = unique.map((i) => faultLines[i]);
+    const groupFaultLines = unique.map((i) => actionableFaultLines[i]);
     const minorityAgents = [
       ...new Set(groupFaultLines.flatMap((fl) => fl.agents_missing))
     ];

package/dist/index.mjs

@@ -777,23 +777,29 @@ function analyzeFaultLines(coherenceResult, cards, options) {
         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 impactScore;
     let severity;
-    if (impactScore >= 0.7) {
-      severity = "critical";
-    } else if (impactScore >= 0.4) {
-      severity = "high";
-    } else if (impactScore >= 0.2) {
-      severity = "medium";
-    } else {
+    if (classification === "complementary") {
+      impactScore = 0;
       severity = "low";
+    } else {
+      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));
+      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) {
@@ -844,12 +850,15 @@ function analyzeFaultLines(coherenceResult, cards, options) {
     return b.impact_score - a.impact_score;
   });
   const alignments = [];
+  const actionableFaultLines = faultLines.filter(
+    (fl) => fl.classification === "resolvable" || fl.classification === "incompatible"
+  );
   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);
+  for (let i = 0; i < actionableFaultLines.length; i++) {
+    for (let j = i + 1; j < actionableFaultLines.length; j++) {
+      const sim = jaccardSimilarity(actionableFaultLines[i].agents_missing, actionableFaultLines[j].agents_missing);
       if (sim > 0.6) {
         const gi = groupAssignment.get(i);
         const gj = groupAssignment.get(j);
@@ -882,7 +891,7 @@ function analyzeFaultLines(coherenceResult, cards, options) {
   for (const [, members] of grouped) {
     if (members.length < 2) continue;
     const unique = [...new Set(members)];
-    const groupFaultLines = unique.map((i) => faultLines[i]);
+    const groupFaultLines = unique.map((i) => actionableFaultLines[i]);
     const minorityAgents = [
       ...new Set(groupFaultLines.flatMap((fl) => fl.agents_missing))
     ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/agent-alignment-protocol",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Agent Alignment Protocol (AAP) - Verification and drift detection for AI agents",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/schemas/alignment-card.ts

@@ -49,7 +49,24 @@ export interface ValueDefinition {
 
 /** Value declarations (SPEC Section 4.4). */
 export interface Values {
-  /** List of value identifiers */
+  /**
+   * Behavioral and ethical values the agent applies in its decision-making.
+   *
+   * This field is actively monitored by AIP at runtime: every value listed here
+   * is expected to appear in AP-Trace `values_applied` fields when it influences
+   * a decision. Declaring a value the agent never applies produces verification
+   * warnings and degrades trust scoring.
+   *
+   * **Include**: Ethical and behavioral commitments — e.g. `transparency`,
+   * `honesty`, `accuracy`, `safety`, `accountability`, `helpfulness`,
+   * `deliberation_before_action`. These describe HOW the agent reasons.
+   *
+   * **Do not include**: Role capabilities, operational principles, or job-function
+   * descriptors — e.g. `fiduciary_precision`, `organizational_clarity`. These
+   * describe WHAT the agent is in its role and belong in `extensions.clpi.role`
+   * or other `extensions` metadata. Capability names (e.g. `read_documents`)
+   * belong in `autonomy_envelope.bounded_actions`.
+   */
   declared: string[];
   /** Definitions for non-standard values */
   definitions?: Record<string, ValueDefinition> | null;

package/src/verification/api.ts

@@ -923,30 +923,38 @@ export function analyzeFaultLines(
     }
 
     // --- impact_score ---
-    let impactScore = impact_on_fleet_score * coordinationOverlap;
-
-    // Reputation weighting: multiply by geometric mean of reputation/1000
-    if (reputationScores && involvedAgents.length > 0) {
-      const repValues = involvedAgents
-        .map(id => (reputationScores[id] ?? 500) / 1000)
-        .map(r => Math.max(0.001, r)); // avoid log(0)
-      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));
-
-    // --- Severity ---
+    // Complementary faults are intentional — they carry zero risk by definition.
+    let impactScore: number;
     let severity: Severity;
-    if (impactScore >= 0.7) {
-      severity = 'critical';
-    } else if (impactScore >= 0.4) {
-      severity = 'high';
-    } else if (impactScore >= 0.2) {
-      severity = 'medium';
-    } else {
+
+    if (classification === 'complementary') {
+      impactScore = 0;
       severity = 'low';
+    } else {
+      impactScore = impact_on_fleet_score * coordinationOverlap;
+
+      // Reputation weighting: multiply by geometric mean of reputation/1000
+      if (reputationScores && involvedAgents.length > 0) {
+        const repValues = involvedAgents
+          .map(id => (reputationScores[id] ?? 500) / 1000)
+          .map(r => Math.max(0.001, r)); // avoid log(0)
+        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));
+
+      // --- Severity ---
+      if (impactScore >= 0.7) {
+        severity = 'critical';
+      } else if (impactScore >= 0.4) {
+        severity = 'high';
+      } else if (impactScore >= 0.2) {
+        severity = 'medium';
+      } else {
+        severity = 'low';
+      }
     }
 
     // --- Resolution hint ---
@@ -1007,17 +1015,22 @@ export function analyzeFaultLines(
   });
 
   // --- Fault line alignment detection ---
+  // Only consider resolvable and incompatible faults — complementary faults are intentional
+  // role specialization and should NEVER trigger a structural fault line alert.
   const alignments: FaultLineAlignment[] = [];
+  const actionableFaultLines = faultLines.filter(
+    fl => fl.classification === 'resolvable' || fl.classification === 'incompatible'
+  );
 
-  // For each pair of fault lines, compute Jaccard of agents_missing sets
+  // For each pair of actionable fault lines, compute Jaccard of agents_missing sets
   // Group fault lines with similarity > 0.6
   const grouped = new Map<number, number[]>(); // groupId → faultLine indices
   const groupAssignment = new Map<number, number>(); // faultLine index → groupId
   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);
+  for (let i = 0; i < actionableFaultLines.length; i++) {
+    for (let j = i + 1; j < actionableFaultLines.length; j++) {
+      const sim = jaccardSimilarity(actionableFaultLines[i].agents_missing, actionableFaultLines[j].agents_missing);
       if (sim > 0.6) {
         // Find or create groups for i and j
         const gi = groupAssignment.get(i);
@@ -1054,7 +1067,7 @@ export function analyzeFaultLines(
   for (const [, members] of grouped) {
     if (members.length < 2) continue;
     const unique = [...new Set(members)];
-    const groupFaultLines = unique.map(i => faultLines[i]);
+    const groupFaultLines = unique.map(i => actionableFaultLines[i]);
 
     const minorityAgents = [
       ...new Set(groupFaultLines.flatMap(fl => fl.agents_missing)),