AirCoding/packages/contracts/src/artifact.ts

/**
 * AirCoding Artifact Contracts
 *
 * Implements ArtifactRef, ArtifactCreateInput, ArtifactContext, ArtifactReadResult,
 * ArtifactStore, DebugKnowledgeStore, LearnedMemoryStore, DebugRecord, LearnedMemory
 * per interface-contracts-v1.md §14, §20 and system-detailed-design.md §3.
 */

// Re-export IDs and types needed for these contracts
import type {
  ArtifactID,
  UUID,
  ISOTimeString,
  JsonObject,
  SessionID,
  TaskID,
  AgentID,
  ToolRunID,
  CommandRunID,
} from './ids.js'
export type {
  ArtifactID,
  UUID,
  ISOTimeString,
  JsonObject,
  SessionID,
  TaskID,
  AgentID,
  ToolRunID,
  CommandRunID,
}

// Re-export EntityRef for DebugKnowledgeStore and LearnedMemoryStore
import type { EntityRef } from './event.js'
export type { EntityRef }

// Re-export EvidenceRef for DebugRecord
import type { EvidenceRef } from './evidence.js'

/**
 * Reference to a stored artifact.
 */
export interface ArtifactRef {
  artifact_id: ArtifactID
  uri: string
  path: string
  type: string
  sha256?: string
  size_bytes?: number
}

/**
 * Input for creating a new artifact.
 */
export interface ArtifactCreateInput {
  type: string
  original_name?: string
  content?: string
  source_path?: string
  associated_entity_type?: string
  associated_entity_id?: string
  metadata?: JsonObject
}

/**
 * Context information for artifact operations.
 */
export interface ArtifactContext {
  session_id: SessionID
  task_id?: TaskID
  agent_id?: AgentID
  tool_run_id?: ToolRunID
  command_run_id?: CommandRunID
}

/**
 * Result of reading an artifact, including optional content.
 */
export interface ArtifactReadResult {
  artifact: ArtifactRef
  content?: string | Uint8Array
  content_type?: string
}

/**
 * Storage interface for artifacts.
 */
export interface ArtifactStore {
  create(input: ArtifactCreateInput, context: ArtifactContext): Promise<ArtifactRef>
  get(artifact_id: ArtifactID): Promise<ArtifactRef | undefined>
  read(artifact_id: ArtifactID): Promise<ArtifactReadResult>
}

// =============================================================================
// Knowledge Store Contracts (merged from knowledge.ts per DD §3)
// =============================================================================

/**
 * A debug record capturing failure diagnosis and resolution.
 */
export interface DebugRecord {
  debug_record_id: UUID
  task_id?: TaskID
  failure_signature: string
  summary: string
  root_cause?: string
  fix_ref?: string
  evidence_refs?: EvidenceRef[]
  verification_refs?: EvidenceRef[]
  created_at: ISOTimeString
  updated_at: ISOTimeString
  metadata_json?: JsonObject
}

/**
 * Storage interface for debug knowledge records.
 */
export interface DebugKnowledgeStore {
  insert(record: DebugRecord): Promise<void>
  lookup_by_signature(failure_signature: string): Promise<DebugRecord[]>
  lookup_by_task(task_id: TaskID): Promise<DebugRecord[]>
  update(debug_record_id: UUID, patch: Partial<DebugRecord>): Promise<void>
}

/**
 * Types of learned memory.
 */
export type LearnedMemoryType = 'project_rule' | 'toolchain_rule' | 'skill_update' | 'debug_experience'

/**
 * Status of learned memory.
 */
export type LearnedMemoryStatus = 'candidate' | 'promoted' | 'archived' | 'rejected'

/**
 * A learned memory entry capturing project knowledge.
 */
export interface LearnedMemory {
  memory_id: UUID
  memory_type: LearnedMemoryType
  summary: string
  content?: string
  source_ref?: EntityRef
  status: LearnedMemoryStatus
  created_at: ISOTimeString
  updated_at: ISOTimeString
  metadata_json?: JsonObject
}

/**
 * Storage interface for learned memory.
 */
export interface LearnedMemoryStore {
  insert(memory: LearnedMemory): Promise<void>
  lookup_by_type(memory_type: LearnedMemoryType): Promise<LearnedMemory[]>
  update_status(memory_id: UUID, status: LearnedMemoryStatus): Promise<void>
  scan_stale(): Promise<LearnedMemory[]>
}