Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.9 KB
Raw Blame
/**
 * #6712 PR 4b (design v3.2 §3.1): the in-memory round batch of a live pass and its request identity. Kept free of heavy
 * imports: sync-run.ts, sync-waivers.ts and the pass (sync-pass-run.ts) all read it.
 */
import { createHash } from 'node:crypto';
import type { BrainEngine } from '../engine.ts';
import type { SyncEntry } from './sync-discovery.ts';
import { assertDrainLease } from './sync-lease.ts';
import { admissionAllows, readSyncAdmission, type SyncAdmission } from './sync-admission.ts';
import { reservePassCost, type PricedIntent } from './sync-pass-episode.ts';

/**
 * #6712 PR 4b (design v3.2 §3.1): a live pass admits each round batch through the cursor machinery of sync-run.ts with no
 * persisted cursor behind it. The batch lives in this process under a key with this prefix, held only while the pass
 * holds the source's drain lease; every step that would compare-and-swap a cursor row asserts the lease instead
 * (`passBatchStep`).
 */
export const PASS_BATCH_KEY_PREFIX = 'pass:';
export const isPassBatchKey = (key: string | null | undefined): key is string => typeof key === 'string' && key.startsWith(PASS_BATCH_KEY_PREFIX);
type BatchHead = { sourceId: string; runId: string; index: number; pending?: { requestId: string } | null };
const passBatches = new Map<string, { value: BatchHead; header: string }>();
/** The in-memory batch under `key` (null: none, or the pass ended). */
export function readPassBatch<T>(key: string): T | null { return (passBatches.get(key)?.value as T | undefined) ?? null; }
/** Replaces (or, with null, drops) the in-memory batch under `key`; `header` is its serialized header, the compare-and-swap's operand. */
export function setPassBatch(key: string, value: BatchHead | null, header = ''): void {
  if (value) passBatches.set(key, { value, header }); else passBatches.delete(key);
}
/**
 * GBRA-130: whether this pass already passed over the refused receipt of `requestId` (a file changed after admission).
 * A pass's request ID is its path at its level, so reading the same receipt again means the committed level did not move:
 * an uncommitted edit, which the settle path holds `worktree_dirty` instead of the pass using its rounds on it.
 * Records the receipt otherwise. Only the newest passes of this process are kept.
 */
export function passedOverBefore(passId: string, requestId: string): boolean {
  const seen = passedOver.get(passId) ?? new Set<string>();
  if (seen.has(requestId)) return true;
  passedOver.delete(passId); passedOver.set(passId, seen.add(requestId));
  for (const old of passedOver.keys()) if (passedOver.size > 8) passedOver.delete(old);
  return false;
}
const passedOver = new Map<string, Set<string>>();
/**
 * One step of an in-memory batch inside `tx`: the drain lease fences it (the pass that holds the lease is the batch's only
 * writer), and it lands only while the batch's header still is `beforeHeader` (the cursor row's compare-and-swap contract).
 * Returns false when it did not land.
 */
export async function passBatchStep<T extends Pick<BrainEngine, 'executeRaw'>>(tx: T, key: string, beforeHeader: string | null, next: BatchHead, nextHeader: string,
  inTx?: (tx: T) => Promise<unknown>): Promise<boolean> {
  await assertDrainLease(tx, next.sourceId);
  const holds = () => (passBatches.get(key)?.header ?? null) === beforeHeader;
  if (!holds()) return false;
  // What rides the step (a hold write or clear) commits in its transaction; the batch moves only after it ran.
  await inTx?.(tx);
  if (!holds()) return false;
  passBatches.set(key, { value: next, header: nextHeader });
  return true;
}
/** The batch's head as the waivers' cursor-row read returns it, fenced by the drain lease. */
export async function passBatchHead(tx: Pick<BrainEngine, 'executeRaw'>, key: string, sourceId: string): Promise<{ run_id: string | null; index: number | null; request_id: string | null } | undefined> {
  await assertDrainLease(tx, sourceId);
  const batch = passBatches.get(key)?.value;
  return batch ? { run_id: batch.runId, index: batch.index, request_id: batch.pending?.requestId ?? null } : undefined;
}

/** RFC 4122 namespace of pass request ids (fixed forever: changing it re-admits a same-pass replay). */
const NS_SYNC_PASS = Buffer.from('5f0c6712b4a84e0b9d1a2c3e4f5a6712', 'hex');
/**
 * `request_id = uuidv5(NS_SYNC_PASS, passId‖path‖level)` (design v3.2 §3.1): a same-pass replay reads the existing receipt.
 * #8729: `retryOf` (the failed request an in-place re-freeze replaces) names a new request, unique per failed receipt, so
 * a retry prepares the entry again instead of reading a failed receipt back; the first freeze keeps the v1 id.
 */
