@mnemom/agent-alignment-protocol 0.1.0

package/src/verification/features.ts

@@ -0,0 +1,157 @@
+/**
+ * Feature extraction for AAP verification.
+ *
+ * Provides feature extraction utilities for computing similarity
+ * between AP-Traces and Alignment Cards.
+ */
+
+import { MIN_WORD_LENGTH } from "../constants";
+import type { AlignmentCard } from "../schemas/alignment-card";
+import type { APTrace } from "../schemas/ap-trace";
+
+/** Sparse feature vector represented as a record. */
+export type FeatureVector = Record<string, number>;
+
+/** Stopwords to filter from text features. */
+const STOPWORDS = new Set([
+  "the", "a", "an", "and", "or", "but", "in", "on", "at", "to", "for",
+  "of", "with", "by", "from", "is", "are", "was", "were", "be", "been",
+  "being", "have", "has", "had", "do", "does", "did", "will", "would",
+  "could", "should", "may", "might", "must", "shall", "can", "this",
+  "that", "these", "those", "it", "its", "as", "if", "then", "else",
+]);
+
+/**
+ * Extract tokens from text, filtering stopwords and short words.
+ */
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .split(/\s+/)
+    .filter((word) => word.length >= MIN_WORD_LENGTH && !STOPWORDS.has(word));
+}
+
+/**
+ * Extract features from an Alignment Card.
+ */
+export function extractCardFeatures(card: AlignmentCard): FeatureVector {
+  const features: FeatureVector = {};
+
+  // Value features
+  for (const value of card.values.declared) {
+    features[`value:${value}`] = 1.0;
+  }
+
+  // Conflicts features
+  for (const conflict of card.values.conflicts_with ?? []) {
+    features[`conflict:${conflict}`] = 1.0;
+  }
+
+  // Action features (aligned with Python: action_name:{action})
+  for (const action of card.autonomy_envelope.bounded_actions) {
+    features[`action_name:${action}`] = 1.0;
+  }
+
+  // Forbidden action features
+  for (const action of card.autonomy_envelope.forbidden_actions ?? []) {
+    features[`forbidden:${action}`] = 1.0;
+  }
+
+  // Escalation trigger features
+  for (const trigger of card.autonomy_envelope.escalation_triggers) {
+    features[`escalation:${trigger.action}`] = 1.0;
+    const conditionTokens = tokenize(trigger.condition);
+    for (const token of conditionTokens) {
+      features[`condition:${token}`] = (features[`condition:${token}`] ?? 0) + 0.5;
+    }
+  }
+
+  // Category features
+  features[`category:${card.principal.type}`] = 1.0;
+  features[`category:${card.principal.relationship}`] = 1.0;
+
+  return features;
+}
+
+/**
+ * Extract features from an AP-Trace.
+ */
+export function extractTraceFeatures(trace: APTrace): FeatureVector {
+  const features: FeatureVector = {};
+
+  // Action features (aligned with Python: action:{type}, category:{category}, action_name:{name})
+  features[`action:${trace.action.type}`] = 1.0;
+  features[`category:${trace.action.category}`] = 1.0;
+  features[`action_name:${trace.action.name}`] = 1.0;
+
+  // Value features from decision
+  for (const value of trace.decision.values_applied) {
+    features[`value:${value}`] = 1.0;
+  }
+
+  // Escalation features
+  if (trace.escalation) {
+    features[`escalation:${trace.escalation.required ? "required" : "not_required"}`] = 1.0;
+    if (trace.escalation.escalation_status) {
+      features[`escalation:${trace.escalation.escalation_status}`] = 1.0;
+    }
+  }
+
+  // Content features from reasoning
+  const reasoningTokens = tokenize(trace.decision.selection_reasoning);
+  for (const token of reasoningTokens) {
+    features[`content:${token}`] = (features[`content:${token}`] ?? 0) + 0.5;
+  }
+
+  // Alternative features
+  for (const alt of trace.decision.alternatives_considered) {
+    const altTokens = tokenize(alt.description);
+    for (const token of altTokens) {
+      features[`content:${token}`] = (features[`content:${token}`] ?? 0) + 0.25;
+    }
+    if (alt.flags) {
+      for (const flag of alt.flags) {
+        features[`flag:${flag}`] = 1.0;
+      }
+    }
+  }
+
+  return features;
+}
+
+/**
+ * Compute cosine similarity between two feature vectors.
+ *
+ * @returns Similarity score between 0.0 and 1.0
+ */
+export function cosineSimilarity(a: FeatureVector, b: FeatureVector): number {
+  const keysA = Object.keys(a);
+  const keysB = new Set(Object.keys(b));
+
+  let dotProduct = 0;
+  let normA = 0;
+  let normB = 0;
+
+  // Compute dot product and norm of A
+  for (const key of keysA) {
+    const valA = a[key];
+    normA += valA * valA;
+    if (keysB.has(key)) {
+      dotProduct += valA * b[key];
+    }
+  }
+
+  // Compute norm of B
+  for (const key of keysB) {
+    const valB = b[key];
+    normB += valB * valB;
+  }
+
+  // Avoid division by zero
+  if (normA === 0 || normB === 0) {
+    return 0;
+  }
+
+  return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+}

package/src/verification/index.ts

@@ -0,0 +1,7 @@
+/**
+ * AAP Verification module exports.
+ */
+
+export * from "./api";
+export * from "./features";
+export * from "./models";

package/src/verification/models.ts

