@mnemom/agent-alignment-protocol 0.1.0

package/src/index.ts

@@ -0,0 +1,135 @@
+/**
+ * Agent Alignment Protocol (AAP) - TypeScript SDK
+ *
+ * This package provides the core verification functionality for AAP:
+ * - verifyTrace: Verify a single AP-Trace against an Alignment Card
+ * - checkCoherence: Check value coherence between two Alignment Cards
+ * - detectDrift: Detect behavioral drift from declared alignment over time
+ *
+ * @example
+ * ```typescript
+ * import { verifyTrace, checkCoherence, detectDrift } from 'agent-alignment-protocol';
+ * import type { AlignmentCard, APTrace } from 'agent-alignment-protocol';
+ *
+ * // Verify a trace
+ * const result = verifyTrace(trace, card);
+ * if (!result.verified) {
+ *   console.log('Violations:', result.violations);
+ * }
+ *
+ * // Check coherence between two cards
+ * const coherence = checkCoherence(myCard, theirCard);
+ * if (!coherence.compatible) {
+ *   console.log('Value conflicts:', coherence.value_alignment.conflicts);
+ * }
+ *
+ * // Detect drift over time
+ * const alerts = detectDrift(card, recentTraces);
+ * for (const alert of alerts) {
+ *   console.log('Drift detected:', alert.analysis.drift_direction);
+ * }
+ * ```
+ *
+ * @see https://aap.dev for documentation
+ * @see SPEC.md for protocol specification
+ */
+
+// Main API exports
+export { verifyTrace, checkCoherence, detectDrift } from "./verification/api";
+
+// Schema types
+export type {
+  // Alignment Card
+  AlignmentCard,
+  Principal,
+  PrincipalType,
+  RelationshipType,
+  Values,
+  ValueDefinition,
+  HierarchyType,
+  AutonomyEnvelope,
+  EscalationTrigger,
+  TriggerAction,
+  MonetaryValue,
+  AuditCommitment,
+  AuditStorage,
+  StorageType,
+  TamperEvidence,
+} from "./schemas/alignment-card";
+
+export type {
+  // AP-Trace
+  APTrace,
+  Action,
+  ActionType,
+  ActionCategory,
+  ActionTarget,
+  Decision,
+  Alternative,
+  Escalation,
+  EscalationStatus,
+  TriggerCheck,
+  PrincipalResponse,
+  TraceContext,
+} from "./schemas/ap-trace";
+
+export type {
+  // Value Coherence
+  AlignmentCardRequest,
+  AlignmentCardResponse,
+  ValueCoherenceCheck,
+  CoherenceResultMessage,
+  ValueCoherenceMessage,
+  RequesterInfo,
+  TaskContext,
+  Signature,
+  ProposedCollaboration,
+  DataSharing,
+  AutonomyScope,
+  Coherence,
+  ValueAlignmentDetail,
+  ValueConflict,
+  ProposedResolution,
+} from "./schemas/value-coherence";
+
+// Result types
+export type {
+  VerificationResult,
+  Violation,
+  ViolationType,
+  Severity,
+  Warning,
+  VerificationMetadata,
+  CoherenceResult,
+  ValueAlignment,
+  ValueConflictResult,
+  DriftAlert,
+  DriftAnalysis,
+  DriftDirection,
+  DriftIndicator,
+} from "./verification/models";
+
+// Utility exports
+export {
+  isCardExpired,
+  hasValue,
+  isActionBounded,
+  isActionForbidden,
+} from "./schemas/alignment-card";
+
+export {
+  getSelectedAlternative,
+  wasEscalated,
+  hadViolations,
+} from "./schemas/ap-trace";
+
+export {
+  extractCardFeatures,
+  extractTraceFeatures,
+  cosineSimilarity,
+} from "./verification/features";
+
+export { createViolation, VIOLATION_SEVERITY } from "./verification/models";
+
+// Constants
+export * from "./constants";

package/src/schemas/alignment-card.ts

