@unrdf/kgc-probe 26.4.2

package/src/index.mjs

@@ -0,0 +1,347 @@
+/**
+ * @fileoverview KGC Probe - Public API
+ *
+ * High-level entry points for:
+ * - Creating probe orchestrator instances
+ * - Registering guards and agents
+ * - Running scans and merging results
+ * - Validating artifacts
+ * - KGC Markdown document validation (frontmatter, blocks, receipts)
+ *
+ * @module @unrdf/kgc-probe
+ */
+
+// ============================================================================
+// ORCHESTRATOR
+// ============================================================================
+
+export { createProbeOrchestrator, ProbeOrchestrator } from './orchestrator.mjs';
+
+// ============================================================================
+// GUARDS REGISTRY
+// ============================================================================
+
+export { createGuardRegistry, GuardRegistry, PATTERNS } from './guards.mjs';
+
+// ============================================================================
+// OBSERVATION VALIDATOR
+// ============================================================================
+
+export { createObservationValidator, ObservationValidator } from './artifact.mjs';
+
+// ============================================================================
+// AGENTS (Factory Functions for 10 probe agents)
+// ============================================================================
+
+export {
+  // Registry
+  createAgentRegistry,
+  AgentRegistry,
+  Agent,
+
+  // 10 Domain Agents
+  OrchestratorAgent,
+  RuntimeAgent,
+  FilesystemAgent,
+  WasmAgent,
+  PerformanceAgent,
+  NetworkAgent,
+  ToolingAgent,
+  StorageAgent,
+  ConcurrencyAgent,
+  SystemAgent,
+
+  // Factory functions
+  createOrchestratorAgent,
+  createRuntimeAgent,
+  createFilesystemAgent,
+  createWasmAgent,
+  createPerformanceAgent,
+  createNetworkAgent,
+  createToolingAgent,
+  createStorageAgent,
+  createConcurrencyAgent,
+  createSystemAgent,
+
+  // Backward compatibility
+  CompletionAgent,
+  ConsistencyAgent,
+  ConformanceAgent,
+  CoverageAgent,
+  CachingAgent,
+  CompletenessAgent,
+  CoherenceAgent,
+  ClusteringAgent,
+  ClassificationAgent,
+  CollaborationAgent,
+  createCompletionAgent,
+  createConsistencyAgent,
+  createConformanceAgent,
+  createCoverageAgent,
+  createCachingAgent,
+  createCompletenessAgent,
+  createCoherenceAgent,
+  createClusteringAgent,
+  createClassificationAgent,
+  createCollaborationAgent
+} from './agents/index.mjs';
+
+// ============================================================================
+// STORAGE BACKENDS
+// ============================================================================
+
+export {
+  MemoryStorage,
+  FileStorage,
+  DatabaseStorage,
+  createMemoryStorage,
+  createFileStorage,
+  createDatabaseStorage,
+  createStorage
+} from './storage/index.mjs';
+
+// ============================================================================
+// RECEIPTS
+// ============================================================================
+
+export {
+  // Constants
+  HASH_ALGORITHM,
+  RECEIPT_VERSION,
+  RECEIPT_TYPES,
+
+  // Hash utilities
+  computeHash,
+  computeChainHash,
+  deterministicSerialize,
+
+  // Merkle
+  buildMerkleTree,
+  verifyMerkleRoot,
+
+  // Receipt creation
+  createObservationReceipt,
+  createMergeReceipt,
+  createVerificationReceipt,
+
+  // Verification
+  verifyObservationReceipt,
+  verifyMergeReceipt,
+  verifyVerificationReceipt,
+
+  // Confidence
+  calculateConfidenceScore,
+  getFailedChecks,
+  summarizeVerification,
+
+  // Chain builder
+  ReceiptChainBuilder,
+  createReceiptChainBuilder
+} from './receipts/index.mjs';
+
+// ============================================================================
+// ARTIFACT OPERATIONS
+// ============================================================================
+
+export {
+  mergeShards,
+  diffArtifacts,
+  verifyArtifact,
+  serializeArtifact,
+  deserializeArtifact,
+  hashObservations,
+  computeArtifactSummary
+} from './artifact.mjs';
+
+// ============================================================================
+// CONVENIENCE: FULL SCAN
+// ============================================================================
+
+export { runProbe } from './probe.mjs';
+
+// ============================================================================
+// ZOD SCHEMAS (All schemas from SPARC specification)
+// ============================================================================
+
+export {
+  // Constants & Regexes
+  SHA256_REGEX,
+  UUID_V4_REGEX,
+  SEMVER_REGEX,
+
+  // KGC Markdown Frontmatter Schemas (Domain 1)
+  SourceSchema,
+  BoundsSchema,
+  AuthorSchema,
+  DiatasisViewSchema,
+  FrontmatterSchema,
+
+  // Block Metadata Schemas (Domain 2)
+  BlockTypeSchema,
+  OutputFormatSchema,
+  DeterminismLevelSchema,
+  BlockMetadataSchema,
+  QueryTypeSchema,
+  ResultBoundsSchema,
+  QueryMetadataSchema,
+  ExtractionTypeSchema,
+  ExtractMetadataSchema,
+  RenderMetadataSchema,
+  ProofTypeSchema,
+  ProofMetadataSchema,
+
+  // Receipt Schemas (Domain 3)
+  DecisionSchema,
+  MerkleProofSchema,
+  ReceiptSchema,
+
+  // Dynamic Section Schemas (Domain 4)
+  DynamicSectionSchema,
+
+  // Error Schemas (Domain 10)
+  ErrorSeveritySchema,
+  ErrorTypeSchema,
+  ProbeErrorSchema,
+  ProbeWarningSchema,
+
+  // Probe Report Schemas
+  DomainResultSchema,
+  ProbeReportSchema,
+
+  // Observation & Artifact Schemas
+  ObservationSchema,
+  ObservationType,
+  ArtifactSummarySchema,
+  ArtifactSchema,
+  ArtifactType,
+
+  // Configuration Schemas
+  ProbeConfigSchema,
+  GuardConfigSchema,
+  StorageConfigSchema,
+
+  // Agent & Guard Schemas
+  AgentSchema,
+  GuardViolationSchema,
+  GuardViolationType,
+
+  // Diff & Result Schemas
+  DiffResultSchema,
+  DiffResultType,
+  ScanResultSchema,
+  ScanResultType
+} from './types.mjs';
+
+// ============================================================================
+// FACTORY FUNCTIONS (25 factories per SPARC specification)
+// ============================================================================
+
+export {
+  // Frontmatter & Sources
+  createFrontmatter,
+  createBounds,
+  createSource,
+  createAuthor,
+
+  // Block Metadata
+  createBlockMetadata,
+  createQueryMetadata,
+  createExtractMetadata,
+  createRenderMetadata,
+  createProofMetadata,
+
+  // Receipts & Proofs
+  createReceipt,
+  createMerkleProof,
+
+  // Observations
+  createObservation,
+
+  // Dynamic Sections
+  createDynamicSection,
+
+  // Errors & Warnings
+  createProbeError,
+  createProbeWarning,
+
+  // Reports & Results
+  createDomainResult,
+  createProbeReport,
+
+  // Configuration
+  createProbeConfig
+} from './types.mjs';
+
+// ============================================================================
+// VALIDATION FUNCTIONS
+// ============================================================================
+
+export {
+  validateObservation,
+  validateArtifact,
+  validateProbeConfig,
+  validateFrontmatter,
+  validateReceipt,
+  tryValidateObservation,
+  tryValidateFrontmatter,
+  tryValidateReceipt
+} from './types.mjs';
+
+// ============================================================================
+// CLI COMMANDS
+// ============================================================================
+
+export {
+  scanCommand,
+  mergeCommand,
+  diffCommand,
+  reportCommand,
+  verifyCommand,
+  probeExtension,
+  ScanArgsSchema,
+  MergeArgsSchema,
+  DiffArgsSchema,
+  ReportArgsSchema,
+  VerifyArgsSchema
+} from './cli.mjs';
+
+// ============================================================================
+// UTILITIES (Logger, Errors)
+// ============================================================================
+
+export {
+  Logger,
+  createLogger,
+  defaultLogger,
+  LOG_LEVELS
+} from './utils/logger.mjs';
+
+export {
+  ProbeError,
+  GuardViolationError,
+  ValidationError,
+  MergeConflictError,
+  ReceiptError,
+  ArtifactNotFoundError,
+  TimeoutError,
+  AgentError,
+  StorageError,
+  ConfigurationError,
+  ErrorCodes,
+  isProbeError,
+  wrapError
+} from './utils/errors.mjs';
+
+// ============================================================================
+// DEFAULT EXPORT (Package Metadata)
+// ============================================================================
+
+/**
+ * Package metadata
+ * @type {Object}
+ */
+export default {
+  name: '@unrdf/kgc-probe',
+  version: '1.0.0',
+  description: 'KGC Probe - Automated knowledge graph integrity scanning with 10 agents and artifact validation'
+};

