pi-chalin 0.1.0

package/src/agents.ts

@@ -0,0 +1,274 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveChalinPaths, type ChalinPathsOptions } from "./paths.ts";
+import {
+  type AgentCatalogDiagnostics,
+  type AgentCapability,
+  type AgentConcern,
+  type AgentDefinition,
+  type AgentMemoryPolicy,
+  type AgentMemoryWritePolicy,
+  type AgentScope,
+  isAgentConcern,
+  isAgentCapability,
+  isAgentScope,
+  isAgentThinkingLevel,
+} from "./schemas.ts";
+
+interface ParsedFrontmatter {
+  frontmatter: Record<string, string>;
+  body: string;
+}
+
+export interface AgentCatalogLoadOptions extends ChalinPathsOptions {}
+
+export interface AgentResolution {
+  agent?: AgentDefinition;
+  error?: string;
+}
+
+export class AgentCatalog {
+  private readonly byScope: Record<AgentScope, Map<string, AgentDefinition>>;
+  readonly diagnostics: AgentCatalogDiagnostics;
+
+  private constructor(
+    byScope: Record<AgentScope, Map<string, AgentDefinition>>,
+    diagnostics: AgentCatalogDiagnostics,
+  ) {
+    this.byScope = byScope;
+    this.diagnostics = diagnostics;
+  }
+
+  static load(options: AgentCatalogLoadOptions): AgentCatalog {
+    const paths = resolveChalinPaths(options);
+    const diagnostics: AgentCatalogDiagnostics = { warnings: [], errors: [] };
+    const byScope: Record<AgentScope, Map<string, AgentDefinition>> = {
+      "built-in": new Map(),
+      project: new Map(),
+      user: new Map(),
+    };
+
+    loadAgentDir(paths.builtInAgentsDir, "built-in", byScope["built-in"], diagnostics);
+    loadAgentDir(paths.userAgentsDir, "user", byScope.user, diagnostics);
+    loadAgentDir(paths.projectAgentsDir, "project", byScope.project, diagnostics);
+
+    return new AgentCatalog(byScope, diagnostics);
+  }
+
+  list(scope?: AgentScope): AgentDefinition[] {
+    const scopes = scope ? [scope] : (["project", "user", "built-in"] as const);
+    return scopes.flatMap((currentScope) => [...this.byScope[currentScope].values()]).sort(compareAgents);
+  }
+
+  listExecutable(): AgentDefinition[] {
+    return this.list().filter((agent) => !agent.diagnostics.some((diag) => diag.startsWith("invalid:")));
+  }
+
+  resolve(reference: string): AgentResolution {
+    const trimmed = reference.trim();
+    if (!trimmed) return { error: "Agent reference must not be empty." };
+
+    const slashIndex = trimmed.indexOf("/");
+    if (slashIndex !== -1) {
+      const maybeScope = trimmed.slice(0, slashIndex);
+      const name = trimmed.slice(slashIndex + 1);
+      if (!isAgentScope(maybeScope)) {
+        return { error: `Unknown agent scope '${maybeScope}'. Use project/name, user/name, or built-in/name.` };
+      }
+      const agent = this.byScope[maybeScope].get(name);
+      return agent ? { agent } : { error: `Agent '${name}' not found in ${maybeScope} scope.` };
+    }
+
+    for (const scope of ["project", "user", "built-in"] as const) {
+      const agent = this.byScope[scope].get(trimmed);
+      if (agent) return { agent };
+    }
+
+    return { error: `Agent '${trimmed}' not found. Available agents: ${this.list().map((agent) => `${agent.scope}/${agent.name}`).join(", ") || "none"}.` };
+  }
+
+  resolveMany(references: string[]): { agents: AgentDefinition[]; errors: string[] } {
+    const agents: AgentDefinition[] = [];
+    const errors: string[] = [];
+    for (const reference of references) {
+      const result = this.resolve(reference);
+      if (result.agent) agents.push(result.agent);
+      if (result.error) errors.push(result.error);
+    }
+    return { agents, errors };
+  }
+}
+
+function compareAgents(a: AgentDefinition, b: AgentDefinition): number {
+  const scopeRank: Record<AgentScope, number> = { project: 0, user: 1, "built-in": 2 };
+  return scopeRank[a.scope] - scopeRank[b.scope] || a.name.localeCompare(b.name);
+}
+
+function loadAgentDir(
+  dir: string,
+  scope: AgentScope,
+  target: Map<string, AgentDefinition>,
+  diagnostics: AgentCatalogDiagnostics,
+): void {
+  if (!fs.existsSync(dir)) return;
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (error) {
+    diagnostics.errors.push(`Failed to read ${scope} agents dir '${dir}': ${errorMessage(error)}`);
+    return;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const filePath = path.join(dir, entry.name);
+    const loaded = loadAgentFile(filePath, scope);
+    for (const warning of loaded.diagnostics) diagnostics.warnings.push(`${filePath}: ${warning}`);
+    if (target.has(loaded.name)) {
+      diagnostics.warnings.push(`${filePath}: duplicate agent '${loaded.name}' in ${scope} scope; later file overwrote earlier definition.`);
+    }
+    target.set(loaded.name, loaded);
+  }
+}
+
+function loadAgentFile(filePath: string, scope: AgentScope): AgentDefinition {
+  const diagnostics: string[] = [];
+  let raw = "";
+  try {
+    raw = fs.readFileSync(filePath, "utf-8");
+  } catch (error) {
+    diagnostics.push(`invalid: failed to read agent file: ${errorMessage(error)}`);
+  }
+
+  const parsed = parseFrontmatter(raw);
+  const fileName = path.basename(filePath, ".md");
+  const name = (parsed.frontmatter.name || fileName).trim();
+  const concern = parseConcern(parsed.frontmatter.concern, diagnostics, filePath);
+  const capabilities = parseCapabilities(parsed.frontmatter.capabilities, concern, parsed.frontmatter.tools, diagnostics);
+  const memory = parseMemoryPolicy(parsed.frontmatter, diagnostics);
+  const model = (parsed.frontmatter.model || "inherit").trim() || "inherit";
+  const thinking = parseThinkingLevel(parsed.frontmatter.thinking ?? parsed.frontmatter["thinking-level"], diagnostics);
+  const tools = parseStringList(parsed.frontmatter.tools);
+  const description = (parsed.frontmatter.description || `${name} agent`).trim();
+
+  if (!name) diagnostics.push("invalid: agent name must not be empty.");
+  if (!parsed.body.trim()) diagnostics.push("invalid: agent system prompt body must not be empty.");
+
+  return {
+    name,
+    scope,
+    concern,
+    capabilities,
+    description,
+    model,
+    thinking,
+    tools,
+    memory,
+    systemPrompt: parsed.body.trim(),
+    sourcePath: filePath,
+    diagnostics,
+  };
+}
+
+function parseThinkingLevel(value: string | undefined, diagnostics: string[]) {
+  const thinking = (value || "inherit").trim();
+  if (isAgentThinkingLevel(thinking)) return thinking;
+  diagnostics.push(`invalid: unknown thinking level '${thinking}'. Use inherit, off, minimal, low, medium, high, or xhigh.`);
+  return "inherit";
+}
+
+function parseCapabilities(value: string | undefined, concern: AgentConcern, tools: string | undefined, diagnostics: string[]): AgentCapability[] {
+  const raw = parseStringList(value);
+  const capabilities = raw.length > 0 ? raw : defaultCapabilities(concern, parseStringList(tools));
+  const valid: AgentCapability[] = [];
+  for (const capability of capabilities) {
+    if (isAgentCapability(capability)) valid.push(capability);
+    else diagnostics.push(`invalid: unknown capability '${capability}'.`);
+  }
+  return [...new Set(valid)];
+}
+
+function defaultCapabilities(concern: AgentConcern, tools: string[]): AgentCapability[] {
+  const fromTools: AgentCapability[] = [];
+  if (tools.some((tool) => ["read", "ls"].includes(tool))) fromTools.push("inspect-files");
+  if (tools.some((tool) => ["grep", "find"].includes(tool))) fromTools.push("search-files");
+  if (tools.includes("bash")) fromTools.push("run-safe-bash");
+  if (tools.includes("edit")) fromTools.push("edit-files");
+  if (tools.includes("write")) fromTools.push("write-new-files");
+  const byConcern: Partial<Record<AgentConcern, AgentCapability[]>> = {
+    recon: ["inspect-files", "search-files", "memory-read"],
+    research: ["inspect-files", "search-files", "external-context", "memory-read"],
+    "context-building": ["inspect-files", "search-files", "memory-read", "memory-write"],
+    planning: ["inspect-files", "search-files", "memory-read", "coordinate"],
+    implementation: ["inspect-files", "search-files", "run-safe-bash", "validate", "edit-files", "write-new-files", "memory-read", "memory-write"],
+    review: ["inspect-files", "search-files", "run-safe-bash", "validate", "memory-read", "memory-write"],
+    "conflict-resolution": ["inspect-files", "search-files", "run-safe-bash", "validate", "edit-files", "memory-read", "memory-write"],
+    "decision-consistency": ["inspect-files", "search-files", "memory-read", "coordinate"],
+    delegation: ["inspect-files", "search-files", "coordinate"],
+    "memory-curation": ["memory-read", "memory-write"],
+  };
+  return [...new Set([...(byConcern[concern] ?? []), ...fromTools])];
+}
+
+export function parseFrontmatter(content: string): ParsedFrontmatter {
+  const normalized = content.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) return { frontmatter: {}, body: normalized };
+
+  const endIndex = normalized.indexOf("\n---", 4);
+  if (endIndex === -1) return { frontmatter: {}, body: normalized };
+
+  const block = normalized.slice(4, endIndex);
+  const body = normalized.slice(endIndex + 4).trim();
+  const frontmatter: Record<string, string> = {};
+
+  for (const line of block.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const match = trimmed.match(/^([A-Za-z0-9_.-]+):\s*(.*)$/);
+    if (!match) continue;
+    let value = match[2]?.trim() ?? "";
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    frontmatter[match[1]!] = value;
+  }
+
+  return { frontmatter, body };
+}
+
+function parseConcern(value: string | undefined, diagnostics: string[], filePath: string): AgentConcern {
+  const concern = (value || "delegation").trim();
+  if (isAgentConcern(concern)) return concern;
+  diagnostics.push(`invalid: unknown concern '${concern}' in '${filePath}'.`);
+  return "delegation";
+}
+
+function parseMemoryPolicy(frontmatter: Record<string, string>, diagnostics: string[]): AgentMemoryPolicy {
+  const rawWrite = (frontmatter["memory-write"] || "candidate").trim();
+  const write: AgentMemoryWritePolicy = rawWrite === "never" || rawWrite === "candidate" || rawWrite === "approved" ? rawWrite : "candidate";
+  if (write !== rawWrite) diagnostics.push(`Invalid memory-write '${rawWrite}'; using 'candidate'.`);
+
+  return {
+    read: parseBoolean(frontmatter["memory-read"], true),
+    write,
+    categories: parseStringList(frontmatter["memory-categories"]),
+  };
+}
+
+function parseBoolean(value: string | undefined, fallback: boolean): boolean {
+  if (value === undefined) return fallback;
+  if (["true", "yes", "1"].includes(value.toLowerCase())) return true;
+  if (["false", "no", "0"].includes(value.toLowerCase())) return false;
+  return fallback;
+}
+
+function parseStringList(value: string | undefined): string[] {
+  if (!value) return [];
+  const trimmed = value.trim();
+  const unwrapped = trimmed.startsWith("[") && trimmed.endsWith("]") ? trimmed.slice(1, -1) : trimmed;
+  return unwrapped.split(",").map((item) => item.trim().replace(/^['\"]|['\"]$/g, "")).filter(Boolean);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/artifacts.ts

@@ -0,0 +1,326 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveChalinPaths, type ChalinPathsOptions } from "./paths.ts";
+import type { RunState } from "./schemas.ts";
+
+export type ArtifactFeatureStatus = "active" | "complete" | "failed" | "paused";
+
+export interface ArtifactCheckpointInput {
+  agent: string;
+  title: string;
+  summary: string;
+  status: ArtifactFeatureStatus;
+  stage?: string;
+  validationRefs?: string[];
+}
+
+export interface ArtifactCheckpoint extends ArtifactCheckpointInput {
+  id: string;
+  createdAt: string;
+}
+
+export interface ValidationContract {
+  id: string;
+  title: string;
+  commands: string[];
+  successCriteria: string[];
+  files?: string[];
+  createdAt?: string;
+}
+
+export interface WorkerSkillInput {
+  name: string;
+  summary: string;
+  rules: string[];
+}
+
+export interface WorkerSkillArtifact extends WorkerSkillInput {
+  path: string;
+  createdAt: string;
+}
+
+export interface ValidationContractArtifact extends ValidationContract {
+  createdAt: string;
+}
+
+export interface InterviewAnswerArtifact {
+  questionId: string;
+  question: string;
+  answer: string;
+  custom?: boolean;
+  recommended?: boolean;
+}
+
+export interface InterviewDecisionInput {
+  task: string;
+  reason: string;
+  status: "answered" | "cancelled" | "non-interactive";
+  answers: InterviewAnswerArtifact[];
+}
+
+export interface InterviewDecisionArtifact extends InterviewDecisionInput {
+  id: string;
+  createdAt: string;
+}
+
+export interface FeatureArtifactState {
+  featureId: string;
+  goal: string;
+  status: ArtifactFeatureStatus;
+  chain: string[];
+  currentStep?: string;
+  checkpoints: ArtifactCheckpoint[];
+  validationContracts: ValidationContractArtifact[];
+  workerSkills: WorkerSkillArtifact[];
+  interviewDecisions: InterviewDecisionArtifact[];
+  updatedAt: string;
+  createdAt: string;
+}
+
+export interface RunArtifactSummary {
+  runId: string;
+  routeKind: RunState["route"]["kind"];
+  agents: string[];
+  status: RunState["status"];
+  startedAt: string;
+  endedAt?: string;
+  durationMs?: number;
+  handoffs: Array<{ agent: string; summary: string; status: string }>;
+  warnings: string[];
+  metrics?: RunState["metrics"];
+  createdAt: string;
+}
+
+export class ArtifactStore {
+  private readonly root: string;
+
+  constructor(options: ChalinPathsOptions) {
+    this.root = path.join(resolveChalinPaths(options).projectRoot, ".pi-chalin", "artifacts");
+  }
+
+  async initFeature(input: { featureId: string; goal: string; chain?: string[]; currentStep?: string }): Promise<FeatureArtifactState> {
+    const now = new Date().toISOString();
+    const existing = await this.loadFeature(input.featureId);
+    const state: FeatureArtifactState = existing ? {
+      ...existing,
+      goal: input.goal,
+      chain: input.chain ?? existing.chain,
+      currentStep: input.currentStep ?? existing.currentStep,
+      status: existing.status === "complete" ? "active" : existing.status,
+      updatedAt: now,
+    } : {
+      featureId: safeId(input.featureId),
+      goal: input.goal,
+      status: "active",
+      chain: input.chain ?? [],
+      currentStep: input.currentStep,
+      checkpoints: [],
+      validationContracts: [],
+      workerSkills: [],
+      interviewDecisions: [],
+      createdAt: now,
+      updatedAt: now,
+    };
+    await this.writeFeatureState(state);
+    return state;
+  }
+
+  async loadFeature(featureId: string): Promise<FeatureArtifactState | undefined> {
+    const file = this.featureStatePath(featureId);
+    if (!fs.existsSync(file)) return undefined;
+    return normalizeFeatureState(JSON.parse(fs.readFileSync(file, "utf-8")) as Partial<FeatureArtifactState>);
+  }
+
+  async appendCheckpoint(featureId: string, input: ArtifactCheckpointInput): Promise<ArtifactCheckpoint> {
+    const state = await this.ensureFeature(featureId);
+    const now = new Date().toISOString();
+    const checkpoint: ArtifactCheckpoint = { ...input, id: `checkpoint-${Date.now().toString(36)}`, createdAt: now };
+    state.checkpoints.push(checkpoint);
+    state.currentStep = input.title;
+    state.status = input.status;
+    state.updatedAt = now;
+    appendJsonLine(this.featurePath(featureId, "checkpoints.jsonl"), checkpoint);
+    await this.writeFeatureState(state);
+    return checkpoint;
+  }
+
+  async saveValidationContract(featureId: string, input: ValidationContract): Promise<ValidationContractArtifact> {
+    const state = await this.ensureFeature(featureId);
+    const contract = { ...input, id: safeId(input.id), createdAt: input.createdAt ?? new Date().toISOString() };
+    state.validationContracts = [...state.validationContracts.filter((item) => item.id !== contract.id), contract];
+    state.updatedAt = contract.createdAt;
+    await this.writeFeatureState(state);
+    atomicWriteJson(this.featurePath(featureId, "validations", `${contract.id}.json`), contract);
+    return contract;
+  }
+
+  async saveWorkerSkill(featureId: string, input: WorkerSkillInput): Promise<WorkerSkillArtifact> {
+    const state = await this.ensureFeature(featureId);
+    const name = safeId(input.name);
+    const skillPath = this.featurePath(featureId, "skills", name, "SKILL.md");
+    const createdAt = new Date().toISOString();
+    const artifact: WorkerSkillArtifact = { ...input, name, path: skillPath, createdAt };
+    atomicWriteText(skillPath, formatWorkerSkill(artifact));
+    state.workerSkills = [...state.workerSkills.filter((item) => item.name !== name), artifact];
+    state.updatedAt = createdAt;
+    await this.writeFeatureState(state);
+    return artifact;
+  }
+
+  async appendInterviewDecision(featureId: string, input: InterviewDecisionInput): Promise<InterviewDecisionArtifact> {
+    const state = await this.ensureFeature(featureId);
+    const createdAt = new Date().toISOString();
+    const artifact: InterviewDecisionArtifact = { ...input, id: `interview-${Date.now().toString(36)}`, createdAt };
+    state.interviewDecisions.push(artifact);
+    state.currentStep = input.status === "answered" ? "Interview answered" : "Interview pending";
+    state.status = input.status === "answered" ? state.status : "paused";
+    state.updatedAt = createdAt;
+    appendJsonLine(this.featurePath(featureId, "interviews.jsonl"), artifact);
+    await this.writeFeatureState(state);
+    return artifact;
+  }
+
+  async resumeContext(featureId: string): Promise<string> {
+    const state = await this.loadFeature(featureId);
+    if (!state) return `No pi-chalin artifacts found for feature '${featureId}'.`;
+    const latest = state.checkpoints.slice(-5).map((checkpoint) => `- ${checkpoint.title} (${checkpoint.agent}, ${checkpoint.status}): ${checkpoint.summary}`);
+    const validations = state.validationContracts.map((contract) => `- ${contract.id}: ${contract.successCriteria.join("; ")}`);
+    const interviews = state.interviewDecisions.slice(-5).flatMap((decision) => [
+      `- ${decision.status}: ${decision.reason}`,
+      ...decision.answers.map((answer) => `  - ${answer.question}: ${answer.answer}`),
+    ]);
+    const skills = state.workerSkills.map((skill) => `- ${skill.name}: ${skill.summary}`);
+    return [
+      `Feature: ${state.featureId}`,
+      `Goal: ${state.goal}`,
+      `Status: ${state.status}`,
+      state.chain.length ? `Chain: ${state.chain.join(" → ")}` : undefined,
+      state.currentStep ? `Current step: ${state.currentStep}` : undefined,
+      latest.length ? "Recent checkpoints:" : undefined,
+      ...latest,
+      validations.length ? "Validation contracts:" : undefined,
+      ...validations,
+      interviews.length ? "Interview decisions:" : undefined,
+      ...interviews,
+      skills.length ? "Worker skills:" : undefined,
+      ...skills,
+    ].filter((line): line is string => Boolean(line)).join("\n");
+  }
+
+  async recordRun(run: RunState): Promise<RunArtifactSummary> {
+    const createdAt = new Date().toISOString();
+    const summary: RunArtifactSummary = {
+      runId: run.id,
+      routeKind: run.route.kind,
+      agents: run.route.agents,
+      status: run.status,
+      startedAt: run.startedAt,
+      endedAt: run.endedAt,
+      durationMs: run.metrics?.durationMs,
+      handoffs: run.steps.map((step) => ({
+        agent: step.agent,
+        status: step.status,
+        summary: compact(step.output?.handoff || step.output?.text || step.error || "", 600),
+      })).filter((item) => item.summary.length > 0),
+      warnings: run.warnings,
+      metrics: run.metrics,
+      createdAt,
+    };
+    atomicWriteJson(this.runPath(run.id, "summary.json"), summary);
+    return summary;
+  }
+
+  async loadRun(runId: string): Promise<RunArtifactSummary | undefined> {
+    const file = this.runPath(runId, "summary.json");
+    if (!fs.existsSync(file)) return undefined;
+    return JSON.parse(fs.readFileSync(file, "utf-8")) as RunArtifactSummary;
+  }
+
+  async listFeatures(): Promise<FeatureArtifactState[]> {
+    const dir = path.join(this.root, "features");
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir)
+      .map((name) => path.join(dir, name, "state.json"))
+      .filter((file) => fs.existsSync(file))
+      .map((file) => normalizeFeatureState(JSON.parse(fs.readFileSync(file, "utf-8")) as Partial<FeatureArtifactState>))
+      .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+  }
+
+  private async ensureFeature(featureId: string): Promise<FeatureArtifactState> {
+    return await this.loadFeature(featureId) ?? await this.initFeature({ featureId, goal: `Continue ${featureId}` });
+  }
+
+  private async writeFeatureState(state: FeatureArtifactState): Promise<void> {
+    atomicWriteJson(this.featureStatePath(state.featureId), state);
+  }
+
+  private featureStatePath(featureId: string): string {
+    return this.featurePath(featureId, "state.json");
+  }
+
+  private featurePath(featureId: string, ...parts: string[]): string {
+    return path.join(this.root, "features", safeId(featureId), ...parts);
+  }
+
+  private runPath(runId: string, ...parts: string[]): string {
+    return path.join(this.root, "runs", safeId(runId), ...parts);
+  }
+}
+
+function safeId(value: string): string {
+  return value.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 96) || "artifact";
+}
+
+function atomicWriteJson(file: string, value: unknown): void {
+  atomicWriteText(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function atomicWriteText(file: string, value: string): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, value);
+  fs.renameSync(tmp, file);
+}
+
+function appendJsonLine(file: string, value: unknown): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, `${JSON.stringify(value)}\n`);
+}
+
+function formatWorkerSkill(skill: WorkerSkillArtifact): string {
+  return [
+    "---",
+    `name: ${skill.name}`,
+    `description: ${skill.summary}`,
+    "---",
+    "",
+    "## Purpose",
+    skill.summary,
+    "",
+    "## Rules",
+    ...skill.rules.map((rule) => `- ${rule}`),
+    "",
+  ].join("\n");
+}
+
+function compact(text: string, max: number): string {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  return normalized.length <= max ? normalized : `${normalized.slice(0, max - 1)}…`;
+}
+
+function normalizeFeatureState(raw: Partial<FeatureArtifactState>): FeatureArtifactState {
+  const now = new Date().toISOString();
+  return {
+    featureId: raw.featureId ?? "artifact",
+    goal: raw.goal ?? "Continue artifact",
+    status: raw.status ?? "active",
+    chain: raw.chain ?? [],
+    currentStep: raw.currentStep,
+    checkpoints: raw.checkpoints ?? [],
+    validationContracts: raw.validationContracts ?? [],
+    workerSkills: raw.workerSkills ?? [],
+    interviewDecisions: raw.interviewDecisions ?? [],
+    createdAt: raw.createdAt ?? now,
+    updatedAt: raw.updatedAt ?? now,
+  };
+}