Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
29.5 KB
Raw Blame
/**
 * #5470 / #5984: no-op screens for a frozen managed-sync entry. An entry whose
 * publication would change nothing advances the cursor without an admission.
 * The decision commits in one transaction that takes the page guard and then the
 * cursor row (the fixed order), re-reads the page and refuses while any
 * unfinished request names the page, so a waiver never overtakes queued work.
 */
import { join } from 'node:path';
import type { BrainEngine, PageSnapshot } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import { heldDiskBytes, prepareManagedSyncMutation, type SyncIntent } from './sync-prepare.ts';
import { heldGitPaths, readSyncImportProvenances, syncImportParserFor, recordSyncImportProvenances, syncDiskProvenance, type SyncImportProvenance, type SyncImportProvenanceBase } from './sync-holds.ts';
import { sameParser } from './sync-prescreen.ts';
import { isSyncReadBound, isUnreadableSyncFile } from './sync-screen.ts';
import { loadActivePackForEngine } from '../schema-pack/engine-resolution.ts';
import { sha256 } from './digest.ts';
import { startClaimPhase } from './claim-phase.ts';
import { inspectUnchanged, kernelPageSql, kernelPageWork, screeningRequest, type KernelPage, type NoopKernelWaiver } from './noop-kernel.ts';
import { chunkManifestReads } from '../search/safe-chunks.ts';
import { validateSyncAuthority, type SyncAuthority } from './sync-authority.ts';
import { readSyncFile, type SyncEntry } from './sync-discovery.ts';
import { isImageFilePath } from '../sync.ts';
import { getWorktreeBinding } from './ownership.ts';
import { assertSyncPageOrigin, syncOriginScope } from './sync-origin.ts';
import { faultPoint } from './fault-points.ts';
import { pipelined } from '../page-state/transactions.ts';
import { noteDrainSql } from './drain-step.ts';
import { REVISION_BACKFILL_PENDING } from '../page-state/types.ts';
import { withScreeningPaths } from './screening-paths.ts';
import { withBoundedReadSession } from './bounded-reads.ts';
import { isPassBatchKey, passBatchHead } from './sync-pass-batch.ts';

/**
 * The cursor row a waiver commits beside, locked FOR UPDATE (the fixed order: the page guard, then the cursor). #6712 PR 4b:
 * a live pass's batch has no row; its head is read under the drain lease instead (`passBatchHead`).
 */
async function heldCursorHead(tx: BrainEngine, key: string, sourceId: string): Promise<{ run_id: string | null; index: number | string | null; request_id: string | null } | undefined> {
  if (isPassBatchKey(key)) return passBatchHead(tx, key, sourceId);
  const [held] = await tx.executeRaw<{ run_id: string | null; index: number | string | null; request_id: string | null }>(`SELECT completed_keys->0->>'runId' AS run_id,
    completed_keys->0->'index' AS index,completed_keys->0->'pending'->>'requestId' AS request_id FROM op_checkpoints WHERE op='managed-sync' AND fingerprint=$1 FOR UPDATE`, [key]);
  return held;
}

export interface WaiverCursor { sourceId: string; incarnation: string; root: string; gitRoot: string; slugMode: 'git-root' | 'source-root';
  binding: { worktree_id: string }; authority: SyncAuthority; runId: string; index: number }
export interface WaiverEntry { requestId: string; slug: string; pageId: number | null; intent: SyncIntent }
/** `provenance` (a Markdown import): what the waiver records as the page's import provenance, as its publication would have. */
export interface NoopWaiver { kind: 'import' | 'delete'; kernel: NoopKernelWaiver[]; provenance?: SyncImportProvenanceBase }