package/src/merge.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Deterministic merge logic for KGC Probe observations
+ *
+ * Merges observations from multiple agents with stable, deterministic ordering.
+ * Guarantees: Same input → same output hash (critical for receipt verification).
+ *
+ * Design principles:
+ * - Deterministic: Stable sort order, canonical representation
+ * - Composable: Works with any observation source
+ * - Verifiable: Produces consistent hashes
+ * - Fast: O(n log n) merge with minimal overhead
+ */
+
+/**
+ * Severity order for stable sorting (highest priority first)
+ */
+const SEVERITY_ORDER = {
+  fatal: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+  trace: 5
+};
+
+/**
+ * Merge observations from multiple sources with deterministic ordering
+ *
+ * Stable sort order:
+ * 1. Category (alphabetical)
+ * 2. Severity (fatal > error > warn > info > debug > trace)
+ * 3. File path (alphabetical)
+ * 4. Line number (ascending)
+ * 5. Agent ID (alphabetical)
+ * 6. Timestamp (ascending)
+ *
+ * @param {import('./observation.mjs').Observation[]} observations - Observations to merge
+ * @returns {import('./observation.mjs').Observation[]} - Sorted observations
+ */
+export function mergeObservations(observations) {
+  // Stable sort (creates new array)
+  return observations.slice().sort((a, b) => {
+    // 1. Category (alphabetical)
+    if (a.category !== b.category) {
+      return a.category.localeCompare(b.category);
+    }
+
+    // 2. Severity (fatal > error > warn > info > debug > trace)
+    if (a.severity !== b.severity) {
+      return SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];
+    }
+
+    // 3. File path (alphabetical)
+    const aFile = a.location?.file || '';
+    const bFile = b.location?.file || '';
+    if (aFile !== bFile) {
+      return aFile.localeCompare(bFile);
+    }
+
+    // 4. Line number (ascending)
+    const aLine = a.location?.line || 0;
+    const bLine = b.location?.line || 0;
+    if (aLine !== bLine) {
+      return aLine - bLine;
+    }
+
+    // 5. Agent ID (alphabetical)
+    if (a.metadata.agentId !== b.metadata.agentId) {
+      return a.metadata.agentId.localeCompare(b.metadata.agentId);
+    }
+
+    // 6. Timestamp (ascending)
+    return a.metadata.timestamp.localeCompare(b.metadata.timestamp);
+  });
+}
+
+/**
+ * Merge observations from multiple agent shards
+ *
+ * @param {Map<string, import('./observation.mjs').Observation[]>} shards - Agent ID → observations
+ * @returns {import('./observation.mjs').Observation[]} - Merged and sorted observations
+ */
+export function mergeShards(shards) {
+  const allObservations = [];
+
+  for (const [agentId, observations] of shards.entries()) {
+    allObservations.push(...observations);
+  }
+
+  return mergeObservations(allObservations);
+}
+
+/**
+ * Deduplicate observations by content hash
+ *
+ * Useful when multiple agents might emit identical observations.
+ *
+ * @param {import('./observation.mjs').Observation[]} observations
+ * @returns {import('./observation.mjs').Observation[]}
+ */
+export function deduplicateObservations(observations) {
+  const seen = new Set();
+  const unique = [];
+
+  for (const obs of observations) {
+    // Create deterministic content key
+    const key = JSON.stringify({
+      category: obs.category,
+      severity: obs.severity,
+      message: obs.message,
+      location: obs.location,
+      data: obs.data,
+      tags: obs.tags.slice().sort()
+    }, Object.keys(obs).sort());
+
+    if (!seen.has(key)) {
+      seen.add(key);
+      unique.push(obs);
+    }
+  }
+
+  return unique;
+}
+
+/**
+ * Group observations by category
+ *
+ * @param {import('./observation.mjs').Observation[]} observations
+ * @returns {Map<string, import('./observation.mjs').Observation[]>}
+ */
+export function groupByCategory(observations) {
+  const groups = new Map();
+
+  for (const obs of observations) {
+    if (!groups.has(obs.category)) {
+      groups.set(obs.category, []);
+    }
+    groups.get(obs.category).push(obs);
+  }
+
+  return groups;
+}
+
+/**
+ * Group observations by severity
+ *
+ * @param {import('./observation.mjs').Observation[]} observations
+ * @returns {Map<string, import('./observation.mjs').Observation[]>}
+ */
+export function groupBySeverity(observations) {
+  const groups = new Map();
+
+  for (const obs of observations) {
+    if (!groups.has(obs.severity)) {
+      groups.set(obs.severity, []);
+    }
+    groups.get(obs.severity).push(obs);
+  }
+
+  return groups;
+}
+
+/**
+ * Filter observations by category
+ *
+ * @param {import('./observation.mjs').Observation[]} observations
+ * @param {string[]} categories - Categories to include
+ * @returns {import('./observation.mjs').Observation[]}
+ */
+export function filterByCategory(observations, categories) {
+  const categorySet = new Set(categories);
+  return observations.filter(obs => categorySet.has(obs.category));
+}
+
+/**
+ * Filter observations by severity (minimum level)
+ *
+ * @param {import('./observation.mjs').Observation[]} observations
+ * @param {string} minSeverity - Minimum severity level
+ * @returns {import('./observation.mjs').Observation[]}
+ */
+export function filterBySeverity(observations, minSeverity) {
+  const minLevel = SEVERITY_ORDER[minSeverity];
+  return observations.filter(obs => SEVERITY_ORDER[obs.severity] <= minLevel);
+}
+
+export default {
+  mergeObservations,
+  mergeShards,
+  deduplicateObservations,
+  groupByCategory,
+  groupBySeverity,
+  filterByCategory,
+  filterBySeverity
+};