@@ -0,0 +1,182 @@
+/**
+ * Verification and drift detection models.
+ *
+ * Defines the result types for AAP verification operations as specified
+ * in SPEC.md Sections 7 (Verification) and 8 (Drift Detection).
+ */
+
+/** Types of verification violations (SPEC Section 7.5). */
+export type ViolationType =
+  | "unbounded_action"
+  | "forbidden_action"
+  | "missed_escalation"
+  | "undeclared_value"
+  | "card_expired"
+  | "card_mismatch";
+
+/** Violation severity levels. */
+export type Severity = "critical" | "high" | "medium" | "low";
+
+/** Mapping of violation types to their severity */
+export const VIOLATION_SEVERITY: Record<ViolationType, Severity> = {
+  unbounded_action: "high",
+  forbidden_action: "critical",
+  missed_escalation: "high",
+  undeclared_value: "medium",
+  card_expired: "high",
+  card_mismatch: "critical",
+};
+
+/** A single verification violation. */
+export interface Violation {
+  /** Type of violation */
+  type: ViolationType;
+  /** Severity level */
+  severity: Severity;
+  /** Human-readable description */
+  description: string;
+  /** JSON path to the violating field */
+  trace_field?: string | null;
+}
+
+/** Create a violation with automatic severity lookup. */
+export function createViolation(
+  type: ViolationType,
+  description: string,
+  traceField?: string | null
+): Violation {
+  return {
+    type,
+    severity: VIOLATION_SEVERITY[type],
+    description,
+    trace_field: traceField,
+  };
+}
+
+/** A verification warning (non-critical issue). */
+export interface Warning {
+  /** Warning type identifier */
+  type: string;
+  /** Human-readable description */
+  description: string;
+  /** JSON path to the relevant field */
+  trace_field?: string | null;
+}
+
+/** Metadata about the verification process. */
+export interface VerificationMetadata {
+  /** Verification algorithm version */
+  algorithm_version: string;
+  /** List of checks that were performed */
+  checks_performed: string[];
+  /** Time taken to perform verification in milliseconds */
+  duration_ms?: number | null;
+}
+
+/** Result of verifying an AP-Trace against an Alignment Card (SPEC Section 7.4). */
+export interface VerificationResult {
+  /** True if no violations were found */
+  verified: boolean;
+  /** ID of the verified trace */
+  trace_id: string;
+  /** ID of the Alignment Card used */
+  card_id: string;
+  /** When verification was performed (ISO 8601) */
+  timestamp: string;
+  /** List of violations found */
+  violations: Violation[];
+  /** List of non-critical warnings */
+  warnings: Warning[];
+  /** Metadata about the verification process */
+  verification_metadata: VerificationMetadata;
+}
+
+/** Categories of behavioral drift (SPEC Section 8.5). */
+export type DriftDirection =
+  | "autonomy_expansion"
+  | "value_drift"
+  | "principal_misalignment"
+  | "communication_drift"
+  | "unknown";
+
+/** A specific indicator of behavioral drift. */
+export interface DriftIndicator {
+  /** Indicator identifier */
+  indicator: string;
+  /** Expected/baseline value */
+  baseline: number;
+  /** Currently observed value */
+  current: number;
+  /** Human-readable explanation */
+  description: string;
+}
+
+/** Detailed analysis of detected drift. */
+export interface DriftAnalysis {
+  /** Current similarity to declared alignment (0.0 to 1.0) */
+  similarity_score: number;
+  /** Number of consecutive low-similarity traces */
+  sustained_traces: number;
+  /** Similarity threshold used */
+  threshold: number;
+  /** Categorized direction of drift */
+  drift_direction: DriftDirection;
+  /** Specific drift indicators */
+  specific_indicators: DriftIndicator[];
+}
+
+/** Alert generated when sustained drift is detected (SPEC Section 8.4). */
+export interface DriftAlert {
+  /** Type of alert */
+  alert_type: "drift_detected";
+  /** Agent exhibiting drift */
+  agent_id: string;
+  /** Alignment Card being drifted from */
+  card_id: string;
+  /** When drift was detected (ISO 8601) */
+  detection_timestamp: string;
+  /** Drift analysis details */
+  analysis: DriftAnalysis;
+  /** Recommended action */
+  recommendation: string;
+  /** IDs of traces exhibiting drift */
+  trace_ids: string[];
+}
+
+/** Analysis of value alignment between two cards. */
+export interface ValueAlignment {
+  /** Values present in both cards */
+  matched: string[];
+  /** Values in one card but not the other */
+  unmatched: string[];
+  /** Direct value conflicts */
+  conflicts: ValueConflictResult[];
+}
+
+/** A conflict between values declared by two agents. */
+export interface ValueConflictResult {
+  /** Value from initiating agent */
+  initiator_value: string;
+  /** Value from responding agent */
+  responder_value: string;
+  /** Type of conflict (incompatible, priority_mismatch, etc.) */
+  conflict_type: string;
+  /** Human-readable explanation */
+  description: string;
+}
+
+/** Result of checking value coherence between two Alignment Cards. */
+export interface CoherenceResult {
+  /** Whether the cards are compatible for coordination */
+  compatible: boolean;
+  /** Coherence score (0.0 to 1.0) */
+  score: number;
+  /** Detailed value alignment analysis */
+  value_alignment: ValueAlignment;
+  /** Whether to proceed with coordination */
+  proceed: boolean;
+  /** Conditions for proceeding (if any) */
+  conditions: string[];
+  /** Proposed conflict resolution (if conflicts exist) */
+  proposed_resolution?: { type: string; reason: string } | null;
+}