export function passRequestId(passId: string, path: string, level: string | null, retryOf?: string): string {
  const hash = createHash('sha1').update(NS_SYNC_PASS).update(`sync_pass:v1:${passId.toLowerCase()}\0${path}\0${level ?? ''}${retryOf ? `\0retry:${retryOf.toLowerCase()}` : ''}`).digest();
  hash[6] = (hash[6]! & 0x0f) | 0x50;
  hash[8] = (hash[8]! & 0x3f) | 0x80;
  const hex = hash.subarray(0, 16).toString('hex');
  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
}

/**
 * The converged watermark a pass records (design v3.2 §2.2): the worktree's highest request `sequence`, and the requests
 * (`r:<id>`) and Git effects (`e:<id>`) still open, at most `cap` (null above it: no idle until a full round re-reads).
 */
export async function readConvergedWatermark(tx: Pick<BrainEngine, 'executeRaw'>, scope: { worktreeId: string; sourceId: string; incarnation: string }, selfRequestId: string | null, cap: number,
  /** `converged.writeback` (sync-pass-row.ts): a folded writeback stamp's own write, and the prior stamp's list, of which the uncommitted stay. */
  writeback?: { own?: string; prior?: readonly string[] }): Promise<{ request_hwm: string; open_at_stamp: string[] | null; writeback?: string[] }> {
  // The worktree's requests and the incarnation's worktree-less ones (writes admitted with sync.write_through=false).
  const [hwm] = await tx.executeRaw<{ hwm: string | null }>(`SELECT GREATEST((SELECT max(sequence) FROM persistence_requests WHERE worktree_id=$1::uuid),
    (SELECT max(sequence) FROM persistence_requests WHERE worktree_id IS NULL AND source_id=$2 AND source_incarnation=$3::uuid))::text AS hwm`, [scope.worktreeId, scope.sourceId, scope.incarnation]);
  const open = await tx.executeRaw<{ id: string }>(`(SELECT 'r:'||request_id::text AS id FROM persistence_requests
      WHERE state IN ('queued','running','recovering') AND (worktree_id=$1::uuid OR worktree_id IS NULL AND source_id=$4 AND source_incarnation=$5::uuid)
        AND request_id IS DISTINCT FROM $2::uuid LIMIT $3)
    UNION ALL (SELECT 'e:'||e.id::text FROM persistence_effects e JOIN persistence_requests r ON r.id=e.request_id
      WHERE r.worktree_id=$1::uuid AND e.kind='git' AND e.state IN ('queued','running') LIMIT $3)`, [scope.worktreeId, selfRequestId, cap + 1, scope.sourceId, scope.incarnation]);
  // The prior list's writebacks whose Git effect has not committed (queued, running, failed or parked) and is not settled stay listed.
  const carried = writeback?.prior?.length ? (await tx.executeRaw<{ id: string }>(`SELECT DISTINCT e.request_id::text AS id FROM persistence_effects e
      WHERE e.request_id = ANY($1::uuid[]) AND e.kind='git' AND e.state<>'committed' AND NOT (e.data ? 'settled')`, [writeback.prior])).map(row => row.id) : [];
  const listed = [...new Set([...(writeback?.own ? [writeback.own] : []), ...carried])];
  return { request_hwm: hwm?.hwm ?? '0', open_at_stamp: open.length > cap ? null : open.map(row => row.id), ...(listed.length ? { writeback: listed } : {}) };
}

/** A round batch's entry: the discovery shape plus the level `L` it was classified at (the request identity's third part). */
export interface PassEntry extends SyncEntry { level: string | null }

/** `sync.admission` no longer admits what a pass froze (design v3.2 §8.1): the pass stops `resumable`, `admission_paused`. */
export class SyncAdmissionPaused extends Error {
  constructor(readonly admission: SyncAdmission) { super(`sync.admission is ${admission}, so this sync admits no more writes of that kind.`); this.name = 'SyncAdmissionPaused'; }
}
/**
 * Fencing 1 (design v3.2 §8): a pass's admission transaction re-reads `sync.admission` and admits nothing it no longer
 * allows (a delete needs `normal`; an import or the stamp needs `normal` or `imports_only`). Cursor intents are unaffected.
 */
export async function assertPassAdmission(tx: Pick<BrainEngine, 'executeRaw'>, intents: ReadonlyArray<PricedIntent>): Promise<void> {
  if (!intents.some(intent => intent.passId)) return;
  const admission = await readSyncAdmission(tx);
  for (const intent of intents) {
    if (intent.passId && !admissionAllows(admission, intent.kind === 'managed_sync_delete' ? 'destructive' : 'import')) throw new SyncAdmissionPaused(admission);
  }
  // Design v3.2 §7: the group's cost reservation commits with its admission.
  await reservePassCost(tx, intents);
}