/** `persistence.sync_preparation_ms` (preparation-budget.ts validates it): the budget a managed sync member's preparation gets; default 120 s. */
export const SYNC_PREPARATION_MS_KEY = 'persistence.sync_preparation_ms';
export const SYNC_PREPARATION_DEFAULT_MS = 120_000;
const BUDGET_TTL_MS = 5000;
let budgets = new WeakMap<object, { at: number; read: Promise<number> }>();
/** The sync preparation budget of `engine`'s brain, read at most every BUDGET_TTL_MS; a failed or malformed read is the default. */
export function syncPreparationBudgetMs(engine: Pick<BrainEngine, 'getConfig'>, now = Date.now()): Promise<number> {
  const held = budgets.get(engine);
  if (held && now - held.at < BUDGET_TTL_MS) return held.read;
  const read = engine.getConfig(SYNC_PREPARATION_MS_KEY).then(value => {
    const n = Number(value?.trim());
    return Number.isInteger(n) && n > 0 ? n : SYNC_PREPARATION_DEFAULT_MS;
  }, () => SYNC_PREPARATION_DEFAULT_MS);
  budgets.set(engine, { at: now, read });
  return read;
}
/** Test seam: the next read sees the current config. */
export function resetSyncPreparationBudget(): void { budgets = new WeakMap(); }

/** The error `raceSyncBudget` rejects with when the budget passes; callers treat it as "cannot decide" and fail open. */
export class SyncPreparationBudgetExceeded extends Error {
  constructor(readonly budgetMs: number) { super(`The sync preparation did not finish within ${budgetMs} ms.`); this.name = 'SyncPreparationBudgetExceeded'; }
}
/**
 * #6278 (1.10): a sync preparation run outside the consumer (a waiver screen or
 * the #5522 origin-equivalence check) runs on the feeder's event loop, where the
 * consumer's deadline cannot see a hang. This races `work` against the sync
 * budget and the run's signal: past the budget it rejects with
 * `SyncPreparationBudgetExceeded` (the caller fails open: nothing is waived,
 * the origin refusal stands, nothing is counted or held); an aborted signal
 * rejects with its reason, so run cancellation propagates. The late result is
 * dropped, never read.
 */
export function raceSyncBudget<T>(work: Promise<T>, budgetMs: number, signal?: AbortSignal): Promise<T> {
  if (signal?.aborted) return Promise.reject(signal.reason ?? new DOMException('The sync was cancelled.', 'AbortError'));
  return new Promise<T>((resolve, reject) => {
    const timer = setTimeout(() => { cleanup(); reject(new SyncPreparationBudgetExceeded(budgetMs)); }, budgetMs);
    timer.unref?.();
    const onAbort = () => { cleanup(); reject(signal!.reason ?? new DOMException('The sync was cancelled.', 'AbortError')); };
    const cleanup = () => { clearTimeout(timer); signal?.removeEventListener('abort', onAbort); };
    signal?.addEventListener('abort', onAbort, { once: true });
    work.then(value => { cleanup(); resolve(value); }, error => { cleanup(); reject(error); });
  });
}
const rethrowAbort = (error: unknown, signal?: AbortSignal) => { if (signal?.aborted) throw error; };

/** DX-A15: `GBRAIN_SYNC_WAIVE_NOOP=0` admits every entry, for triage. */
export function noopWaiversEnabled(env: NodeJS.ProcessEnv = process.env): boolean { return env.GBRAIN_SYNC_WAIVE_NOOP !== '0'; }

const PAGE_MATCH = `r.source_id=$3 AND (r.slug=$4 OR r.page_id=$5::bigint OR r.intent->'renameFrom'->>'slug'=$4 OR r.intent->'renameFrom'->>'pageId'=$6
  OR ($7::text IS NOT NULL AND (r.intent->>'path'=$7 OR r.intent->>'sourcePath'=$8 OR r.intent->'renameFrom'->>'sourcePath'=$8)))`;
/**
 * CEO-A12/A34: an unfinished request for the page, by slug, page id or a rename
 * from it; #6278: also by the entry's file path or origin, or a rename from that
 * origin (`$7`, `$8`; null skips the path match). Each branch matches one
 * partial request index: worktree pending, worktree recovery, and
 * database-only pending by source incarnation.
 */
