State Migrations

Contents

Overview

stateDiagram-v2
    [*] --> Idle
    Idle --> Scanning : startup trigger
    Scanning --> NothingFound : no legacy dirs
    NothingFound --> Idle
    Scanning --> PlanReady : legacy detected
    PlanReady --> Preview : compute copy plan
    Preview --> Executing : user confirms or auto-approve
    Preview --> Aborted : conflict detected
    Aborted --> Idle
    Executing --> Verifying : all moves complete
    Verifying --> Done : checksums match
    Verifying --> Rollback : mismatch detected
    Rollback --> Idle : restore originals
    Done --> [*]

The state diagram above shows the full migration lifecycle. The system starts in Idle, scans for legacy directories on startup, computes a copy plan, previews it, executes atomic moves, and verifies the result. If verification fails, a rollback restores the originals.

Decision Points

How It Works

The migration pipeline is implemented across two main files: state-migrations.ts (200+ lines) handles directory-level moves, and legacy-migrate.ts in the config module handles config format transformation. Both follow the same detect–plan–execute–verify pattern.

Legacy Detection

The LegacyStateDetection type captures the result of the initial filesystem scan. Each field maps to a specific legacy directory or file pattern.

/** Result of scanning for legacy state artifacts */
interface LegacyStateDetection {
  hasLegacySessions: boolean;
  hasLegacyAgents: boolean;
  hasWhatsAppAuth: boolean;
  hasPairingAllowlist: boolean;
  legacyConfigPath: string | null;
  legacyConfigVersion: number | null;
}

/** Session entry compatible with both old and new formats */
interface SessionEntryLike {
  sessionId: string;
  updatedAt: number;
  [key: string]: unknown;
}

async function detectLegacyState(
  homedir: string
): Promise<LegacyStateDetection> {
  const clawDir = path.join(homedir, ".claw");
  const [sessions, agents, waAuth, allowlist, config] = await Promise.all([
    directoryExists(path.join(clawDir, "sessions")),
    directoryExists(path.join(clawDir, "agents")),
    directoryExists(path.join(clawDir, "whatsapp-auth")),
    fileExists(path.join(clawDir, "pairing-allowlist.json")),
    findLegacyConfig(clawDir),
  ]);
  return {
    hasLegacySessions: sessions,
    hasLegacyAgents: agents,
    hasWhatsAppAuth: waAuth,
    hasPairingAllowlist: allowlist,
    legacyConfigPath: config?.path ?? null,
    legacyConfigVersion: config?.version ?? null,
  };
}

Session Store Parsing

Legacy session stores use JSON5 format (allowing comments and trailing commas). The readSessionStoreJson5 function handles this gracefully:

interface SessionStoreResult {
  ok: boolean;
  store: Record<string, SessionEntry>;
}

async function readSessionStoreJson5(
  filePath: string
): Promise<SessionStoreResult> {
  try {
    const raw = await fs.readFile(filePath, "utf-8");
    const parsed = JSON5.parse(raw);
    if (typeof parsed !== "object" || parsed === null) {
      return { ok: false, store: {} };
    }
    const store: Record<string, SessionEntry> = {};
    for (const [key, value] of Object.entries(parsed)) {
      if (isSessionEntryLike(value)) {
        store[key] = normalizeSessionEntry(value);
      }
    }
    return { ok: true, store };
  } catch {
    return { ok: false, store: {} };
  }
}

Copy Plan Computation

Once legacy artifacts are detected, the pipeline computes a deterministic copy plan—a list of source/target pairs with conflict annotations. The plan is fully computed before any filesystem mutation occurs.

Config Validation Pipeline

Config migration follows a five-stage pipeline that transforms raw config text into a validated, typed object:

Migration Detection Algorithm

