Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.4 KB
Raw Blame
/**
 * The `managedWrite` diagnostic of a managed sync result: what a page request's terminal receipt (or its pending state)
 * means for the operator, with the retry command and, for a pinned-worktree conflict, whether only line endings differ.
 * Moved out of `sync-run.ts` unchanged (#6340 kept that module under its size cap; `writeWaitOf` followed for #6513).
 */
import type { ManagedSyncWriteDiagnostic } from './sync-run.ts';
import type { WriteWait } from './service.ts';
import type { SyncCursorOptions, SyncIntent } from './sync-prepare.ts';
import type { WriteRequest } from './model.ts';
import type { SyncProcessingOptions } from './sync-authority.ts';
import { isTerminalWriteState, publicWriteReceipt } from './types.ts';
import { receiptFor } from './journal.ts';
import { writeFailureDiagnostic } from './verb-errors.ts';
import { checkpointRetryCommand } from './checkpoint-validation.ts';
import { readSyncFile } from './sync-discovery.ts';
import { sha256 } from './digest.ts';
import { classifyTerminal } from './terminal-classify.ts';
import { SYNC_PASS_SUPERSEDED } from './sync-checkpoint-replaced.ts';

export function managedSyncWriteDiagnostic(cursor: { sourceId: string; root: string; processingOptions?: SyncProcessingOptions; syncOptions: SyncCursorOptions | null },
  pending: { slug: string; intent: SyncIntent }, row: WriteRequest): ManagedSyncWriteDiagnostic {
  const terminal = isTerminalWriteState(row.state);
  const code = terminal ? row.error_code ?? (row.state === 'cancelled' ? 'cancelled' : 'storage_error') : 'write_pending';
  const blockedReason = ['writer_busy', 'writer_pool_capacity', 'owner_unavailable', 'recovery_required', 'writer_lock_unavailable',
    'database_contention', 'consumer_stopping', 'revision_changed_repreparing', 'unexpected_file_bytes', 'unexpected_staging_bytes',
    'preparation_deadline', 'group_member_waiting', 'lane_lock_timeout', 'lane_statement_timeout'].includes(row.blocked_reason ?? '') ? row.blocked_reason! : 'write_pending';
  // GBRA-133 PR 3a: a live pass's checkpoint (its stamp) publishes only under the pass that admitted it. A pass that stops with it
  // pending has ended, so the next pass supersedes it: nothing to resume, nothing failed.
  const superseded = pending.intent.kind === 'managed_sync_checkpoint' && !!pending.intent.passId && (!terminal || code === SYNC_PASS_SUPERSEDED);
  const detail = terminal ? writeFailureDiagnostic(code, row.error_message) : superseded ? {
    reason: blockedReason, message: 'This pass ended before its checkpoint published, so the checkpoint is superseded: it is bound to the pass that admitted it and never publishes after it.',
    suggestion: 'Nothing to resume and nothing failed: the pages this pass committed stand, and the next sync pass re-reads the source and stamps its own checkpoint. Do not resubmit or cancel this request.',
  } : {
    reason: blockedReason, message: 'The write is accepted but not committed; the sync checkpoint has not advanced.',
    suggestion: 'Re-run the same sync options to resume this request. Do not submit a replacement request or skip the pending write.',
  };
  // #6712 PR 2 (L5): a terminal receipt's diagnosis category, and the public one beside it, from the one classifier.
  const verdict = terminal ? classifyTerminal({ request_id: row.request_id, source_id: row.source_id, slug: row.slug, operation: row.operation, state: row.state, error_code: row.error_code,
    error_detail: row.error_detail ?? null, recovery: row.recovery, blocked_reason: row.blocked_reason, compacted: row.compacted, publication_started: row.publication_started,
    error_message: row.error_message, intent_kind: typeof row.intent?.kind === 'string' ? row.intent.kind : null }) : null;
  const diagnostic: ManagedSyncWriteDiagnostic = { source_id: cursor.sourceId, slug: pending.slug,
    path: pending.intent.path, write_error: code, ...detail, ...(verdict ? { category: verdict.category, public_category: verdict.public_category } : {}), ...(superseded ? { disposition: 'superseded' as const } : {}),
    write_request: publicWriteReceipt(receiptFor(row)) };
  // #6194: an import that lost to a database write the hold could not prove; the retry re-imports the Git version unless discovery's drift guard holds it.
  if (terminal && code === 'revision_conflict' && pending.intent.kind === 'managed_sync_import') diagnostic.suggestion = `The page changed in the database after this import was frozen. `
    + `Before retrying, compare the file and the page with gbrain sources reconcile ${cursor.sourceId} ${pending.slug} --preview (it writes nothing): a retry re-imports the Git version over the database one. ${diagnostic.suggestion}`;
  if (terminal && !superseded) diagnostic.suggestion += ` After repair, run ${checkpointRetryCommand({ sourceId: cursor.sourceId, processingOptions: cursor.processingOptions, syncOptions: cursor.syncOptions ?? null, repoPath: pending.intent.repoPath })} to retry it under a new request. Skipping failures cannot bypass a managed write.`;
  if (diagnostic.reason === 'pinned_git_worktree_conflict' && pending.intent.path && pending.intent.content !== null) {
    try {
      const bytes = readSyncFile(cursor.root, pending.intent.path);
      if (bytes && sha256(bytes) === pending.intent.rawHash && sha256(bytes) !== sha256(pending.intent.content)
        && bytes.equals(Buffer.from(bytes.toString('utf8')))
        && bytes.toString('utf8').replace(/\r\n/g, '\n') === pending.intent.content.replace(/\r\n/g, '\n')) {
        diagnostic.line_endings = 'crlf_lf_only';
        diagnostic.message += ' The frozen working-tree and Git versions differ only by CRLF/LF line endings; exact byte protection still applies.';
      }
    } catch {}
  }
  return diagnostic;
}

/** DX-A3 / ENG-A12: how the wait for a still-unfinished sync write ended, with its request ID kept. */
export type ManagedSyncWriteWait = { status: 'pending'; request_id: string }
  | { status: 'blocked'; request_id: string; cause: string; command: string }
  | { status: 'read_failed'; request_id: string; reason: string; transient: boolean; sqlstate?: string; attempts: number; message: string; why: string };
export function writeWaitOf(wait: WriteWait): ManagedSyncWriteWait {
  if (wait.kind === 'blocked') return { status: 'blocked', request_id: wait.request_id, cause: wait.cause, command: wait.command };
  if (wait.kind !== 'read_failed') return { status: 'pending', request_id: wait.row.request_id };
  const { kind: _kind, row: _row, ...failure } = wait;
  return { status: 'read_failed', ...failure };
}