@weavelogic/knowledge-graph-agent 0.2.0 → 0.4.0

package/dist/audit/config.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Exochain Audit Configuration
+ *
+ * Configuration for deterministic logging with DAG-BFT consensus.
+ * Supports multiple backends: file, postgres, and memory.
+ *
+ * @module audit/config
+ */
+/**
+ * Storage backend types for audit chain.
+ * - `file`: Local file-based storage with rotation support
+ * - `postgres`: PostgreSQL database with schema isolation
+ * - `memory`: In-memory storage for testing/development
+ */
+export type AuditBackend = 'file' | 'postgres' | 'memory';
+/**
+ * Consensus mechanism types for achieving finality.
+ * - `proof-of-learning`: Learning-based consensus for AI agents
+ * - `byzantine`: Classical BFT consensus (2f+1 validators)
+ * - `raft`: Leader-based consensus for simpler setups
+ * - `gossip`: Epidemic-style eventual consistency
+ * - `none`: No consensus, single-agent mode
+ */
+export type ConsensusType = 'proof-of-learning' | 'byzantine' | 'raft' | 'gossip' | 'none';
+/**
+ * File backend configuration options.
+ */
+export interface FileBackendConfig {
+    /** Directory for storing audit chain data */
+    dataDir: string;
+    /** Maximum file size in bytes before rotation (default: 10MB) */
+    maxFileSize?: number;
+    /** Number of events before rotating to new file */
+    rotateAfterEvents?: number;
+}
+/**
+ * PostgreSQL backend configuration options.
+ */
+export interface PostgresBackendConfig {
+    /** PostgreSQL connection string */
+    connectionString: string;
+    /** Database schema for audit tables */
+    schema: string;
+}
+/**
+ * Audit chain configuration defining storage, consensus, and syndication settings.
+ */
+export interface AuditChainConfig {
+    /** Storage backend type */
+    backend: AuditBackend;
+    /** Agent's DID (Decentralized Identifier) for event signing */
+    agentDid: string;
+    /** Ed25519 private key for signing (64-byte hex string) */
+    privateKey?: string;
+    /** Enable consensus mechanism for finality */
+    enableConsensus: boolean;
+    /** Type of consensus mechanism to use */
+    consensusType: ConsensusType;
+    /** Number of events between checkpoints */
+    checkpointInterval: number;
+    /** File backend configuration (required if backend is 'file') */
+    file?: FileBackendConfig;
+    /** PostgreSQL backend configuration (required if backend is 'postgres') */
+    postgres?: PostgresBackendConfig;
+    /** Peer endpoints for event syndication */
+    peers?: string[];
+    /** Enable automatic peer syndication */
+    enableSyndication: boolean;
+    /** Interval between syndication attempts in milliseconds */
+    syndicationInterval?: number;
+}
+/**
+ * Default checkpoint interval (every 100 events).
+ */
+export declare const DEFAULT_CHECKPOINT_INTERVAL = 100;
+/**
+ * Default syndication interval (5 minutes).
+ */
+export declare const DEFAULT_SYNDICATION_INTERVAL: number;
+/**
+ * Default maximum file size for file backend (10MB).
+ */
+export declare const DEFAULT_MAX_FILE_SIZE: number;
+/**
+ * Default number of events before file rotation.
+ */
+export declare const DEFAULT_ROTATE_AFTER_EVENTS = 10000;
+/**
+ * Create audit chain configuration from environment variables.
+ *
+ * Environment variables:
+ * - `EXOCHAIN_BACKEND`: Storage backend (file|postgres|memory)
+ * - `EXOCHAIN_AGENT_DID`: Agent's decentralized identifier
+ * - `EXOCHAIN_PRIVATE_KEY`: Ed25519 private key for signing
+ * - `EXOCHAIN_ENABLE_CONSENSUS`: Enable consensus (true|false)
+ * - `EXOCHAIN_CONSENSUS_TYPE`: Consensus mechanism type
+ * - `EXOCHAIN_CHECKPOINT_INTERVAL`: Events between checkpoints
+ * - `EXOCHAIN_ENABLE_SYNDICATION`: Enable peer syndication
+ * - `EXOCHAIN_SYNDICATION_INTERVAL`: Syndication interval in ms
+ * - `EXOCHAIN_PEER_ENDPOINTS`: Comma-separated peer URLs
+ * - `EXOCHAIN_DATA_DIR`: Data directory for file backend
+ * - `EXOCHAIN_MAX_FILE_SIZE`: Max file size for file backend
+ * - `EXOCHAIN_ROTATE_AFTER_EVENTS`: Events before file rotation
+ * - `DATABASE_URL`: PostgreSQL connection string
+ * - `EXOCHAIN_SCHEMA`: PostgreSQL schema name
+ *
+ * @returns Fully populated AuditChainConfig
+ *
+ * @example
+ * ```typescript
+ * // Set environment variables
+ * process.env.EXOCHAIN_BACKEND = 'file';
+ * process.env.EXOCHAIN_DATA_DIR = './audit-data';
+ *
+ * const config = createAuditChainConfig();
+ * ```
+ */
+export declare function createAuditChainConfig(): AuditChainConfig;
+/**
+ * Validation result for audit chain configuration.
+ */
+export interface ConfigValidationResult {
+    /** Whether the configuration is valid */
+    valid: boolean;
+    /** List of validation error messages */
+    errors: string[];
+}
+/**
+ * Validate audit chain configuration for completeness and consistency.
+ *
+ * @param config - The configuration to validate
+ * @returns Validation result with errors if invalid
+ *
+ * @example
+ * ```typescript
+ * const config = createAuditChainConfig();
+ * const result = validateAuditChainConfig(config);
+ *
+ * if (!result.valid) {
+ *   console.error('Configuration errors:', result.errors);
+ * }
+ * ```
+ */
+export declare function validateAuditChainConfig(config: AuditChainConfig): ConfigValidationResult;
+/**
+ * Default configuration created from environment variables.
+ * This is a convenience export for simple use cases.
+ */
+export declare const defaultConfig: AuditChainConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/audit/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/audit/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE3F;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,mCAAmC;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2BAA2B;IAC3B,OAAO,EAAE,YAAY,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,eAAe,EAAE,OAAO,CAAC;IACzB,yCAAyC;IACzC,aAAa,EAAE,aAAa,CAAC;IAC7B,2CAA2C;IAC3C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,wCAAwC;IACxC,iBAAiB,EAAE,OAAO,CAAC;IAC3B,4DAA4D;IAC5D,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;GAEG;AACH,eAAO,MAAM,4BAA4B,QAAgB,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,qBAAqB,QAAmB,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,2BAA2B,QAAQ,CAAC;AAmBjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,CAgDzD;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,KAAK,EAAE,OAAO,CAAC;IACf,wCAAwC;IACxC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,gBAAgB,GAAG,sBAAsB,CA2DzF;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,kBAA2B,CAAC"}

