Pada arsitektur editor kreatif atau multimedia berbasis agent (seperti FableCut atau editor video berbasis web), state proyek umumnya diserialisasi dalam satu file JSON terstruktur. Masalah muncul ketika AI agent dan pengguna memodifikasi file ini secara bersamaan tanpa sinkronisasi transaksi yang ketat. Kondisi race condition ini memicu state drift: struktur JSON terpotong, referensi node timeline rusak, atau validasi schema gagal saat runtime.

Gejala Korupsi Schema pada Konkurensi Agent-User

State drift pada agentic editor terjadi saat model LLM mengeksekusi tool call mutasi state (misalnya split_clip atau reorder_tracks) bersamaan dengan mutasi langsung dari UI pengguna (misalnya pergeseran playhead atau resize elemen). Gejala umum yang muncul meliputi:

  • Partial JSON write: Agent menulis perubahan secara streaming atau non-atomik langsung ke storage/memory, menghasilkan payload yang tidak valid secara sintaksis.
  • Dangling references: Agent menghapus layer atau aset yang UUID-nya masih dijadikan referensi oleh komponen aktif di client runtime.
  • Inverted timeline boundaries: Nilai startTime lebih besar daripada endTime akibat perhitungan token offset yang meleset pada parser agent.
  • Client white-screen: React/Svelte runtime client gagal melakukan render ulang karena TypeError: Cannot read properties of undefined saat mengakses array node yang hilang.

Observasi Metrik Parsing Error via Sentry dan Prometheus

Deteksi dini kegagalan parsing state membutuhkan instrumentasi pada frontend dan backend sync gateway. Frontend mengirimkan trace error parsing ke Sentry saat deserialisasi gagal, sementara backend mencatat metrik kegagalan schema via Prometheus.

Contoh instrumentasi frontend untuk menangkap failure parsing ke Sentry:

import * as Sentry from "@sentry/browser";

export function parseProjectState(rawPayload: string) {
  try {
    return JSON.parse(rawPayload);
  } catch (error) {
    Sentry.captureException(error, {
      tags: {
        component: "StateDeserializer",
        mutationSource: "agent_stream",
      },
      extra: {
        rawSnippet: rawPayload.slice(0, 500),
      },
    });
    throw new Error("PROJECT_STATE_CORRUPTED");
  }
}

Pada backend sync gateway, ekspor metrik Counter ke Prometheus untuk memonitor lonjakan kegagalan validasi schema saat agen memproses instruksi:

import { Counter } from "prom-client";

export const projectSchemaErrorCounter = new Counter({
  name: "editor_project_schema_validation_errors_total",
  help: "Total schema validation failures triggered by state updates",
  labelNames: ["source", "error_type"],
});

// Digunakan di middleware penyimpanan state:
// projectSchemaErrorCounter.inc({ source: "agent", error_type: "zod_validation_failed" });

Strategi Rollback Atomic Berbasis Snapshot File

Saat deteksi anomali terjadi, mutasi yang sedang berjalan harus dibatalkan seketika dan state file harus dikembalikan ke kondisi valid terakhir (last-known-good state). Penulisan file proyek harus selalu menggunakan operasi atomic write (tulis ke file temporary terlebih dahulu, kemudian ganti nama file via rename atomik di level POSIX/filesystem) untuk mencegah partial file overwrite.

import { promises as fs } from "fs";
import path from "path";

export async function saveAtomicSnapshot(
  projectPath: string,
  state: Record<string, unknown>,
  version: number
): Promise<void> {
  const dir = path.dirname(projectPath);
  const tempPath = path.join(dir, `.state.${version}.tmp`);
  const snapshotPath = path.join(dir, `snapshot.v${version}.json`);
  const payload = JSON.stringify(state, null, 2);

  // 1. Simpan salinan snapshot versi valid
  await fs.writeFile(snapshotPath, payload, "utf-8");

  // 2. Tulis ke file temporary lalu lakukan rename atomik
  await fs.writeFile(tempPath, payload, "utf-8");
  await fs.rename(tempPath, projectPath);
}

export async function rollbackToSnapshot(
  projectPath: string,
  targetVersion: number
): Promise<void> {
  const dir = path.dirname(projectPath);
  const snapshotPath = path.join(dir, `snapshot.v${targetVersion}.json`);
  
  // Validasi snapshot ada sebelum mengembalikan file
  await fs.access(snapshotPath);
  await fs.copyFile(snapshotPath, projectPath);
}

Implementasi Pencegahan: Schema Validation dan Optimistic Locking

Pencegahan struktural memerlukan dua lapisan pertahanan: validasi schema menggunakan Zod sebelum mutasi diterapkan ke storage, dan optimistic locking menggunakan field versi inkremental untuk mencegah penulisan tumpang tindih antara pengguna dan agent.

import { z } from "zod";

// 1. Definisi Schema Strict
export const ProjectSchema = z.object({
  id: z.string().uuid(),
  version: z.number().int().nonnegative(),
  timeline: z.object({
    fps: z.number().min(1).max(120),
    tracks: z.array(
      z.object({
        id: z.string(),
        startTime: z.number().nonnegative(),
        duration: z.number().positive(),
      })
    ),
  }),
});

export type ProjectState = z.infer<typeof ProjectSchema>;

// 2. Mutasi dengan Optimistic Locking
export function applyStateMutation(
  currentState: ProjectState,
  incomingPatch: Partial<ProjectState>,
  expectedVersion: number
): ProjectState {
  if (currentState.version !== expectedVersion) {
    throw new Error(
      `STATE_CONFLICT: Version mismatch. Current: ${currentState.version}, Expected: ${expectedVersion}`
    );
  }

  const nextPayload = {
    ...currentState,
    ...incomingPatch,
    version: currentState.version + 1,
  };

  // Validasi schema runtime sebelum commit
  return ProjectSchema.parse(nextPayload);
}

Catatan: Jika agent mengalami kegagalan konflik versi (STATE_CONFLICT), agen wajib melakukan sinkronisasi ulang (re-fetch) terhadap state terbaru, mengkalkulasi ulang diff, lalu mencoba eksekusi kembali.

Ringkasan Postmortem: Insiden Korupsi State

Ringkasan Insiden: Sebanyak 14% sesi pengguna aktif mengalami freeze UI setelah agent mengeksekusi modifikasi track bersamaan dengan editing manual pengguna.

Akar Masalah (Root Cause): Endpoint sinkronisasi memproses payload agent tanpa memvalidasi konsistensi versi. Agent membaca versi 12, memproses instruksi selama 2,5 detik sementara pengguna mengubah versi ke 13. Agent menulis kembali hasil diff dengan basis versi 12, menimpa perubahan pengguna dan memotong field track yang tidak lengkap.

Tindakan Mitigasi:

  1. Mengaktifkan pemeriksaan schema Zod secara sinkron di gateway API state.
  2. Menerapkan rejection kode HTTP 409 Conflict saat versi basis mutasi tidak cocok dengan versi storage.
  3. Mengimplementasikan pipeline snapshot otomatis setiap 5 perubahan state untuk fallback instan client.