Feat/cerberus erep (#940)

* feat: reference mapping

* feat: sync

* feat: reference

Author: coodos

platforms/cerberus/client/src/database/data-source.ts

@@ -9,6 +9,7 @@ import path from "path";
 import { UserEVaultMapping } from "./entities/UserEVaultMapping";
 import { VotingObservation } from "./entities/VotingObservation";
 import { CharterSignature } from "./entities/CharterSignature";
+import { Reference } from "./entities/Reference";
 
 config({ path: path.resolve(__dirname, "../../../../.env") });
 
@@ -25,6 +26,7 @@ export const AppDataSource = new DataSource({
         UserEVaultMapping,
         VotingObservation,
         CharterSignature,
+        Reference,
     ],
     migrations: [path.join(__dirname, "migrations", "*.ts")],
     subscribers: [PostgresSubscriber],

platforms/cerberus/client/src/database/entities/Reference.ts

@@ -0,0 +1,45 @@
+import { Entity, PrimaryGeneratedColumn, Column, ManyToOne, JoinColumn, CreateDateColumn, UpdateDateColumn } from "typeorm";
+import { User } from "./User";
+
+@Entity("references")
+export class Reference {
+    @PrimaryGeneratedColumn("uuid")
+    id!: string;
+
+    @Column()
+    targetType!: string; // "user", "group", "platform"
+
+    @Column()
+    targetId!: string;
+
+    @Column()
+    targetName!: string;
+
+    @Column("text")
+    content!: string;
+
+    @Column()
+    referenceType!: string; // "general", "violation", etc.
+
+    @Column("int", { nullable: true })
+    numericScore?: number; // 1-5 score
+
+    @Column()
+    authorId!: string;
+
+    @ManyToOne(() => User)
+    @JoinColumn({ name: "authorId" })
+    author!: User;
+
+    @Column({ default: "signed" })
+    status!: string; // "signed", "revoked"
+
+    @Column({ default: false })
+    anonymous!: boolean;
+
+    @CreateDateColumn()
+    createdAt!: Date;
+
+    @UpdateDateColumn()
+    updatedAt!: Date;
+}

platforms/cerberus/client/src/services/CerberusTriggerService.ts

@@ -5,6 +5,7 @@ import { GroupService } from "./GroupService";
 import { UserService } from "./UserService";
 import { PlatformEVaultService } from "./PlatformEVaultService";
 import { VotingContextService } from "./VotingContextService";
+import { ReferenceWriterService } from "./ReferenceWriterService";
 
 interface CharterViolation {
     violation: string;
@@ -28,6 +29,7 @@ export class CerberusTriggerService {
     private userService: UserService;
     private platformService: PlatformEVaultService;
     private votingContextService: VotingContextService;
+    private referenceWriterService: ReferenceWriterService;
     private openaiApiKey: string;
 
     constructor() {
@@ -36,6 +38,7 @@ export class CerberusTriggerService {
         this.userService = new UserService();
         this.platformService = PlatformEVaultService.getInstance();
         this.votingContextService = new VotingContextService();
+        this.referenceWriterService = new ReferenceWriterService();
         this.openaiApiKey = process.env.OPENAI_API_KEY || "";
     }
 
@@ -319,6 +322,14 @@ export class CerberusTriggerService {
      */
     async analyzeCharterViolations(messages: Message[], group: Group, lastVoteMessage?: Message): Promise<{
         violations: string[];
+        userViolations: Array<{
+            userId: string;
+            userName: string;
+            userEname: string | null;
+            violation: string;
+            severity: "low" | "medium" | "high";
+            score: number;
+        }>;
         summary: string;
         hasVotingIssues: boolean;
         votingStatus: string;
@@ -327,6 +338,7 @@ export class CerberusTriggerService {
         if (!this.openaiApiKey) {
             return {
                 violations: [],
+                userViolations: [],
                 summary: "⚠️ OpenAI API key not configured. Cannot analyze charter violations.",
                 hasVotingIssues: false,
                 votingStatus: "Not analyzed",
@@ -385,10 +397,13 @@ VOTING CONTEXT:
                 console.log(votingContext);
             }
 
-            // Format messages for analysis
-            const messagesText = messages.map(msg => 
-                `[${msg.createdAt.toLocaleString()}] ${msg.sender ? msg.sender.name : 'System'}: ${msg.text}`
-            ).join('\n');
+            // Format messages for analysis — include sender ID and ename for structured violation reporting
+            const messagesText = messages.map(msg => {
+                const senderInfo = msg.sender
+                    ? `${msg.sender.name || 'Unknown'} (id:${msg.sender.id}${msg.sender.ename ? ', ename:' + msg.sender.ename : ''})`
+                    : 'System';
+                return `[${msg.createdAt.toLocaleString()}] ${senderInfo}: ${msg.text}`;
+            }).join('\n');
 
             const charterText = group.charter || "No charter defined for this group.";
 
@@ -430,6 +445,16 @@ CHARTER ENFORCEMENT:
 RESPOND WITH ONLY PURE JSON - NO MARKDOWN, NO CODE BLOCKS:
 {
     "violations": ["array of detailed violation descriptions with justifications"],
+    "userViolations": [
+        {
+            "userId": "the user's id from the message (id:xxx)",
+            "userName": "the user's display name",
+            "userEname": "the user's ename if available, or null",
+            "violation": "one-sentence description of what rule was violated",
+            "severity": "low" | "medium" | "high",
+            "score": 1-5 (1 = severe, 5 = minor/warning)
+        }
+    ],
     "summary": "comprehensive summary with specific examples and actionable recommendations",
     "hasVotingIssues": boolean,
     "votingStatus": "string describing current voting situation with reasoning",
@@ -486,8 +511,14 @@ Be thorough and justify your reasoning. Provide clear, actionable recommendation
 
             // Parse the JSON response
             try {
-                const analysis = JSON.parse(content);
-                
+                // Strip markdown code fences if present
+                let jsonContent = content.trim();
+                if (jsonContent.startsWith("```")) {
+                    jsonContent = jsonContent.replace(/^```(?:json)?\s*/, "").replace(/```\s*$/, "").trim();
+                }
+
+                const analysis = JSON.parse(jsonContent);
+
                 // Validate required fields
                 if (!Array.isArray(analysis.violations) ||
                     typeof analysis.summary !== 'string' ||
@@ -497,6 +528,11 @@ Be thorough and justify your reasoning. Provide clear, actionable recommendation
                     throw new Error("Invalid JSON structure from OpenAI");
                 }
 
+                // Ensure userViolations exists and is an array
+                if (!Array.isArray(analysis.userViolations)) {
+                    analysis.userViolations = [];
+                }
+
                 return analysis;
 
             } catch (parseError) {
@@ -505,6 +541,7 @@ Be thorough and justify your reasoning. Provide clear, actionable recommendation
 
                 return {
                     violations: [],
+                    userViolations: [],
                     summary: "❌ Error analyzing messages. Please check the logs.",
                     hasVotingIssues: false,
                     votingStatus: "Error occurred",
@@ -516,6 +553,7 @@ Be thorough and justify your reasoning. Provide clear, actionable recommendation
             console.error("Error analyzing with AI:", error);
             return {
                 violations: [],
+                userViolations: [],
                 summary: "❌ Error analyzing charter violations. Please check the logs.",
                 hasVotingIssues: false,
                 votingStatus: "Error occurred",
@@ -589,11 +627,50 @@ Be thorough and justify your reasoning. Provide clear, actionable recommendation
                 });
             }
 
+            // Write violation references for users who violated the charter
+            if (analysis.userViolations && analysis.userViolations.length > 0) {
+                try {
+                    // Resolve a Cerberus system user as the author of the reference
+                    // Use the first group participant as a fallback author, or try "cerberus" ename
+                    let authorId: string | null = null;
+                    const cerberusUser = await this.referenceWriterService.resolveUserId("cerberus");
+                    if (cerberusUser) {
+                        authorId = cerberusUser.id;
+                    } else {
+                        // Use the trigger message sender or first available user
+                        const allUsers = await this.userService.getAllUsers();
+                        if (allUsers.length > 0) authorId = allUsers[0].id;
+                    }
+
+                    if (authorId) {
+                        const violationRefs = analysis.userViolations.map((uv: any) => ({
+                            targetId: uv.userId,
+                            targetName: uv.userName,
+                            targetEname: uv.userEname || undefined,
+                            content: `[Cerberus - Charter Violation in ${groupWithCharter.name}] ${uv.violation}`,
+                            numericScore: Math.max(1, Math.min(5, uv.score || 2))
+                        }));
+
+                        await this.referenceWriterService.writeViolationReferences(
+                            violationRefs,
+                            triggerMessage.group.id,
+                            groupWithCharter.name,
+                            authorId
+                        );
+                        console.log(`📝 Wrote ${violationRefs.length} violation references`);
+                    } else {
+                        console.warn("⚠️ No author user found for violation references");
+                    }
+                } catch (refError) {
+                    console.error("❌ Error writing violation references:", refError);
+                }
+            }
+
             // Build the final analysis text
             let analysisText: string;
             if (analysis.violations.length > 0) {
                 analysisText = `🚨 CHARTER VIOLATIONS DETECTED!\n\n${analysis.summary}`;
-                
+
                 // Add enforcement information if available
                 if (analysis.enforcement && analysis.enforcement !== "No enforcement possible - API not configured") {
                     analysisText += `\n\n⚖️ ENFORCEMENT:\n${analysis.enforcement}`;

platforms/cerberus/client/src/services/ReferenceWriterService.ts

@@ -0,0 +1,118 @@
+import { AppDataSource } from "../database/data-source";
+import { Reference } from "../database/entities/Reference";
+import { User } from "../database/entities/User";
+
+interface ViolationReference {
+    targetId: string;       // User ID of the violator
+    targetName: string;     // Display name of the violator
+    targetEname?: string;   // ename of the violator
+    content: string;        // Description of the violation
+    numericScore: number;   // 1-5 (1 = severe violation, 5 = minor)
+}
+
+export class ReferenceWriterService {
+    private referenceRepository = AppDataSource.getRepository(Reference);
+    private userRepository = AppDataSource.getRepository(User);
+    private eReputationBaseUrl: string;
+    private platformSecret: string;
+
+    constructor() {
+        this.eReputationBaseUrl = process.env.PUBLIC_EREPUTATION_BASE_URL || "http://localhost:8765";
+        this.platformSecret = process.env.PLATFORM_SHARED_SECRET || "";
+    }
+
+    /**
+     * Write violation references for users who violated the charter.
+     * Writes to both local DB (for eVault sync) and eReputation API directly.
+     */
+    async writeViolationReferences(
+        violations: ViolationReference[],
+        groupId: string,
+        groupName: string,
+        authorId: string
+    ): Promise<void> {
+        for (const violation of violations) {
+            try {
+                // 1. Write to local DB (triggers web3adapter → eVault sync)
+                await this.writeLocalReference(violation, authorId);
+
+                // 2. Write directly to eReputation API
+                await this.writeToEReputationApi(violation, authorId);
+
+                console.log(`✅ Violation reference written for ${violation.targetName} (${violation.targetId})`);
+            } catch (error) {
+                console.error(`❌ Failed to write violation reference for ${violation.targetName}:`, error);
+            }
+        }
+    }
+
+    /**
+     * Write reference to local Cerberus DB — the web3adapter subscriber
+     * will pick it up and sync to eVault automatically.
+     */
+    private async writeLocalReference(violation: ViolationReference, authorId: string): Promise<Reference> {
+        const reference = this.referenceRepository.create({
+            targetType: "user",
+            targetId: violation.targetId,
+            targetName: violation.targetName,
+            content: violation.content,
+            referenceType: "violation",
+            numericScore: violation.numericScore,
+            authorId,
+            status: "signed",
+            anonymous: false
+        });
+
+        return await this.referenceRepository.save(reference);
+    }
+
+    /**
+     * Write reference directly to eReputation API using the platform shared secret.
+     */
+    private async writeToEReputationApi(violation: ViolationReference, authorId: string): Promise<void> {
+        if (!this.platformSecret) {
+            console.warn("⚠️ PLATFORM_SHARED_SECRET not set, skipping eReputation API call");
+            return;
+        }
+
+        try {
+            const response = await fetch(`${this.eReputationBaseUrl}/api/references/system`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-Platform-Secret": this.platformSecret
+                },
+                body: JSON.stringify({
+                    targetType: "user",
+                    targetId: violation.targetId,
+                    targetName: violation.targetName,
+                    content: violation.content,
+                    referenceType: "violation",
+                    numericScore: violation.numericScore,
+                    authorId,
+                    anonymous: false
+                })
+            });
+
+            if (!response.ok) {
+                const errorText = await response.text();
+                console.error(`❌ eReputation API error (${response.status}): ${errorText}`);
+            }
+        } catch (error) {
+            console.error("❌ Failed to call eReputation API:", error);
+        }
+    }
+
+    /**
+     * Resolve a user name/ename to their user ID in the local database.
+     */
+    async resolveUserId(nameOrEname: string): Promise<User | null> {
+        // Try ename first
+        let user = await this.userRepository.findOne({ where: { ename: nameOrEname } });
+        if (user) return user;
+
+        // Try name
+        user = await this.userRepository.findOne({ where: { name: nameOrEname } });
+        return user;
+    }
+}

platforms/cerberus/client/src/web3adapter/mappings/reference.mapping.json

@@ -0,0 +1,19 @@
+{
+    "tableName": "references",
+    "schemaId": "550e8400-e29b-41d4-a716-446655440010",
+    "ownerEnamePath": "users(author.ename)",
+    "localToUniversalMap": {
+        "id": "id",
+        "targetType": "targetType",
+        "targetId": "targetId",
+        "targetName": "targetName",
+        "content": "content",
+        "referenceType": "referenceType",
+        "numericScore": "numericScore",
+        "authorId": "users(author.id),author",
+        "status": "status",
+        "anonymous": "anonymous",
+        "createdAt": "__date(createdAt)",
+        "updatedAt": "__date(updatedAt)"
+    }
+}

platforms/cerberus/client/src/web3adapter/watchers/subscriber.ts

@@ -448,6 +448,8 @@ export class PostgresSubscriber implements EntitySubscriberInterface {
                 return ["sender", "group"];
             case "CharterSignature":
                 return ["user", "group"];
+            case "Reference":
+                return ["author"];
             default:
                 return [];
         }