@@ -0,0 +1,166 @@
+/**
+ * Alignment Card schema - Agent alignment declaration.
+ *
+ * Defines the Alignment Card structure per SPEC Section 4. An Alignment Card
+ * is a structured document declaring an agent's alignment posture.
+ *
+ * @see SPEC.md Section 4 for complete specification.
+ */
+
+/** Type of principal the agent serves. */
+export type PrincipalType = "human" | "organization" | "agent" | "unspecified";
+
+/** Nature of authority delegation from principal to agent. */
+export type RelationshipType = "delegated_authority" | "advisory" | "autonomous";
+
+/** How value conflicts are resolved. */
+export type HierarchyType = "lexicographic" | "weighted" | "contextual";
+
+/** Action to take when escalation trigger matches. */
+export type TriggerAction = "escalate" | "deny" | "log";
+
+/** Audit log storage type. */
+export type StorageType = "local" | "remote" | "distributed";
+
+/** Tamper-evidence mechanism for audit logs. */
+export type TamperEvidence = "append_only" | "signed" | "merkle";
+
+/** Principal relationship declaration (SPEC Section 4.3). */
+export interface Principal {
+  /** Type of principal */
+  type: PrincipalType;
+  /** Principal identifier (DID, email, org ID) */
+  identifier?: string | null;
+  /** Nature of authority delegation */
+  relationship: RelationshipType;
+  /** Endpoint for escalation notifications */
+  escalation_contact?: string | null;
+}
+
+/** Definition of a custom value. */
+export interface ValueDefinition {
+  /** Human-readable name */
+  name: string;
+  /** What this value means operationally */
+  description: string;
+  /** Priority for lexicographic ordering (higher = more important) */
+  priority?: number;
+}
+
+/** Value declarations (SPEC Section 4.4). */
+export interface Values {
+  /** List of value identifiers */
+  declared: string[];
+  /** Definitions for non-standard values */
+  definitions?: Record<string, ValueDefinition> | null;
+  /** Values this agent refuses to coordinate with */
+  conflicts_with?: string[] | null;
+  /** How value conflicts are resolved */
+  hierarchy?: HierarchyType | null;
+}
+
+/** Condition that triggers escalation (SPEC Section 4.5). */
+export interface EscalationTrigger {
+  /** Condition expression (see SPEC Section 4.6) */
+  condition: string;
+  /** Action to take when trigger matches */
+  action: TriggerAction;
+  /** Human-readable explanation */
+  reason: string;
+}
+
+/** Monetary value specification. */
+export interface MonetaryValue {
+  /** Numeric amount */
+  amount: number;
+  /** ISO 4217 currency code */
+  currency?: string;
+}
+
+/** Autonomy bounds and escalation triggers (SPEC Section 4.5). */
+export interface AutonomyEnvelope {
+  /** Actions permitted without escalation */
+  bounded_actions: string[];
+  /** Conditions requiring escalation */
+  escalation_triggers: EscalationTrigger[];
+  /** Maximum transaction value without escalation */
+  max_autonomous_value?: MonetaryValue | null;
+  /** Actions never permitted */
+  forbidden_actions?: string[] | null;
+}
+
+/** Audit log storage configuration. */
+export interface AuditStorage {
+  /** Storage type */
+  type: StorageType;
+  /** Storage endpoint or location */
+  location?: string | null;
+}
+
+/** Audit trail commitments (SPEC Section 4.7). */
+export interface AuditCommitment {
+  /** Trace format identifier */
+  trace_format?: string;
+  /** Minimum retention period in days */
+  retention_days: number;
+  /** Storage configuration */
+  storage?: AuditStorage | null;
+  /** Whether traces can be queried externally */
+  queryable: boolean;
+  /** Endpoint for trace queries (required if queryable=true) */
+  query_endpoint?: string | null;
+  /** Tamper-evidence mechanism */
+  tamper_evidence?: TamperEvidence | null;
+}
+
+/**
+ * Alignment Card - Agent alignment declaration (SPEC Section 4).
+ *
+ * A structured document declaring an agent's alignment posture. It MUST be
+ * machine-readable (JSON) and SHOULD be human-readable.
+ */
+export interface AlignmentCard {
+  /** AAP specification version */
+  aap_version?: string;
+  /** Unique identifier for this card (UUID or URI) */
+  card_id: string;
+  /** Identifier for the agent (DID, URL, or UUID) */
+  agent_id: string;
+  /** When this card was issued (ISO 8601) */
+  issued_at: string;
+  /** When this card expires (ISO 8601) */
+  expires_at?: string | null;
+  /** Principal relationship declaration */
+  principal: Principal;
+  /** Value declarations */
+  values: Values;
+  /** Autonomy bounds and escalation triggers */
+  autonomy_envelope: AutonomyEnvelope;
+  /** Audit trail commitments */
+  audit_commitment: AuditCommitment;
+  /** Protocol-specific extensions */
+  extensions?: Record<string, unknown> | null;
+}
+
+// Utility functions
+
+/** Check if an alignment card has expired. */
+export function isCardExpired(card: AlignmentCard): boolean {
+  if (!card.expires_at) return false;
+  return new Date() > new Date(card.expires_at);
+}
+
+/** Check if a value is declared in the card. */
+export function hasValue(card: AlignmentCard, value: string): boolean {
+  return card.values.declared.includes(value);
+}
+
+/** Check if an action is in the bounded actions list. */
+export function isActionBounded(card: AlignmentCard, action: string): boolean {
+  return card.autonomy_envelope.bounded_actions.includes(action);
+}
+
+/** Check if an action is forbidden. */
+export function isActionForbidden(card: AlignmentCard, action: string): boolean {
+  return (card.autonomy_envelope.forbidden_actions ?? []).includes(action);
+}