export const UNFINISHED_PAGE_REQUEST_SQL = `SELECT 1 FROM (
  (SELECT r.id FROM persistence_requests r WHERE r.worktree_id=$1::uuid AND r.state IN ('queued','running','recovering') AND ${PAGE_MATCH} LIMIT 1)
  UNION ALL (SELECT r.id FROM persistence_requests r WHERE r.worktree_id=$1::uuid AND r.recovery IS NOT NULL AND ${PAGE_MATCH} LIMIT 1)
  UNION ALL (SELECT r.id FROM persistence_requests r WHERE r.source_incarnation=$2::uuid AND r.worktree_id IS NULL
    AND r.state IN ('queued','running','recovering') AND ${PAGE_MATCH} LIMIT 1)) unfinished LIMIT 1`;

/** The parameters of `UNFINISHED_PAGE_REQUEST_SQL` for one frozen entry (slug, page id, file path and origin). */
export function unfinishedPageRequestParams(cursor: Pick<WaiverCursor, 'sourceId' | 'incarnation' | 'binding'>, pending: Pick<WaiverEntry, 'slug' | 'pageId' | 'intent'>): unknown[] {
  return [cursor.binding.worktree_id, cursor.incarnation, cursor.sourceId, pending.slug, pending.pageId, String(pending.pageId),
    pending.intent.path ?? null, pending.intent.sourcePath ?? pending.intent.path ?? null];
}

/**
 * Screens a frozen, unadmitted entry. Returns null to admit, or the cursor that
 * `advance` (the waiver won) or `reread` (the cursor moved meanwhile) returns
 * inside the waiver transaction. A revoked sync authority throws before any
 * waiver decision.
 */
export async function waiveNoopEntry<C extends WaiverCursor>(engine: BrainEngine, cursor: C, pending: WaiverEntry, config: GBrainConfig, key: string,
  advance: (tx: BrainEngine, waived: NoopWaiver) => Promise<C>, reread: (tx: BrainEngine) => Promise<C>, signal?: AbortSignal): Promise<C | null> {
  const waived = await screenWaiver(engine, cursor, pending, config, signal);
  if (!waived) return null;
  const intent = pending.intent;
  return engine.transaction(async tx => {
    await tx.lockPageKeys([{ sourceId: cursor.sourceId, slug: pending.slug }]);
    const held = await heldCursorHead(tx, key, cursor.sourceId);
    if (held?.run_id !== cursor.runId || Number(held.index) !== cursor.index || held.request_id !== pending.requestId) return reread(tx);
    const snapshot = await tx.readPageSnapshot(pending.slug, { sourceId: cursor.sourceId, includeDeleted: true });
    if (waived.kind === 'delete') {
      if (!softDeletedAt(snapshot, pending) || waiverRead(cursor.root, intent.path!) !== null) return null;
      try { await assertSyncPageOrigin(tx, cursor.sourceId, intent.sourcePath!, pending.pageId, true, syncOriginScope(cursor)); }
      catch { return null; }
    } else if (snapshot?.page.id !== pending.pageId || snapshot.page.deleted_at != null || snapshot.revision !== intent.expected_revision) return null;
    const unfinished = await tx.executeRaw(UNFINISHED_PAGE_REQUEST_SQL, unfinishedPageRequestParams(cursor, pending));
    if (unfinished.length) return null;
    const provenance = waivedProvenance(cursor, pending, waived, snapshot!.revision);
    if (provenance === false) return null;
    await recordSyncImportProvenances(tx, provenance ? [provenance] : []);
    return advance(tx, waived);
  });
}

/**
 * The screen half of a waiver, before its transaction: whether this frozen,
 * unadmitted entry's publication would change nothing (a delete of a page
 * already soft-deleted at its frozen revision, or an unchanged import). A
 * revoked sync authority throws.
 * #5984 G3: `frozen` is what the freeze of this entry just read and validated
 * (its page snapshot, then the sync authority); the screen of an entry frozen
 * for a waiver run uses it instead of reading both again. The run's waiver
 * transaction re-validates every entry under its locks either way.
 */
