speckl/reference-agent/src/types.ts

/**
 * Speckl Reference Agent Architecture
 * 
 * Core types and protocols for the tiered agent harness.
 * Orchestrator → Team Lead → SME hierarchy with TillDone condition tracking.
 */

// ─── Speck Types ────────────────────────────────────────────

export interface SpeckDefinition {
  name: string;
  input: Record<string, SpeckType>;
  output: SpeckType;
  constraints: Constraint[];
  verify: VerifyCondition[];
  events?: EventDef[];
  imports?: ImportRef[];
  interface?: string;
}

export type SpeckType =
  | PrimitiveType
  | RecordType
  | ListType
  | NamedType;

export type PrimitiveType = "Nat" | "Int" | "Real" | "Bool" | "String" | "Bytes";

export interface RecordType {
  kind: "record";
  fields: Record<string, SpeckType>;
}

export interface ListType {
  kind: "list";
  element: SpeckType;
}

export interface NamedType {
  kind: "named";
  name: string;
  typeArgs?: SpeckType[];
}

export interface Constraint {
  id: string;
  expression: string; // SpeckDL expression text
  compiledToZ3?: string; // SMT-LIB2 assertion
}

export interface VerifyCondition {
  id: string;
  kind: "always" | "eventually" | "implies";
  expression: string;
  proven?: boolean;
  counterexample?: Record<string, unknown>;
}

export interface EventDef {
  name: string;
  fields: Record<string, SpeckType>;
}

export interface ImportRef {
  path: string;
  alias?: string;
}

// ─── Agent Protocol ─────────────────────────────────────────

export type TaskStatus = "pending" | "in_progress" | "blocked" | "completed" | "failed";

export interface TaskMessage {
  id: string;
  type: "task_assign" | "task_result" | "task_blocked" | "task_failed";
  from: AgentId;
  to: AgentId;
  payload: TaskPayload;
  timestamp: string; // ISO 8601
  provenance: ProvenanceEdge[];
}

export interface TaskPayload {
  task: Task;
  speck?: SpeckDefinition;
  context?: Record<string, unknown>;
}

export interface Task {
  id: string;
  speckName: string;
  taskType: TaskType;
  description: string;
  priority: number;
  parentTaskId?: string;
  createdAt: string;
}

export type TaskType = 
  | "verify_speck"      // Run Z3 verification on a Speck
  | "compile_to_dst"    // Compile verified Speck to DST
  | "compile_to_typescript"   // Compile DST to TypeScript
  | "generate_code"     // Generate code from verified Speck
  | "generate_docs"     // Generate documentation from provenance graph
  | "integrate"         // Integration/glue code
  | "review"            // Human review checkpoint
  ;

export interface AgentId {
  type: "orchestrator" | "team_lead" | "sme";
  name: string;
  specialization?: string;
}

export interface ProvenanceEdge {
  source: string;      // URI or ID of the source artifact
  target: string;     // URI or ID of the derived artifact
  relation: string;   // "compiled_to" | "verified_by" | "generated_from" | "derived_from"
  tool: string;       // Tool that created this edge
  timestamp: string;
  metadata?: Record<string, unknown>;
}

// ─── TillDone Condition Tracking ─────────────────────────────

export interface TillDoneCondition {
  taskId: string;
  description: string;
  predicate: (result: TaskResult) => boolean;
  isDone: boolean;
}

export interface TaskResult {
  taskId: string;
  status: "success" | "failure";
  output?: unknown;
  provenance: ProvenanceEdge[];
  completedAt: string;
}

// ─── Provenance Graph ───────────────────────────────────────

export interface ProvenanceNode {
  id: string;
  type: "speck" | "z3_assertion" | "dst" | "code" | "docs" | "event";
  label: string;
  metadata: Record<string, unknown>;
}

export interface ProvenanceGraph {
  nodes: Map<string, ProvenanceNode>;
  edges: ProvenanceEdge[];
  addNode(node: ProvenanceNode): void;
  addEdge(edge: ProvenanceEdge): void;
  query(source?: string, relation?: string, target?: string): ProvenanceEdge[];
  toJSON(): object;
}