@longarc/mdash 3.1.1 → 3.1.3

package/src/context/provenance.ts

@@ -0,0 +1,380 @@
+/**
+ * Caret — Provenance Chain Implementation
+ * @module @longarcstudios/caret/provenance
+ * 
+ * Immutable provenance tracking for context fragments.
+ * Every fragment knows exactly where it came from.
+ */
+
+import type {
+  ProvenanceRecord,
+  ProvenanceChain,
+  SourceURI,
+  Attribution,
+  TrustLevel,
+  Timestamp,
+  Hash,
+} from './types.js';
+import { sha256Object, rollingHash } from './crypto/hash.js';
+
+// ============================================================================
+// FACTORY FUNCTIONS
+// ============================================================================
+
+/**
+ * Create a new ProvenanceRecord.
+ */
+export async function createProvenanceRecord(options: {
+  source: SourceURI | string;
+  attribution: Attribution;
+  trust_level?: number;
+  parent_hash?: Hash | null;
+  signature?: string;
+}): Promise<ProvenanceRecord> {
+  const trust = validateTrustLevel(options.trust_level ?? getDefaultTrust(options.attribution));
+  
+  return {
+    source: options.source as SourceURI,
+    attribution: options.attribution,
+    trust_level: trust,
+    timestamp: new Date().toISOString() as Timestamp,
+    parent_hash: options.parent_hash ?? null,
+    signature: options.signature,
+  };
+}
+
+/**
+ * Create a new ProvenanceChain with a single record.
+ */
+export async function createProvenanceChain(
+  record: ProvenanceRecord
+): Promise<ProvenanceChain> {
+  const chain_hash = await sha256Object(record);
+  
+  return {
+    head: record,
+    tail: null,
+    length: 1,
+    chain_hash,
+  };
+}
+
+/**
+ * Extend an existing ProvenanceChain with a new record.
+ * Returns a new chain (immutable).
+ */
+export async function extendProvenanceChain(
+  chain: ProvenanceChain,
+  record: ProvenanceRecord
+): Promise<ProvenanceChain> {
+  // Update record's parent_hash to point to current chain
+  const linkedRecord: ProvenanceRecord = {
+    ...record,
+    parent_hash: chain.chain_hash,
+  };
+  
+  // Compute new chain hash
+  const recordHash = await sha256Object(linkedRecord);
+  const chain_hash = await rollingHash([chain.chain_hash, recordHash]);
+  
+  return {
+    head: linkedRecord,
+    tail: chain,
+    length: chain.length + 1,
+    chain_hash,
+  };
+}
+
+// ============================================================================
+// CHAIN OPERATIONS
+// ============================================================================
+
+/**
+ * Get all records in the chain as an array (head to tail).
+ */
+export function flattenChain(chain: ProvenanceChain): ProvenanceRecord[] {
+  const records: ProvenanceRecord[] = [];
+  let current: ProvenanceChain | null = chain;
+  
+  while (current !== null) {
+    records.push(current.head);
+    current = current.tail;
+  }
+  
+  return records;
+}
+
+/**
+ * Find a record in the chain by source URI.
+ */
+export function findBySource(
+  chain: ProvenanceChain,
+  source: SourceURI | string
+): ProvenanceRecord | null {
+  let current: ProvenanceChain | null = chain;
+  
+  while (current !== null) {
+    if (current.head.source === source) {
+      return current.head;
+    }
+    current = current.tail;
+  }
+  
+  return null;
+}
+
+/**
+ * Get the minimum trust level in the chain.
+ */
+export function getMinTrust(chain: ProvenanceChain): TrustLevel {
+  let min = chain.head.trust_level;
+  let current: ProvenanceChain | null = chain.tail;
+  
+  while (current !== null) {
+    if (current.head.trust_level < min) {
+      min = current.head.trust_level;
+    }
+    current = current.tail;
+  }
+  
+  return min;
+}
+
+/**
+ * Get the maximum trust level in the chain.
+ */
+export function getMaxTrust(chain: ProvenanceChain): TrustLevel {
+  let max = chain.head.trust_level;
+  let current: ProvenanceChain | null = chain.tail;
+  
+  while (current !== null) {
+    if (current.head.trust_level > max) {
+      max = current.head.trust_level;
+    }
+    current = current.tail;
+  }
+  
+  return max;
+}
+
+/**
+ * Check if chain contains a specific attribution type.
+ */
+export function hasAttribution(
+  chain: ProvenanceChain,
+  attribution: Attribution
+): boolean {
+  let current: ProvenanceChain | null = chain;
+  
+  while (current !== null) {
+    if (current.head.attribution === attribution) {
+      return true;
+    }
+    current = current.tail;
+  }
+  
+  return false;
+}
+
+/**
+ * Get all unique attributions in the chain.
+ */
+export function getAttributions(chain: ProvenanceChain): Attribution[] {
+  const attributions = new Set<Attribution>();
+  let current: ProvenanceChain | null = chain;
+  
+  while (current !== null) {
+    attributions.add(current.head.attribution);
+    current = current.tail;
+  }
+  
+  return Array.from(attributions);
+}
+
+// ============================================================================
+// CHAIN VERIFICATION
+// ============================================================================
+
+/**
+ * Verify the integrity of a provenance chain.
+ * Checks that all hash links are valid.
+ */
+export async function verifyChain(chain: ProvenanceChain): Promise<{
+  valid: boolean;
+  errors: string[];
+}> {
+  const errors: string[] = [];
+  
+  // Single-record chain
+  if (chain.length === 1) {
+    const expectedHash = await sha256Object(chain.head);
+    if (expectedHash !== chain.chain_hash) {
+      errors.push('Chain hash mismatch for single-record chain');
+    }
+    return { valid: errors.length === 0, errors };
+  }
+  
+  // Multi-record chain
+  let current: ProvenanceChain | null = chain;
+  const recordHashes: Hash[] = [];
+  
+  while (current !== null) {
+    const recordHash = await sha256Object(current.head);
+    recordHashes.unshift(recordHash); // Add to front (we're traversing head to tail)
+    
+    // Check parent_hash linkage
+    if (current.tail !== null && current.head.parent_hash !== current.tail.chain_hash) {
+      errors.push(`Parent hash mismatch at depth ${recordHashes.length}`);
+    }
+    
+    current = current.tail;
+  }
+  
+  // Verify rolling hash
+  const expectedChainHash = await computeChainHash(chain);
+  if (expectedChainHash !== chain.chain_hash) {
+    errors.push('Rolling chain hash verification failed');
+  }
+  
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Recompute the chain hash from records.
+ */
+async function computeChainHash(chain: ProvenanceChain): Promise<Hash> {
+  if (chain.tail === null) {
+    return sha256Object(chain.head);
+  }
+  
+  const tailHash = await computeChainHash(chain.tail);
+  const headHash = await sha256Object(chain.head);
+  return rollingHash([tailHash, headHash]);
+}
+
+// ============================================================================
+// CHAIN MERGING
+// ============================================================================
+
+/**
+ * Merge multiple provenance chains into one.
+ * Used when composing multiple fragments into a manifold.
+ * 
+ * Strategy: Creates a new chain with all records, ordered by timestamp.
+ */
+export async function mergeChains(
+  chains: readonly ProvenanceChain[]
+): Promise<ProvenanceChain> {
+  if (chains.length === 0) {
+    throw new Error('Cannot merge empty chain array');
+  }
+  
+  if (chains.length === 1) {
+    const first = chains[0];
+    if (!first) throw new Error('Invalid chain');
+    return first;
+  }
+  
+  // Collect all records
+  const allRecords: ProvenanceRecord[] = [];
+  for (const chain of chains) {
+    allRecords.push(...flattenChain(chain));
+  }
+  
+  // Sort by timestamp (oldest first)
+  allRecords.sort((a, b) => 
+    new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime()
+  );
+  
+  // Deduplicate by source + timestamp
+  const seen = new Set<string>();
+  const uniqueRecords = allRecords.filter(record => {
+    const key = `${record.source}:${record.timestamp}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+  
+  // Build new chain
+  const firstRecord = uniqueRecords[0];
+  if (!firstRecord) {
+    throw new Error('No records to merge');
+  }
+  
+  let result = await createProvenanceChain(firstRecord);
+  
+  for (let i = 1; i < uniqueRecords.length; i++) {
+    const record = uniqueRecords[i];
+    if (record) {
+      result = await extendProvenanceChain(result, record);
+    }
+  }
+  
+  return result;
+}
+
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+
+/**
+ * Get default trust level for an attribution type.
+ */
+function getDefaultTrust(attribution: Attribution): number {
+  switch (attribution) {
+    case 'system':
+      return 100;
+    case 'operator':
+      return 90;
+    case 'user':
+      return 70;
+    case 'derived':
+      return 60;
+    case 'agent':
+      return 50;
+    case 'external':
+      return 30;
+    default:
+      return 50;
+  }
+}
+
+/**
+ * Validate and clamp trust level to 0-100.
+ */
+function validateTrustLevel(value: number): TrustLevel {
+  const clamped = Math.max(0, Math.min(100, Math.round(value)));
+  return clamped as TrustLevel;
+}
+
+/**
+ * Parse a source string into a SourceURI.
+ * Validates the format if strict mode is enabled.
+ */
+export function parseSourceURI(source: string, strict = false): SourceURI {
+  if (strict) {
+    // Validate URI format: scheme://path
+    const uriPattern = /^[a-z][a-z0-9+.-]*:\/\/.+$/i;
+    if (!uriPattern.test(source)) {
+      throw new Error('Invalid source URI format');
+    }
+  }
+  
+  return source as SourceURI;
+}
+
+/**
+ * Create a timestamp for the current moment.
+ */
+export function now(): Timestamp {
+  return new Date().toISOString() as Timestamp;
+}
+
+/**
+ * Check if a timestamp is expired given a max age.
+ */
+export function isExpired(timestamp: Timestamp, maxAgeMs: number): boolean {
+  const then = new Date(timestamp).getTime();
+  const now = Date.now();
+  return (now - then) > maxAgeMs;
+}