export async function screenWaiver(engine: BrainEngine, cursor: WaiverCursor, pending: WaiverEntry, config: GBrainConfig, signal?: AbortSignal,
  frozen?: { snapshot: PageSnapshot | null }): Promise<NoopWaiver | null> {
  if (!noopWaiversEnabled() || pending.pageId === null) return null;
  return withScreeningPaths(() => screenWaiverEntry(engine, cursor, pending, config, signal, frozen));
}
async function screenWaiverEntry(engine: BrainEngine, cursor: WaiverCursor, pending: WaiverEntry, config: GBrainConfig, signal?: AbortSignal,
  frozen?: { snapshot: PageSnapshot | null }): Promise<NoopWaiver | null> {
  const intent = pending.intent;
  if (intent.kind === 'managed_sync_delete') {
    if (intent.unownedDeletion || intent.renameFrom || intent.rawHash !== null || typeof intent.path !== 'string' || typeof intent.sourcePath !== 'string') return null;
    const snapshot = frozen ? frozen.snapshot : await engine.readPageSnapshot(pending.slug, { sourceId: cursor.sourceId, includeDeleted: true });
    if (!softDeletedAt(snapshot, pending)) return null;
    if (!frozen) await validateSyncAuthority(engine, cursor.authority, pending.slug);
    return { kind: 'delete', kernel: [] };
  }
  const unchanged = await unchangedSyncImport(engine, cursor, pending, config, signal, frozen?.snapshot);
  if (!unchanged) return null;
  if (!frozen) await validateSyncAuthority(engine, cursor.authority, pending.slug);
  return { kind: 'import', ...unchanged };
}

/** #5984: `GBRAIN_SYNC_WAIVE_BATCH=0` (or `sync.waive_batch=false`) waives one entry per transaction, as before. */
export async function waiverBatchEnabled(engine: BrainEngine, env: NodeJS.ProcessEnv = process.env): Promise<boolean> {
  const value = env.GBRAIN_SYNC_WAIVE_BATCH ?? await engine.getConfig('sync.waive_batch').catch(() => null);
  return !(value === '0' || value === 'false');
}
export interface WaiverRunEntry { pending: WaiverEntry; waived: NoopWaiver }
/** #6423: the most calls `waiveNoopRun` pipelines in one round trip (two per entry: the unfinished-request read and the delete origin check). */
export const WAIVER_PIPELINE_MAX = 64;
/**
 * #5984 Phase 3: commits a run of consecutive screened waivers at the cursor
 * head in one transaction. It takes every page guard (in the engine's key
 * order) and then the cursor row, which must still be at the run's first entry
 * with nothing pending; it re-validates each entry inside the transaction
 * (page identity, revision and deleted state, file absence and origin for a
 * delete, no unfinished request for the page) and advances only past the
 * contiguous validated prefix. Returns null when not even the first entry
 * holds, or on a lock or statement timeout, so the caller takes the per-entry
 * path; `next` is the frozen entry that stopped the prefix, for that path to
 * screen again without re-freezing; `reread` answers when another run moved
 * the cursor.
 */
