Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { randomUUID } from 'node:crypto';
import { relative, sep } from 'node:path';
import type { BrainEngine } from '../engine.ts';
import { ENGINE_ROOT } from '../engine-root.ts';
import type { PageSnapshot } from '../page-state/types.ts';
import { opError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import type { PreparedMutation } from './coordinator.ts';
import { fileContentHash } from './large-file.ts';
import { PARK_AFTER_FAILURES, REMOTE_AUTO_LINKS_KEY, REMOTE_MENTION_OPERATIONS, WITHHELD_BY_MIRROR, type EffectKind, type PersistenceEffect, type EffectRequest } from './effect-model.ts';
import type { SqlEngine, WriteRequest } from './model.ts';
import { recordChronicleDecision } from '../chronicle/ledger.ts';
import { isFactsExtractionEnabled } from '../facts/extract.ts';
import { loadConfig } from '../config.ts';
import { resolveDefaultVisibility } from '../facts/visibility.ts';
import { declarePersistenceProtocol, isPersistenceDeclaration, PERSISTENCE_PROTOCOL_PREDICATE } from './protocol.ts';
import { claimOwner, EXPIRED_PREPARING_CHARGE_SQL } from './claim-phase.ts';
import { refreshFenceClear } from './worktree-refresh-schema.ts';
import { pageBatchChildRequestIds } from './page-batch-id.ts';
import { EFFECT_FAULT_POINTS, faultPoint } from './fault-points.ts';
import { asciiLowerSql, edgeTrimSql } from '../edge-whitespace.ts';
/**
* `snapshot` is the publication's final read of the page, including deleted rows, in this transaction.
* A remote put_page/capture/edit_page also queues a `links` effect (an append_page to the compiled truth, one scoped
* to its appended bytes), in one statement that inserts nothing while `auto_link` or `mcp.remote_auto_links` is off (unset is on).
*/
export async function queuePublicationEffects(tx: BrainEngine, row: EffectRequest & Partial<Pick<WriteRequest, 'operation' | 'intent' | 'authority' | 'principal_kind' | 'principal_id'>>, snapshot: PageSnapshot | null,
outcome: Record<string, unknown>, prepared?: PreparedMutation,
/** A grouped publication completes its members after queueing all of them, then calls `reconcileFinishedBatch` itself. */
opts: { deferBatchReconcile?: boolean; /** G2 (git-door.ts): the file is already committed; its Git effect only pushes. */ pushOnly?: boolean;
/** GBRA-190 G4 (D2): every page a multi-page publication wrote, sorted by slug; its Git and embedding effects walk them (effect-targets.ts). */
pageTargets?: readonly { slug: string; page_id: number; revision: string }[] } = {}): Promise<void> {
if (prepared?.noop || prepared?.target === 'skill_bundle') return;
await declarePersistenceProtocol(tx);
const revision = snapshot?.revision;
const data = { slug: row.slug, page_id: snapshot?.page.id };
// #6007: the effects are inserted together, in queue order, by one statement at the end.
const queued: { kind: EffectKind; data: Record<string, unknown>; gated?: boolean }[] = [];
const queue = (kind: EffectKind, extra: Record<string, unknown> = {}) => { queued.push({ kind, data: { ...data, ...extra } }); };
const companionFiles = (prepared?.companions ?? []).some(companion => companion.file);
if (opts.pageTargets && (prepared?.file || companionFiles) && row.worktree_id) {
queue('git', { version: 2, targets: opts.pageTargets, ...(opts.pushOnly ? { push_only: true } : {}) });
if (!opts.pushOnly && outcome.persistence && typeof outcome.persistence === 'object') Object.assign(outcome.persistence, { git_state: 'queued' });
} else if (prepared?.file && row.worktree_id) {
const [binding] = await tx.executeRaw<{ local_path: string }>(`SELECT h.local_path FROM persistence_host_bindings h
JOIN persistence_worktrees w ON w.id=h.worktree_id AND w.owner_host_id=h.host_id WHERE w.id=$1::uuid`, [row.worktree_id]);
if (!binding?.local_path) throw opError('owner_unavailable', 'Cannot record the canonical Git target without its owner binding.',
`Worktree ${row.worktree_id} of source ${row.source_id} has no host binding for its owner, so request ${row.id} could not record its Git target. Read the request's receipt; the owner host's binding is restored by its claim or transfer.`,
row.principal_kind === 'local_cli' ? { fix: readFix(`Reads request ${row.id}'s durable receipt, read-only.`, { argv: ['gbrain', 'write-request', '--', row.id] }) } : {});
const commit = prepared.file.commit;
queue('git', { relative_path: relative(binding.local_path, prepared.file.path).split(sep).join('/'),
expected_hash: prepared.file.content === null ? null : fileContentHash(prepared.file.content),
...(opts.pushOnly ? { push_only: true } : commit ? { commit_subject: commit.subject, commit_line: commit.line, ...(commit.trailers?.length ? { commit_trailers: commit.trailers } : {}) } : {}) });
if (!opts.pushOnly && outcome.persistence && typeof outcome.persistence === 'object') Object.assign(outcome.persistence, { git_state: 'queued' });
}
if (snapshot && !snapshot.page.deleted_at) {
if (!prepared?.deferEmbedding && !prepared?.embeddingCurrent) queue('embedding', opts.pageTargets ? { version: 2, targets: opts.pageTargets } : {});
outcome.embedding_state = await embeddingDisabled(tx) ? 'disabled' : prepared?.deferEmbedding ? 'deferred' : prepared?.embeddingCurrent ? 'current' : 'queued';
if ((outcome.facts_backstop as { queued?: boolean } | undefined)?.queued) {
if (!(await isFactsExtractionEnabled(tx))) outcome.facts_backstop = { skipped: 'extraction_disabled' };
else queue('facts-backstop', { visibility: await resolveDefaultVisibility(tx) });
}
// The links effect is inserted with the others, gated in SQL on auto_link and mcp.remote_auto_links.
if (queuesMentionLinks(row, prepared)) queued.push({ kind: 'links', data: { ...data, ...(prepared?.mentionRange ? { range: prepared.mentionRange } : {}) }, gated: true });
// #5876: the Life Chronicle decision is a ledger row, not an effect; the `chronicle` cycle phase executes it.
await recordChronicleDecision(tx, row, snapshot, outcome);
} else if (opts.pageTargets?.length && !prepared?.deferEmbedding) queue('embedding', { version: 2, targets: opts.pageTargets });
const inserted = queued.length ? await tx.executeRaw<{ kind: string }>(`INSERT INTO persistence_effects (request_id,kind,revision,data,source_id,source_incarnation,worktree_id)
SELECT $1::uuid,t.e->>'kind',$2::uuid,t.e->'data',$3,$4::uuid,$5::uuid FROM jsonb_array_elements($6::text::jsonb) WITH ORDINALITY AS t(e,n)
WHERE NOT (COALESCE((t.e->>'gated')::boolean,false) AND EXISTS (SELECT 1 FROM config
WHERE key IN ('auto_link',$7) AND ${asciiLowerSql(edgeTrimSql('value'))} IN ('false','0','no','off')))
ORDER BY t.n ON CONFLICT(request_id,kind) DO NOTHING RETURNING kind`,
[row.id, revision ?? null, row.source_id, row.source_incarnation, row.worktree_id, JSON.stringify(queued), REMOTE_AUTO_LINKS_KEY]) : [];
if (queued.some(effect => effect.kind === 'links')) {
if (inserted.some(effect => effect.kind === 'links')) outcome.auto_links = { ...(outcome.auto_links as Record<string, unknown> | undefined), mention_links: 'queued' };
if (!opts.deferBatchReconcile) await reconcileFinishedBatch(tx, row);
}
}
/**
* Whether a publication of this request queues a mention `links` effect: a remote page write without trusted
* auto-linking. #7122: an append_page queues one only when it appended to the compiled truth (`mentionRange`).
*/
export function queuesMentionLinks(row: Partial<Pick<WriteRequest, 'operation' | 'authority'>>, prepared?: Pick<PreparedMutation, 'mentionRange'>): boolean {
if (!row.authority || !row.operation || (row.authority.autoLinkTrusted ?? !row.authority.remote)) return false;
return REMOTE_MENTION_OPERATIONS.includes(row.operation) || (row.operation === 'append_page' && !!prepared?.mentionRange);
}
/**
* #6007: when the last unfinished page of a `put_pages` batch publishes, its
* earlier pages' links effects may have run before this page existed; re-arm
* them once so forward references inside the batch resolve, with no client poll.
*/
export async function reconcileFinishedBatch(tx: BrainEngine, row: EffectRequest & Partial<Pick<WriteRequest, 'intent' | 'principal_kind' | 'principal_id'>>): Promise<void> {
const batch = row.intent?.page_batch as { id?: unknown; size?: unknown } | undefined;
if (!batch || typeof batch.id !== 'string' || typeof batch.size !== 'number' || batch.size < 2 || !row.principal_kind || !row.principal_id) return;
const siblings = await tx.executeRaw<{ id: string; state: string }>(`SELECT id,state FROM persistence_requests
WHERE principal_kind=$1 AND principal_id=$2 AND request_id=ANY($3::uuid[]) AND id<>$4::uuid AND intent->'page_batch'->>'id'=$5`,
[row.principal_kind, row.principal_id, pageBatchChildRequestIds(batch.id, batch.size), row.id, batch.id]);
if (siblings.some(sibling => !['committed', 'conflict', 'failed', 'cancelled'].includes(sibling.state))) return;
await queueLinksReconcile(tx, { sourceId: row.source_id, requestIds: [row.id, ...siblings.filter(sibling => sibling.state === 'committed').map(sibling => sibling.id)] });
}
/**
* Re-arm the `links` effects of requests published together (a batch), so each
* page's mention links resolve against every page the batch created. Call it
* in the transaction that commits the batch's last page, or after it. An effect
* whose page changed since finishes as superseded; a claimed effect loses its
* claim and runs again. `slugs` narrows the re-armed effects to those pages.
* Each effect is re-armed at most once (`data.batch_reconciled`), so repeated
* status reads of a finished batch do not redo the work. Returns how many were re-armed.
*/
export async function queueLinksReconcile(tx: SqlEngine, opts: { sourceId: string; requestIds: readonly string[]; slugs?: readonly string[] }): Promise<number> {
if (!opts.requestIds.length) return 0;
const rows = await tx.executeRaw(`UPDATE persistence_effects SET state='queued',execution_token=NULL,claim_expires_at=NULL,claim_owner=NULL,
next_attempt_at=now(),error_code=NULL,outcome=NULL,updated_at=now(),data=data||'{"batch_reconciled":true}'::jsonb
WHERE kind='links' AND source_id=$1 AND request_id=ANY($2::uuid[]) AND ($3::text[] IS NULL OR data->>'slug'=ANY($3::text[]))
AND NOT (data ? 'batch_reconciled') AND recovery IS NULL AND ${PERSISTENCE_PROTOCOL_PREDICATE} RETURNING id`, [opts.sourceId, [...opts.requestIds], opts.slugs ? [...opts.slugs] : null]);
return rows.length;
}
/**
* A keyless brain (`init --no-embedding`: `embedding_disabled` on the file or
* DB plane, the same pair the embedding effect refuses on) reports
* `embedding_state: "disabled"` (agent-first operator wave E5): its
* embedding effect settles as skipped, so "queued" would promise vectors that
* never arrive.
*/
async function embeddingDisabled(tx: BrainEngine): Promise<boolean> {
if (loadConfig()?.embedding_disabled === true) return true;
return (await tx.getConfig('embedding_disabled')) === 'true';
}
/** GBRA-133: the `pid:nonce:start` key of the owner an effect's `claim_owner` stamp names (the request side's key, consumer.ts). */
export const EFFECT_OWNER_KEY_SQL = (e: string) =>
`concat_ws(':',${e}.claim_owner->'owner'->>'pid',${e}.claim_owner->'owner'->>'nonce',${e}.claim_owner->'owner'->>'start')`;
/**
* GBRA-133: a running effect with no recovery record whose stamp of its current token names an owner in `param`, the
* owners the consumer proved dead (`claimOwnerProvablyDead`). It is claimable now, not when its 2-minute lease runs out:
* the takeover mints a new token, so the dead owner's outcome writes (each a compare-and-set on the token) cannot land, and
* the Git and mirror kinds still take the worktree's native lock first. An effect holding a recovery record keeps its own
* path (`selectEffectRecoveries` under the native lock).
*/
const DEAD_OWNER_EFFECT_SQL = (e: string, param: string) => `${e}.state='running' AND ${e}.recovery IS NULL
AND ${e}.claim_owner->>'token'=${e}.execution_token::text AND ${EFFECT_OWNER_KEY_SQL(e)}=ANY(${param}::text[])`;
/** The `claim_owner` stamp of the claim minting `token`: this process (`claimOwner`). */
export const effectClaimStamp = (token: string) => JSON.stringify({ token, owner: claimOwner() });
/**
* Claims release their database connection before waiting for a filesystem lock/provider. Nothing on a refresh-fenced worktree is claimed.
* `deadOwners` (GBRA-133): owner keys the consumer proved dead, whose running effects are claimable before their lease lapses.
*/
export async function claimPersistenceEffect(engine: BrainEngine, hostId: string, deadOwners: readonly string[] = []): Promise<PersistenceEffect | null> {
return engine.transactionDirect(async tx => {
await declarePersistenceProtocol(tx);
const [candidate] = await tx.executeRaw<PersistenceEffect>(`SELECT e.* FROM persistence_effects e
LEFT JOIN persistence_worktrees w ON w.id=e.worktree_id
WHERE (e.state='queued' OR e.state='running' AND e.claim_expires_at<now() OR ${DEAD_OWNER_EFFECT_SQL('e', '$2')}) AND e.next_attempt_at<=now()
AND (e.worktree_id IS NULL OR w.owner_host_id=$1::uuid) AND (e.worktree_id IS NULL OR ${refreshFenceClear('e')})
AND e.recovery IS NULL AND NOT EXISTS (SELECT 1 FROM persistence_effects blocked
WHERE blocked.worktree_id=e.worktree_id AND blocked.recovery IS NOT NULL)
AND NOT EXISTS (SELECT 1 FROM persistence_requests blocked
WHERE blocked.worktree_id=e.worktree_id AND blocked.recovery IS NOT NULL)
AND (e.kind='withdrawal-mirror' OR NOT EXISTS (SELECT 1 FROM persistence_effects mirror
WHERE mirror.request_id=e.request_id AND mirror.kind='withdrawal-mirror' AND mirror.state IN ('queued','running')))
ORDER BY e.next_attempt_at,e.id LIMIT 1 FOR UPDATE OF e SKIP LOCKED`, [hostId, [...deadOwners]]);
if (!candidate) return null;
const token = randomUUID();
const [claimed] = await tx.executeRaw<PersistenceEffect>(`UPDATE persistence_effects SET state='running',execution_token=$2::uuid,claim_owner=$3::text::jsonb,
claim_expires_at=now()+interval '2 minutes',attempts=attempts+1,updated_at=now() WHERE id=$1 RETURNING *`, [candidate.id, token, effectClaimStamp(token)]);
return claimed;
}, { pipelineFirst: isPersistenceDeclaration });
}
/** #5530: an effect that commits exactly one recorded file (not a withdrawal walk or a source scan). */
export function singleFileGitEffect(effect: PersistenceEffect): boolean {
return effect.kind === 'git' && typeof effect.data.relative_path === 'string' && effect.data.version === undefined
&& !effect.data.source_scan && effect.data.targets === undefined;
}
/**
* GBRA-130 A-12: what a request's withdrawal mirror proves about its pages, read
* when a Git or embedding attempt executes. `pending`: the mirror is queued or
* running (a retry-effects requeue lands between the claim and the attempt), so
* the attempt waits. `published`: pages whose file the mirror rewrote (its
* recovery records each one, `data.published`); a cursor position is no proof,
* since the mirror also passes pages it skipped or found without a file.
* `passed`: pages the mirror moved past without parking or awaiting a retry; it
* never revisits them. `files`: the hash of the bytes the mirror wrote to each
* published page's file and the revision it rendered (`data.published_files`).
*/
export interface MirrorGate { state: 'pending' | 'failed' | 'committed'; published: Set<string>; passed: Set<string>; files: Map<string, { hash: string; revision: string }> }
/**
* Per request id, the gate of its withdrawal mirror: every mirror that has not
* committed, and a committed one that recorded its publications. A request
* without such a mirror is absent and its work is unrestricted.
*/
export async function mirrorGates(engine: SqlEngine, requestIds: readonly string[]): Promise<Map<string, MirrorGate>> {
if (!requestIds.length) return new Map();
const rows = await engine.executeRaw<{ request_id: string; state: PersistenceEffect['state']; data: PersistenceEffect['data'] }>(
`SELECT request_id::text AS request_id,state,data FROM persistence_effects WHERE kind='withdrawal-mirror' AND (state<>'committed' OR data ? 'published')
AND request_id=ANY($1::uuid[])`, [[...new Set(requestIds)]]);
return new Map(rows.map(({ request_id, state, data }) => {
const after = data.after_slug;
const unfinished = new Set([...(data.parked ?? []).flatMap(entry => entry.slug ? [entry.slug] : []), ...(data.retry_slugs ?? [])]);
const passed = (data.targets ?? []).filter(target => after !== undefined && target.slug <= after && !unfinished.has(target.slug)).map(target => target.slug);
return [request_id, { state: state === 'queued' || state === 'running' ? 'pending' : state, published: new Set(data.published ?? []), passed: new Set(passed),
files: new Map(Object.entries(data.published_files ?? {})) }];
}));
}
/**
* GBRA-130 A-12: once a request's withdrawal mirror has committed, the Git and
* embedding targets parked behind it (`withdrawal_mirror_failed`) get another
* attempt with no operator retry: a scan revisits them first
* (`data.retry_slugs`), a single-target effect runs again. Other parked targets
* stay parked, and a claimed effect is left to its claim. The mirror's commit
* calls this in its own transaction; each effect pass calls it again for the
* requests it touched, for a park that settled after a concurrent mirror commit.
*/
const REARMABLE = `e.request_id=ANY($1::uuid[])
AND e.kind IN ('git','embedding') AND e.state IN ('queued','failed') AND e.execution_token IS NULL AND e.recovery IS NULL AND NOT (e.data ? 'settled')
AND EXISTS (SELECT 1 FROM jsonb_array_elements(COALESCE(e.data->'parked','[]'::jsonb)) AS p(target) WHERE p.target->>'error_code'=$2)
AND EXISTS (SELECT 1 FROM persistence_effects m WHERE m.request_id=e.request_id AND m.kind='withdrawal-mirror' AND m.state='committed')`;
/** Whether any of these requests has a target rearmWithheldTargets would re-arm; a pass opens its re-arm transaction only then. */
export async function hasRearmableTargets(engine: SqlEngine, requestIds: readonly string[]): Promise<boolean> {
if (!requestIds.length) return false;
return (await engine.executeRaw(`SELECT 1 FROM persistence_effects e WHERE ${REARMABLE} LIMIT 1`, [[...new Set(requestIds)], WITHHELD_BY_MIRROR])).length > 0;
}
export async function rearmWithheldTargets(engine: SqlEngine, requestIds: readonly string[]): Promise<number> {
if (!requestIds.length) return 0;
const rows = await engine.executeRaw<PersistenceEffect>(`SELECT e.* FROM persistence_effects e WHERE ${REARMABLE}
ORDER BY e.id FOR UPDATE OF e SKIP LOCKED`, [[...new Set(requestIds)], WITHHELD_BY_MIRROR]);
for (const effect of rows) {
const { parked = [], ...data } = effect.data;
const kept = parked.filter(entry => entry.error_code !== WITHHELD_BY_MIRROR);
const scanning = data.targets !== undefined || data.source_scan === true;
const slugs = scanning ? parked.flatMap(entry => entry.error_code === WITHHELD_BY_MIRROR && entry.slug ? [entry.slug] : []) : [];
const retrying = [...new Set([...(data.retry_slugs ?? []), ...slugs])];
await engine.executeRaw(`UPDATE persistence_effects SET state='queued',data=$2::text::jsonb,error_code=NULL,claim_expires_at=NULL,claim_owner=NULL,
next_attempt_at=now(),updated_at=now() WHERE id=$1 AND execution_token IS NULL AND recovery IS NULL AND ${PERSISTENCE_PROTOCOL_PREDICATE}`,
[effect.id, JSON.stringify({ ...data, ...(kept.length ? { parked: kept } : {}), ...(retrying.length ? { retry_slugs: retrying } : {}),
...(effect.kind === 'embedding' ? { embedding_attempt_base: effect.attempts } : {}) })]);
}
return rows.length;
}
/**
* #5530: claim up to `limit` more ready single-file Git effects for one
* worktree, under the same readiness, recovery and withdrawal-mirror ordering
* rules as claimPersistenceEffect, so the runner commits them together.
*/
export async function claimCoalescedGitEffects(engine: BrainEngine, hostId: string, worktreeId: string, limit: number,
deadOwners: readonly string[] = []): Promise<PersistenceEffect[]> {
if (limit <= 0) return [];
const rows = await engine.transactionDirect(async tx => {
await declarePersistenceProtocol(tx);
// The worktree-wide conditions (owner, refresh fence, recovery blocks) are one
// InitPlan, so the claim walks persistence_effects_pending in order and stops at
// $3 rows instead of probing every ready effect of the worktree.
return tx.executeRaw<PersistenceEffect>(`WITH ready AS (SELECT e.id,gen_random_uuid() AS token FROM persistence_effects e
WHERE EXISTS (SELECT 1 FROM persistence_worktrees w WHERE w.id=$2::uuid AND w.owner_host_id=$1::uuid
AND ${refreshFenceClear('w', 'id')}
AND NOT EXISTS (SELECT 1 FROM persistence_effects blocked WHERE blocked.worktree_id=w.id AND blocked.recovery IS NOT NULL)
AND NOT EXISTS (SELECT 1 FROM persistence_requests blocked WHERE blocked.worktree_id=w.id AND blocked.recovery IS NOT NULL))
AND e.worktree_id=$2::uuid AND e.kind='git' AND e.data ? 'relative_path'
AND NOT (e.data ? 'targets') AND NOT (e.data ? 'source_scan') AND NOT (e.data ? 'version')
AND (e.state='queued' OR e.state='running' AND e.claim_expires_at<now() OR ${DEAD_OWNER_EFFECT_SQL('e', '$4')}) AND e.next_attempt_at<=now()
AND e.recovery IS NULL
AND NOT EXISTS (SELECT 1 FROM persistence_effects mirror
WHERE mirror.request_id=e.request_id AND mirror.kind='withdrawal-mirror' AND mirror.state IN ('queued','running'))
ORDER BY e.next_attempt_at,e.id LIMIT $3 FOR UPDATE OF e SKIP LOCKED)
UPDATE persistence_effects p SET state='running',execution_token=ready.token,
claim_owner=jsonb_build_object('token',ready.token::text,'owner',$5::text::jsonb),
claim_expires_at=now()+interval '2 minutes',attempts=attempts+1,updated_at=now()
FROM ready WHERE p.id=ready.id RETURNING p.*`, [hostId, worktreeId, limit, [...deadOwners], JSON.stringify(claimOwner())]);
}, { pipelineFirst: isPersistenceDeclaration });
return rows.sort((a, b) => Number(a.id) - Number(b.id));
}
/** When this process started; on PGLite no claim written earlier can belong to a live owner. */
export const PROCESS_STARTED_AT = new Date(performance.timeOrigin);
/**
* #9227: the instant before which every running claim on this brain is abandoned, or null when this process cannot
* prove it. Only a PGLite engine that holds its datastore lock proves it: no other process can have renewed a claim
* since this one started, so the owner of an older claim has exited. A process without the lock, and every Postgres
* brain, gets null and releases nothing here.
*/
export function abandonedClaimCutoff(engine: BrainEngine): Date | null {
if (engine.kind !== 'pglite') return null;
const root = (engine as { [ENGINE_ROOT]?: { holdsDatastoreLock?: () => boolean } })[ENGINE_ROOT];
return root?.holdsDatastoreLock?.() === true ? PROCESS_STARTED_AT : null;
}
/**
* PGLite only, and only while this engine holds the datastore lock (`abandonedClaimCutoff`): the datastore admits one
* process, and this one opened it at `processStartedAt`, so a claim last written before then was held by an owner
* that has exited (a crash or SIGKILL). Release those claims now instead of
* waiting out their leases (effects 2 minutes, requests 30 s); a withdrawal
* mirror left running would otherwise also hold back writes to its pages.
* Claims with a recovery record stay with the recovery path.
*/
/**
* `chargePreparing` (#6278, the `preparation_deadlines` switch): a request whose
* dead owner stamped the reclaimed claim `preparing` is charged one preparation
* attempt, the same rule as the Postgres expired-claim sweep (consumer.ts), so a
* kill loop reaches `persistence.max_preparation_attempts`.
*/
export async function releaseAbandonedClaims(engine: BrainEngine, processStartedAt: Date, chargePreparing = false): Promise<number> {
if (!abandonedClaimCutoff(engine)) return 0;
const effects = await engine.executeRaw(`UPDATE persistence_effects SET state='queued',execution_token=NULL,claim_expires_at=NULL,claim_owner=NULL,
next_attempt_at=LEAST(next_attempt_at,now()) WHERE state='running' AND recovery IS NULL AND updated_at<$1::timestamptz
AND ${PERSISTENCE_PROTOCOL_PREDICATE} RETURNING id`, [processStartedAt.toISOString()]);
const requests = await engine.executeRaw(`UPDATE persistence_requests r SET state='queued',execution_token=NULL,claim_expires_at=NULL,
preparation_attempts=preparation_attempts+CASE WHEN $2::boolean THEN ${EXPIRED_PREPARING_CHARGE_SQL('r')} ELSE 0 END
WHERE state='running' AND recovery IS NULL AND publication_started=false AND updated_at<$1::timestamptz
AND ${PERSISTENCE_PROTOCOL_PREDICATE} RETURNING id`, [processStartedAt.toISOString(), chargePreparing]);
return effects.length + requests.length;
}
/** @internal Claim renewals made between the pieces of a segmented page's file (effectClaimKeeper), by effect kind, for the bounded-work test. Counts, not time. */
export const effectClaimWork: Record<string, number> = {};
/**
* Called between the pieces of a long read or write under a withdrawal-mirror or Git claim (a segmented page's file
* rendered, staged or compared): renews the 2-minute claim once `intervalMs` has passed since the last renewal, also
* while the mirror holds its recovery record, and refuses with `write_claim_lost` once the claim moved.
*/
export function effectClaimKeeper(engine: BrainEngine, effect: PersistenceEffect, intervalMs: number): () => Promise<void> {
let last = performance.now();
return async () => {
if (performance.now() - last < intervalMs) return;
last = performance.now();
effectClaimWork[effect.kind] = (effectClaimWork[effect.kind] ?? 0) + 1;
const rows = await engine.executeRawDirect(`UPDATE persistence_effects SET claim_expires_at=now()+interval '2 minutes',updated_at=now()
WHERE id=$1 AND execution_token=$2::uuid AND state='running' AND ${PERSISTENCE_PROTOCOL_PREDICATE} RETURNING id`, [effect.id, effect.execution_token]);
if (rows.length !== 1) throw opError('write_claim_lost', 'The effect claim changed.',
`Another worker took over this ${effect.kind} effect of source ${effect.source_id} (its claim expired or was reassigned), so this attempt stopped; the current holder finishes it. Inspect the owner's effects rather than retrying by hand.`,
{ fix: readFix(`Shows source ${effect.source_id}'s canonical owner with its blocking, retrying and parked effects, read-only.`,
{ argv: ['gbrain', 'sources', 'writer', 'status', '--source', effect.source_id, '--json'] }) });
};
}
export async function renewPersistenceEffectClaim(engine: SqlEngine, effect: PersistenceEffect): Promise<boolean> {
const rows = await engine.executeRaw(`UPDATE persistence_effects SET claim_expires_at=now()+interval '2 minutes',updated_at=now()
WHERE id=$1 AND execution_token=$2::uuid AND state='running' AND recovery IS NULL AND ${PERSISTENCE_PROTOCOL_PREDICATE} RETURNING id`, [effect.id, effect.execution_token]);
return rows.length === 1;
}
export async function advanceEffectCursor(engine: SqlEngine, effect: PersistenceEffect, slug: string): Promise<void> {
const retrying = effect.data.retry_slugs ?? [];
if (retrying.includes(slug)) {
// A retried parked target finishes without moving the scan cursor. Each
// remaining retried target keeps a single authorized attempt.
const { retry_slugs: _retry, target_failures: _failures, failing_target: _target, ...data } = effect.data;
const remaining = retrying.filter(candidate => candidate !== slug);
await requeueEffect(engine, effect, remaining.length ? { ...data, retry_slugs: remaining, target_failures: PARK_AFTER_FAILURES - 1 } : data, null, 0);
return;
}
await engine.executeRaw(`UPDATE persistence_effects SET state='queued',data=jsonb_set(
CASE WHEN kind='embedding' THEN jsonb_set(data,'{embedding_attempt_base}',to_jsonb(attempts)) ELSE data-'target_failures'-'failing_target' END,'{after_slug}',to_jsonb($3::text)),
execution_token=NULL,claim_expires_at=NULL,claim_owner=NULL,next_attempt_at=now(),error_code=NULL,
updated_at=now()
WHERE id=$1 AND execution_token=$2::uuid AND recovery IS NULL AND ${PERSISTENCE_PROTOCOL_PREDICATE}`, [effect.id, effect.execution_token, slug]);
}
/** An effect with parked targets finishes as failed (`targets_parked`), never as committed. */
export async function completeEffect(engine: SqlEngine, effect: PersistenceEffect, outcome: Record<string, unknown> = {}): Promise<void> {
await faultPoint(EFFECT_FAULT_POINTS[effect.kind], { effectId: effect.id, requestId: effect.request_id, sourceId: effect.source_id });
await engine.executeRaw(`UPDATE persistence_effects SET
state=CASE WHEN jsonb_array_length(COALESCE(data->'parked','[]'::jsonb))>0 THEN 'failed' ELSE 'committed' END,
error_code=CASE WHEN jsonb_array_length(COALESCE(data->'parked','[]'::jsonb))>0 THEN 'targets_parked' END,
data=data-'retry_slugs'-'target_failures'-'failing_target'-'busy_retries'-'busy_since'-'busy_at',execution_token=NULL,claim_expires_at=NULL,claim_owner=NULL,
outcome=$3::text::jsonb,updated_at=now() WHERE id=$1 AND execution_token=$2::uuid AND recovery IS NULL AND ${PERSISTENCE_PROTOCOL_PREDICATE}`,
[effect.id, effect.execution_token, JSON.stringify(outcome)]);
}
export async function retryEffect(engine: SqlEngine, effect: PersistenceEffect, reason: string, delayMs = 1000): Promise<void> {
await engine.executeRaw(`UPDATE persistence_effects SET state='queued',execution_token=NULL,claim_expires_at=NULL,claim_owner=NULL,error_code=$3,
next_attempt_at=now()+($4::double precision*interval '1 millisecond'),updated_at=now()
WHERE id=$1 AND execution_token=$2::uuid AND ${PERSISTENCE_PROTOCOL_PREDICATE}`, [effect.id, effect.execution_token, reason, delayMs]);
}
/** GBRA-133: the longest a `writer_busy` effect waits before its next claim. */
export const BUSY_RETRY_MAX_MS = 60_000;
/**
* GBRA-133: a `writer_busy` retry backs off per consecutive busy retry (250 ms doubling to `BUSY_RETRY_MAX_MS`), so a
* catch-up that cannot take the worktree stops claiming its effects several times a second. A streak whose last busy
* retry is over two caps old starts again. It never parks: contention says nothing about the target.
*/
export async function retryBusyEffect(engine: SqlEngine, effect: PersistenceEffect, now = Date.now()): Promise<void> {
const last = Date.parse(effect.data.busy_at ?? '');
const streak = Number.isFinite(last) && now - last < 2 * BUSY_RETRY_MAX_MS ? (effect.data.busy_retries ?? 0) + 1 : 1;
const busy = { busy_retries: streak, busy_since: streak > 1 && effect.data.busy_since ? effect.data.busy_since : new Date(now).toISOString(), busy_at: new Date(now).toISOString() };
await engine.executeRaw(`UPDATE persistence_effects SET state='queued',execution_token=NULL,claim_expires_at=NULL,claim_owner=NULL,error_code='writer_busy',
data=data||$3::text::jsonb,next_attempt_at=now()+($4::double precision*interval '1 millisecond'),updated_at=now()
WHERE id=$1 AND execution_token=$2::uuid AND ${PERSISTENCE_PROTOCOL_PREDICATE}`,
[effect.id, effect.execution_token, JSON.stringify(busy), Math.min(BUSY_RETRY_MAX_MS, 250 * 2 ** Math.min(streak - 1, 8))]);
}
/** Release a claim with replacement bookkeeping; parking never applies while recovery is recorded. */
export async function requeueEffect(engine: SqlEngine, effect: PersistenceEffect, data: PersistenceEffect['data'], reason: string | null, delayMs: number): Promise<void> {
await engine.executeRaw(`UPDATE persistence_effects SET state='queued',data=$3::text::jsonb,execution_token=NULL,claim_expires_at=NULL,claim_owner=NULL,error_code=$4,
next_attempt_at=now()+($5::double precision*interval '1 millisecond'),updated_at=now()
WHERE id=$1 AND execution_token=$2::uuid AND recovery IS NULL AND ${PERSISTENCE_PROTOCOL_PREDICATE}`,
[effect.id, effect.execution_token, JSON.stringify(data), reason, delayMs]);
}
export async function parkEffect(engine: SqlEngine, effect: PersistenceEffect, data: PersistenceEffect['data']): Promise<void> {
await engine.executeRaw(`UPDATE persistence_effects SET state='failed',data=$3::text::jsonb,execution_token=NULL,claim_expires_at=NULL,claim_owner=NULL,
error_code='targets_parked',updated_at=now() WHERE id=$1 AND execution_token=$2::uuid AND recovery IS NULL AND ${PERSISTENCE_PROTOCOL_PREDICATE}`,
[effect.id, effect.execution_token, JSON.stringify(data)]);
}
export async function failEffect(engine: SqlEngine, effect: PersistenceEffect, reason: string): Promise<void> {
await engine.executeRaw(`UPDATE persistence_effects SET state='failed',execution_token=NULL,claim_expires_at=NULL,claim_owner=NULL,error_code=$3,updated_at=now()
WHERE id=$1 AND execution_token=$2::uuid AND recovery IS NULL AND ${PERSISTENCE_PROTOCOL_PREDICATE}`, [effect.id, effect.execution_token, reason]);
}
/**
* #9227: what a classic write's receipt says about Git, read from its Git effect each time the receipt is read. Its
* publication stored `git_state: queued` (`queuePublicationEffects`) and nothing rewrites it, so the effect row is the
* live answer: `committed` with the commit's oid (an effect that recorded none, from an older build or a file Git
* already held, reads `committed` without one), `superseded`, `skipped` or `failed` with the reason, `retrying`
* with the last attempt's error, `running`, `recovering`, and `queued` only while the effect is queued. Null when the
* request has no Git effect row.
*/
export async function gitReceiptState(engine: SqlEngine, requestId: string): Promise<{ git_state: string; git_commit?: string; git_reason?: string } | null> {
const [row] = await engine.executeRaw<{ state: string; error_code: string | null; recovering: boolean; outcome: Record<string, unknown> | null }>(
`SELECT state,error_code,outcome,recovery IS NOT NULL AS recovering FROM persistence_effects WHERE request_id=$1::uuid AND kind='git' ORDER BY id DESC LIMIT 1`, [requestId]);
if (!row) return null;
const reason = (value: unknown) => typeof value === 'string' && /^[a-z_]{1,80}$/.test(value) ? { git_reason: value } : {};
if (row.recovering) return { git_state: 'recovering' };
if (row.state === 'failed') return { git_state: 'failed', ...reason(row.error_code) };
if (row.state === 'queued') return row.error_code ? { git_state: 'retrying', ...reason(row.error_code) } : { git_state: 'queued' };
if (row.state !== 'committed') return { git_state: row.state };
const git = row.outcome?.git;
if (git === 'superseded' || git === 'skipped') return { git_state: git, ...reason(row.outcome?.reason) };
const commit = row.outcome?.commit;
return { git_state: 'committed', ...(typeof commit === 'string' && /^[0-9a-f]{40,64}$/.test(commit) ? { git_commit: commit } : {}) };
}
/** Only public kind/state/reason, aggregated so withdrawal page counts cannot leak. */
export async function publicEffectsForRequest(engine: SqlEngine, requestId: string): Promise<Array<{ kind: EffectKind; state: string; reason?: string; push?: string; added?: number; removed?: number;
invalid_targets?: Array<{ slug: string; reason: 'invalid_slug' }> }>> {
const rows = await engine.executeRaw<{ kind: EffectKind; state: string; error_code: string | null; recovering: boolean; outcome: Record<string, unknown> | null }>(
'SELECT kind,state,error_code,outcome,recovery IS NOT NULL AS recovering FROM persistence_effects WHERE request_id=$1::uuid ORDER BY kind', [requestId]);
return rows.filter(row => ['git', 'embedding', 'withdrawal-mirror', 'facts-backstop', 'links'].includes(row.kind)).map(row => {
const reason = row.error_code ?? row.outcome?.reason;
const push = row.outcome?.push;
const invalid = Array.isArray(row.outcome?.skipped_targets) ? (row.outcome.skipped_targets as Array<{ slug: string; reason: string }>)
.filter(target => target.reason === 'invalid_slug').map(target => ({ slug: target.slug, reason: 'invalid_slug' as const })) : [];
return { kind: row.kind, state: row.recovering ? 'recovering' : row.outcome?.git === 'skipped' || row.outcome?.facts === 'skipped' || row.outcome?.embedding === 'skipped' || row.outcome?.links === 'skipped' ? 'skipped'
: row.outcome?.facts === 'queued' ? 'dispatched' : row.state,
...(typeof reason === 'string' && /^[a-z_]{1,80}$/.test(reason) ? { reason } : {}),
...(row.kind === 'git' && (push === 'committed' || push === 'skipped') ? { push } : {}),
...(row.kind === 'links' && row.outcome?.links === 'committed' ? { added: Number(row.outcome.added), removed: Number(row.outcome.removed) } : {}),
...(invalid.length ? { invalid_targets: invalid } : {}),
};
});
}