@longarc/mdash 3.1.2 → 3.1.3

package/src/context/types.ts

@@ -0,0 +1,679 @@
+/**
+ * Caret — Context Primitive Engine
+ * @module @longarcstudios/caret
+ * @version 0.2.0
+ * 
+ * Core type definitions for the Caret context primitive system.
+ * All types are immutable by design — no mutations after creation.
+ * 
+ * Architecture: LLM at the edges, cryptography at the core.
+ * 
+ * v0.2.0: Research patterns integration
+ * - MdashActionCode for standardized action vocabulary
+ * - InfluenceBudget for MCCA-compliant bounds
+ * - InfluenceConstraint for influence-based resolution
+ * - Outcome<T> for Intent-Experience-Utility tracking
+ */
+
+// ============================================================================
+// PRIMITIVE TYPES
+// ============================================================================
+
+/** SHA-256 hash represented as hex string (64 characters) */
+export type Hash = string & { readonly __brand: 'Hash' };
+
+/** UUID v4 for unique identification */
+export type FragmentId = string & { readonly __brand: 'FragmentId' };
+
+/** ISO-8601 timestamp with timezone */
+export type Timestamp = string & { readonly __brand: 'Timestamp' };
+
+/** HMAC-SHA256 seal for tamper detection */
+export type Seal = string & { readonly __brand: 'Seal' };
+
+/** URI-style source identifier (e.g., "org://hr/policies/pto-2024") */
+export type SourceURI = string & { readonly __brand: 'SourceURI' };
+
+/** Token count (non-negative integer) */
+export type TokenCount = number & { readonly __brand: 'TokenCount' };
+
+// ============================================================================
+// TRUST & ATTRIBUTION
+// ============================================================================
+
+/** Trust level from 0-100 indicating confidence in source */
+export type TrustLevel = number & { readonly __brand: 'TrustLevel' };
+
+/** Attribution sources for context fragments */
+export type Attribution = 
+  | 'system'      // System-generated (highest trust)
+  | 'operator'    // Human operator input
+  | 'user'        // End-user input
+  | 'agent'       // AI agent generated
+  | 'external'    // External API/service
+  | 'derived';    // Computed from other fragments
+
+// ============================================================================
+// MCCA & ACTION CODES (Research Patterns v3.1.0)
+// ============================================================================
+
+/**
+ * mdash action codes for atomic attestation encoding.
+ * Every action in the system maps to exactly one code.
+ */
+export type MdashActionCode =
+  | 'INVOKE'      // Warrant activation
+  | 'APPROVE'     // Authority grant
+  | 'ATTEST'      // State certification
+  | 'REVOKE'      // Authority withdrawal
+  | 'CHECKPOINT'  // State snapshot
+  | 'ESCALATE'    // Boundary approach
+  | 'TERMINATE';  // Execution end
+
+/**
+ * MCCA-compliant influence budget.
+ * Constrains how much each context source can affect agent behavior.
+ * 
+ * MCCA bounds:
+ * - system: ≥0.40 (operator instructions dominate)
+ * - user: ≤0.35 (user input bounded)
+ * - environment: ≤0.20 (tool outputs limited)
+ * - assistant: ≤0.25 (self-influence capped)
+ */
+export interface InfluenceBudget {
+  /** System prompt influence (≥0.40 per MCCA) */
+  readonly system: number;
+  /** User input influence (≤0.35 per MCCA) */
+  readonly user: number;
+  /** Environment influence (≤0.20 per MCCA) */
+  readonly environment: number;
+  /** Assistant self-influence (≤0.25 per MCCA) */
+  readonly assistant: number;
+}
+
+/** Default MCCA influence budget */
+export const DEFAULT_MCCA_BUDGET: InfluenceBudget = {
+  system: 0.45,
+  user: 0.30,
+  environment: 0.15,
+  assistant: 0.10,
+};
+
+/** Default trust levels by attribution */
+export const DEFAULT_TRUST_LEVELS: Record<Attribution, number> = {
+  system: 100,
+  operator: 90,
+  user: 70,
+  derived: 60,
+  agent: 50,
+  external: 30,
+};
+
+/** Provenance record for a single fragment */
+export interface ProvenanceRecord {
+  readonly source: SourceURI;
+  readonly attribution: Attribution;
+  readonly trust_level: TrustLevel;
+  readonly timestamp: Timestamp;
+  readonly parent_hash: Hash | null;
+  readonly signature?: string; // Optional Ed25519 signature
+}
+
+/** Chain of provenance records (immutable linked list) */
+export interface ProvenanceChain {
+  readonly head: ProvenanceRecord;
+  readonly tail: ProvenanceChain | null;
+  readonly length: number;
+  readonly chain_hash: Hash;
+}
+
+// ============================================================================
+// SEMANTIC UNITS
+// ============================================================================
+
+/** Semantic type classification for content */
+export type SemanticType =
+  | 'text'          // Plain text content
+  | 'structured'    // JSON-serializable object
+  | 'policy'        // Governance policy
+  | 'state'         // Agent/system state
+  | 'reference'     // Reference to external resource
+  | 'composite';    // Composed from multiple fragments
+
+/** Semantic unit — the content payload of a fragment */
+export interface SemanticUnit<T = unknown> {
+  readonly type: SemanticType;
+  readonly data: T;
+  readonly token_count: TokenCount;
+  readonly compression_ratio?: number; // If compressed
+}
+
+// ============================================================================
+// CONSTRAINTS
+// ============================================================================
+
+/** Time-based constraint */
+export interface TimeConstraint {
+  readonly kind: 'time';
+  readonly max_age_ms?: number;
+  readonly not_before?: Timestamp;
+  readonly not_after?: Timestamp;
+}
+
+/** Scope-based constraint */
+export interface ScopeConstraint {
+  readonly kind: 'scope';
+  readonly allowed_domains: readonly string[];
+  readonly denied_domains?: readonly string[];
+}
+
+/** Trust-based constraint */
+export interface TrustConstraint {
+  readonly kind: 'trust';
+  readonly minimum_trust: TrustLevel;
+  readonly required_attributions?: readonly Attribution[];
+}
+
+/** Signature requirement constraint */
+export interface SignatureConstraint {
+  readonly kind: 'signature';
+  readonly required: boolean;
+  readonly allowed_signers?: readonly string[];
+}
+
+/** 
+ * Influence budget constraint (MCCA compliance).
+ * Enforces bounds on context source influence.
+ */
+export interface InfluenceConstraint {
+  readonly kind: 'influence';
+  /** MCCA-compliant influence budget */
+  readonly budget: InfluenceBudget;
+  /** Enforcement mode */
+  readonly enforcement: 'strict' | 'advisory';
+}
+
+/** Union of all constraint types */
+export type Constraint = 
+  | TimeConstraint 
+  | ScopeConstraint 
+  | TrustConstraint 
+  | SignatureConstraint
+  | InfluenceConstraint;
+
+// ============================================================================
+// CONTEXT FRAGMENT
+// ============================================================================
+
+/** 
+ * ContextFragment — The atomic unit of structured context.
+ * 
+ * Immutable by construction. Once sealed, a fragment cannot be modified.
+ * Any "update" creates a new fragment with updated provenance.
+ */
+export interface ContextFragment<T = unknown> {
+  /** Unique identifier (UUID v4) */
+  readonly id: FragmentId;
+  
+  /** SHA-256 hash of the sealed content */
+  readonly hash: Hash;
+  
+  /** The semantic content payload */
+  readonly content: SemanticUnit<T>;
+  
+  /** Full provenance chain */
+  readonly provenance: ProvenanceChain;
+  
+  /** When this fragment was sealed */
+  readonly sealed_at: Timestamp;
+  
+  /** HMAC seal for tamper detection */
+  readonly seal: Seal;
+  
+  /** Constraints on fragment usage */
+  readonly constraints: readonly Constraint[];
+  
+  /** Version for schema evolution */
+  readonly version: '1.0' | 'v3.1';
+}
+
+// ============================================================================
+// MANIFOLD (COMPOSED CONTEXT)
+// ============================================================================
+
+/** Composition strategy for manifold creation */
+export type CompositionStrategy =
+  | 'concatenate'   // Simple concatenation
+  | 'priority'      // Higher trust first
+  | 'recency'       // Most recent first
+  | 'semantic';     // Semantic deduplication
+
+/** Options for manifold composition */
+export interface ComposeOptions {
+  /** Maximum token ceiling for composed output */
+  readonly ceiling: TokenCount | string; // e.g., "8k tokens"
+  
+  /** Composition strategy */
+  readonly strategy?: CompositionStrategy;
+  
+  /** Whether to preserve full provenance chain */
+  readonly preserve_provenance?: boolean;
+  
+  /** Minimum trust level for included fragments */
+  readonly min_trust?: TrustLevel;
+}
+
+/** 
+ * Manifold — A composed context from multiple fragments.
+ * 
+ * Represents a "view" over fragments, optimized for a token ceiling.
+ * Maintains provenance links to all source fragments.
+ */
+export interface Manifold<T = unknown> {
+  /** Unique identifier for this manifold */
+  readonly id: FragmentId;
+  
+  /** Hash of the composed content */
+  readonly hash: Hash;
+  
+  /** The composed semantic content */
+  readonly content: SemanticUnit<T>;
+  
+  /** Source fragment IDs in composition order */
+  readonly sources: readonly FragmentId[];
+  
+  /** Aggregated provenance (merged chains) */
+  readonly provenance: ProvenanceChain;
+  
+  /** Composition metadata */
+  readonly composition: {
+    readonly strategy: CompositionStrategy;
+    readonly ceiling: TokenCount;
+    readonly actual_tokens: TokenCount;
+    readonly fragments_included: number;
+    readonly fragments_excluded: number;
+    readonly compression_applied: boolean;
+  };
+  
+  /** When this manifold was created */
+  readonly created_at: Timestamp;
+  
+  /** HMAC seal */
+  readonly seal: Seal;
+}
+
+// ============================================================================
+// RESOLUTION
+// ============================================================================
+
+/** Result of resolving a fragment through constraints */
+export interface ResolutionResult<T = unknown> {
+  readonly success: boolean;
+  readonly fragment: ContextFragment<T> | null;
+  readonly violations: readonly ConstraintViolation[];
+  readonly resolved_at: Timestamp;
+}
+
+/** Details of a constraint violation */
+export interface ConstraintViolation {
+  readonly constraint: Constraint;
+  readonly reason: string;
+  readonly severity: 'error' | 'warning';
+}
+
+// ============================================================================
+// STORAGE INTERFACE
+// ============================================================================
+
+/** Abstract storage interface for fragments */
+export interface FragmentStore {
+  /** Store a fragment */
+  put(fragment: ContextFragment): Promise<void>;
+  
+  /** Retrieve a fragment by ID */
+  get(id: FragmentId): Promise<ContextFragment | null>;
+  
+  /** Retrieve a fragment by hash */
+  getByHash(hash: Hash): Promise<ContextFragment | null>;
+  
+  /** Query fragments by source */
+  queryBySource(source: SourceURI): Promise<readonly ContextFragment[]>;
+  
+  /** Query fragments by time range */
+  queryByTime(from: Timestamp, to: Timestamp): Promise<readonly ContextFragment[]>;
+  
+  /** Delete a fragment (soft delete — marks as deleted) */
+  delete(id: FragmentId): Promise<boolean>;
+  
+  /** Verify integrity of stored fragment */
+  verify(id: FragmentId): Promise<boolean>;
+  
+  // === Three-Layer Index (Optional) ===
+  
+  /**
+   * Layer 2: Keyword search (lexical).
+   * Optional method — implementations may return undefined.
+   * 
+   * @param keywords - Keywords to match
+   * @param matchMode - 'any' matches if any keyword found, 'all' requires all keywords
+   * @returns Matching fragments
+   */
+  queryByKeywords?(
+    keywords: string[],
+    matchMode: 'any' | 'all'
+  ): Promise<readonly ContextFragment[]>;
+  
+  /**
+   * Layer 1: Semantic similarity search.
+   * Optional method — implementations may return undefined.
+   * 
+   * @param embedding - Query embedding vector
+   * @param threshold - Minimum similarity threshold (0.0-1.0)
+   * @param limit - Maximum results to return
+   * @returns Matching fragments with similarity scores
+   */
+  queryBySimilarity?(
+    embedding: Float32Array,
+    threshold: number,
+    limit: number
+  ): Promise<readonly { fragment: ContextFragment; similarity: number }[]>;
+}
+
+// ============================================================================
+// RUNTIME INTERFACE
+// ============================================================================
+
+/** Caret runtime configuration */
+export interface CaretConfig {
+  /** Secret key for HMAC sealing */
+  seal_key: string;
+  
+  /** Default trust level for unspecified sources */
+  default_trust: TrustLevel;
+  
+  /** Whether to enforce signature requirements */
+  require_signatures: boolean;
+  
+  /** Token counting strategy */
+  tokenizer: 'cl100k' | 'p50k' | 'custom';
+  
+  /** Custom tokenizer function */
+  custom_tokenizer?: (text: string) => number;
+}
+
+/** The Caret runtime instance */
+export interface CaretRuntime {
+  /** Seal content into a fragment */
+  seal<T>(options: SealOptions<T>): Promise<ContextFragment<T>>;
+  
+  /** Compose fragments into a manifold */
+  compose<T>(fragments: readonly ContextFragment[], options: ComposeOptions): Promise<Manifold<T>>;
+  
+  /** Resolve a fragment through constraints */
+  resolve<T>(fragment: ContextFragment<T>): Promise<ResolutionResult<T>>;
+  
+  /** Verify a fragment's integrity */
+  verify(fragment: ContextFragment): Promise<boolean>;
+  
+  /** Get the fragment store */
+  readonly store: FragmentStore;
+}
+
+/** Options for sealing content */
+export interface SealOptions<T = unknown> {
+  /** The content to seal */
+  readonly content: T;
+  
+  /** Source URI for provenance */
+  readonly source: SourceURI | string;
+  
+  /** Attribution type */
+  readonly attribution: Attribution;
+  
+  /** Trust level (0-100) */
+  readonly trust_level?: number;
+  
+  /** Constraints to apply */
+  readonly constraints?: readonly Constraint[];
+  
+  /** Parent fragment for provenance chain */
+  readonly parent?: ContextFragment;
+  
+  /** Optional signature */
+  readonly signature?: string;
+  
+  /** 
+   * Enable atomic encoding with coreference resolution.
+   * Transforms ambiguous text into explicit references.
+   */
+  readonly atomic_encoding?: {
+    readonly enabled: boolean;
+    readonly context?: CoreferenceContext;
+  };
+}
+
+/** Context for coreference resolution */
+export interface CoreferenceContext {
+  /** Reference time for relative time resolution */
+  readonly referenceTime: string;
+  /** Last mentioned agent ID */
+  readonly lastAgentId?: string;
+  /** Last mentioned warrant ID */
+  readonly lastWarrantId?: string;
+  /** Last mentioned checkpoint ID */
+  readonly lastCheckpointId?: string;
+}
+
+// ============================================================================
+// TYPE GUARDS
+// ============================================================================
+
+/** Type guard for Hash */
+export function isHash(value: unknown): value is Hash {
+  return typeof value === 'string' && /^[a-f0-9]{64}$/i.test(value);
+}
+
+/** Type guard for FragmentId */
+export function isFragmentId(value: unknown): value is FragmentId {
+  return typeof value === 'string' && 
+    /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+
+/** Type guard for Timestamp */
+export function isTimestamp(value: unknown): value is Timestamp {
+  if (typeof value !== 'string') return false;
+  const date = new Date(value);
+  return !isNaN(date.getTime());
+}
+
+/** Type guard for TrustLevel */
+export function isTrustLevel(value: unknown): value is TrustLevel {
+  return typeof value === 'number' && value >= 0 && value <= 100;
+}
+
+/** Type guard for TokenCount */
+export function isTokenCount(value: unknown): value is TokenCount {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+
+/** Type guard for ContextFragment */
+export function isContextFragment(value: unknown): value is ContextFragment {
+  if (typeof value !== 'object' || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    isFragmentId(v.id) &&
+    isHash(v.hash) &&
+    typeof v.content === 'object' &&
+    typeof v.provenance === 'object' &&
+    isTimestamp(v.sealed_at) &&
+    typeof v.seal === 'string' &&
+    Array.isArray(v.constraints) &&
+    (v.version === 'v3.1' || v.version === '1.0')
+  );
+}
+
+// ============================================================================
+// OUTCOME TRACKING (Intent-Experience-Utility)
+// ============================================================================
+
+/**
+ * Single step in execution trace.
+ * Records action, state observation, and influence consumed.
+ */
+export interface ExecutionStep {
+  /** Unique step identifier */
+  readonly step_id: string;
+  /** ISO 8601 timestamp */
+  readonly timestamp: Timestamp;
+  /** Action performed */
+  readonly action: MdashActionCode;
+  /** Hash of observed state after action */
+  readonly observation_hash: Hash;
+  /** Influence consumed by this step */
+  readonly influence_consumed: InfluenceBudget;
+  /** Checkpoint hash if step created checkpoint */
+  readonly checkpoint_hash?: Hash;
+}
+
+/**
+ * Complete execution trace for a warrant/task.
+ */
+export interface ExecutionTrace {
+  /** Unique trace identifier */
+  readonly trace_id: FragmentId;
+  /** Ordered execution steps */
+  readonly steps: readonly ExecutionStep[];
+  /** Final execution status */
+  readonly outcome: 'success' | 'failure' | 'partial' | 'aborted';
+  /** Terminal state hash */
+  readonly terminal_state: Hash;
+  /** Total influence consumed across all steps */
+  readonly total_influence: InfluenceBudget;
+}
+
+/**
+ * Learned utility score for an outcome.
+ * Updated incrementally via feedback.
+ */
+export interface UtilityScore {
+  /** Learned outcome value [-1.0, 1.0] */
+  readonly score: number;
+  /** Estimation confidence [0.0, 1.0] */
+  readonly confidence: number;
+  /** Number of times score has been updated */
+  readonly update_count: number;
+}
+
+/**
+ * Agent's contribution to outcome (liability attribution).
+ */
+export interface LiabilityShare {
+  /** Agent identifier */
+  readonly agent_id: string;
+  /** Fraction of outcome attributed (0.0-1.0) */
+  readonly contribution: number;
+  /** Attestation IDs supporting attribution */
+  readonly evidence: readonly string[];
+}
+
+/**
+ * Outcome<T> — Intent-Experience-Utility triplet.
+ * 
+ * Wraps a fragment result with execution context:
+ * - Intent: What was authorized
+ * - Experience: What actually happened
+ * - Utility: How valuable the outcome was
+ */
+export interface Outcome<T = unknown> {
+  /** The fragment produced by execution */
+  readonly result: ContextFragment<T>;
+  
+  /** Original authorization (Intent) */
+  readonly intent: {
+    /** Natural language objective */
+    readonly objective: string;
+    /** Constraints on execution */
+    readonly constraints: readonly Constraint[];
+    /** MCCA influence budget */
+    readonly influence_budget?: InfluenceBudget;
+    /** Verifiable success criteria */
+    readonly success_criteria?: readonly string[];
+  };
+  
+  /** Execution trace (Experience) */
+  readonly trace: ExecutionTrace;
+  
+  /** Learned utility score (Utility) */
+  readonly utility: UtilityScore;
+  
+  /** Liability distribution across agents */
+  readonly liability: readonly LiabilityShare[];
+}
+
+/**
+ * Feedback for utility score updates.
+ */
+export interface UtilityFeedback {
+  /** Observed outcome reward [-1.0, 1.0] */
+  readonly reward: number;
+  /** Source of feedback */
+  readonly source: 'environment' | 'human' | 'system';
+  /** ISO 8601 timestamp */
+  readonly timestamp: Timestamp;
+  /** Optional explanation */
+  readonly rationale?: string;
+}
+
+/**
+ * Credit assignment for a single execution step.
+ */
+export interface StepCredit {
+  /** Step identifier */
+  readonly step_id: string;
+  /** Credit value (portion of terminal reward) */
+  readonly credit: number;
+  /** Influence consumed by this step */
+  readonly influence: number;
+  /** Influence as fraction of total */
+  readonly influence_fraction: number;
+}
+
+/**
+ * Complete credit assignment for an execution.
+ */
+export interface CreditAssignment {
+  /** Trace identifier */
+  readonly trace_id: FragmentId;
+  /** Terminal reward being distributed */
+  readonly terminal_reward: number;
+  /** Credit per step */
+  readonly step_credits: readonly StepCredit[];
+  /** Timestamp of assignment */
+  readonly assigned_at: Timestamp;
+}
+
+// ============================================================================
+// RESEARCH PATTERN TYPE GUARDS
+// ============================================================================
+
+/** Type guard for valid MCCA influence budget */
+export function isValidInfluenceBudget(budget: InfluenceBudget): boolean {
+  return (
+    budget.system >= 0.40 &&
+    budget.user <= 0.35 &&
+    budget.environment <= 0.20 &&
+    budget.assistant <= 0.25 &&
+    Math.abs(budget.system + budget.user + budget.environment + budget.assistant - 1.0) < 0.01
+  );
+}
+
+/** Sum all components of an influence budget */
+export function sumInfluence(budget: InfluenceBudget): number {
+  return budget.system + budget.user + budget.environment + budget.assistant;
+}
+
+/** Type guard for MdashActionCode */
+export function isMdashActionCode(value: unknown): value is MdashActionCode {
+  const validCodes = ['INVOKE', 'APPROVE', 'ATTEST', 'REVOKE', 'CHECKPOINT', 'ESCALATE', 'TERMINATE'];
+  return typeof value === 'string' && validCodes.includes(value);
+}