export async function waiveNoopRun<C extends WaiverCursor>(engine: BrainEngine, cursor: C, run: readonly WaiverRunEntry[], key: string,
  advance: (tx: BrainEngine, prefix: readonly WaiverRunEntry[]) => Promise<C>, reread: (tx: BrainEngine) => Promise<C>): Promise<{ cursor: C; waived: number; next?: WaiverEntry } | null> {
  if (!run.length) return null;
  try {
    return await engine.transaction(async tx => {
      await tx.executeRaw("SELECT set_config('lock_timeout','2s',true),set_config('statement_timeout','10s',true)");
      await tx.lockPageKeys(run.map(entry => ({ sourceId: cursor.sourceId, slug: entry.pending.slug })));
      const held = await heldCursorHead(tx, key, cursor.sourceId);
      if (held?.run_id !== cursor.runId || Number(held.index) !== cursor.index || held.request_id != null) return { cursor: await reread(tx), waived: 0 };
      await faultPoint('sync:mid_waiver_run', { sourceId: cursor.sourceId });
      // The run's screens may span many entries: an owner change since the first one sends the run back to the per-entry path.
      const binding = await getWorktreeBinding(tx, cursor.sourceId);
      if (!binding || String(binding.owner_epoch) !== run[0]!.pending.intent.ownerEpoch) return null;
      const pages = await tx.executeRaw<{ id: number | string; slug: string; deleted: boolean; knowledge_revision: string | number | null }>(
        'SELECT id,slug,deleted_at IS NOT NULL AS deleted,knowledge_revision FROM pages WHERE source_id=$1 AND slug=ANY($2::text[])', [cursor.sourceId, run.map(entry => entry.pending.slug)]);
      const bySlug = new Map(pages.map(page => [page.slug, page]));
      const scope = syncOriginScope(cursor);
      // #6423: the per-entry checks go out in pipelined chunks of at most WAIVER_PIPELINE_MAX calls, and a chunk is sent only
      // while every entry before it validated (the prefix stops at the first entry that does not).
      let valid = 0;
      const provenances: Array<Omit<SyncImportProvenance, 'recorded_at' | 'validated'>> = [];
      chunks: for (let from = 0; from < run.length; from += WAIVER_PIPELINE_MAX / 2) {
        const chunk = run.slice(from, from + WAIVER_PIPELINE_MAX / 2);
        noteDrainSql(UNFINISHED_PAGE_REQUEST_SQL);
        const checks = await pipelined(tx, chunk.flatMap(({ pending, waived }) => [
          () => tx.executeRaw(UNFINISHED_PAGE_REQUEST_SQL, unfinishedPageRequestParams(cursor, pending)),
          () => waived.kind === 'delete'
            ? assertSyncPageOrigin(tx, cursor.sourceId, pending.intent.sourcePath!, pending.pageId, true, scope).then(() => true, () => false)
            : Promise.resolve(true),
        ])) as Array<unknown[] | boolean>;
        for (const [i, { pending, waived }] of chunk.entries()) {
          const page = bySlug.get(pending.slug);
          const revision = page ? page.knowledge_revision == null ? REVISION_BACKFILL_PENDING : String(page.knowledge_revision) : null;
          if (!page || Number(page.id) !== pending.pageId || revision !== pending.intent.expected_revision) break chunks;
          if (waived.kind === 'delete' ? !page.deleted || waiverRead(cursor.root, pending.intent.path!) !== null : page.deleted) break chunks;
          if ((checks[2 * i] as unknown[]).length || checks[2 * i + 1] !== true) break chunks;
          const provenance = waivedProvenance(cursor, pending, waived, revision!);
          if (provenance === false) break chunks;
          if (provenance) provenances.push(provenance);
          valid++;
        }
      }
      if (!valid) return null;
      await recordSyncImportProvenances(tx, provenances);
      return { cursor: await advance(tx, run.slice(0, valid)), waived: valid, ...(valid < run.length ? { next: run[valid]!.pending } : {}) };
    });
  } catch (error) {
    const code = (error as { code?: unknown } | null)?.code;
    if (code === '55P03' || code === '57014') return null;
    throw error;
  }
}

