@mnemom/agent-alignment-protocol 0.6.0 → 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

@@ -747,6 +747,13 @@ 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();
@@ -757,6 +764,10 @@ function analyzeFaultLines(coherenceResult, cards, options) {
   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 {
@@ -789,6 +800,13 @@ function analyzeFaultLines(coherenceResult, cards, options) {
     })()) {
       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));
     })()) {
@@ -816,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) {
@@ -883,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);
@@ -921,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

@@ -690,6 +690,13 @@ 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();
@@ -700,6 +707,10 @@ function analyzeFaultLines(coherenceResult, cards, options) {
   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 {
@@ -732,6 +743,13 @@ function analyzeFaultLines(coherenceResult, cards, options) {
     })()) {
       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));
     })()) {
@@ -759,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) {
@@ -826,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);
@@ -864,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.0",
+  "version": "0.6.2",
   "description": "Agent Alignment Protocol (AAP) - Verification and drift detection for AI agents",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -54,4 +54,4 @@
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}

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

@@ -788,6 +788,15 @@ function hasRoleKeyword(agentId: string): boolean {
   return ROLE_KEYWORDS.some(kw => lower.includes(kw));
 }
 
+/** Extract the CLPI role from a card's extensions, if present. */
+function getClpiRole(card: AlignmentCard): string | null {
+  const ext = (card as unknown as { extensions?: Record<string, unknown> }).extensions;
+  if (!ext) return null;
+  const clpi = ext['clpi'] as Record<string, unknown> | undefined;
+  if (!clpi || typeof clpi['role'] !== 'string') return null;
+  return clpi['role'] || null;
+}
+
 /**
  * Analyze fault lines in a fleet based on a FleetCoherenceResult.
  *
@@ -815,6 +824,12 @@ export function analyzeFaultLines(
     agentConflictMap.set(agentId, new Set(card.values.conflicts_with ?? []));
   }
 
+  // Build lookup: agentId → CLPI role (from extensions.clpi.role)
+  const agentRoleMap = new Map<string, string | null>();
+  for (const { agentId, card } of cards) {
+    agentRoleMap.set(agentId, getClpiRole(card));
+  }
+
   const faultLines: FaultLine[] = [];
 
   for (const divergence of coherenceResult.divergence_report) {
@@ -863,7 +878,18 @@ export function analyzeFaultLines(
       agents_declaring.length >= 1 &&
       agents_missing.length >= 1 &&
       (() => {
-        // complementary: heuristic — some agent (declaring or missing) has a role keyword
+        // complementary: the declaring agents all share a CLPI role that the missing
+        // agents do NOT share — indicating intentional role specialization, not a gap.
+        // Primary check: extensions.clpi.role (authoritative)
+        const declaringRoles = new Set(agents_declaring.map(id => agentRoleMap.get(id) ?? null).filter(Boolean));
+        const missingRoles = new Set(agents_missing.map(id => agentRoleMap.get(id) ?? null).filter(Boolean));
+        if (declaringRoles.size > 0) {
+          // All declaring agents share a role that none of the missing agents have
+          const declaringRoleArr = [...declaringRoles];
+          const isRoleExclusive = declaringRoleArr.every(role => !missingRoles.has(role));
+          if (isRoleExclusive) return true;
+        }
+        // Fallback: agent ID contains a role keyword (original heuristic)
         const allInvolved = [...agents_declaring, ...agents_missing];
         return allInvolved.some(id => hasRoleKeyword(id));
       })()
@@ -897,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 ---
@@ -981,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);
@@ -1028,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)),