Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: the sync's held-move plan ends at one deadline, bare-name resolution included

garrytan079188ae2f11
diff --git a/src/core/facts/held-fact-move.ts b/src/core/facts/held-fact-move.ts
index c9a72249b1..2f10370a7a 100644
--- a/src/core/facts/held-fact-move.ts
+++ b/src/core/facts/held-fact-move.ts
@@ -16,13 +16,11 @@ import { folderHoldingSlug, holdingSlugSql, isHoldingSlug, UNATTRIBUTED_MEMORY_S
import { maintenancePreflight, planHeldRowDrop, submitMaintenanceIntent, submitPlannedFactFenceAdoption, type HeldDrop } from '../persistence/prepared-maintenance.ts';
import { privatePagesFilterFragment } from '../search/private-visibility.ts';
import { getWorktreeBinding } from '../persistence/ownership.ts';
-import { isStatementTimeout } from '../persistence/bounded-reads.ts';
+import { isStatementTimeout, PreparationDeadlineError } from '../persistence/bounded-reads.ts';
+import { registerEngineView } from '../persistence/switches.ts';
import { syncPreparationBudgetMs } from '../persistence/sync-waivers.ts';
import { isFenceHold, pageHasFile, planManagedPage, type UnfencedFactRow } from './unfenced-facts.ts';
-/** The bound the sync path puts on each raw read of the held move (its preparation budget); a rule's apply and maintenance pass none. */
-export interface HeldMoveReads { timeoutMs?: number }
-
export interface HeldFactMoveOutcome {
moved: number;
moved_slugs: string[];
@@ -47,25 +45,25 @@ export interface HeldFactMoveOutcome {
* coverage covers the entity, its folder's holding page. An exact page rule on the entity's own slug, and an access state
* this database role cannot read, are refused: no holding page carries their readers.
*/
-export async function holdingHome(engine: BrainEngine, sourceId: string, entity: string | null, reads: HeldMoveReads = {}):
+export async function holdingHome(engine: BrainEngine, sourceId: string, entity: string | null):
Promise<{ slug: string } | { refused: 'page_rule' | 'access_unreadable' } | null> {
if ((await getWorktreeBinding(engine, sourceId))?.canonical_git !== true) return null;
if (/^(false|0|off|no)$/i.test(await engine.getConfig('sync.write_through') ?? 'true')) return null;
if (entity !== null && entity !== UNATTRIBUTED_MEMORY_SLUG
- && (await engine.executeRaw('SELECT 1 FROM pages WHERE source_id=$1 AND slug=$2 AND deleted_at IS NOT NULL', [sourceId, entity], reads)).length) return null;
- return holdingPageFor(engine, sourceId, entity, reads);
+ && (await engine.executeRaw('SELECT 1 FROM pages WHERE source_id=$1 AND slug=$2 AND deleted_at IS NOT NULL', [sourceId, entity])).length) return null;
+ return holdingPageFor(engine, sourceId, entity);
}
/** The holding page holdingHome classifies `entity` to by its access rules alone, whether or not a writer holds rows now. */
-export async function holdingPageFor(engine: BrainEngine, sourceId: string, entity: string | null, reads: HeldMoveReads = {}):
+export async function holdingPageFor(engine: BrainEngine, sourceId: string, entity: string | null):
Promise<{ slug: string } | { refused: 'page_rule' | 'access_unreadable' }> {
if (entity === null || entity === UNATTRIBUTED_MEMORY_SLUG) return { slug: UNATTRIBUTED_MEMORY_SLUG };
const access = await engine.executeRaw<{ unreadable: boolean; page_rule: boolean; restricted: boolean }>(
`SELECT gbrain_access_state_unreadable() AS unreadable,
(EXISTS (SELECT 1 FROM access_rules r WHERE r.source_id=$1 AND r.prefix=$2)
OR EXISTS (SELECT 1 FROM access_pending_coverage c WHERE c.source_id=$1 AND c.prefix=$2)) AS page_rule,
- (gbrain_access_folder_rules($1, $2) IS NOT NULL OR gbrain_access_pending_covers($1, $2)) AS restricted`, [sourceId, entity], reads).catch((error: unknown) => {
- if (reads.timeoutMs !== undefined && isStatementTimeout(error)) throw error;
+ (gbrain_access_folder_rules($1, $2) IS NOT NULL OR gbrain_access_pending_covers($1, $2)) AS restricted`, [sourceId, entity]).catch((error: unknown) => {
+ if (error instanceof PreparationDeadlineError) throw error;
return null;
});
const row = access?.[0];
@@ -79,8 +77,8 @@ export async function holdingPageFor(engine: BrainEngine, sourceId: string, enti
* name that way), the one page `remember` itself would resolve the name to. Two or more such pages: the row stays held and
* the candidates are named. Null: no page yet.
*/
-export async function heldFactTarget(engine: BrainEngine, sourceId: string, key: string, reads: HeldMoveReads = {}): Promise<{ slug: string } | { ambiguous: string[] } | null> {
- if ((await engine.executeRaw('SELECT 1 FROM pages WHERE source_id=$1 AND slug=$2 AND deleted_at IS NULL', [sourceId, key], reads)).length) return { slug: key };
+export async function heldFactTarget(engine: BrainEngine, sourceId: string, key: string): Promise<{ slug: string } | { ambiguous: string[] } | null> {
+ if ((await engine.executeRaw('SELECT 1 FROM pages WHERE source_id=$1 AND slug=$2 AND deleted_at IS NULL', [sourceId, key])).length) return { slug: key };
if (key.includes('/')) return null;
const { entityReferenceCandidates, resolveStrictEntityReference } = await import('../entities/resolve.ts');
const strict = await resolveStrictEntityReference(engine, sourceId, key, { sameName: true });
@@ -124,9 +122,9 @@ export type HoldingHome = Awaited<ReturnType<typeof holdingHome>>;
* force; a preview passes its desired rules). Null: the rows stay where they are.
*/
export async function heldRowDestination(engine: BrainEngine, sourceId: string, key: string, from: string,
- home: (key: string) => Promise<HoldingHome> = k => holdingHome(engine, sourceId, k), reads: HeldMoveReads = {}):
+ home: (key: string) => Promise<HoldingHome> = k => holdingHome(engine, sourceId, k)):
Promise<{ slug: string; kind: 'page' | 'create' | 'rehome' } | { unmovable: string } | null> {
- const target = await heldFactTarget(engine, sourceId, key, reads);
+ const target = await heldFactTarget(engine, sourceId, key);
if (target && 'ambiguous' in target) return { unmovable: ambiguousHeldReason(target.ambiguous) };
if (target) return { slug: target.slug, kind: 'page' };
const h = await home(key);
@@ -149,28 +147,27 @@ export interface HeldMoveGroup {
* decides a page-less entity's holding page (a preview passes its desired rules); `hidden` names pages the change makes
* unreadable to some reader (a preview's desired rules), so their note is `moved`.
*/
-export async function planHeldMoves(engine: BrainEngine, sourceId: string, opts: { home?: (key: string) => Promise<HoldingHome>; hidden?: (slug: string) => boolean } & HeldMoveReads = {}):
+export async function planHeldMoves(engine: BrainEngine, sourceId: string, opts: { home?: (key: string) => Promise<HoldingHome>; hidden?: (slug: string) => boolean } = {}):
Promise<{ groups: HeldMoveGroup[]; unmovable: HeldFactMoveOutcome['unmovable'] }> {
- const reads = { timeoutMs: opts.timeoutMs };
const onHolding = `f.source_id = $1 AND f.source_markdown_slug IN (SELECT hp.slug FROM pages hp WHERE hp.source_id = $1 AND ${holdingSlugSql('hp.slug')})
AND f.row_num IS NOT NULL AND f.dimension IS NULL AND f.entity_slug IS NOT NULL AND NOT ${holdingSlugSql('f.entity_slug')}`;
const rows = await engine.executeRaw<HeldRow>(
`SELECT id, source_id, entity_slug, fact, kind, visibility, notability, context, valid_from, valid_until, source, confidence,
claim_metric, claim_value, claim_unit, claim_period, attributed_to, true AS page_exists, source_markdown_slug AS from_slug
- FROM facts f WHERE ${onHolding} AND f.expired_at IS NULL ORDER BY f.source_markdown_slug, f.entity_slug, f.id`, [sourceId], reads);
+ FROM facts f WHERE ${onHolding} AND f.expired_at IS NULL ORDER BY f.source_markdown_slug, f.entity_slug, f.id`, [sourceId]);
// A struck row keeps its facts row (expired) at its row number; one an active fact reuses is not struck.
const struck = await engine.executeRaw<{ from_slug: string; entity_slug: string; row_num: number; fact: string }>(
`SELECT DISTINCT ON (f.source_markdown_slug, f.row_num) f.source_markdown_slug AS from_slug, f.entity_slug, f.row_num, f.fact FROM facts f
WHERE ${onHolding} AND f.expired_at IS NOT NULL AND NOT EXISTS (SELECT 1 FROM facts a WHERE a.source_id = f.source_id
AND a.source_markdown_slug = f.source_markdown_slug AND a.row_num = f.row_num AND a.expired_at IS NULL)
- ORDER BY f.source_markdown_slug, f.row_num, f.id DESC`, [sourceId], reads);
+ ORDER BY f.source_markdown_slug, f.row_num, f.id DESC`, [sourceId]);
const keys = new Map<string, { from: string; key: string; group: HeldRow[]; struck: HeldDrop[] }>();
const at = (from: string, key: string) => keys.get(`${from}\0${key}`) ?? keys.set(`${from}\0${key}`, { from, key, group: [], struck: [] }).get(`${from}\0${key}`)!;
for (const row of rows) at(row.from_slug, row.entity_slug!).group.push(row);
for (const s of struck) at(s.from_slug, s.entity_slug).struck.push({ row_num: Number(s.row_num), entity: s.entity_slug, claim: s.fact });
const plan: Awaited<ReturnType<typeof planHeldMoves>> = { groups: [], unmovable: [] };
for (const { from, key, group, struck: withdrawn } of keys.values()) {
- const dest = await heldRowDestination(engine, sourceId, key, from, opts.home ?? (k => holdingHome(engine, sourceId, k, reads)), reads);
+ const dest = await heldRowDestination(engine, sourceId, key, from, opts.home);
if (!dest) continue;
if ('unmovable' in dest) {
if (group.length) plan.unmovable.push({ code: 'held_fact_unmovable', slug: key, fact_ids: group.map(r => Number(r.id)), reason: dest.unmovable });
@@ -179,7 +176,7 @@ export async function planHeldMoves(engine: BrainEngine, sourceId: string, opts:
// A fact moved into a page not every reader of the source can read, or off a folder's holding page, leaves the
// holding page with no trace of where it went.
const [page] = dest.kind === 'page' && from === UNATTRIBUTED_MEMORY_SLUG && !opts.hidden?.(dest.slug) ? await engine.executeRaw<{ visible: boolean }>(
- `SELECT ${privatePagesFilterFragment('p')} AS visible FROM pages p WHERE p.source_id=$1 AND p.slug=$2 AND p.deleted_at IS NULL`, [sourceId, dest.slug], reads) : [];
+ `SELECT ${privatePagesFilterFragment('p')} AS visible FROM pages p WHERE p.source_id=$1 AND p.slug=$2 AND p.deleted_at IS NULL`, [sourceId, dest.slug]) : [];
const note = page?.visible === true ? `moved to ${dest.slug}` : 'moved';
if (group.length) plan.groups.push({ slug: dest.slug, kind: dest.kind, from, key, group, note, struck: note === 'moved' ? withdrawn : [] });
else if (note === 'moved') plan.groups.push({ slug: from, kind: 'drop', from, key, group, note, struck: withdrawn });
@@ -199,23 +196,47 @@ export function heldMoveIncomplete(held: Pick<HeldFactMoveOutcome, 'segmented_pa
* GST-2492 (B2): after a sync releases its lease, the held facts a rule it applied narrows below their holding page's
* readers (a folder rule over the shared page, an exact page rule over a folder's holding page, or a pending narrowing)
* leave that page at once instead of at the next maintenance cycle (still the fallback after a crash). Null when none is due.
- * Each raw read it issues ends on the server at the sync preparation budget, so a lock another session holds on its tables
- * never holds a statement of the sync past it (#6318): a read ended there while planning rejects, one inside a group's move
- * leaves that group unmovable, and maintenance moves them later.
+ * A lock another session holds never keeps the sync past its preparation budget (#6318): the due check and the plan share
+ * one deadline (planningView), and the move's own page reads each end at the budget. A plan cut off there rejects, a group
+ * cut off in its move stays unmovable, and maintenance moves them later.
*/
export async function moveRuledSharedHeld(engine: BrainEngine, sourceId: string): Promise<HeldFactMoveOutcome | null> {
- const reads = { timeoutMs: await syncPreparationBudgetMs(engine) };
- const [due] = await engine.executeRaw<{ due: boolean }>(`SELECT EXISTS (SELECT 1 FROM facts f WHERE f.source_id = $1
+ const budget = await syncPreparationBudgetMs(engine);
+ const planning = planningView(engine, Date.now() + budget);
+ const [due] = await planning.executeRaw<{ due: boolean }>(`SELECT EXISTS (SELECT 1 FROM facts f WHERE f.source_id = $1
AND f.source_markdown_slug IN (SELECT hp.slug FROM pages hp WHERE hp.source_id = $1 AND ${holdingSlugSql('hp.slug')})
AND f.row_num IS NOT NULL AND f.dimension IS NULL AND f.entity_slug IS NOT NULL AND NOT ${holdingSlugSql('f.entity_slug')}
AND (gbrain_access_folder_rules(f.source_id, f.entity_slug) IS DISTINCT FROM gbrain_access_folder_rules(f.source_id, f.source_markdown_slug)
- OR (gbrain_access_pending_covers(f.source_id, f.entity_slug) AND NOT gbrain_access_pending_covers(f.source_id, f.source_markdown_slug)))) AS due`, [sourceId], reads);
- return due?.due ? moveHeldFacts(engine, sourceId, reads) : null;
+ OR (gbrain_access_pending_covers(f.source_id, f.entity_slug) AND NOT gbrain_access_pending_covers(f.source_id, f.source_markdown_slug)))) AS due`, [sourceId]);
+ return due?.due ? moveHeldFacts(engine, sourceId, { planning, timeoutMs: budget }) : null;
+}
+
+/**
+ * The engine the sync path plans a held move on: every raw read through it, the bare-name resolver's alias read included,
+ * ends on the server at `deadlineAt`, and one ended there rejects as a PreparationDeadlineError. PGLite plans on the engine.
+ */
+function planningView(engine: BrainEngine, deadlineAt: number): BrainEngine {
+ if (engine.kind !== 'postgres') return engine;
+ const view: BrainEngine = registerEngineView(new Proxy(engine, { get(target, key) {
+ if (key === 'executeRaw') return async (sql: string, params?: unknown[], opts?: Parameters<BrainEngine['executeRaw']>[2]) => {
+ if (Date.now() >= deadlineAt) throw new PreparationDeadlineError('held_move_plan', null);
+ try { return await target.executeRaw(sql, params, { ...opts, timeoutMs: Math.max(1, deadlineAt - Date.now()) }); } catch (error) {
+ if (isStatementTimeout(error)) throw new PreparationDeadlineError('held_move_plan', error.code, error);
+ throw error;
+ }
+ };
+ const value = Reflect.get(target, key, target);
+ // The alias read runs on the engine's own executeRaw: bound to the view, it takes the deadline too.
+ if (key === 'resolveAliases') return value.bind(view);
+ return typeof value === 'function' ? value.bind(target) : value;
+ } }), engine);
+ return view;
}
-export async function moveHeldFacts(engine: BrainEngine, sourceId: string, reads: HeldMoveReads = {}): Promise<HeldFactMoveOutcome> {
+export async function moveHeldFacts(engine: BrainEngine, sourceId: string, bound: { planning?: BrainEngine; timeoutMs?: number } = {}): Promise<HeldFactMoveOutcome> {
const outcome: HeldFactMoveOutcome = { moved: 0, moved_slugs: [], rehomed: 0, unmovable: [], write_errors: 0, segmented_versions_not_edited: 0, segmented_pages: [], pending: [] };
- const plan = await planHeldMoves(engine, sourceId, reads);
+ const plan = await planHeldMoves(bound.planning ?? engine, sourceId);
+ const reads = { timeoutMs: bound.timeoutMs };
outcome.unmovable.push(...plan.unmovable);
if (plan.groups.length === 0) return outcome;
const authority = await maintenancePreflight(engine, sourceId);
@@ -266,7 +287,7 @@ export async function moveHeldFacts(engine: BrainEngine, sourceId: string, reads
else { outcome.moved += plan.fence.assignments.length; outcome.moved_slugs.push(slug); }
}
const [edited] = await engine.executeRaw<{ n: number | null }>(`SELECT (outcome->'held_versions_edited'->>'segmented_versions_not_edited')::int AS n
- FROM persistence_requests WHERE request_id = $1::uuid`, [requestId], reads);
+ FROM persistence_requests WHERE request_id = $1::uuid`, [requestId]);
const n = Number(edited?.n ?? 0), seen = outcome.segmented_pages.find(p => p.slug === from);
if (n && seen) seen.versions = Math.max(seen.versions, n);
else if (n) outcome.segmented_pages.push({ slug: from, versions: n });
diff --git a/test/folder-holding-page-gst2492.test.ts b/test/folder-holding-page-gst2492.test.ts
index 0ae97a16ec..b4b2e26bd4 100644
--- a/test/folder-holding-page-gst2492.test.ts
+++ b/test/folder-holding-page-gst2492.test.ts
@@ -303,13 +303,44 @@ for (const backend of testBackends()) describe(`[${backend}] the folder-rule hol
const error = await caught(moveRuledSharedHeld(engine, 'default'));
return { code: error?.code, ms: performance.now() - started };
});
- expect(ended.code).toBe('57014');
+ expect(ended.code).toBe('preparation_deadline');
expect(ended.ms).toBeLessThan(budget + 3_000);
} finally { await holder.end(); resetSyncPreparationBudget(); }
expect(await moveRuledSharedHeld(engine, 'default')).toMatchObject({ rehomed: 1, unmovable: [], write_errors: 0 });
expect(await factRows(engine, claim)).toMatchObject([{ entity_slug: entity, source_markdown_slug: 'clients/acme-example/memory/unattributed' }]);
}), 300_000);
+ test.skipIf(backend !== 'postgres')('on the sync path a bare-name held row\'s resolution ends at the plan\'s deadline while another session locks page_aliases; once the lock drops the move completes', () => strict(async ({ engine, ctx }) => {
+ const entity = 'clients/acme-example/brief';
+ const claim = 'The acme-example brief carries an alias-locked clause.';
+ const bare = 'Kofi Example takes calls on Fridays.';
+ expect(await remember(ctx, claim, entity)).toMatchObject({ page: HOLD });
+ expect(await remember(ctx, bare, 'Kofi Example')).toMatchObject({ page: HOLD });
+ policySeams.afterInstall = () => { throw new Error('interrupted'); };
+ await expect(rules(engine, [rule('clients', 'clients/acme-example/', ['alice-example'])])).rejects.toThrow('interrupted');
+ policySeams.afterInstall = undefined;
+ __resetPrivateVisibilityCacheForTests();
+ const budget = 1_000;
+ await engine.setConfig('persistence.sync_preparation_ms', String(budget));
+ resetSyncPreparationBudget();
+ const [{ db }] = await engine.executeRaw<{ db: string }>('SELECT current_database() AS db');
+ const url = new URL(databaseUrl!); url.pathname = `/${db}`;
+ const holder = postgres(url.toString(), { max: 1, prepare: false, onnotice: () => {} });
+ try {
+ const ended = await holder.begin(async sql => {
+ await sql.unsafe('LOCK TABLE page_aliases IN ACCESS EXCLUSIVE MODE');
+ const started = performance.now();
+ const error = await caught(moveRuledSharedHeld(engine, 'default'));
+ return { code: error?.code, ms: performance.now() - started };
+ });
+ expect(ended.code).toBe('preparation_deadline');
+ expect(ended.ms).toBeLessThan(budget + 3_000);
+ } finally { await holder.end(); resetSyncPreparationBudget(); }
+ expect(await moveRuledSharedHeld(engine, 'default')).toMatchObject({ rehomed: 1, unmovable: [], write_errors: 0 });
+ expect(await factRows(engine, claim)).toMatchObject([{ entity_slug: entity, source_markdown_slug: 'clients/acme-example/memory/unattributed' }]);
+ expect(await factRows(engine, bare)).toMatchObject([{ entity_slug: 'kofi-example', source_markdown_slug: HOLD }]);
+ }), 300_000);
+
const versionBodies = (engine: BrainEngine, slug: string) => engine.executeRaw<{ id: number; body: string }>(
`SELECT v.id::int AS id, COALESCE(v.compiled_truth, '') || '\u0001' || COALESCE(v.timeline, '') AS body FROM page_versions v JOIN pages p ON p.id = v.page_id
WHERE p.source_id = 'default' AND p.slug = $1 ORDER BY v.id`, [slug]);