@longarc/mdash 3.1.1 → 3.1.3

package/src/context/utils/atomic.ts

@@ -0,0 +1,207 @@
+/**
+ * Caret — Atomic Encoding Utilities
+ * @module @longarcstudios/caret/utils/atomic
+ * 
+ * Coreference resolution for atomic attestation encoding.
+ * Transforms ambiguous text into explicit references.
+ * 
+ * Rules:
+ * - Pronouns → Agent IDs
+ * - Relative time → ISO 8601 timestamps
+ * - "it/this/that" → Explicit entity IDs
+ * - Ambiguous verbs → MdashActionCode
+ */
+
+import type { CoreferenceContext, MdashActionCode } from '../types.js';
+
+// ============================================================================
+// COREFERENCE PATTERNS
+// ============================================================================
+
+interface CoreferencePattern {
+  pattern: RegExp;
+  resolver: (match: string, context: CoreferenceContext) => string;
+}
+
+const COREFERENCE_PATTERNS: CoreferencePattern[] = [
+  // Pronouns → Agent IDs
+  {
+    pattern: /\b(he|she|it|they)\b/gi,
+    resolver: (_, ctx) => ctx.lastAgentId ?? 'Agent_unknown',
+  },
+  // Relative time → ISO 8601
+  {
+    pattern: /\byesterday\b/gi,
+    resolver: (_, ctx) => {
+      const d = new Date(ctx.referenceTime);
+      d.setDate(d.getDate() - 1);
+      return d.toISOString();
+    },
+  },
+  {
+    pattern: /\btomorrow\b/gi,
+    resolver: (_, ctx) => {
+      const d = new Date(ctx.referenceTime);
+      d.setDate(d.getDate() + 1);
+      return d.toISOString();
+    },
+  },
+  {
+    pattern: /\bnow\b/gi,
+    resolver: (_, ctx) => new Date(ctx.referenceTime).toISOString(),
+  },
+  {
+    pattern: /\btoday\b/gi,
+    resolver: (_, ctx) => {
+      const d = new Date(ctx.referenceTime);
+      d.setHours(0, 0, 0, 0);
+      return d.toISOString();
+    },
+  },
+  // Implicit references → Explicit IDs
+  {
+    pattern: /\bthe warrant\b/gi,
+    resolver: (_, ctx) => ctx.lastWarrantId ?? 'Warrant_unknown',
+  },
+  {
+    pattern: /\bthe checkpoint\b/gi,
+    resolver: (_, ctx) => ctx.lastCheckpointId ?? 'Checkpoint_unknown',
+  },
+  {
+    pattern: /\bthe agent\b/gi,
+    resolver: (_, ctx) => ctx.lastAgentId ?? 'Agent_unknown',
+  },
+];
+
+// ============================================================================
+// MAIN FUNCTIONS
+// ============================================================================
+
+/**
+ * Resolve coreferences in a text string.
+ * Transforms ambiguous language into atomic references.
+ * 
+ * @example
+ * ```ts
+ * const result = resolveCoreferences(
+ *   "He approved it yesterday",
+ *   {
+ *     referenceTime: '2026-01-18T12:00:00Z',
+ *     lastAgentId: 'Agent_0x7f3a',
+ *     lastWarrantId: 'Warrant_0x8b2c'
+ *   }
+ * );
+ * // "Agent_0x7f3a approved Warrant_0x8b2c 2026-01-17T12:00:00.000Z"
+ * ```
+ */
+export function resolveCoreferences(
+  text: string,
+  context: CoreferenceContext
+): string {
+  let resolved = text;
+  
+  for (const { pattern, resolver } of COREFERENCE_PATTERNS) {
+    resolved = resolved.replace(pattern, (match) => resolver(match, context));
+  }
+  
+  return resolved;
+}
+
+/**
+ * Create a default coreference context with current time.
+ */
+export function createDefaultContext(
+  overrides?: Partial<CoreferenceContext>
+): CoreferenceContext {
+  return {
+    referenceTime: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+/**
+ * Check if text contains unresolved coreferences.
+ * Useful for validation before sealing.
+ */
+export function hasUnresolvedCoreferences(text: string): boolean {
+  const patterns = [
+    /\b(he|she|it|they)\b/i,
+    /\b(yesterday|tomorrow|now|today)\b/i,
+    /\bthe (warrant|checkpoint|agent)\b/i,
+  ];
+  
+  return patterns.some(p => p.test(text));
+}
+
+/**
+ * Extract entity IDs from resolved text.
+ * Returns all Agent_, Warrant_, Checkpoint_, User_ prefixed IDs.
+ */
+export function extractEntityIds(text: string): string[] {
+  const pattern = /\b(Agent|Warrant|Checkpoint|User)_[a-f0-9]+\b/gi;
+  const matches = text.match(pattern);
+  return matches ? [...new Set(matches)] : [];
+}
+
+// ============================================================================
+// CANONICAL ENCODING
+// ============================================================================
+
+/**
+ * Atomic attestation structure (pre-hash).
+ */
+export interface AtomicAttestationInput {
+  subject: string;
+  action: MdashActionCode;
+  object?: string;
+  timestamp: string;
+  context?: string;
+}
+
+/**
+ * Create canonical encoding for commitment hash.
+ * Deterministic string representation suitable for hashing.
+ */
+export function canonicalEncode(attestation: AtomicAttestationInput): string {
+  const parts = [
+    attestation.subject,
+    attestation.action,
+    attestation.object ?? '',
+    attestation.timestamp,
+    attestation.context ?? '',
+  ];
+  
+  return parts.join('|');
+}
+
+/**
+ * Compute SHA-256 hash of canonical encoding.
+ * Uses Web Crypto API for cross-platform compatibility.
+ */
+export async function computeCommitmentHash(
+  attestation: AtomicAttestationInput
+): Promise<string> {
+  const canonical = canonicalEncode(attestation);
+  const encoder = new TextEncoder();
+  const data = encoder.encode(canonical);
+  
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  
+  return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Validate atomic attestation subject format.
+ * Must be Entity_hexid pattern.
+ */
+export function isValidSubject(subject: string): boolean {
+  return /^(Agent|Warrant|Checkpoint|User)_[a-f0-9]+$/i.test(subject);
+}
+
+/**
+ * Validate ISO 8601 timestamp format.
+ */
+export function isValidTimestamp(timestamp: string): boolean {
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/.test(timestamp);
+}

package/src/context/utils/credit.ts

@@ -0,0 +1,224 @@
+/**
+ * Caret — Credit Assignment Utilities
+ * @module @longarcstudios/caret/utils/credit
+ * 
+ * Step-wise credit assignment for execution traces.
+ * Distributes terminal reward proportionally to influence consumption.
+ * 
+ * Properties:
+ * - Credits sum to terminal reward (conservation)
+ * - Higher influence steps receive higher credit
+ * - Works for arbitrarily long chains
+ */
+
+import type {
+  ExecutionTrace,
+  CreditAssignment,
+  StepCredit,
+  LiabilityShare,
+  InfluenceBudget,
+  Timestamp,
+} from '../types.js';
+import { sumInfluence } from '../types.js';
+
+// ============================================================================
+// CREDIT ASSIGNMENT
+// ============================================================================
+
+/**
+ * Assign credit to execution steps proportional to influence consumption.
+ * Terminal reward is distributed to all steps based on their contribution.
+ * 
+ * @param trace - Execution trace with steps
+ * @param terminalReward - Final outcome reward to distribute
+ * @returns Credit assignment for all steps
+ * 
+ * @example
+ * ```ts
+ * const credits = assignCredit(trace, 1.0);
+ * // Sum of credits.step_credits[].credit === 1.0
+ * ```
+ */
+export function assignCredit(
+  trace: ExecutionTrace,
+  terminalReward: number
+): CreditAssignment {
+  // Compute total influence
+  const totalInfluence = trace.steps.reduce(
+    (sum, step) => sum + sumInfluence(step.influence_consumed),
+    0
+  );
+  
+  // Distribute credit proportionally
+  const stepCredits: StepCredit[] = trace.steps.map((step) => {
+    const influence = sumInfluence(step.influence_consumed);
+    const influenceFraction = totalInfluence > 0 ? influence / totalInfluence : 0;
+    
+    return {
+      step_id: step.step_id,
+      credit: influenceFraction * terminalReward,
+      influence,
+      influence_fraction: influenceFraction,
+    };
+  });
+  
+  return {
+    trace_id: trace.trace_id,
+    terminal_reward: terminalReward,
+    step_credits: stepCredits,
+    assigned_at: new Date().toISOString() as Timestamp,
+  };
+}
+
+/**
+ * Validate that credit assignment conserves terminal reward.
+ * Credits should sum to terminal reward within tolerance.
+ */
+export function validateCreditAssignment(
+  assignment: CreditAssignment,
+  tolerance: number = 0.001
+): boolean {
+  const creditSum = assignment.step_credits.reduce(
+    (acc, step) => acc + step.credit,
+    0
+  );
+  return Math.abs(creditSum - assignment.terminal_reward) < tolerance;
+}
+
+// ============================================================================
+// LIABILITY ATTRIBUTION
+// ============================================================================
+
+/**
+ * Extract agent ID from step ID.
+ * Convention: step IDs prefixed with agent identifier.
+ */
+function extractAgentId(stepId: string): string {
+  const match = stepId.match(/^(Agent_[a-f0-9]+)/i);
+  return match && match[1] ? match[1] : 'Agent_unknown';
+}
+
+/**
+ * Attribute liability to contributing agents based on influence consumption.
+ * 
+ * @param trace - Execution trace
+ * @returns Liability shares summing to 1.0
+ */
+export function attributeLiability(trace: ExecutionTrace): LiabilityShare[] {
+  // Compute total influence
+  const totalInfluence = trace.steps.reduce(
+    (sum, step) => sum + sumInfluence(step.influence_consumed),
+    0
+  );
+  
+  if (totalInfluence === 0) {
+    return []; // No liability if no influence consumed
+  }
+  
+  // Group steps by agent
+  const agentContributions = new Map<string, {
+    influence: number;
+    steps: string[];
+  }>();
+  
+  for (const step of trace.steps) {
+    const agentId = extractAgentId(step.step_id);
+    const stepInfluence = sumInfluence(step.influence_consumed);
+    
+    const existing = agentContributions.get(agentId) ?? { influence: 0, steps: [] };
+    existing.influence += stepInfluence;
+    existing.steps.push(step.step_id);
+    agentContributions.set(agentId, existing);
+  }
+  
+  // Convert to liability shares
+  return Array.from(agentContributions.entries()).map(([agentId, data]) => ({
+    agent_id: agentId,
+    contribution: data.influence / totalInfluence,
+    evidence: data.steps,
+  }));
+}
+
+/**
+ * Validate that liability shares sum to 1.0 within tolerance.
+ */
+export function validateLiabilityShares(
+  shares: LiabilityShare[],
+  tolerance: number = 0.001
+): boolean {
+  if (shares.length === 0) return true; // Empty is valid
+  
+  const sum = shares.reduce((acc, share) => acc + share.contribution, 0);
+  return Math.abs(sum - 1.0) < tolerance;
+}
+
+// ============================================================================
+// INFLUENCE UTILITIES
+// ============================================================================
+
+/**
+ * Create MCCA-compliant default influence budget.
+ */
+export function createDefaultInfluenceBudget(): InfluenceBudget {
+  return {
+    system: 0.45,
+    user: 0.30,
+    environment: 0.15,
+    assistant: 0.10,
+  };
+}
+
+/**
+ * Check if influence budget is MCCA-compliant.
+ */
+export function isMCCACompliant(budget: InfluenceBudget): boolean {
+  return (
+    budget.system >= 0.40 &&
+    budget.user <= 0.35 &&
+    budget.environment <= 0.20 &&
+    budget.assistant <= 0.25
+  );
+}
+
+/**
+ * Normalize influence budget to sum to 1.0.
+ */
+export function normalizeInfluenceBudget(budget: InfluenceBudget): InfluenceBudget {
+  const total = sumInfluence(budget);
+  
+  if (total === 0) {
+    return createDefaultInfluenceBudget();
+  }
+  
+  return {
+    system: budget.system / total,
+    user: budget.user / total,
+    environment: budget.environment / total,
+    assistant: budget.assistant / total,
+  };
+}
+
+/**
+ * Add two influence budgets.
+ */
+export function addInfluenceBudgets(
+  a: InfluenceBudget,
+  b: InfluenceBudget
+): InfluenceBudget {
+  return {
+    system: a.system + b.system,
+    user: a.user + b.user,
+    environment: a.environment + b.environment,
+    assistant: a.assistant + b.assistant,
+  };
+}
+
+/**
+ * Compute total influence consumed in a trace.
+ */
+export function computeTraceInfluence(trace: ExecutionTrace): InfluenceBudget {
+  return trace.steps.reduce(
+    (total, step) => addInfluenceBudgets(total, step.influence_consumed),
+    { system: 0, user: 0, environment: 0, assistant: 0 }
+  );
+}

package/src/context/utils/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Caret — Utility Functions
+ * @module @longarcstudios/caret/utils
+ * 
+ * Research pattern utilities for Caret v0.2.0:
+ * - Atomic encoding (coreference resolution)
+ * - Utility learning (incremental score updates)
+ * - Credit assignment (step-wise reward distribution)
+ */
+
+export * from './atomic.js';
+export * from './utility.js';
+export * from './credit.js';

package/src/context/utils/utility.ts

@@ -0,0 +1,200 @@
+/**
+ * Caret — Utility Learning Functions
+ * @module @longarcstudios/caret/utils/utility
+ * 
+ * Incremental utility score learning.
+ * Implements: score ← score + α(reward - score)
+ */
+
+import type {
+  Outcome,
+  UtilityScore,
+  UtilityFeedback,
+} from '../types.js';
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+/** Default learning rate for utility updates */
+const DEFAULT_ALPHA = 0.1;
+
+/** Confidence saturation constant (updates needed for ~90% confidence) */
+const CONFIDENCE_TAU = 10;
+
+// ============================================================================
+// UTILITY UPDATE
+// ============================================================================
+
+/**
+ * Update utility score based on feedback.
+ * Implements incremental learning: score ← score + α(reward - score)
+ * 
+ * @param current - Current utility score
+ * @param feedback - Feedback to incorporate
+ * @param alpha - Learning rate (default 0.1)
+ * @returns Updated utility score (immutable)
+ * 
+ * @example
+ * ```ts
+ * const updated = updateUtilityScore(
+ *   { score: 0.5, confidence: 0.3, update_count: 3 },
+ *   { reward: 0.8, source: 'human', timestamp: '2026-01-18T12:00:00Z' }
+ * );
+ * // { score: 0.53, confidence: 0.33, update_count: 4 }
+ * ```
+ */
+export function updateUtilityScore(
+  current: UtilityScore,
+  feedback: UtilityFeedback,
+  alpha: number = DEFAULT_ALPHA
+): UtilityScore {
+  // Clamp feedback reward to [-1, 1]
+  const reward = Math.max(-1, Math.min(1, feedback.reward));
+  
+  // Incremental update
+  const newScore = Math.max(-1, Math.min(1,
+    current.score + alpha * (reward - current.score)
+  ));
+  
+  // Update confidence based on count
+  const newCount = current.update_count + 1;
+  const newConfidence = Math.min(0.99, 1 - Math.exp(-newCount / CONFIDENCE_TAU));
+  
+  return {
+    score: newScore,
+    confidence: newConfidence,
+    update_count: newCount,
+  };
+}
+
+/**
+ * Update an Outcome's utility score based on feedback.
+ * Returns a new Outcome with updated utility (immutable).
+ */
+export function updateOutcomeUtility<T>(
+  outcome: Outcome<T>,
+  feedback: UtilityFeedback,
+  alpha: number = DEFAULT_ALPHA
+): Outcome<T> {
+  return {
+    ...outcome,
+    utility: updateUtilityScore(outcome.utility, feedback, alpha),
+  };
+}
+
+// ============================================================================
+// UTILITY INITIALIZATION
+// ============================================================================
+
+/**
+ * Create a fresh utility score (no observations yet).
+ */
+export function createInitialUtility(priorScore: number = 0): UtilityScore {
+  return {
+    score: Math.max(-1, Math.min(1, priorScore)),
+    confidence: 0,
+    update_count: 0,
+  };
+}
+
+/**
+ * Create utility score from historical observations.
+ */
+export function createUtilityFromHistory(
+  rewards: number[],
+  alpha: number = DEFAULT_ALPHA
+): UtilityScore {
+  let utility = createInitialUtility();
+  
+  for (const reward of rewards) {
+    utility = updateUtilityScore(
+      utility,
+      { reward, source: 'system', timestamp: new Date().toISOString() as any },
+      alpha
+    );
+  }
+  
+  return utility;
+}
+
+// ============================================================================
+// UTILITY PREDICTION
+// ============================================================================
+
+/**
+ * Predict success probability from historical outcomes.
+ * Uses exponential moving average with recency bias.
+ * 
+ * @param historicalScores - Array of past utility scores
+ * @param decayFactor - Weight decay per position (default 0.9)
+ * @returns Predicted success probability [0, 1]
+ */
+export function predictSuccess(
+  historicalScores: UtilityScore[],
+  decayFactor: number = 0.9
+): number {
+  if (historicalScores.length === 0) {
+    return 0.5; // Uninformative prior
+  }
+  
+  // Sort by update count (proxy for recency if no timestamps)
+  const sorted = [...historicalScores].sort(
+    (a, b) => b.update_count - a.update_count
+  );
+  
+  let weightedSum = 0;
+  let weightSum = 0;
+  
+  for (let i = 0; i < sorted.length; i++) {
+    const score = sorted[i];
+    if (!score) continue;
+    
+    const weight = Math.pow(decayFactor, i);
+    // Map score from [-1, 1] to [0, 1] for probability
+    const prob = (score.score + 1) / 2;
+    
+    weightedSum += weight * prob;
+    weightSum += weight;
+  }
+  
+  return weightedSum / weightSum;
+}
+
+/**
+ * Compute expected utility given success probability and reward magnitudes.
+ */
+export function expectedUtility(
+  successProb: number,
+  successReward: number,
+  failureReward: number
+): number {
+  return successProb * successReward + (1 - successProb) * failureReward;
+}
+
+// ============================================================================
+// UTILITY COMPARISON
+// ============================================================================
+
+/**
+ * Compare two utility scores, accounting for confidence.
+ * Returns positive if a > b, negative if a < b, zero if equivalent.
+ */
+export function compareUtility(a: UtilityScore, b: UtilityScore): number {
+  // Weight by confidence
+  const aWeighted = a.score * a.confidence;
+  const bWeighted = b.score * b.confidence;
+  
+  return aWeighted - bWeighted;
+}
+
+/**
+ * Select the best outcome from a list by utility.
+ */
+export function selectBestOutcome<T>(outcomes: Outcome<T>[]): Outcome<T> | null {
+  if (outcomes.length === 0) return null;
+  
+  return outcomes.reduce((best, current) =>
+    compareUtility(current.utility, best.utility) > 0 ? current : best
+  );
+}