/** #6712 PR 1: a prescreened manifest entry (sync-prescreen.ts), as the guarded kernel run checks it. */
export interface PrescreenedEntry { slug: string; pageId: number; revision: string; path: string; sourcePath: string }
/** The most prescreened entries one kernel transaction passes. */
export const PRESCREEN_RUN_MAX = 500;
/** The consecutive prescreened manifest entries from `index` (none the kernel already declined in this run), at most `limit`. */
export function prescreenedHead(entries: ReadonlyArray<SyncEntry>, index: number, missed: ReadonlySet<number>, limit: number): PrescreenedEntry[] {
  const run: PrescreenedEntry[] = [];
  for (let at = index; at < entries.length && run.length < Math.min(PRESCREEN_RUN_MAX, limit); at++) {
    const entry = entries[at]!;
    if (!entry.prescreened || missed.has(at)) break;
    run.push({ slug: entry.slug!, pageId: Number(entry.pageId), revision: String(entry.revision), path: entry.path, sourcePath: entry.sourcePath });
  }
  return run;
}
/**
 * #6712 PR 1 (L1): the guarded no-op kernel's bounded checks for a run of consecutive prescreened entries at the cursor
 * head, with no preparation: the prescreen already matched each file to its recorded import, so only the database side
 * and the file on disk are re-checked here. One transaction takes every page guard, then the cursor row (still at the
 * run's first entry, nothing pending), confirms the owner epoch, and passes the contiguous prefix whose entries each
 * hold: authority (checked before the transaction; a revoked grant throws), identity (the same page id, live, at the
 * frozen revision), projection and metadata (`kernelPageWork`), the import provenance (the record still names the
 * frozen revision, and the file on disk still has the recorded bytes), no unfinished request for the page, and no
 * active hold on the path. Returns null when not even the first entry holds (or on a lock or statement timeout): the
 * caller imports that entry through the ordinary path. Only this run skips durably; the prescreen never does.
 */
export async function waivePrescreenedRun<C extends WaiverCursor & { binding: { owner_epoch: string | number } }>(engine: BrainEngine, cursor: C,
  run: readonly PrescreenedEntry[], key: string, input: { embeddingRequested: boolean; noSchemaPack: boolean },
  advance: (tx: BrainEngine, count: number) => Promise<C>, reread: (tx: BrainEngine) => Promise<C>): Promise<{ cursor: C; waived: number } | null> {
  if (!run.length || !noopWaiversEnabled()) return null;
  for (let i = 0; i < run.length; i += 16) await Promise.all(run.slice(i, i + 16).map(entry => validateSyncAuthority(engine, cursor.authority, entry.slug)));
  // A cursor frozen by another binary or under another schema pack re-checks the parser fingerprint its prescreen matched.
  const pack = input.noSchemaPack ? null : await loadActivePackForEngine(engine, { remote: false, sourceId: cursor.sourceId }).catch(() => null);
  try {
    return await engine.transaction(async tx => {
      await tx.executeRaw("SELECT set_config('lock_timeout','2s',true),set_config('statement_timeout','10s',true)");
      await tx.lockPageKeys(run.map(entry => ({ sourceId: cursor.sourceId, slug: entry.slug })));
      const held = await heldCursorHead(tx, key, cursor.sourceId);
      if (held?.run_id !== cursor.runId || Number(held.index) !== cursor.index || held.request_id != null) return { cursor: await reread(tx), waived: 0 };
      await faultPoint('sync:prescreened', { sourceId: cursor.sourceId });
      const binding = await getWorktreeBinding(tx, cursor.sourceId);
      if (!binding || String(binding.owner_epoch) !== String(cursor.binding.owner_epoch)) return null;
      const pages = new Map((await tx.executeRaw<KernelPage>(`${kernelPageSql(await chunkManifestReads(engine, tx))} WHERE p.source_id=$1 AND p.slug=ANY($2::text[]) AND p.deleted_at IS NULL`,
        [cursor.sourceId, run.map(entry => entry.slug)])).map(page => [page.slug, page]));
      const records = await readSyncImportProvenances(tx, cursor.sourceId, cursor.incarnation, run.map(entry => entry.pageId));
      const holds = await heldGitPaths(tx, cursor.sourceId, cursor.incarnation, run.map(entry => entry.path));
      let valid = 0;
      chunks: for (let from = 0; from < run.length; from += WAIVER_PIPELINE_MAX) {
        const chunk = run.slice(from, from + WAIVER_PIPELINE_MAX);
        noteDrainSql(UNFINISHED_PAGE_REQUEST_SQL);
        const unfinished = await pipelined(tx, chunk.map(entry => () => tx.executeRaw(UNFINISHED_PAGE_REQUEST_SQL,
          unfinishedPageRequestParams(cursor, { slug: entry.slug, pageId: entry.pageId, intent: { path: entry.path, sourcePath: entry.sourcePath } as SyncIntent })))) as unknown[][];
        for (const [i, entry] of chunk.entries()) {
          const page = pages.get(entry.slug), record = records.get(entry.pageId);
          if (!page || Number(page.id) !== entry.pageId || page.knowledge_revision !== entry.revision || unfinished[i]!.length || holds.has(entry.path)) break chunks;
          if (kernelPageWork(page, { sourcePath: entry.sourcePath, embeddingRequested: input.embeddingRequested }) !== null) break chunks;
          if (!record?.disk_sha256 || record.revision !== entry.revision || !sameParser(record.parser, syncImportParserFor(entry.sourcePath, pack?.identity ?? null))) break chunks;
          const bytes = waiverRead(cursor.root, entry.path);
          if (!bytes || sha256(bytes) !== record.disk_sha256) break chunks;
          valid++;
        }
      }
      if (!valid) return null;
      return { cursor: await advance(tx, valid), waived: valid };
    });
  } catch (error) {
    const code = (error as { code?: unknown } | null)?.code;
    if (code === '55P03' || code === '57014') return null;
    throw error;
  }
}