package/dist/audit/config.js

@@ -0,0 +1,111 @@
+const DEFAULT_CHECKPOINT_INTERVAL = 100;
+const DEFAULT_SYNDICATION_INTERVAL = 5 * 60 * 1e3;
+const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;
+const DEFAULT_ROTATE_AFTER_EVENTS = 1e4;
+function generateDefaultDid() {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 10);
+  return `did:exo:agent-${timestamp}${random}`;
+}
+function createAuditChainConfig() {
+  const backend = process.env.EXOCHAIN_BACKEND || "memory";
+  const baseConfig = {
+    backend,
+    agentDid: process.env.EXOCHAIN_AGENT_DID || generateDefaultDid(),
+    privateKey: process.env.EXOCHAIN_PRIVATE_KEY,
+    enableConsensus: process.env.EXOCHAIN_ENABLE_CONSENSUS === "true",
+    consensusType: process.env.EXOCHAIN_CONSENSUS_TYPE || "none",
+    checkpointInterval: parseInt(
+      process.env.EXOCHAIN_CHECKPOINT_INTERVAL || String(DEFAULT_CHECKPOINT_INTERVAL),
+      10
+    ),
+    enableSyndication: process.env.EXOCHAIN_ENABLE_SYNDICATION === "true",
+    syndicationInterval: parseInt(
+      process.env.EXOCHAIN_SYNDICATION_INTERVAL || String(DEFAULT_SYNDICATION_INTERVAL),
+      10
+    ),
+    peers: process.env.EXOCHAIN_PEER_ENDPOINTS?.split(",").filter(Boolean) || []
+  };
+  switch (backend) {
+    case "file":
+      return {
+        ...baseConfig,
+        file: {
+          dataDir: process.env.EXOCHAIN_DATA_DIR || ".exochain",
+          maxFileSize: parseInt(
+            process.env.EXOCHAIN_MAX_FILE_SIZE || String(DEFAULT_MAX_FILE_SIZE),
+            10
+          ),
+          rotateAfterEvents: parseInt(
+            process.env.EXOCHAIN_ROTATE_AFTER_EVENTS || String(DEFAULT_ROTATE_AFTER_EVENTS),
+            10
+          )
+        }
+      };
+    case "postgres":
+      return {
+        ...baseConfig,
+        postgres: {
+          connectionString: process.env.DATABASE_URL || "postgres://localhost:5432/kg_agent",
+          schema: process.env.EXOCHAIN_SCHEMA || "exochain"
+        }
+      };
+    default:
+      return baseConfig;
+  }
+}
+function validateAuditChainConfig(config) {
+  const errors = [];
+  if (!config.agentDid) {
+    errors.push("Agent DID is required");
+  } else if (!config.agentDid.startsWith("did:")) {
+    errors.push('Agent DID must be a valid DID (starting with "did:")');
+  }
+  if (config.backend === "file") {
+    if (!config.file?.dataDir) {
+      errors.push("File data directory is required for file backend");
+    }
+    if (config.file?.maxFileSize !== void 0 && config.file.maxFileSize <= 0) {
+      errors.push("Max file size must be positive");
+    }
+    if (config.file?.rotateAfterEvents !== void 0 && config.file.rotateAfterEvents <= 0) {
+      errors.push("Rotate after events must be positive");
+    }
+  }
+  if (config.backend === "postgres") {
+    if (!config.postgres?.connectionString) {
+      errors.push("PostgreSQL connection string is required for postgres backend");
+    }
+    if (!config.postgres?.schema) {
+      errors.push("PostgreSQL schema is required for postgres backend");
+    }
+  }
+  if (config.enableConsensus && config.consensusType === "none") {
+    errors.push("Consensus type must be specified when consensus is enabled");
+  }
+  if (config.enableSyndication && (!config.peers || config.peers.length === 0)) {
+    errors.push("At least one peer is required for syndication");
+  }
+  if (config.checkpointInterval <= 0) {
+    errors.push("Checkpoint interval must be positive");
+  }
+  if (config.syndicationInterval !== void 0 && config.syndicationInterval <= 0) {
+    errors.push("Syndication interval must be positive");
+  }
+  if (config.privateKey !== void 0) {
+    if (!/^[0-9a-fA-F]{128}$/.test(config.privateKey)) {
+      errors.push("Private key must be a 64-byte hex string (128 characters)");
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+createAuditChainConfig();
+export {
+  DEFAULT_CHECKPOINT_INTERVAL,
+  DEFAULT_MAX_FILE_SIZE,
+  DEFAULT_ROTATE_AFTER_EVENTS,
+  DEFAULT_SYNDICATION_INTERVAL,
+  createAuditChainConfig,
+  validateAuditChainConfig
+};
+//# sourceMappingURL=config.js.map

package/dist/audit/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sources":["../../src/audit/config.ts"],"sourcesContent":["/**\n * Exochain Audit Configuration\n *\n * Configuration for deterministic logging with DAG-BFT consensus.\n * Supports multiple backends: file, postgres, and memory.\n *\n * @module audit/config\n */\n\n/**\n * Storage backend types for audit chain.\n * - `file`: Local file-based storage with rotation support\n * - `postgres`: PostgreSQL database with schema isolation\n * - `memory`: In-memory storage for testing/development\n */\nexport type AuditBackend = 'file' | 'postgres' | 'memory';\n\n/**\n * Consensus mechanism types for achieving finality.\n * - `proof-of-learning`: Learning-based consensus for AI agents\n * - `byzantine`: Classical BFT consensus (2f+1 validators)\n * - `raft`: Leader-based consensus for simpler setups\n * - `gossip`: Epidemic-style eventual consistency\n * - `none`: No consensus, single-agent mode\n */\nexport type ConsensusType = 'proof-of-learning' | 'byzantine' | 'raft' | 'gossip' | 'none';\n\n/**\n * File backend configuration options.\n */\nexport interface FileBackendConfig {\n  /** Directory for storing audit chain data */\n  dataDir: string;\n  /** Maximum file size in bytes before rotation (default: 10MB) */\n  maxFileSize?: number;\n  /** Number of events before rotating to new file */\n  rotateAfterEvents?: number;\n}\n\n/**\n * PostgreSQL backend configuration options.\n */\nexport interface PostgresBackendConfig {\n  /** PostgreSQL connection string */\n  connectionString: string;\n  /** Database schema for audit tables */\n  schema: string;\n}\n\n/**\n * Audit chain configuration defining storage, consensus, and syndication settings.\n */\nexport interface AuditChainConfig {\n  /** Storage backend type */\n  backend: AuditBackend;\n  /** Agent's DID (Decentralized Identifier) for event signing */\n  agentDid: string;\n  /** Ed25519 private key for signing (64-byte hex string) */\n  privateKey?: string;\n  /** Enable consensus mechanism for finality */\n  enableConsensus: boolean;\n  /** Type of consensus mechanism to use */\n  consensusType: ConsensusType;\n  /** Number of events between checkpoints */\n  checkpointInterval: number;\n  /** File backend configuration (required if backend is 'file') */\n  file?: FileBackendConfig;\n  /** PostgreSQL backend configuration (required if backend is 'postgres') */\n  postgres?: PostgresBackendConfig;\n  /** Peer endpoints for event syndication */\n  peers?: string[];\n  /** Enable automatic peer syndication */\n  enableSyndication: boolean;\n  /** Interval between syndication attempts in milliseconds */\n  syndicationInterval?: number;\n}\n\n/**\n * Default checkpoint interval (every 100 events).\n */\nexport const DEFAULT_CHECKPOINT_INTERVAL = 100;\n\n/**\n * Default syndication interval (5 minutes).\n */\nexport const DEFAULT_SYNDICATION_INTERVAL = 5 * 60 * 1000;\n\n/**\n * Default maximum file size for file backend (10MB).\n */\nexport const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;\n\n/**\n * Default number of events before file rotation.\n */\nexport const DEFAULT_ROTATE_AFTER_EVENTS = 10000;\n\n/**\n * Generate a default DID for the agent based on timestamp and random component.\n *\n * @returns A unique DID string in the format `did:exo:agent-{timestamp}{random}`\n *\n * @example\n * ```typescript\n * const did = generateDefaultDid();\n * // did:exo:agent-m1abc123xyz\n * ```\n */\nfunction generateDefaultDid(): string {\n  const timestamp = Date.now().toString(36);\n  const random = Math.random().toString(36).substring(2, 10);\n  return `did:exo:agent-${timestamp}${random}`;\n}\n\n/**\n * Create audit chain configuration from environment variables.\n *\n * Environment variables:\n * - `EXOCHAIN_BACKEND`: Storage backend (file|postgres|memory)\n * - `EXOCHAIN_AGENT_DID`: Agent's decentralized identifier\n * - `EXOCHAIN_PRIVATE_KEY`: Ed25519 private key for signing\n * - `EXOCHAIN_ENABLE_CONSENSUS`: Enable consensus (true|false)\n * - `EXOCHAIN_CONSENSUS_TYPE`: Consensus mechanism type\n * - `EXOCHAIN_CHECKPOINT_INTERVAL`: Events between checkpoints\n * - `EXOCHAIN_ENABLE_SYNDICATION`: Enable peer syndication\n * - `EXOCHAIN_SYNDICATION_INTERVAL`: Syndication interval in ms\n * - `EXOCHAIN_PEER_ENDPOINTS`: Comma-separated peer URLs\n * - `EXOCHAIN_DATA_DIR`: Data directory for file backend\n * - `EXOCHAIN_MAX_FILE_SIZE`: Max file size for file backend\n * - `EXOCHAIN_ROTATE_AFTER_EVENTS`: Events before file rotation\n * - `DATABASE_URL`: PostgreSQL connection string\n * - `EXOCHAIN_SCHEMA`: PostgreSQL schema name\n *\n * @returns Fully populated AuditChainConfig\n *\n * @example\n * ```typescript\n * // Set environment variables\n * process.env.EXOCHAIN_BACKEND = 'file';\n * process.env.EXOCHAIN_DATA_DIR = './audit-data';\n *\n * const config = createAuditChainConfig();\n * ```\n */\nexport function createAuditChainConfig(): AuditChainConfig {\n  const backend = (process.env.EXOCHAIN_BACKEND || 'memory') as AuditBackend;\n\n  const baseConfig: AuditChainConfig = {\n    backend,\n    agentDid: process.env.EXOCHAIN_AGENT_DID || generateDefaultDid(),\n    privateKey: process.env.EXOCHAIN_PRIVATE_KEY,\n    enableConsensus: process.env.EXOCHAIN_ENABLE_CONSENSUS === 'true',\n    consensusType: (process.env.EXOCHAIN_CONSENSUS_TYPE || 'none') as ConsensusType,\n    checkpointInterval: parseInt(\n      process.env.EXOCHAIN_CHECKPOINT_INTERVAL || String(DEFAULT_CHECKPOINT_INTERVAL),\n      10\n    ),\n    enableSyndication: process.env.EXOCHAIN_ENABLE_SYNDICATION === 'true',\n    syndicationInterval: parseInt(\n      process.env.EXOCHAIN_SYNDICATION_INTERVAL || String(DEFAULT_SYNDICATION_INTERVAL),\n      10\n    ),\n    peers: process.env.EXOCHAIN_PEER_ENDPOINTS?.split(',').filter(Boolean) || [],\n  };\n\n  switch (backend) {\n    case 'file':\n      return {\n        ...baseConfig,\n        file: {\n          dataDir: process.env.EXOCHAIN_DATA_DIR || '.exochain',\n          maxFileSize: parseInt(\n            process.env.EXOCHAIN_MAX_FILE_SIZE || String(DEFAULT_MAX_FILE_SIZE),\n            10\n          ),\n          rotateAfterEvents: parseInt(\n            process.env.EXOCHAIN_ROTATE_AFTER_EVENTS || String(DEFAULT_ROTATE_AFTER_EVENTS),\n            10\n          ),\n        },\n      };\n    case 'postgres':\n      return {\n        ...baseConfig,\n        postgres: {\n          connectionString: process.env.DATABASE_URL || 'postgres://localhost:5432/kg_agent',\n          schema: process.env.EXOCHAIN_SCHEMA || 'exochain',\n        },\n      };\n    default:\n      return baseConfig;\n  }\n}\n\n/**\n * Validation result for audit chain configuration.\n */\nexport interface ConfigValidationResult {\n  /** Whether the configuration is valid */\n  valid: boolean;\n  /** List of validation error messages */\n  errors: string[];\n}\n\n/**\n * Validate audit chain configuration for completeness and consistency.\n *\n * @param config - The configuration to validate\n * @returns Validation result with errors if invalid\n *\n * @example\n * ```typescript\n * const config = createAuditChainConfig();\n * const result = validateAuditChainConfig(config);\n *\n * if (!result.valid) {\n *   console.error('Configuration errors:', result.errors);\n * }\n * ```\n */\nexport function validateAuditChainConfig(config: AuditChainConfig): ConfigValidationResult {\n  const errors: string[] = [];\n\n  // Required field validation\n  if (!config.agentDid) {\n    errors.push('Agent DID is required');\n  } else if (!config.agentDid.startsWith('did:')) {\n    errors.push('Agent DID must be a valid DID (starting with \"did:\")');\n  }\n\n  // Backend-specific validation\n  if (config.backend === 'file') {\n    if (!config.file?.dataDir) {\n      errors.push('File data directory is required for file backend');\n    }\n    if (config.file?.maxFileSize !== undefined && config.file.maxFileSize <= 0) {\n      errors.push('Max file size must be positive');\n    }\n    if (config.file?.rotateAfterEvents !== undefined && config.file.rotateAfterEvents <= 0) {\n      errors.push('Rotate after events must be positive');\n    }\n  }\n\n  if (config.backend === 'postgres') {\n    if (!config.postgres?.connectionString) {\n      errors.push('PostgreSQL connection string is required for postgres backend');\n    }\n    if (!config.postgres?.schema) {\n      errors.push('PostgreSQL schema is required for postgres backend');\n    }\n  }\n\n  // Consensus validation\n  if (config.enableConsensus && config.consensusType === 'none') {\n    errors.push('Consensus type must be specified when consensus is enabled');\n  }\n\n  // Syndication validation\n  if (config.enableSyndication && (!config.peers || config.peers.length === 0)) {\n    errors.push('At least one peer is required for syndication');\n  }\n\n  // Interval validation\n  if (config.checkpointInterval <= 0) {\n    errors.push('Checkpoint interval must be positive');\n  }\n\n  if (config.syndicationInterval !== undefined && config.syndicationInterval <= 0) {\n    errors.push('Syndication interval must be positive');\n  }\n\n  // Private key validation (if provided)\n  if (config.privateKey !== undefined) {\n    if (!/^[0-9a-fA-F]{128}$/.test(config.privateKey)) {\n      errors.push('Private key must be a 64-byte hex string (128 characters)');\n    }\n  }\n\n  return { valid: errors.length === 0, errors };\n}\n\n/**\n * Default configuration created from environment variables.\n * This is a convenience export for simple use cases.\n */\nexport const defaultConfig = createAuditChainConfig();\n"],"names":[],"mappings":"AAgFO,MAAM,8BAA8B;AAKpC,MAAM,+BAA+B,IAAI,KAAK;AAK9C,MAAM,wBAAwB,KAAK,OAAO;AAK1C,MAAM,8BAA8B;AAa3C,SAAS,qBAA6B;AACpC,QAAM,YAAY,KAAK,IAAA,EAAM,SAAS,EAAE;AACxC,QAAM,SAAS,KAAK,SAAS,SAAS,EAAE,EAAE,UAAU,GAAG,EAAE;AACzD,SAAO,iBAAiB,SAAS,GAAG,MAAM;AAC5C;AAgCO,SAAS,yBAA2C;AACzD,QAAM,UAAW,QAAQ,IAAI,oBAAoB;AAEjD,QAAM,aAA+B;AAAA,IACnC;AAAA,IACA,UAAU,QAAQ,IAAI,sBAAsB,mBAAA;AAAA,IAC5C,YAAY,QAAQ,IAAI;AAAA,IACxB,iBAAiB,QAAQ,IAAI,8BAA8B;AAAA,IAC3D,eAAgB,QAAQ,IAAI,2BAA2B;AAAA,IACvD,oBAAoB;AAAA,MAClB,QAAQ,IAAI,gCAAgC,OAAO,2BAA2B;AAAA,MAC9E;AAAA,IAAA;AAAA,IAEF,mBAAmB,QAAQ,IAAI,gCAAgC;AAAA,IAC/D,qBAAqB;AAAA,MACnB,QAAQ,IAAI,iCAAiC,OAAO,4BAA4B;AAAA,MAChF;AAAA,IAAA;AAAA,IAEF,OAAO,QAAQ,IAAI,yBAAyB,MAAM,GAAG,EAAE,OAAO,OAAO,KAAK,CAAA;AAAA,EAAC;AAG7E,UAAQ,SAAA;AAAA,IACN,KAAK;AACH,aAAO;AAAA,QACL,GAAG;AAAA,QACH,MAAM;AAAA,UACJ,SAAS,QAAQ,IAAI,qBAAqB;AAAA,UAC1C,aAAa;AAAA,YACX,QAAQ,IAAI,0BAA0B,OAAO,qBAAqB;AAAA,YAClE;AAAA,UAAA;AAAA,UAEF,mBAAmB;AAAA,YACjB,QAAQ,IAAI,gCAAgC,OAAO,2BAA2B;AAAA,YAC9E;AAAA,UAAA;AAAA,QACF;AAAA,MACF;AAAA,IAEJ,KAAK;AACH,aAAO;AAAA,QACL,GAAG;AAAA,QACH,UAAU;AAAA,UACR,kBAAkB,QAAQ,IAAI,gBAAgB;AAAA,UAC9C,QAAQ,QAAQ,IAAI,mBAAmB;AAAA,QAAA;AAAA,MACzC;AAAA,IAEJ;AACE,aAAO;AAAA,EAAA;AAEb;AA4BO,SAAS,yBAAyB,QAAkD;AACzF,QAAM,SAAmB,CAAA;AAGzB,MAAI,CAAC,OAAO,UAAU;AACpB,WAAO,KAAK,uBAAuB;AAAA,EACrC,WAAW,CAAC,OAAO,SAAS,WAAW,MAAM,GAAG;AAC9C,WAAO,KAAK,sDAAsD;AAAA,EACpE;AAGA,MAAI,OAAO,YAAY,QAAQ;AAC7B,QAAI,CAAC,OAAO,MAAM,SAAS;AACzB,aAAO,KAAK,kDAAkD;AAAA,IAChE;AACA,QAAI,OAAO,MAAM,gBAAgB,UAAa,OAAO,KAAK,eAAe,GAAG;AAC1E,aAAO,KAAK,gCAAgC;AAAA,IAC9C;AACA,QAAI,OAAO,MAAM,sBAAsB,UAAa,OAAO,KAAK,qBAAqB,GAAG;AACtF,aAAO,KAAK,sCAAsC;AAAA,IACpD;AAAA,EACF;AAEA,MAAI,OAAO,YAAY,YAAY;AACjC,QAAI,CAAC,OAAO,UAAU,kBAAkB;AACtC,aAAO,KAAK,+DAA+D;AAAA,IAC7E;AACA,QAAI,CAAC,OAAO,UAAU,QAAQ;AAC5B,aAAO,KAAK,oDAAoD;AAAA,IAClE;AAAA,EACF;AAGA,MAAI,OAAO,mBAAmB,OAAO,kBAAkB,QAAQ;AAC7D,WAAO,KAAK,4DAA4D;AAAA,EAC1E;AAGA,MAAI,OAAO,sBAAsB,CAAC,OAAO,SAAS,OAAO,MAAM,WAAW,IAAI;AAC5E,WAAO,KAAK,+CAA+C;AAAA,EAC7D;AAGA,MAAI,OAAO,sBAAsB,GAAG;AAClC,WAAO,KAAK,sCAAsC;AAAA,EACpD;AAEA,MAAI,OAAO,wBAAwB,UAAa,OAAO,uBAAuB,GAAG;AAC/E,WAAO,KAAK,uCAAuC;AAAA,EACrD;AAGA,MAAI,OAAO,eAAe,QAAW;AACnC,QAAI,CAAC,qBAAqB,KAAK,OAAO,UAAU,GAAG;AACjD,aAAO,KAAK,2DAA2D;AAAA,IACzE;AAAA,EACF;AAEA,SAAO,EAAE,OAAO,OAAO,WAAW,GAAG,OAAA;AACvC;AAM6B,uBAAA;"}

package/dist/audit/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Audit Module
+ *
+ * Exports all audit-related functionality for deterministic logging
+ * with DAG-BFT consensus support. This module provides:
+ *
+ * - Configuration management for multiple storage backends
+ * - Type definitions for events, checkpoints, and synchronization
+ * - Utility functions for Hybrid Logical Clock operations
+ *
+ * @module audit
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createAuditChainConfig,
+ *   validateAuditChainConfig,
+ *   type LedgerEvent,
+ *   type KnowledgeGraphEventPayload,
+ *   createHLC,
+ * } from './audit/index.js';
+ *
+ * // Create and validate configuration
+ * const config = createAuditChainConfig();
+ * const { valid, errors } = validateAuditChainConfig(config);
+ *
+ * if (!valid) {
+ *   throw new Error(`Invalid config: ${errors.join(', ')}`);
+ * }
+ *
+ * // Create an HLC for event ordering
+ * const hlc = createHLC();
+ * ```
+ */
+export { type AuditBackend, type ConsensusType, type FileBackendConfig, type PostgresBackendConfig, type AuditChainConfig, type ConfigValidationResult, DEFAULT_CHECKPOINT_INTERVAL, DEFAULT_SYNDICATION_INTERVAL, DEFAULT_MAX_FILE_SIZE, DEFAULT_ROTATE_AFTER_EVENTS, createAuditChainConfig, validateAuditChainConfig, defaultConfig, } from './config.js';
+export { type Blake3Hash, type Ed25519Signature, type Did, type HybridLogicalClock, type NodeCreatedPayload, type NodeUpdatedPayload, type NodeDeletedPayload, type EdgeCreatedPayload, type EdgeDeletedPayload, type QueryExecutedPayload, type WorkflowStartedPayload, type WorkflowCompletedPayload, type WorkflowStepCompletedPayload, type GapDetectedPayload, type TaskSpecGeneratedPayload, type ConflictDetectedPayload, type ConflictResolvedPayload, type SyncStartedPayload, type SyncCompletedPayload, type CheckpointCreatedPayload, type KnowledgeGraphEventPayload, type EventEnvelope, type LedgerEvent, type ValidatorSignature, type Checkpoint, type MerkleProof, type SyncRequest, type SyncResponse, type EventQueryOptions, type EventQueryResult, type ChainStatus, type ChainStats, type EventValidation, type ExtractPayload, type EventType, compareHLC, createHLC, mergeHLC, } from './types.js';
+export { AuditChain, createAuditChain } from './services/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/audit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,2BAA2B,EAC3B,4BAA4B,EAC5B,qBAAqB,EACrB,2BAA2B,EAC3B,sBAAsB,EACtB,wBAAwB,EACxB,aAAa,GACd,MAAM,aAAa,CAAC;AAGrB,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,GAAG,EAGR,KAAK,kBAAkB,EAGvB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,4BAA4B,EACjC,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAG7B,KAAK,0BAA0B,EAG/B,KAAK,aAAa,EAClB,KAAK,WAAW,EAGhB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,WAAW,EAGhB,KAAK,WAAW,EAChB,KAAK,YAAY,EAGjB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EAGrB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,eAAe,EAGpB,KAAK,cAAc,EACnB,KAAK,SAAS,EAGd,UAAU,EACV,SAAS,EACT,QAAQ,GACT,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/audit/services/audit-chain.d.ts

@@ -0,0 +1,276 @@
+/**
+ * Audit Chain Service
+ *
+ * Implements deterministic logging with:
+ * - DAG (Directed Acyclic Graph) structure for event ordering
+ * - Hybrid Logical Clocks (HLC) for distributed ordering
+ * - BLAKE3 hashing for event IDs
+ * - Ed25519 signatures for authenticity
+ *
+ * @module audit/services/audit-chain
+ */
+import type { Blake3Hash, KnowledgeGraphEventPayload, LedgerEvent, Checkpoint, MerkleProof, EventQueryOptions, EventQueryResult, ChainStats, EventValidation } from '../types.js';
+import type { AuditChainConfig } from '../config.js';
+/**
+ * Audit Chain class
+ *
+ * Provides:
+ * - Event creation and signing
+ * - DAG-based event storage
+ * - HLC-based ordering
+ * - Checkpoint creation
+ * - Event querying with Merkle proofs
+ *
+ * @example
+ * ```typescript
+ * const chain = createAuditChain({ agentDid: 'did:key:abc123' });
+ *
+ * // Append an event
+ * const event = await chain.appendEvent({
+ *   type: 'NodeCreated',
+ *   nodeId: 'node-1',
+ *   nodeType: 'Document',
+ *   properties: { title: 'My Doc' }
+ * });
+ *
+ * // Query events
+ * const result = await chain.queryEvents({ type: 'NodeCreated', limit: 10 });
+ * ```
+ */
+export declare class AuditChain {
+    private config;
+    private events;
+    private tips;
+    private hlc;
+    private checkpoints;
+    private eventsSinceCheckpoint;
+    /**
+     * Create a new AuditChain instance
+     *
+     * @param config - Partial configuration (merged with defaults)
+     */
+    constructor(config?: Partial<AuditChainConfig>);
+    /**
+     * Tick the HLC and return new timestamp
+     *
+     * Implements the HLC tick algorithm:
+     * - If physical time has advanced, reset logical counter
+     * - Otherwise, increment logical counter
+     *
+     * @returns New HLC timestamp
+     */
+    private tickHLC;
+    /**
+     * Update HLC based on received event
+     *
+     * Implements the HLC receive algorithm:
+     * - Take max of local, remote, and current time
+     * - Adjust logical counter appropriately
+     *
+     * @param received - HLC from received event
+     */
+    private updateHLC;
+    /**
+     * Compare two HLCs
+     *
+     * @param a - First HLC
+     * @param b - Second HLC
+     * @returns Negative if a < b, positive if a > b, zero if equal
+     */
+    private compareHLC;
+    /**
+     * Get current DAG tips (events with no children)
+     *
+     * Tips are the "leaf" events in the DAG that have not been
+     * referenced as parents by any other event.
+     *
+     * @returns Array of tip event IDs
+     */
+    getTips(): Blake3Hash[];
+    /**
+     * Append an event to the chain
+     *
+     * Creates a new event with:
+     * - Current tips as parents (DAG structure)
+     * - New HLC timestamp
+     * - Signature for authenticity
+     *
+     * @param payload - Event payload to append
+     * @returns The created ledger event
+     *
+     * @example
+     * ```typescript
+     * const event = await chain.appendEvent({
+     *   type: 'NodeCreated',
+     *   nodeId: 'doc-1',
+     *   nodeType: 'Document',
+     *   properties: { title: 'README' }
+     * });
+     * console.log('Event ID:', event.id);
+     * ```
+     */
+    appendEvent(payload: KnowledgeGraphEventPayload): Promise<LedgerEvent>;
+    /**
+     * Validate and insert an external event
+     *
+     * Performs validation:
+     * - Signature verification
+     * - Parent existence check
+     * - Causality verification (HLC ordering)
+     * - Event ID recomputation
+     *
+     * @param event - External event to validate and insert
+     * @returns Validation result with details
+     *
+     * @example
+     * ```typescript
+     * const validation = await chain.validateAndInsert(externalEvent);
+     * if (validation.valid) {
+     *   console.log('Event inserted successfully');
+     * } else {
+     *   console.error('Validation failed:', validation.errors);
+     * }
+     * ```
+     */
+    validateAndInsert(event: LedgerEvent): Promise<EventValidation>;
+    /**
+     * Create a checkpoint
+     *
+     * Checkpoints provide:
+     * - Periodic state snapshots
+     * - Efficient verification of chain integrity
+     * - Recovery points for sync
+     *
+     * @returns The created checkpoint
+     */
+    createCheckpoint(): Promise<Checkpoint>;
+    /**
+     * Get the latest checkpoint
+     *
+     * @returns The most recent checkpoint, or null if none exist
+     */
+    getLatestCheckpoint(): Checkpoint | null;
+    /**
+     * Get an event by ID
+     *
+     * @param eventId - Event ID to look up
+     * @returns The event, or null if not found
+     */
+    getEvent(eventId: Blake3Hash): LedgerEvent | null;
+    /**
+     * Query events
+     *
+     * Supports filtering by:
+     * - Event type
+     * - Author DID
+     * - Time range (HLC)
+     * - With optional Merkle proofs
+     *
+     * @param options - Query options
+     * @returns Query result with matching events
+     *
+     * @example
+     * ```typescript
+     * // Get all NodeCreated events
+     * const result = await chain.queryEvents({
+     *   type: 'NodeCreated',
+     *   limit: 50,
+     *   includeProof: true
+     * });
+     *
+     * for (const event of result.events) {
+     *   console.log(event.envelope.payload);
+     * }
+     * ```
+     */
+    queryEvents(options: EventQueryOptions): Promise<EventQueryResult>;
+    /**
+     * Generate a Merkle proof for an event
+     *
+     * @param eventId - Event ID to generate proof for
+     * @returns Merkle proof structure
+     */
+    private generateMerkleProof;
+    /**
+     * Verify a Merkle proof
+     *
+     * @param proof - Proof to verify
+     * @returns Whether the proof is valid
+     */
+    verifyMerkleProof(proof: MerkleProof): boolean;
+    /**
+     * Get chain statistics
+     *
+     * @returns Current chain statistics
+     */
+    getStats(): ChainStats;
+    /**
+     * Get configuration
+     *
+     * @returns Current configuration (copy)
+     */
+    getConfig(): AuditChainConfig;
+    /**
+     * Clear all events (for testing)
+     *
+     * Resets the chain to initial state.
+     */
+    clear(): void;
+    /**
+     * Export chain data
+     *
+     * Exports all events, checkpoints, and tips for backup or sync.
+     *
+     * @returns Exported chain data
+     */
+    export(): {
+        events: LedgerEvent[];
+        checkpoints: Checkpoint[];
+        tips: Blake3Hash[];
+    };
+    /**
+     * Import chain data
+     *
+     * Imports events from external source, validating each.
+     *
+     * @param data - Data to import
+     * @returns Import statistics
+     *
+     * @example
+     * ```typescript
+     * const exported = sourceChain.export();
+     * const { imported, rejected } = await targetChain.import(exported);
+     * console.log(`Imported ${imported} events, rejected ${rejected}`);
+     * ```
+     */
+    import(data: {
+        events: LedgerEvent[];
+        checkpoints?: Checkpoint[];
+    }): Promise<{
+        imported: number;
+        rejected: number;
+    }>;
+}
+/**
+ * Create an audit chain instance
+ *
+ * Factory function for creating AuditChain instances.
+ *
+ * @param config - Optional configuration overrides
+ * @returns New AuditChain instance
+ *
+ * @example
+ * ```typescript
+ * // Create with defaults
+ * const chain = createAuditChain();
+ *
+ * // Create with custom config
+ * const chain = createAuditChain({
+ *   agentDid: 'did:key:myagent',
+ *   backend: 'sqlite',
+ *   sqlitePath: './audit.db'
+ * });
+ * ```
+ */
+export declare function createAuditChain(config?: Partial<AuditChainConfig>): AuditChain;
+//# sourceMappingURL=audit-chain.d.ts.map

package/dist/audit/services/audit-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-chain.d.ts","sourceRoot":"","sources":["../../../src/audit/services/audit-chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,UAAU,EAIV,0BAA0B,EAE1B,WAAW,EACX,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,eAAe,EAChB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAoErD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,MAAM,CAA2C;IACzD,OAAO,CAAC,IAAI,CAA8B;IAC1C,OAAO,CAAC,GAAG,CAAqB;IAChC,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,qBAAqB,CAAa;IAE1C;;;;OAIG;gBACS,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC;IAqB9C;;;;;;;;OAQG;IACH,OAAO,CAAC,OAAO;IAef;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS;IAyBjB;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAOlB;;;;;;;OAOG;IACH,OAAO,IAAI,UAAU,EAAE;IAIvB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,WAAW,CACf,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,WAAW,CAAC;IAuDvB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;IAkErE;;;;;;;;;OASG;IACG,gBAAgB,IAAI,OAAO,CAAC,UAAU,CAAC;IAsC7C;;;;OAIG;IACH,mBAAmB,IAAI,UAAU,GAAG,IAAI;IAIxC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI;IAIjD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,WAAW,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAkDxE;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAuB3B;;;;;OAKG;IACH,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAM9C;;;;OAIG;IACH,QAAQ,IAAI,UAAU;IA0BtB;;;;OAIG;IACH,SAAS,IAAI,gBAAgB;IAI7B;;;;OAIG;IACH,KAAK,IAAI,IAAI;IASb;;;;;;OAMG;IACH,MAAM,IAAI;QACR,MAAM,EAAE,WAAW,EAAE,CAAC;QACtB,WAAW,EAAE,UAAU,EAAE,CAAC;QAC1B,IAAI,EAAE,UAAU,EAAE,CAAC;KACpB;IAQD;;;;;;;;;;;;;;OAcG;IACG,MAAM,CAAC,IAAI,EAAE;QACjB,MAAM,EAAE,WAAW,EAAE,CAAC;QACtB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;KAC5B,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAyBpD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GACjC,UAAU,CAEZ"}