flowchart TD
    A["Read ~/.claw directory listing"] --> B{"sessions/ exists?"}
    B -- Yes --> C["Mark hasLegacySessions"]
    B -- No --> D{"agents/ exists?"}
    C --> D
    D -- Yes --> E["Mark hasLegacyAgents"]
    D -- No --> F{"whatsapp-auth/ exists?"}
    E --> F
    F -- Yes --> G["Mark hasWhatsAppAuth"]
    F -- No --> H{"pairing-allowlist.json exists?"}
    G --> H
    H -- Yes --> I["Mark hasPairingAllowlist"]
    H -- No --> J{"Config file found?"}
    I --> J
    J -- Yes --> K["Parse config, extract version"]
    J -- No --> L["No legacy config"]
    K --> M{"Any legacy flag set?"}
    L --> M
    M -- Yes --> N["Compute copy plan"]
    M -- No --> O["Return: nothing to migrate"]
    N --> P["Check for conflicts"]
    P --> Q{"Conflicts found?"}
    Q -- Yes --> R["Abort with diagnostic"]
    Q -- No --> S["Preview plan to user"]
    S --> T["Execute atomic moves"]
    T --> U["Verify checksums"]
    U --> V["Migration complete"]

The flowchart above traces the full detection-to-execution path. Each diamond is a decision point where the algorithm can short-circuit. The atomic move phase uses rename() calls that are crash-safe on POSIX filesystems—either the rename completes or the source remains untouched.

Annotated Code Walkthrough

Walk through the config validation pipeline that runs after raw config text is read from disk.

import JSON5 from "json5";
import { z } from "zod";

async function loadConfig(
  filePath: string
): Promise<ResolvedConfig> {
  const raw = await fs.readFile(filePath, "utf-8");
  const parsed = JSON5.parse(raw);
  // Stage 1: JSON5 parse complete
  return validateConfig(parsed);
}

function substituteEnvVars(
  obj: Record<string, unknown>
): Record<string, unknown> {
  const result: Record<string, unknown> = {};
  for (const [key, value] of Object.entries(obj)) {
    if (typeof value === "string") {
      result[key] = value.replace(
        /\$\{(\w+)\}/g,
        (_, name) => process.env[name] ?? ""
      );
    } else if (typeof value === "object" && value !== null) {
      result[key] = substituteEnvVars(
        value as Record<string, unknown>
      );
    } else {
      result[key] = value;
    }
  }
  return result;
}

const ConfigSchema = z.object({
  version: z.literal(2),
  dataDir: z.string().default("~/.openclaw/data"),
  logLevel: z.enum(["debug", "info", "warn", "error"]).default("info"),
  maxRetries: z.number().int().min(0).max(100).default(5),
  dangerousKeys: z.array(z.string()).optional(),
});

function validateConfig(
  parsed: unknown
): ResolvedConfig {
  const substituted = substituteEnvVars(
    parsed as Record<string, unknown>
  );
  const result = ConfigSchema.parse(substituted);
  if (result.dangerousKeys?.length) {
    console.warn(
      "Config contains dangerous keys:",
      result.dangerousKeys
    );
  }
  return result as ResolvedConfig;
}

const KEY_RENAMES: Record<string, string> = {
  "data_dir": "dataDir",
  "log_level": "logLevel",
  "max_retries": "maxRetries",
  "wa_auth_path": "whatsappAuthPath",
};

function migrateLegacyConfig(
  old: Record<string, unknown>
): Record<string, unknown> {
  const migrated: Record<string, unknown> = { version: 2 };
  for (const [key, value] of Object.entries(old)) {
    const newKey = KEY_RENAMES[key] ?? key;
    migrated[newKey] = value;
  }
  return migrated;
}

Edge Cases & Error Handling

Configuration

Related Topics

See also:

• store overview — the parent sub-module page
• Data Models — the type definitions that migrations must produce
• Query Builder — atomic I/O primitives used during the move phase

Directory Map

src/infra/store/
├── state-migrations.ts        ← LegacyStateDetection, scan, plan, execute, verify (200+ lines)
├── session-store.ts           ← readSessionStoreJson5(), SessionEntry normalization
└── ...
src/infra/config/
├── legacy-migrate.ts          ← KEY_RENAMES map, migrateLegacyConfig()
├── config-schema.ts           ← Zod ConfigSchema, env substitution
└── ...