/** #5984: whether `waiveNoopEntry` would waive this frozen entry now (read-only; the bulk group stops before such an entry). */
export async function wouldWaiveEntry(engine: BrainEngine, cursor: WaiverCursor, pending: WaiverEntry, config: GBrainConfig, signal?: AbortSignal): Promise<boolean> {
  if (!noopWaiversEnabled() || pending.pageId === null) return false;
  const intent = pending.intent;
  if (intent.kind === 'managed_sync_delete') {
    if (intent.unownedDeletion || intent.renameFrom || intent.rawHash !== null || typeof intent.path !== 'string' || typeof intent.sourcePath !== 'string') return false;
    return softDeletedAt(await engine.readPageSnapshot(pending.slug, { sourceId: cursor.sourceId, includeDeleted: true }), pending);
  }
  return (await unchangedSyncImport(engine, cursor, pending, config, signal)) !== null;
}

/**
 * GBRA-133 S-68: a waiver's read of the working-tree file; undefined when the freeze would hold it (over the read bound, or
 * `file_unreadable`: a symlink, a FIFO, a permission error), so the entry is not waived and goes on to admission instead of
 * failing the run.
 */
function waiverRead(root: string, path: string): Buffer | null | undefined {
  try { return readSyncFile(root, path); } catch (error) { if (isSyncReadBound(error) || isUnreadableSyncFile(error)) return undefined; throw error; }
}

/**
 * #6712: the import provenance a waived import records in its waiver transaction, from the file read there: false when
 * the file no longer has the frozen raw hash (the entry is not waived), null for a waiver that records none (a delete,
 * or an import whose preparation carried no provenance, such as a code file).
 * #8089: the disk half follows `syncDiskBytes`' rule. The imported bytes are the ones whose hash the provenance records
 * (the frozen content, or for a `published` no-op the working file); the file read here is recorded only when it holds
 * them (up to line endings), else the imported bytes are. When neither is in hand, nothing is recorded.
 */
export function waivedProvenance(cursor: WaiverCursor, pending: WaiverEntry, waived: NoopWaiver, revision: string): Omit<SyncImportProvenance, 'recorded_at' | 'validated'> | false | null {
  if (waived.kind !== 'import') return null;
  const bytes = waiverRead(cursor.root, pending.intent.path!);
  if (bytes === undefined || (bytes === null ? null : sha256(bytes)) !== pending.intent.rawHash) return false;
  if (!waived.provenance) return null;
  const content = typeof pending.intent.content === 'string' ? Buffer.from(pending.intent.content) : null;
  const imported = content && sha256(content) === waived.provenance.raw_sha256 ? content
    : bytes && sha256(bytes) === waived.provenance.raw_sha256 ? bytes : null;
  if (!imported) return null;
  return { ...waived.provenance, page_id: pending.pageId!, revision, ...syncDiskProvenance(heldDiskBytes(bytes, imported), pending.intent.target) };
}

