Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
persistence: refresh write barrier (deferred state, release trigger, replay refresh-change check), flag off
garrytancfe41a44f6cd
diff --git a/src/core/persistence/consumer-heartbeat.ts b/src/core/persistence/consumer-heartbeat.tsindex ca2189502c..0ab6bf1fb6 100644--- a/src/core/persistence/consumer-heartbeat.ts+++ b/src/core/persistence/consumer-heartbeat.ts@@ -213,12 +213,14 @@ export interface ConsumerHeartbeat {}type DirectEngine = SqlEngine & Partial<Pick<BrainEngine, 'kind' | 'executeRawDirect'>>;+/** What this binary's consumer can drain (v290): `refresh_barrier_1` claims writes deferred behind a worktree refresh. */+export const CONSUMER_CAPABILITIES = ['refresh_barrier_1'] as const;const RENEW_SQL = `WITH purged AS (DELETE FROM persistence_consumers WHERE host_id=$1::uuid AND renewed_at < now() - ($14::integer * interval '1 millisecond') AND NOT (pid=$2::integer AND nonce=$3))- INSERT INTO persistence_consumers(host_id,pid,nonce,pid_ns,kind,mode,restart_required,root_barrier_age_ms,pool,host_json_path,persistence_home,minted_under,version,boot_id,process_start,segment_reader)- VALUES($1::uuid,$2::integer,$3,$4,$5,$6,$7::boolean,$8::integer,$9::text::jsonb,$10,$11,$12::text::jsonb,$13,$15,$16,true)+ INSERT INTO persistence_consumers(host_id,pid,nonce,pid_ns,kind,mode,restart_required,root_barrier_age_ms,pool,host_json_path,persistence_home,minted_under,version,boot_id,process_start,segment_reader,capabilities)+ VALUES($1::uuid,$2::integer,$3,$4,$5,$6,$7::boolean,$8::integer,$9::text::jsonb,$10,$11,$12::text::jsonb,$13,$15,$16,true,ARRAY['${CONSUMER_CAPABILITIES.join("','")}']::text[])ON CONFLICT (host_id,pid,nonce) DO UPDATE SET renewed_at=now(),mode=EXCLUDED.mode,restart_required=EXCLUDED.restart_required,- root_barrier_age_ms=EXCLUDED.root_barrier_age_ms,pool=EXCLUDED.pool,version=EXCLUDED.version,segment_reader=EXCLUDED.segment_reader`;+ root_barrier_age_ms=EXCLUDED.root_barrier_age_ms,pool=EXCLUDED.pool,version=EXCLUDED.version,segment_reader=EXCLUDED.segment_reader,capabilities=EXCLUDED.capabilities`;/*** Starts this process's heartbeat row for `hostId` and renews it everydiff --git a/src/core/persistence/coordinator.ts b/src/core/persistence/coordinator.tsindex 88e7f71326..83641967f0 100644--- a/src/core/persistence/coordinator.ts+++ b/src/core/persistence/coordinator.ts@@ -29,6 +29,7 @@ import { withFilesystemPublication } from './filesystem-guard.ts';import { mayReprepare } from './semantic.ts';import { tryAcquirePublicationCapacity } from './pool-capacity.ts';import { queuePublicationEffects } from './effect-journal.ts';+import { deferredReplayRefusal } from './refresh-barrier.ts';import { timePublicationStep } from './publication-timing.ts';import type { AppendedRange, GitCommitNote } from './effect-model.ts';import { authorizePageVisibility } from './page-visibility.ts';@@ -530,6 +531,9 @@ export async function publishMutation(engine: BrainEngine, row: WriteRequest, prreturn (await getWriteRequestById(engine, row.id))!;}}+ // PR B: a write deferred behind a refresh publishes only when its credential still holds and the refresh changed none of its files.+ const deferredRefusal = await deferredReplayRefusal(engine, row, files);+ if (deferredRefusal) return await engine.transaction(tx => completeWrite(tx, row, deferredRefusal.state, {}, deferredRefusal.failure));releaseCapacity = tryAcquirePublicationCapacity(engine);if (!releaseCapacity) {await releaseUnpublishedClaim(engine, row, 'writer_pool_capacity');diff --git a/src/core/persistence/group-publish.ts b/src/core/persistence/group-publish.tsindex 1598ce5055..e22939a775 100644--- a/src/core/persistence/group-publish.ts+++ b/src/core/persistence/group-publish.ts@@ -500,7 +500,8 @@ function seam(name: PublicationBoundary, row: WriteRequest): Promise<void> {export async function publishSingleWrite(engine: BrainEngine, row: WriteRequest, prepared: PreparedMutation, hostId = hostIdFor(engine), hooks: GroupHooks = {},transaction?: TransactionRunner): Promise<WriteRequest> {const single: PublicationHooks = hooks.projectionPending ? { projectionPending: hooks.projectionPending } : {};- if (engine.kind !== 'postgres' || !singleWrite(row) || !groupable(row, prepared) || !await writeSwitchOn(engine, 'single_write_group').catch(() => true)) {+ // PR B: a write deferred behind a refresh takes the plain path, whose refresh-change check runs before anything publishes.+ if (engine.kind !== 'postgres' || row.deferred_refresh_id || !singleWrite(row) || !groupable(row, prepared) || !await writeSwitchOn(engine, 'single_write_group').catch(() => true)) {return publishMutation(engine, row, prepared, hostId, single);}try { assertMutationProtocol(row); } catch { return publishMutation(engine, row, prepared, hostId, single); }diff --git a/src/core/persistence/journal.ts b/src/core/persistence/journal.tsindex 566d8a1e61..5a325589d2 100644--- a/src/core/persistence/journal.ts+++ b/src/core/persistence/journal.ts@@ -21,11 +21,11 @@ import { writerStamp } from './writer-versions.ts';import { intentCarriesContent, intentCarriesPurgedContent, PURGE_PRESENCE_COLUMNS } from './purged-intent.ts';import { hostname } from 'node:os';import { claimOwner, claimOwnerKind, claimPhaseStamp, startClaimPhase } from './claim-phase.ts';-import { consumerIdentity, RESIDENT_CONSUMER_KINDS } from './consumer-heartbeat.ts';+import { CONSUMER_LIVE_MS, consumerIdentity, RESIDENT_CONSUMER_KINDS } from './consumer-heartbeat.ts';import { classifyHolderLiveness, syncLockId } from '../db-lock.ts';import { publicFailureDetail } from './publication-failure.ts';import { catalogueError } from '../error-catalogue.ts';-import { ACTIVE_REFRESH_STATES_SQL, refreshFenceClear } from './worktree-refresh-schema.ts';+import { ACTIVE_REFRESH_STATES_SQL, refreshFenceClear, RELEASED_DEFERRED } from './worktree-refresh-schema.ts';import { assertMutationProtocol, assertSharedSkillPersistence, declareDurablePersistence, declarePersistenceProtocol, isPersistenceDeclaration, PERSISTENCE_PROTOCOL_PREDICATE } from './protocol.ts';import { assertGraduationAdmission } from './graduation-custody.ts';import { schemaAdmissionRefusal } from './schema-admission.ts';@@ -292,14 +292,16 @@ async function prepareAdmission(engine: BrainEngine, input: WriteAdmission, overconst origin = resolveAdmissionOrigin(input.origin);// #6741 C: a declared background producer is refused before any receipt when the source's owner fails its verification.if (input.worktreeId && declaredBackground(input.origin)) await assertBackgroundOwner(engine, input.sourceId, ownerStatusFix);+ const barrier = input.worktreeId && deferrable(input) ? await readRefreshBarrier(engine) : null;return { requestId, apply: async (tx: BrainEngine): Promise<WriteRequest> => {await declarePersistenceProtocol(tx);// The guards are sent together in lock order (worktree, source, writer, counters) and judged in// that order: the first refusal in this list is the one reported, as when they ran one by one.+ let deferTo: string | null = null;const [, , , , , counters, topology, prior] = await pipelined(tx, [() => assertGraduationAdmission(tx),async () => assertMutationProtocol({ target_kind: input.targetKind, protocol_version: input.protocolVersion }),- async () => { if (input.worktreeId) await assertWorktreeAdmission(tx, input, true); },+ async () => { if (input.worktreeId) deferTo = await assertWorktreeAdmission(tx, input, true, barrier); },// Source membership is locked before principal/counter/request guards. A// deleted/recreated source never receives work accepted for its old identity.async () => {@@ -346,12 +348,12 @@ async function prepareAdmission(engine: BrainEngine, input: WriteAdmission, overINSERT INTO persistence_requests(principal_kind,principal_id,request_id,operation,source_id,source_incarnation,page_id,slug,worktree_id,topology_generation,digest,intent,authority,intent_bytes,terminal_reservation,target_kind,protocol_version,- admitter_version,admitter_host_id,client_request_id,admitter_segment_reader)- VALUES($1,$2,$3::uuid,$4,$5,$6::uuid,$7,$8,$9::uuid,$10,$11,$12::text::jsonb,$13::text::jsonb,$14,$15,$16,$17,$18,$19::uuid,$21,true)+ admitter_version,admitter_host_id,client_request_id,admitter_segment_reader,state,deferred_refresh_id)+ VALUES($1,$2,$3::uuid,$4,$5,$6::uuid,$7,$8,$9::uuid,$10,$11,$12::text::jsonb,$13::text::jsonb,$14,$15,$16,$17,$18,$19::uuid,$21,true,$22,$23::uuid)RETURNING *`, [input.principal.kind, input.principal.id, requestId, input.operation, input.sourceId,input.sourceIncarnation, input.pageId ?? null, input.slug, input.worktreeId ?? null, input.topologyGeneration ?? null,fingerprint, JSON.stringify(input.intent), JSON.stringify(input.authority), bytes, terminalBytes, input.targetKind ?? 'page', input.protocolVersion ?? 1,- stamp.version, stamp.hostId, counters.map(c => c.key), input.clientRequestId ?? null]);+ stamp.version, stamp.hostId, counters.map(c => c.key), input.clientRequestId ?? null, deferTo ? 'deferred' : 'queued', deferTo]);return row;} };}@@ -504,7 +506,7 @@ export async function claimGroupFollowers(engine: BrainEngine, head: WriteReques// (the first non-member) for the claim's round trips, so its recovery record and reads waited on the lane.const next = await tx.executeRaw<{ id: string; state: string; grp: string | null; recovering: boolean; claim_phase: unknown }>(`WITH next AS (SELECT id,sequence,state,${GROUP_KEY_SQL} AS grp,recovery IS NOT NULL AS recovering,NOT ${BACKOFF_ELAPSED('persistence_requests')} AS backoff,transient_interruptions>0 AS charged FROM persistence_requests- WHERE worktree_id=$1::uuid AND sequence>$2 AND (state IN ('queued','running','recovering') OR recovery IS NOT NULL) ORDER BY sequence LIMIT $3),+ WHERE worktree_id=$1::uuid AND sequence>$2 AND (state IN ('queued','running','recovering') OR recovery IS NOT NULL OR ${RELEASED_DEFERRED('persistence_requests')}) ORDER BY sequence LIMIT $3),-- v261: a member still in its transient backoff ends the group's prefix like a non-member, and so does one already-- charged a transient interruption: it publishes alone, so a batch that overruns only as a whole is not retried as one.bound AS (SELECT min(sequence) AS sequence FROM next WHERE grp IS DISTINCT FROM $4 OR state<>'queued' OR recovering OR backoff OR charged)@@ -590,33 +592,64 @@ export async function chargePreparationAttempt(engine: SqlEngine, row: WriteRequ* binding (#6007: both read in one statement after the lock; the fence is* judged first, as before).*/-async function assertWorktreeAdmission(tx: BrainEngine, input: WriteAdmission, replayable = false): Promise<void> {- // Sent together: the server takes the share lock before it reads the fence and the binding.+async function assertWorktreeAdmission(tx: BrainEngine, input: WriteAdmission, replayable = false, barrier: RefreshBarrier | null = null): Promise<string | null> {+ // Sent together: the server takes the share lock before it reads the fence and the binding. PR B: with the barrier on, the+ // active refresh row is locked right after the worktree (protocol.ts lock order), so a deferral and the refresh's terminal+ // transition serialize on it, and the syncing completion below upgrades no lock.const [[worktree], [state]] = await pipelined(tx, [() => tx.executeRaw<{ state: string; owner_epoch: string }>('SELECT state,owner_epoch::text AS owner_epoch FROM persistence_worktrees WHERE id=$1::uuid FOR SHARE', [input.worktreeId]),() => tx.executeRaw<{ refresh: { id: string; state: string; source_ids: string[] } | string | null; bound: boolean }>(`SELECT(SELECT row_to_json(f) FROM (SELECT id,state,source_ids FROM persistence_worktree_refreshes- WHERE worktree_id=$3::uuid AND state IN ${ACTIVE_REFRESH_STATES_SQL} LIMIT 1) f) AS refresh,+ WHERE worktree_id=$3::uuid AND state IN ${ACTIVE_REFRESH_STATES_SQL} LIMIT 1${barrier ? ' FOR NO KEY UPDATE' : ''}) f) AS refresh,EXISTS (SELECT 1 FROM persistence_source_bindings WHERE source_id=$1AND source_incarnation=$2::uuid AND worktree_id=$3::uuid AND topology_generation=$4) AS bound`,[input.sourceId, input.sourceIncarnation, input.worktreeId, input.topologyGeneration]),]) as [Array<{ state: string; owner_epoch: string }>, Array<{ refresh: { id: string; state: string; source_ids: string[] } | string | null; bound: boolean }>];const refresh = typeof state?.refresh === 'string' ? JSON.parse(state.refresh) as { id: string; state: string; source_ids: string[] } : state?.refresh ?? null;- if (refresh) await assertWorktreeNotRefreshing(tx, input, refresh, replayable);+ const deferTo = refresh ? await assertWorktreeNotRefreshing(tx, input, refresh, replayable, barrier) : null;// #6741 C: a background producer never takes a permanent request id against a worktree in recovery (a draining owner still replays).if (worktree?.state === 'recovering' && resolveAdmissionOrigin(input.origin) === 'background') throw backgroundWorktreeInactive(input.sourceId, worktree.state, ownerStatusFix(input.sourceId));if (!state?.bound || input.ownerEpoch != null && worktree && worktree.owner_epoch !== String(input.ownerEpoch)) throw opError('source_changed', 'The source binding changed during admission.',`Source ${input.sourceId}'s worktree binding changed (a claim, transfer or lifecycle change) while this write was being admitted, so nothing was accepted. Check the owner with the command in fix, then submit the write again; reusing the same request_id is safe because nothing was recorded.`,{ fix: ownerStatusFix(input.sourceId) });+ return deferTo;+}++/** PR B: the refresh barrier's bound when it is on (docs/designs/REFRESH_WRITE_BARRIER.md). */+export interface RefreshBarrier { maxDeferred: number }+export const REFRESH_BARRIER_MAX_DEFERRED_KEY = 'persistence.refresh_barrier_max_deferred';+export const REFRESH_BARRIER_MAX_DEFERRED = 1000;+/** What a consumer advertises (consumer-heartbeat.ts CONSUMER_CAPABILITIES) and admission requires of every live one on the owner host. */+export const REFRESH_BARRIER_CAPABILITY = 'refresh_barrier_1';+/** A single page write may wait behind a refresh; jobs (managed sync included), grouped batches and skill bundles keep the refusal. */+function deferrable(input: WriteAdmission): boolean {+ return (input.targetKind ?? 'page') === 'page' && input.operation !== 'submit_job' && publicationGroupKey({ operation: input.operation, intent: input.intent }) === null;+}+async function readRefreshBarrier(engine: BrainEngine): Promise<RefreshBarrier | null> {+ if (!await writeSwitchOn(engine, 'refresh_barrier').catch(() => false)) return null;+ const [row] = await engine.executeRaw<{ value: string }>('SELECT value FROM config WHERE key=$1', [REFRESH_BARRIER_MAX_DEFERRED_KEY]);+ const configured = Number(row?.value);+ return { maxDeferred: Number.isSafeInteger(configured) && configured > 0 ? configured : REFRESH_BARRIER_MAX_DEFERRED };+}+/** Room under the per-refresh cap, and every live consumer of the worktree's owner host can drain a deferred write. */+async function deferralRoom(tx: BrainEngine, worktreeId: string, refreshId: string, barrier: RefreshBarrier): Promise<boolean> {+ const [row] = await tx.executeRaw<{ deferred: number; incapable: boolean }>(`SELECT+ (SELECT count(*) FROM persistence_requests WHERE deferred_refresh_id=$1::uuid AND state='deferred')::int AS deferred,+ EXISTS (SELECT 1 FROM persistence_consumers c JOIN persistence_worktrees w ON w.owner_host_id=c.host_id WHERE w.id=$2::uuid+ AND c.renewed_at>now()-($3::integer*interval '1 millisecond') AND NOT ($4=ANY(c.capabilities))) AS incapable`,+ [refreshId, worktreeId, CONSUMER_LIVE_MS, REFRESH_BARRIER_CAPABILITY]);+ return !!row && !row.incapable && Number(row.deferred) < barrier.maxDeferred;}-async function assertWorktreeNotRefreshing(tx: BrainEngine, input: WriteAdmission, refresh: { id: string; state: string; source_ids: string[] }, replayable: boolean): Promise<void> {+/** The refresh to defer this write behind, or null when it is admitted normally; otherwise refuses. */+async function assertWorktreeNotRefreshing(tx: BrainEngine, input: WriteAdmission, refresh: { id: string; state: string; source_ids: string[] }, replayable: boolean,+ barrier: RefreshBarrier | null): Promise<string | null> {const managedSync = input.operation === 'submit_job' && String(input.intent.kind ?? '').startsWith('managed_sync_');- if (refresh.state === 'syncing' && managedSync) return;+ if (refresh.state === 'syncing' && managedSync) return null;if (refresh.state === 'syncing') {const completed = await tx.executeRaw(`UPDATE persistence_worktree_refreshes f SET state='completed',completed_at=now(),updated_at=now()WHERE f.id=$1::uuid AND f.state='syncing' AND NOT EXISTS (SELECT 1 FROM sources s WHERE s.id=ANY(f.source_ids)AND s.last_commit IS DISTINCT FROM f.target_head) RETURNING f.id`, [refresh.id]);- if (completed.length) return;+ if (completed.length) return null;}if (refresh.state === 'recovery_required') throw catalogueError('refresh_recovery_required',`Refresh ${refresh.id} could not verify the checkout HEAD of source ${input.sourceId}; writes to its worktree stay fenced.`,@@ -626,7 +659,9 @@ async function assertWorktreeNotRefreshing(tx: BrainEngine, input: WriteAdmissio`Retry the same request_id after retry_after_ms: 1000. Check progress with gbrain sources writer status ${input.sourceId}.`);// A single write's replay of a request already accepted (its acknowledgement lost before the fence) reconciles to its// receipt instead; a group admission never bypasses, since its other items may be new.- if (replayable && input.requestId && await getWriteRequest(tx, input.principal, input.requestId)) return;+ if (replayable && input.requestId && await getWriteRequest(tx, input.principal, input.requestId)) return null;+ // PR B: with the barrier on, the write waits behind the refresh as a deferred request instead of being refused.+ if (barrier && input.worktreeId && await deferralRoom(tx, input.worktreeId, refresh.id, barrier)) return refresh.id;error.detail = 'retry_after_ms=1000';error.retryable = true;// GST-1387: nothing was recorded, so the same call is retried after the delay (actor provider renders next: wait).@@ -641,7 +676,9 @@ async function assertWorktreeNotRefreshing(tx: BrainEngine, input: WriteAdmissio* so each probe is an index range scan rather than a walk of every pending row.*/export const EARLIER_HEAD = (earlier: string, r: string, priority: string, laneRoots: string) => `${earlier}.sequence<${r}.sequence- AND ${earlier}.state IN ('queued','running','recovering') AND NOT ${PASSES_QUEUED_SYNC(earlier, r, priority, laneRoots)}`;+ AND (${earlier}.state IN ('queued','running','recovering') OR ${RELEASED_DEFERRED(earlier)}) AND NOT ${PASSES_QUEUED_SYNC(earlier, r, priority, laneRoots)}`;+/** Sets the session flag the v290 deferred-row guard requires of a claim that moves a deferred row to running. */+export const REFRESH_BARRIER_CLAIM_PREDICATE = "set_config('gbrain.refresh_barrier','1',true)='1'";/*** The rows `claimNextWrite` may claim, over `persistence_requests r LEFT JOIN* persistence_worktrees w`, with $1 = host id and $2 = excluded root keys. An@@ -671,7 +708,7 @@ const PASSES_QUEUED_SYNC = (earlier: string, r: string, priority: string, laneRo* run in the claiming process: there a foreground write also passes running lane groups that do not name its* page and publishes beside them on the process's shared worktree lock (group-publish.ts).*/-export const claimableWriteSql = (priority: string, laneRoots = "'{}'::text[]") => `r.state='queued' AND (r.worktree_id IS NULL OR (w.owner_host_id=$1::uuid AND w.state='active'))+export const claimableWriteSql = (priority: string, laneRoots = "'{}'::text[]") => `(r.state='queued' OR ${RELEASED_DEFERRED('r')}) AND (r.worktree_id IS NULL OR (w.owner_host_id=$1::uuid AND w.state='active'))AND (r.worktree_id IS NULL OR ${refreshFenceClear('r')})AND NOT (COALESCE(r.worktree_id::text,'db:'||r.source_incarnation::text)=ANY($2::text[]))AND NOT EXISTS (SELECT 1 FROM persistence_effects blocked WHERE blocked.worktree_id=r.worktree_id AND blocked.recovery IS NOT NULL)@@ -737,7 +774,7 @@ const LEASE_HELD = `EXISTS (SELECT 1 FROM gbrain_cycle_locks l WHERE ${SYNC_KIND* head-of-root rules' business, and one stalled in another process must not stop the sync behind it.*/const FOREGROUND_WAITING_ON = (nonce: string, seen: string, worktree = 'TRUE') => `SELECT f.worktree_id, f.sequence FROM persistence_requests f- WHERE ${worktree} AND f.state IN ('queued','running','recovering') AND (f.state<>'running' OR (NOT f.publication_started+ WHERE ${worktree} AND (f.state IN ('queued','running','recovering') OR ${RELEASED_DEFERRED('f')}) AND (f.state<>'running' OR (NOT f.publication_startedAND f.claim_phase->'owner'->>'nonce' IS DISTINCT FROM ${nonce}))AND f.recovery IS NULL AND NOT ${SYNC_KIND('f')}AND NOT EXISTS (SELECT 1 FROM persistence_requests named WHERE named.worktree_id=f.worktree_id AND named.sequence<f.sequence@@ -781,7 +818,7 @@ export async function claimNextWrite(engine: BrainEngine, hostId: string, leaseMconst token = randomUUID();const [claimed] = await tx.executeRaw<WriteRequest & { passed_sync: boolean; seen_sequence: string | null }>(`UPDATE persistence_requests SET state='running',execution_token=$2::uuid,claim_expires_at=now()+($3::double precision*interval '1 millisecond'),- updated_at=now(),blocked_reason=NULL,claim_phase=$4::text::jsonb WHERE id=$1::uuid RETURNING *,EXISTS (SELECT 1 FROM persistence_requests earlier+ updated_at=now(),blocked_reason=NULL,claim_phase=$4::text::jsonb WHERE id=$1::uuid AND ${REFRESH_BARRIER_CLAIM_PREDICATE} RETURNING *,EXISTS (SELECT 1 FROM persistence_requests earlierWHERE earlier.worktree_id=persistence_requests.worktree_id AND earlier.sequence<persistence_requests.sequenceAND earlier.state='queued' AND ${SYNC_KIND('earlier')}) AS passed_sync,CASE WHEN ${SYNC_KIND('persistence_requests')} THEN (SELECT max(sequence) FROM persistence_requests)::text END AS seen_sequence`,@@ -816,7 +853,7 @@ export async function claimNextLaneHead(engine: BrainEngine, hostId: string, worAND mirror.kind='withdrawal-mirror' AND mirror.state IN ('queued','running'))AND NOT EXISTS (SELECT 1 FROM persistence_requests blocked WHERE blocked.worktree_id=r.worktree_id AND blocked.recovery IS NOT NULL)AND NOT EXISTS (SELECT 1 FROM persistence_requests earlier WHERE earlier.worktree_id=r.worktree_id AND earlier.sequence<r.sequence- AND (earlier.state IN ('queued','recovering') OR (earlier.state='running' AND COALESCE(earlier.intent->>'lane','')<>$3)))+ AND (earlier.state IN ('queued','recovering') OR ${RELEASED_DEFERRED('earlier')} OR (earlier.state='running' AND COALESCE(earlier.intent->>'lane','')<>$3)))-- #5984 Phase 4.5: no new lane head while a foreground write that may go first waits (a claimed one publishes-- beside the lanes), except one head after each foreground commit since this run's last head claim.AND NOT ((${foregroundPrioritySql()}) AND r.worktree_id IN (SELECT f.worktree_id FROM (${FOREGROUND_WAITING_ON('$5::text', '$4::bigint', 'f.worktree_id=$2::uuid')}) f))@@ -1217,11 +1254,15 @@ export async function compactReceipt(engine: BrainEngine, row: Pick<WriteRequestreturn { freed_bytes: freed };});}-export function receiptFor(row: WriteRequest, facts?: WriteHealthFacts, now = Date.now()) {+export function receiptFor(stored: WriteRequest, facts?: WriteHealthFacts, now = Date.now()) {+ // PR B: a deferred row reads as queued (every receipt reader, an older client's included, knows that state) plus `deferred`.+ const state: Exclude<RequestState, 'deferred'> = stored.state === 'deferred' ? 'queued' : stored.state;+ const row = { ...stored, state };return {...(row.outcome ?? {}),...(row.outcome ? { outcome: row.outcome } : {}),- request_id: row.request_id, ...(row.client_request_id ? { client_request_id: row.client_request_id } : {}), state: row.state,+ request_id: row.request_id, ...(row.client_request_id ? { client_request_id: row.client_request_id } : {}), state,+ ...(stored.state === 'deferred' && stored.deferred_refresh_id ? { deferred: { refresh_id: stored.deferred_refresh_id } } : {}),...writeHealth(row, facts, now),...(row.error_code ? { write_error: row.error_code } : {}),...(row.error_detail ? { write_error_detail: publicFailureDetail(row.error_detail) } : {}),diff --git a/src/core/persistence/model.ts b/src/core/persistence/model.tsindex 6b26a8bbd7..29b8f31325 100644--- a/src/core/persistence/model.ts+++ b/src/core/persistence/model.ts@@ -2,7 +2,8 @@ import type { BrainEngine } from '../engine.ts';import { assertRecoveryVersion } from './recovery-version.ts';export type Principal = { kind: 'oauth_client' | 'legacy_token' | 'local_cli' | 'local_stdio' | 'application'; id: string };-export type RequestState = 'queued' | 'running' | 'recovering' | 'committed' | 'conflict' | 'failed' | 'cancelled';+/** `deferred` (PR B, docs/designs/REFRESH_WRITE_BARRIER.md): admitted during a worktree refresh, unclaimable until it is released. */+export type RequestState = 'queued' | 'deferred' | 'running' | 'recovering' | 'committed' | 'conflict' | 'failed' | 'cancelled';export interface WriteAuthority {version: 1;principal: Principal;@@ -121,6 +122,8 @@ export interface WriteRequest {authority: WriteAuthority;sequence: string | number;state: RequestState;+ /** The refresh a deferred write was admitted behind; kept after it drains, so its claim runs the refresh-change check. */+ deferred_refresh_id?: string | null;execution_token: string | null;claim_expires_at: Date | string | null;recovery: RecoveryRecord | null;diff --git a/src/core/persistence/refresh-barrier.ts b/src/core/persistence/refresh-barrier.tsnew file mode 100644index 0000000000..e07f4faa1c--- /dev/null+++ b/src/core/persistence/refresh-barrier.ts@@ -0,0 +1,72 @@+/**+ * Convergence PR B (docs/designs/REFRESH_WRITE_BARRIER.md): the replay side of the refresh write barrier.+ *+ * A page write admitted while `gbrain sources refresh` held its worktree waits in state `deferred` (journal.ts) until the+ * refresh is released (completed or aborted). When it is claimed, before anything is published, two checks run here:+ * the write's durable authority against current grants (it may have waited minutes), and whether the refresh changed+ * any file the publication writes. A refresh that changed one ends the write `revision_conflict` (nothing applied), so+ * a page the refresh changed is never overwritten. The check reads git, not the page revision: a refresh completes even+ * when a member's sync is blocked, so git can hold the refreshed bytes before the database does.+ */+import { relative, sep } from 'node:path';+import { execFileBounded } from '../bounded-child-exec.ts';+import { gitChildEnv } from '../git-env.ts';+import { OperationError } from '../ops/contract.ts';+import { authorizeWrite } from './authority.ts';+import type { SqlEngine, WriteRequest } from './model.ts';++const GIT_ENV = { GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'Never', LC_ALL: 'C', GIT_OPTIONAL_LOCKS: '0' };+const DIFF_TIMEOUT_MS = 30_000;+const CACHED_REFRESHES = 32;+/** The paths each refresh changed, per checkout root: one diff serves the whole drain behind it. */+const changed = new Map<string, Promise<ReadonlySet<string> | null>>();++/** Paths (repository-relative, forward slashes) refresh `refreshId` changed; empty for an aborted refresh; null when unreadable. */+async function refreshChangedPaths(engine: SqlEngine, refreshId: string, root: string): Promise<ReadonlySet<string> | null> {+ const key = `${refreshId}\0${root}`;+ const held = changed.get(key);+ if (held) return held;+ const read = (async () => {+ const [refresh] = await engine.executeRaw<{ state: string; old_head: string; target_head: string; released: boolean }>(+ 'SELECT state,old_head,target_head,released_at IS NOT NULL AS released FROM persistence_worktree_refreshes WHERE id=$1::uuid', [refreshId]);+ if (!refresh?.released) return null;+ if (refresh.state === 'aborted' || refresh.old_head === refresh.target_head) return new Set<string>();+ const { error, stdout } = await execFileBounded('git', ['-C', root, '-c', 'core.quotepath=false', 'diff', '--name-only', '-z', '--no-renames',+ refresh.old_head, refresh.target_head], { timeout: DIFF_TIMEOUT_MS, maxBuffer: 64 * 1024 ** 2, env: gitChildEnv(GIT_ENV) });+ return error ? null : new Set(stdout.split('\0').filter(Boolean));+ })();+ changed.set(key, read);+ read.then(paths => { if (paths === null && changed.get(key) === read) changed.delete(key); }, () => { if (changed.get(key) === read) changed.delete(key); });+ while (changed.size > CACHED_REFRESHES) changed.delete(changed.keys().next().value!);+ return read;+}++export interface DeferredRefusal { state: 'conflict' | 'failed'; failure: { code: string; message: string } }++/**+ * Null when a claimed deferred write may publish `files` (its own page file and its companions'); otherwise the terminal+ * refusal to record. A row that was never deferred is not checked.+ */+export async function deferredReplayRefusal(engine: SqlEngine, row: WriteRequest, files: ReadonlyArray<{ path: string; root: string }>): Promise<DeferredRefusal | null> {+ const refreshId = row.deferred_refresh_id;+ if (!refreshId) return null;+ try { await authorizeWrite(engine, row.authority, row.operation, row.slug); } catch (error) {+ if (!(error instanceof OperationError)) throw error;+ return { state: 'failed', failure: { code: error.code, message: `Request ${row.request_id} waited behind refresh ${refreshId}, and its credential no longer grants this write: ${error.message}` } };+ }+ let unreadable = false;+ const touched: string[] = [];+ for (const file of files) {+ const paths = await refreshChangedPaths(engine, refreshId, file.root);+ const target = relative(file.root, file.path).split(sep).join('/');+ if (paths === null) unreadable = true;+ if (paths === null || paths.has(target)) touched.push(target);+ }+ if (!touched.length) return null;+ return { state: 'conflict', failure: { code: 'revision_conflict', message: unreadable+ ? `Request ${row.request_id} waited behind refresh ${refreshId}, and what that refresh changed could not be read, so nothing was applied. Read the page again and submit the change with a new request_id.`+ : `Refresh ${refreshId} changed ${touched.join(', ')} after request ${row.request_id} was accepted, so nothing was applied and no newer content was overwritten. Read the page again and submit the change with a new request_id.` } };+}++/** Test seam: forget every cached refresh diff. */+export function _resetRefreshBarrierCacheForTests(): void { changed.clear(); }diff --git a/src/core/persistence/switches.ts b/src/core/persistence/switches.tsindex 7a12a0bc36..a6ef668412 100644--- a/src/core/persistence/switches.ts+++ b/src/core/persistence/switches.ts@@ -28,6 +28,11 @@ export const WRITE_SWITCHES = {* (consumer-election.ts) instead of starting their own. Off by default until Phase 0's preregistered reading sets it.*/single_consumer: { key: 'persistence.single_consumer', env: 'GBRAIN_SINGLE_CONSUMER', defaultOn: false },+ /**+ * Convergence PR B: a page write that meets a worktree refresh is admitted `deferred` and publishes after the refresh, instead+ * of being refused `worktree_refreshing`. Off by default; turned on per brain once every routed producer polls its receipts.+ */+ refresh_barrier: { key: 'persistence.refresh_barrier', env: 'GBRAIN_REFRESH_BARRIER', defaultOn: false },} as const;export type WriteSwitch = keyof typeof WRITE_SWITCHES;export type WriteSwitches = Record<WriteSwitch, boolean>;diff --git a/src/core/persistence/types.ts b/src/core/persistence/types.tsindex 146f28b8d1..0bdc0d8ad5 100644--- a/src/core/persistence/types.ts+++ b/src/core/persistence/types.ts@@ -60,6 +60,8 @@ export interface WriteReceipt {created_at?: string;updated_at?: string;diagnostic?: WriteDiagnostic;+ /** PR B: the write waits behind this worktree refresh and publishes after it (docs/guides/write-refusals.md#deferred-writes). */+ deferred?: { refresh_id: string };/** #7248: a remember's target page and the entity slug its fact is keyed under (set on its own replies, never read back from the journal). */target?: { slug: string | null; entity_slug: string | null };}@@ -81,7 +83,7 @@ export function isWriteErrorCode(value: unknown): value is WriteErrorCode {return typeof value === 'string' && (WRITE_ERROR_CODES as readonly string[]).includes(value);}-export function isTerminalWriteState(state: WriteRequestState): boolean {+export function isTerminalWriteState(state: WriteRequestState | 'deferred'): boolean {return state === 'committed' || state === 'conflict' || state === 'failed' || state === 'cancelled';}diff --git a/src/core/persistence/worktree-refresh-schema.ts b/src/core/persistence/worktree-refresh-schema.tsindex 0595a98992..0196ccb6f9 100644--- a/src/core/persistence/worktree-refresh-schema.ts+++ b/src/core/persistence/worktree-refresh-schema.ts@@ -44,6 +44,13 @@ export const ACTIVE_REFRESH_STATES_SQL = "('draining','fenced','merged','syncing*/export const CHECKOUT_EFFECT_KINDS_SQL = "('git','withdrawal-mirror')";+/**+ * PR B (docs/designs/REFRESH_WRITE_BARRIER.md): a `deferred` request whose refresh is released is waiting work like a queued+ * row; one whose refresh is still running is invisible to every claim, head and drain check (it waits for the refresh).+ */+export const RELEASED_DEFERRED = (r: string) => `(${r}.state='deferred' AND EXISTS (SELECT 1 FROM persistence_worktree_refreshes released+ WHERE released.id=${r}.deferred_refresh_id AND released.released_at IS NOT NULL))`;+/*** Claim predicate for a row aliased `alias` whose `column` (default `worktree_id`) names the worktree: while* a refresh holds the checkout fence (`fenced`, `merged`) or its HEAD isdiff --git a/src/core/persistence/worktree-refresh.ts b/src/core/persistence/worktree-refresh.tsindex 8330cd580e..2298ad8ed4 100644--- a/src/core/persistence/worktree-refresh.ts+++ b/src/core/persistence/worktree-refresh.ts@@ -40,7 +40,7 @@ import { getWorktreeBinding, managedPersistenceEnabled, type WorktreeBinding } fimport { isPhysicalRootMetadata } from './physical-root-record.ts';import { startPersistenceConsumer } from './service.ts';import { lockTopologyPrincipal, lockTopologyRows, topologyPrincipal, withTopologyLocks } from './topology-locks.ts';-import { ACTIVE_REFRESH_STATES_SQL, CHECKOUT_EFFECT_KINDS_SQL, type WorktreeRefreshState } from './worktree-refresh-schema.ts';+import { ACTIVE_REFRESH_STATES_SQL, CHECKOUT_EFFECT_KINDS_SQL, RELEASED_DEFERRED, type WorktreeRefreshState } from './worktree-refresh-schema.ts';import { gitChildEnv } from '../git-env.ts';import type { QuarantineEntry } from '../git/commit-push.ts';import { isTruthy } from '../connectors/config-keys.ts';@@ -506,7 +506,7 @@ async function assertNoUnfinishedSync(engine: BrainEngine, members: string[]): Pasync function drainCounts(engine: BrainEngine, worktreeId: string): Promise<{ requests: number; effects: number; recovery: number }> {const [row] = await engine.executeRaw<{ requests: number; effects: number; recovery: number }>(`SELECT- (SELECT count(*) FROM persistence_requests WHERE worktree_id=$1::uuid AND state IN ('queued','running','recovering'))::int AS requests,+ (SELECT count(*) FROM persistence_requests r WHERE r.worktree_id=$1::uuid AND (r.state IN ('queued','running','recovering') OR ${RELEASED_DEFERRED('r')}))::int AS requests,(SELECT count(*) FROM persistence_effects WHERE worktree_id=$1::uuid AND kind IN ${CHECKOUT_EFFECT_KINDS_SQL} AND state IN ('queued','running'))::int AS effects,((SELECT count(*) FROM persistence_requests WHERE worktree_id=$1::uuid AND recovery IS NOT NULL)+(SELECT count(*) FROM persistence_effects WHERE worktree_id=$1::uuid AND recovery IS NOT NULL))::int AS recovery`, [worktreeId]);@@ -786,8 +786,8 @@ async function fenceDraining(engine: BrainEngine, sourceId: string, plan: Plan,throw refusal('refresh_source_changed', 'The worktree ownership or source membership changed after the refresh precheck; nothing moved.', `Retry gbrain sources refresh ${sourceId}`);}const [row] = await tx.executeRaw<WorktreeRefreshRow>(`INSERT INTO persistence_worktree_refreshes- (worktree_id,source_ids,principal_id,owner_epoch,topology_generation,state,old_head,target_head,upstream_ref,preserved_uncommitted,outcome)- VALUES($1::uuid,$2::text[],$3::uuid,$4,$5,'draining',$6,$7,$8,$9::text[],$10::text::jsonb) RETURNING *`,+ (worktree_id,source_ids,principal_id,owner_epoch,topology_generation,state,old_head,target_head,upstream_ref,preserved_uncommitted,outcome,barrier_sequence)+ VALUES($1::uuid,$2::text[],$3::uuid,$4,$5,'draining',$6,$7,$8,$9::text[],$10::text::jsonb,(SELECT max(sequence) FROM persistence_requests)) RETURNING *`,[plan.binding.worktree_id, plan.members, principal, String(current.owner_epoch), String(current.topology_generation),plan.oldHead, plan.targetHead, plan.upstreamRef, plan.preserved, JSON.stringify({ holder: refreshHolder(engine) })]);return row;diff --git a/src/core/schema-migrations/latest.generated.ts b/src/core/schema-migrations/latest.generated.tsindex df044247f9..c794939689 100644--- a/src/core/schema-migrations/latest.generated.ts+++ b/src/core/schema-migrations/latest.generated.ts@@ -4,4 +4,4 @@// The highest schema migration version (migrate.ts LATEST_VERSION), importable without// loading the migrations themselves.-export const LATEST_SCHEMA_VERSION = 289;+export const LATEST_SCHEMA_VERSION = 290;diff --git a/src/core/schema-migrations/registry.generated.ts b/src/core/schema-migrations/registry.generated.tsindex 2e6879d2ad..f467ec5438 100644--- a/src/core/schema-migrations/registry.generated.ts+++ b/src/core/schema-migrations/registry.generated.ts@@ -290,6 +290,7 @@ import { v286 } from './v286-qm-actor-links.ts';import { v287 } from './v287-multi-page-recovery-record.ts';import { v288 } from './v288-decide-proposals-claim-pair-index.ts';import { v289 } from './v289-page-change-reasons.ts';+import { v290 } from './v290-refresh-write-barrier.ts';// Array order is historical (see HISTORICAL_ARRAY_ORDER in the generator); the// runner sorts by version before applying.@@ -578,4 +579,5 @@ export const MIGRATIONS: Migration[] = [v287,v288,v289,+ v290,];diff --git a/src/core/schema-migrations/v290-refresh-write-barrier.ts b/src/core/schema-migrations/v290-refresh-write-barrier.tsnew file mode 100644index 0000000000..9d8f2c3b05--- /dev/null+++ b/src/core/schema-migrations/v290-refresh-write-barrier.ts@@ -0,0 +1,104 @@+import type { Migration } from './types.ts';++// Applied by src/core/migrate.ts on the next initSchema(); see docs/ENGINES.md+// ("Canonical schema sources") for when schema.sql or a TS fragment also changes.+//+// Convergence PR B (docs/designs/REFRESH_WRITE_BARRIER.md): the refresh write barrier.+// - persistence_requests.state gains 'deferred': a page write admitted while a+// `gbrain sources refresh` holds its worktree waits there, invisible to every+// claim, drain and head selector (old binaries included), until its refresh+// is released; deferred_refresh_id names that refresh.+// - persistence_worktree_refreshes.released_at is set by trigger when the refresh+// reaches completed or aborted, whoever moves it (a mixed-version window+// included); barrier_sequence is diagnostic.+// - gbrain_request_deferred: a deferred row leaves the state only to running (a+// barrier-aware claim of a released refresh), failed or cancelled.+// - persistence_consumers.capabilities: what a live consumer can drain; admission+// defers only when every live consumer of the owner host can.+// Postgres swaps the state CHECK with ADD ... NOT VALID then VALIDATE (no long+// ACCESS EXCLUSIVE scan), outside a transaction like v114; PGLite does it in one+// shot. The number is a placeholder restamped at the merge slot.+export const v290: Migration = {+ version: 290,+ name: 'refresh_write_barrier',+ idempotent: true,+ transaction: false,+ sql: '',+ sqlFor: {+ postgres: `+ ALTER TABLE persistence_worktree_refreshes ADD COLUMN IF NOT EXISTS barrier_sequence bigint;+ ALTER TABLE persistence_worktree_refreshes ADD COLUMN IF NOT EXISTS released_at timestamptz;+ UPDATE persistence_worktree_refreshes SET released_at=COALESCE(completed_at,updated_at) WHERE state IN ('completed','aborted') AND released_at IS NULL;+ ALTER TABLE persistence_requests ADD COLUMN IF NOT EXISTS deferred_refresh_id uuid REFERENCES persistence_worktree_refreshes(id);+ ALTER TABLE persistence_consumers ADD COLUMN IF NOT EXISTS capabilities text[] NOT NULL DEFAULT '{}';+ CREATE INDEX IF NOT EXISTS persistence_requests_deferred ON persistence_requests(deferred_refresh_id, sequence) WHERE state='deferred';+ CREATE OR REPLACE FUNCTION gbrain_release_refresh_barrier() RETURNS trigger LANGUAGE plpgsql SET search_path = pg_catalog, public AS $$+ BEGIN+ NEW.released_at := COALESCE(NEW.released_at, now());+ RETURN NEW;+ END $$;+ DROP TRIGGER IF EXISTS gbrain_refresh_release ON persistence_worktree_refreshes;+ CREATE TRIGGER gbrain_refresh_release BEFORE UPDATE OF state ON persistence_worktree_refreshes FOR EACH ROW+ WHEN (NEW.state IN ('completed','aborted') AND OLD.state NOT IN ('completed','aborted'))+ EXECUTE FUNCTION gbrain_release_refresh_barrier();+ CREATE OR REPLACE FUNCTION gbrain_guard_deferred_request() RETURNS trigger LANGUAGE plpgsql SET search_path = pg_catalog, public AS $$+ BEGIN+ IF NEW.state='deferred' THEN+ IF OLD.state<>'deferred' THEN RAISE EXCEPTION 'unsupported_mutation_protocol: only admission defers a request' USING ERRCODE='42501'; END IF;+ RETURN NEW;+ END IF;+ IF NEW.state IN ('failed','cancelled') THEN RETURN NEW; END IF;+ IF NEW.state='running' AND COALESCE(current_setting('gbrain.refresh_barrier',true),'')='1'+ AND EXISTS (SELECT 1 FROM persistence_worktree_refreshes f WHERE f.id=OLD.deferred_refresh_id AND f.released_at IS NOT NULL) THEN+ RETURN NEW;+ END IF;+ RAISE EXCEPTION 'writer_upgrade_required: a deferred request is claimed only by a refresh-barrier consumer after its refresh is released' USING ERRCODE='42501';+ END $$;+ DROP TRIGGER IF EXISTS gbrain_request_deferred ON persistence_requests;+ CREATE TRIGGER gbrain_request_deferred BEFORE UPDATE OF state ON persistence_requests FOR EACH ROW+ WHEN (OLD.state='deferred' OR NEW.state='deferred')+ EXECUTE FUNCTION gbrain_guard_deferred_request();+ ALTER TABLE persistence_requests DROP CONSTRAINT IF EXISTS persistence_requests_state_check;+ ALTER TABLE persistence_requests ADD CONSTRAINT persistence_requests_state_check+ CHECK (state IN ('queued','deferred','running','recovering','committed','conflict','failed','cancelled')) NOT VALID;+ ALTER TABLE persistence_requests VALIDATE CONSTRAINT persistence_requests_state_check;+ `,+ pglite: `+ ALTER TABLE persistence_worktree_refreshes ADD COLUMN IF NOT EXISTS barrier_sequence bigint;+ ALTER TABLE persistence_worktree_refreshes ADD COLUMN IF NOT EXISTS released_at timestamptz;+ UPDATE persistence_worktree_refreshes SET released_at=COALESCE(completed_at,updated_at) WHERE state IN ('completed','aborted') AND released_at IS NULL;+ ALTER TABLE persistence_requests ADD COLUMN IF NOT EXISTS deferred_refresh_id uuid REFERENCES persistence_worktree_refreshes(id);+ ALTER TABLE persistence_consumers ADD COLUMN IF NOT EXISTS capabilities text[] NOT NULL DEFAULT '{}';+ CREATE INDEX IF NOT EXISTS persistence_requests_deferred ON persistence_requests(deferred_refresh_id, sequence) WHERE state='deferred';+ CREATE OR REPLACE FUNCTION gbrain_release_refresh_barrier() RETURNS trigger LANGUAGE plpgsql SET search_path = pg_catalog, public AS $$+ BEGIN+ NEW.released_at := COALESCE(NEW.released_at, now());+ RETURN NEW;+ END $$;+ DROP TRIGGER IF EXISTS gbrain_refresh_release ON persistence_worktree_refreshes;+ CREATE TRIGGER gbrain_refresh_release BEFORE UPDATE OF state ON persistence_worktree_refreshes FOR EACH ROW+ WHEN (NEW.state IN ('completed','aborted') AND OLD.state NOT IN ('completed','aborted'))+ EXECUTE FUNCTION gbrain_release_refresh_barrier();+ CREATE OR REPLACE FUNCTION gbrain_guard_deferred_request() RETURNS trigger LANGUAGE plpgsql SET search_path = pg_catalog, public AS $$+ BEGIN+ IF NEW.state='deferred' THEN+ IF OLD.state<>'deferred' THEN RAISE EXCEPTION 'unsupported_mutation_protocol: only admission defers a request' USING ERRCODE='42501'; END IF;+ RETURN NEW;+ END IF;+ IF NEW.state IN ('failed','cancelled') THEN RETURN NEW; END IF;+ IF NEW.state='running' AND COALESCE(current_setting('gbrain.refresh_barrier',true),'')='1'+ AND EXISTS (SELECT 1 FROM persistence_worktree_refreshes f WHERE f.id=OLD.deferred_refresh_id AND f.released_at IS NOT NULL) THEN+ RETURN NEW;+ END IF;+ RAISE EXCEPTION 'writer_upgrade_required: a deferred request is claimed only by a refresh-barrier consumer after its refresh is released' USING ERRCODE='42501';+ END $$;+ DROP TRIGGER IF EXISTS gbrain_request_deferred ON persistence_requests;+ CREATE TRIGGER gbrain_request_deferred BEFORE UPDATE OF state ON persistence_requests FOR EACH ROW+ WHEN (OLD.state='deferred' OR NEW.state='deferred')+ EXECUTE FUNCTION gbrain_guard_deferred_request();+ ALTER TABLE persistence_requests DROP CONSTRAINT IF EXISTS persistence_requests_state_check;+ ALTER TABLE persistence_requests ADD CONSTRAINT persistence_requests_state_check+ CHECK (state IN ('queued','deferred','running','recovering','committed','conflict','failed','cancelled'));+ `,+ },+};