package/src/schemas/ap-trace.ts

@@ -0,0 +1,163 @@
+/**
+ * AP-Trace schema - Audit log format for agent decisions.
+ *
+ * Defines the AP-Trace structure per SPEC Section 5. An AP-Trace entry
+ * records an agent's decision process.
+ *
+ * @see SPEC.md Section 5 for complete specification.
+ */
+
+/** Type of action taken or considered. */
+export type ActionType = "recommend" | "execute" | "escalate" | "deny";
+
+/** How the action relates to the autonomy envelope. */
+export type ActionCategory = "bounded" | "escalation_trigger" | "forbidden";
+
+/** Status of an escalation. */
+export type EscalationStatus = "pending" | "approved" | "denied" | "timeout";
+
+/** Resource affected by the action. */
+export interface ActionTarget {
+  /** Resource type */
+  type: string;
+  /** Resource identifier */
+  identifier: string;
+}
+
+/** Action taken or considered (SPEC Section 5.4). */
+export interface Action {
+  /** Action type */
+  type: ActionType;
+  /** Human-readable action name */
+  name: string;
+  /** How this action relates to autonomy envelope */
+  category: ActionCategory;
+  /** Resource affected */
+  target?: ActionTarget | null;
+  /** Action parameters */
+  parameters?: Record<string, unknown> | null;
+}
+
+/** An alternative considered during decision-making. */
+export interface Alternative {
+  /** Unique identifier for this option */
+  option_id: string;
+  /** Human-readable description */
+  description: string;
+  /** Computed score (0.0 to 1.0) */
+  score?: number | null;
+  /** Breakdown of score components */
+  scoring_factors?: Record<string, number> | null;
+  /** Concerns or flags about this option */
+  flags?: string[] | null;
+}
+
+/** Decision process record (SPEC Section 5.5). */
+export interface Decision {
+  /** Options evaluated (minimum 1) */
+  alternatives_considered: Alternative[];
+  /** Option ID selected */
+  selected: string;
+  /** Human-readable explanation of why this was chosen */
+  selection_reasoning: string;
+  /** Values that influenced this decision */
+  values_applied: string[];
+  /** Decision confidence (0.0 to 1.0) */
+  confidence?: number | null;
+}
+
+/** Record of checking an escalation trigger. */
+export interface TriggerCheck {
+  /** Trigger condition that was checked */
+  trigger: string;
+  /** Whether the trigger matched */
+  matched: boolean;
+  /** Observed value (for comparison triggers) */
+  value_observed?: unknown | null;
+}
+
+/** Response from principal to escalation. */
+export interface PrincipalResponse {
+  /** Principal's decision */
+  decision: string;
+  /** When decision was made (ISO 8601) */
+  timestamp: string;
+  /** Conditions attached to approval */
+  conditions?: string[] | null;
+}
+
+/** Escalation evaluation record (SPEC Section 5.6). */
+export interface Escalation {
+  /** Whether escalation was evaluated */
+  evaluated: boolean;
+  /** Triggers that were evaluated */
+  triggers_checked?: TriggerCheck[] | null;
+  /** Whether escalation is required */
+  required: boolean;
+  /** Human-readable explanation */
+  reason: string;
+  /** Escalation request ID (if escalation required) */
+  escalation_id?: string | null;
+  /** Status of escalation (if escalation required) */
+  escalation_status?: EscalationStatus | null;
+  /** Principal's response (if escalation required) */
+  principal_response?: PrincipalResponse | null;
+}
+
+/** Additional context for the trace (SPEC Section 5.7). */
+export interface TraceContext {
+  /** Session identifier */
+  session_id?: string | null;
+  /** Turn number in conversation */
+  conversation_turn?: number | null;
+  /** IDs of related prior traces */
+  prior_trace_ids?: string[] | null;
+  /** Environment metadata (client, locale, etc.) */
+  environment?: Record<string, unknown> | null;
+  /** Additional arbitrary metadata */
+  metadata?: Record<string, unknown> | null;
+}
+
+/**
+ * AP-Trace - Audit log entry for agent decisions (SPEC Section 5).
+ *
+ * An AP-Trace records an agent's decision process, enabling verification
+ * that observed behavior is consistent with declared alignment.
+ */
+export interface APTrace {
+  /** Unique identifier (UUID) */
+  trace_id: string;
+  /** Agent that generated this trace */
+  agent_id: string;
+  /** Alignment Card in effect */
+  card_id: string;
+  /** When this trace was created (ISO 8601) */
+  timestamp: string;
+  /** Action taken or considered */
+  action: Action;
+  /** Decision process record */
+  decision: Decision;
+  /** Escalation evaluation (if applicable) */
+  escalation?: Escalation | null;
+  /** Additional context */
+  context?: TraceContext | null;
+}
+
+// Utility functions
+
+/** Get the selected alternative from the decision. */
+export function getSelectedAlternative(trace: APTrace): Alternative | undefined {
+  return trace.decision.alternatives_considered.find(
+    (alt) => alt.option_id === trace.decision.selected
+  );
+}
+
+/** Check if this decision was escalated. */
+export function wasEscalated(trace: APTrace): boolean {
+  return trace.escalation != null && trace.escalation.required;
+}
+
+/** Check if the action was forbidden or triggered unhandled escalation. */
+export function hadViolations(trace: APTrace): boolean {
+  return trace.action.category === "forbidden";
+}