function softDeletedAt(snapshot: Awaited<ReturnType<BrainEngine['readPageSnapshot']>>, pending: WaiverEntry): boolean {
  return snapshot?.page.id === pending.pageId && snapshot.page.deleted_at != null && snapshot.revision === pending.intent.expected_revision;
}

/**
 * #5470 no-op screen for working-tree and company-profile sync: runs the sync
 * preparer on the frozen, unadmitted entry. A rename or a canonical overlay is
 * always admitted. Returns null to admit, or the kernel waivers the skip used and the provenance its waiver records.
 * #5751: a managed working-tree entry waives the two admit reasons its no-op
 * publication can never resolve (a pending contextual-mode stamp, and file
 * bytes that differ from the prepared content yet parse to the same page), so
 * an unchanged legacy file stops taking a request ID on every run.
 * #6278: the preparation races the sync budget (`raceSyncBudget`); past it
 * nothing is waived, and a cancelled run propagates.
 */
export async function unchangedSyncImport(engine: BrainEngine, cursor: WaiverCursor, pending: WaiverEntry, config: GBrainConfig, signal?: AbortSignal,
  frozenSnapshot?: PageSnapshot | null): Promise<Pick<NoopWaiver, 'kernel' | 'provenance'> | null> {
  const intent = pending.intent;
  if (intent.kind !== 'managed_sync_import' || intent.renameFrom || pending.pageId === null || typeof intent.path !== 'string' || typeof intent.content !== 'string') return null;
  // #6529: an image's preparation is provider work; its hash no-op is decided under the admitted request instead.
  if (isImageFilePath(intent.path)) return null;
  try {
    const snapshot = frozenSnapshot !== undefined ? frozenSnapshot : await engine.readPageSnapshot(pending.slug, { sourceId: cursor.sourceId, includeDeleted: true });
    const row = screeningRequest({ source_id: cursor.sourceId, source_incarnation: cursor.incarnation, slug: pending.slug, page_id: pending.pageId,
      worktree_id: cursor.binding.worktree_id, authority: cursor.authority.writer, intent, request_id: pending.requestId });
    // #6278 (1.4): the clock carries the budget, so the preparation's lock-prone reads end on the server at it (boundedReads).
    const budgetMs = await syncPreparationBudgetMs(engine);
    // GBRA-75 wave 9: the screen's bounded reads share one transaction (withBoundedReadSession), each still bounded on the server.
    const prepared = await withBoundedReadSession(engine, session =>
      raceSyncBudget(prepareManagedSyncMutation(session, row, config, startClaimPhase(Date.now(), undefined, budgetMs), { unsaved: true }), budgetMs, signal));
    if (prepared.file || prepared.target === 'skill_bundle') return null;
    const file = { root: cursor.root, path: join(cursor.root, intent.path), content: intent.content };
    const inspected = await inspectUnchanged(engine, { prepared: { ...prepared, target: 'page', file }, snapshot, sourcePath: intent.sourcePath, databaseOnly: false,
      embeddingRequested: !prepared.deferEmbedding && !config.embedding_disabled && !!config.embedding_model?.trim(),
      waive: intent.working === true ? ['contextual_mode', 'canonical_file_differs'] : undefined });
    if (inspected.admitReason) return null;
    await prepared.validate?.(engine);
    // #6712 PR 1: a #5751 waiver records no provenance, since the prescreen would skip the file where the kernel admits it.
    return { kernel: inspected.waived ?? [], ...(prepared.importProvenance && !inspected.waived?.length ? { provenance: prepared.importProvenance } : {}) };
  } catch (error) {
    rethrowAbort(error, signal);
    return null;
  }
}