package/src/schemas/index.ts

@@ -0,0 +1,7 @@
+/**
+ * AAP Schema exports.
+ */
+
+export * from "./alignment-card";
+export * from "./ap-trace";
+export * from "./value-coherence";

package/src/schemas/value-coherence.ts

@@ -0,0 +1,177 @@
+/**
+ * Value Coherence Handshake messages - Agent-to-agent alignment verification.
+ *
+ * Defines the message types for the Value Coherence Handshake protocol
+ * per SPEC Section 6.
+ *
+ * @see SPEC.md Section 6 for complete specification.
+ */
+
+import type { AlignmentCard } from "./alignment-card";
+
+/** Information about the agent making a request. */
+export interface RequesterInfo {
+  /** Agent identifier (DID, URL, or UUID) */
+  agent_id: string;
+  /** Requester's Alignment Card ID */
+  card_id: string;
+}
+
+/** Context about the task for which alignment is being checked. */
+export interface TaskContext {
+  /** Type of task being proposed */
+  task_type: string;
+  /** Values required for this task */
+  values_required?: string[] | null;
+  /** Categories of data involved */
+  data_categories?: string[] | null;
+}
+
+/** Request for an agent's Alignment Card (SPEC Section 6.3.1). */
+export interface AlignmentCardRequest {
+  /** Message type identifier */
+  message_type?: "alignment_card_request";
+  /** Unique request identifier */
+  request_id: string;
+  /** Information about requesting agent */
+  requester: RequesterInfo;
+  /** Context about the proposed task */
+  task_context?: TaskContext | null;
+  /** When request was made (ISO 8601) */
+  timestamp?: string;
+}
+
+/** Cryptographic signature for authentication. */
+export interface Signature {
+  /** Signature algorithm (e.g., Ed25519) */
+  algorithm: string;
+  /** Base64-encoded signature */
+  value: string;
+  /** Key identifier */
+  key_id: string;
+}
+
+/** Response with an agent's Alignment Card (SPEC Section 6.3.2). */
+export interface AlignmentCardResponse {
+  /** Message type identifier */
+  message_type?: "alignment_card_response";
+  /** Request ID being responded to */
+  request_id: string;
+  /** Responder's Alignment Card */
+  alignment_card: AlignmentCard;
+  /** Optional signature for authentication */
+  signature?: Signature | null;
+  /** When response was made (ISO 8601) */
+  timestamp?: string;
+}
+
+/** Data sharing specification for collaboration. */
+export interface DataSharing {
+  /** Data categories initiator will share */
+  from_initiator?: string[];
+  /** Data categories responder will share */
+  from_responder?: string[];
+}
+
+/** Scope of autonomous actions for collaboration. */
+export interface AutonomyScope {
+  /** Actions initiator may take */
+  initiator_actions?: string[];
+  /** Actions responder may take */
+  responder_actions?: string[];
+}
+
+/** Proposed collaboration details. */
+export interface ProposedCollaboration {
+  /** Type of task */
+  task_type: string;
+  /** Values both agents should apply */
+  values_intersection?: string[] | null;
+  /** Data sharing specification */
+  data_sharing?: DataSharing | null;
+  /** Scope of autonomous actions */
+  autonomy_scope?: AutonomyScope | null;
+}
+
+/** Value coherence check request (SPEC Section 6.3.3). */
+export interface ValueCoherenceCheck {
+  /** Message type identifier */
+  message_type?: "value_coherence_check";
+  /** Request ID */
+  request_id: string;
+  /** Initiator's Alignment Card ID */
+  initiator_card_id: string;
+  /** Responder's Alignment Card ID */
+  responder_card_id: string;
+  /** Proposed collaboration details */
+  proposed_collaboration: ProposedCollaboration;
+  /** When check was requested (ISO 8601) */
+  timestamp?: string;
+}
+
+/** A conflict between values declared by two agents. */
+export interface ValueConflict {
+  /** 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;
+}
+
+/** Detailed value alignment analysis. */
+export interface ValueAlignmentDetail {
+  /** Values present in both cards */
+  matched?: string[];
+  /** Values in one card but not the other */
+  unmatched?: string[];
+  /** Direct value conflicts */
+  conflicts?: ValueConflict[];
+}
+
+/** Coherence assessment. */
+export interface Coherence {
+  /** Whether agents are compatible */
+  compatible: boolean;
+  /** Coherence score (0.0 to 1.0) */
+  score: number;
+  /** Detailed alignment analysis */
+  value_alignment: ValueAlignmentDetail;
+}
+
+/** Proposed resolution for value conflicts. */
+export interface ProposedResolution {
+  /** Resolution type */
+  type: string;
+  /** Why this resolution is proposed */
+  reason: string;
+  /** Alternative proposal (if applicable) */
+  alternative?: Record<string, unknown> | null;
+}
+
+/** Coherence result message (SPEC Section 6.3.4). */
+export interface CoherenceResultMessage {
+  /** Message type identifier */
+  message_type?: "coherence_result";
+  /** Request ID being responded to */
+  request_id: string;
+  /** Coherence assessment */
+  coherence: Coherence;
+  /** Whether to proceed with coordination */
+  proceed: boolean;
+  /** Conditions for proceeding (if any) */
+  conditions?: string[] | null;
+  /** Proposed resolution (if conflicts exist) */
+  proposed_resolution?: ProposedResolution | null;
+  /** When result was generated (ISO 8601) */
+  timestamp?: string;
+}
+
+/** Union of all Value Coherence Handshake message types. */
+export type ValueCoherenceMessage =
+  | AlignmentCardRequest
+  | AlignmentCardResponse
+  | ValueCoherenceCheck
+  | CoherenceResultMessage;