Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(search): readiness probe runs with JIT off and keys its cache on the trust floor (#8033)

garrytanfc6f1d630f10
diff --git a/docs/architecture/key-files/core-search-1.md b/docs/architecture/key-files/core-search-1.md
index 198dd347ac..8bc4106410 100644
--- a/docs/architecture/key-files/core-search-1.md
+++ b/docs/architecture/key-files/core-search-1.md
@@ -67,7 +67,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/core/search/private-visibility.ts` — shared page-visibility resolver and SQL predicates. Explicit local trust disables page filtering; operator env/config opt-outs keep their semantics; failed config reads enforce privacy. `privatePagesFilterFragment` authorizes concrete page rows and `isPrivatePage` is its row-side twin: explicit `private` hides a page, absent visibility is world for ordinary pages and private for extracted atoms (`type = 'atom'`) and synthesized concepts (`type = 'concept'` with `synthesized_by`), because their origin may be a private page or transcript. The page predicate also follows derived origins: an atom whose `source_slug` page is explicitly private, and a synthesized concept with a private input atom (or an input whose origin is private) over `concept-provenance` edges, are private whatever their own field says, so a later private flip of an origin reaches derived pages before any repair. Chronicle events follow `event.depth` (fail closed). Declared lineage matches `derived_from` slugs with `= ANY(ARRAY(...))`, not `IN (SELECT ... jsonb_array_elements_text(...))`: same rows, but the planner priced the IN form as a 100-row semi-join per page and pushed every read carrying the rule past `jit_above_cost` (`test/e2e/private-visibility-plan-postgres.test.ts`). `privateSnapshotFilterFragment` is the same rule on a row's own frontmatter for `page_versions`. `effectiveVisibility(origin)` (transcript or missing origin private, page origin per the read rule) and `strictestVisibility` are used by both `extract_atoms` paths, concept synthesis and `gbrain repair visibility`. Remote publication rechecks (`persistence/page-visibility.ts`) and the alias-inject recheck in `hybrid.ts` use the same rule. Tests: `test/private-visibility.test.ts`, `test/derived-page-visibility.test.ts` (PGLite and Postgres); link origins and timeline projections use independent ID-based predicates. `privateProvenanceFilterFragment` hides a fact whose provenance page (`source_markdown_slug`) is private; the fact-list reads in `engine-sql/facts.ts` (by entity, since, keyset, session, supersessions, trajectory) apply it behind `FactListOpts.excludePrivate` / `TrajectoryOpts.excludePrivate`, which every remote fact surface resolves with `resolveExcludePrivatePages` (`test/remote-fact-list-private-provenance.test.ts`, both engines). Remote fact writes apply the same predicate behind an `excludePrivate` option: `forget` (`guardRemoteForget`, the row lock in `persistence/memory-mutations.ts`, `recordFactWithdrawal`, `similarActiveAfterForget`) and `remember` (`decideSingleFact`'s exact and cosine arms, `decideReplacement`), so a fact remote reads hide is `not_found` to a remote write and never matched as its duplicate (`test/remote-fact-write-private-provenance.test.ts`, both engines). Legacy slug-set helpers only enumerate names; they never authorize another row's data. `ops/context.ts:readPolicyOpts` combines canonical source precedence, resolved privacy and holder permissions. Both engines filter content/history/graph/identity/analytics before limits or aggregation; current and historical visibility are checked independently while page privacy is enforced. Semantic response caching remains disabled, so visibility-key folding alone never authorizes reuse.
-- `src/core/search/projection-readiness.ts` — one statement probes visible unsealed pages: ready, projection_pending, by_design (protected/archived only, if none pending) or unknown; LIMIT 1 arms use the v161 pending index. Cached per scope by DB generation (page clock, pages filenode, archive flags, no open tx); `GBRAIN_PROJECTION_READINESS_CACHE=0` disables.
+- `src/core/search/projection-readiness.ts` — one JIT-off statement probes visible unsealed pages: ready, projection_pending, by_design (only protected/archived unsealed) or unknown; LIMIT 1 arms use the v161 pending index. Cached per scope by DB generation (page clock, pages filenode, archive flags, no open tx); `GBRAIN_PROJECTION_READINESS_CACHE=0` disables.
- `src/core/search/projection-statistics.ts` — current-projection expression statistics, strict migration postconditions and owner-authorized batch refresh. Migration 160 verifies object identity and populated samples before advancing the ledger, distinguishing empty tables and row-security-hidden statistics. Import, sync, reindex and drained recovery refresh outside page locks; failures preserve completed writes and give a maintenance hint. A pass that changed fewer than 50 + 10% of the sampled pages leaves the statistics alone once they exist (the projection statistic and, on Postgres, every `SEARCH_STATISTICS_COLUMNS` column: `missingSearchStatistics`), and PGLite then analyzes only the hot tables its row deltas mark stale. On Postgres it also samples the page columns search filters read (`SEARCH_PAGE_STATISTICS_SQL`) and the chunk `SEARCH_STATISTICS_COLUMNS`; a vacuum holding a table defers it (analyze-lock.ts). `refreshChunkStatistics` runs the chunk step after a drain that changed 50 + 10% of chunks (any sans statistics): without them the vector candidate statement sorts every eligible chunk instead of walking the HNSW index (`test/e2e/vector-chunk-statistics-postgres.test.ts`). Absent search statistics (pg_upgrade, a deleted pg_statistic; 50-60 s searches at 5k pages) get `ensureSearchStatistics`: PostgresEngine runs it once per engine in the background on its first pool search (never awaited; disconnect waits), and doctor `planner_stats_stale` plus `repair planner-stats` report and apply the same refresh (`test/search-statistics-guard.test.ts`).
diff --git a/src/core/search/projection-readiness.ts b/src/core/search/projection-readiness.ts
index 7fd1a32483..a7f12b7afc 100644
--- a/src/core/search/projection-readiness.ts
+++ b/src/core/search/projection-readiness.ts
@@ -30,7 +30,7 @@ export function __resetProjectionReadinessCacheForTests(): void { readinessCache
function scopeKey(scope: ProjectionReadinessScope): string {
const sorted = (values?: string[]) => values === undefined ? null : [...new Set(values)].sort();
return JSON.stringify([scope.sourceId ?? null, sorted(scope.sourceIds), scope.excludePrivate === true, scope.requireSafeChunks === true,
- scope.pageKind ?? null, sorted(scope.types), sorted(scope.excludeSlugPrefixes)]);
+ scope.minTrust ?? null, scope.suppressFlagged === true, scope.pageKind ?? null, sorted(scope.types), sorted(scope.excludeSlugPrefixes)]);
}
/**
@@ -92,6 +92,8 @@ async function probeUncached(
// EXISTS chose a sequential scan of pages that expected to stop at once; on a sealed brain it read every page
// (~600 ms at 600k pages, on every cold call). Ordering by idx_pages_projection_pending's columns under LIMIT 1
// makes that partial index the cheap first row, so the probe reads only the unsealed pages.
+ // JIT off (#8033): a remote caller's private-visibility subplans lift the estimate past jit_above_cost, and compiling
+ // them cost ~66 of ~67 ms at 20k pages while the probe itself reads one index row.
const unsealed = (cond: string) => `(SELECT true FROM pages p JOIN sources s ON s.id = p.source_id
WHERE p.deleted_at IS NULL
AND p.text_projection_revision IS DISTINCT FROM p.knowledge_revision
@@ -102,6 +104,7 @@ async function probeUncached(
`WITH r AS MATERIALIZED (SELECT ${unsealed(`${cls} NOT IN ('protected','archived')`)} AS pending)
SELECT r.pending, CASE WHEN r.pending THEN false ELSE ${unsealed(`${cls} IN ('protected','archived')`)} END AS by_design FROM r`,
params,
+ { jitOff: true },
);
if (typeof rows[0]?.pending !== 'boolean') throw new Error('Invalid readiness result');
if (rows[0].pending) {
diff --git a/test/e2e/projection-readiness-plan-postgres.test.ts b/test/e2e/projection-readiness-plan-postgres.test.ts
index 657bed80c1..92d9fa1339 100644
--- a/test/e2e/projection-readiness-plan-postgres.test.ts
+++ b/test/e2e/projection-readiness-plan-postgres.test.ts
@@ -10,6 +10,7 @@
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import type { BrainEngine } from '../../src/core/engine.ts';
+import { PostgresEngine } from '../../src/core/postgres-engine.ts';
import { probeProjectionReadiness, type ProjectionReadinessScope } from '../../src/core/search/projection-readiness.ts';
import { isolatedPersistencePostgres } from '../helpers/persistence-postgres.ts';
import { withEnv } from '../helpers/with-env.ts';
@@ -20,9 +21,10 @@ const describePostgres = hasDatabase() ? describe : describe.skip;
describePostgres('projection readiness probe plan on Postgres (GBRA-156)', () => {
let engine: BrainEngine;
let close: () => Promise<void>;
+ let databaseUrl: string;
beforeAll(async () => {
- ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
+ ({ engine, close, databaseUrl } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
await engine.executeRaw("INSERT INTO sources(id,name) VALUES ('source-a','source-a'),('source-b','source-b') ON CONFLICT DO NOTHING");
await engine.executeRaw(`INSERT INTO pages(source_id,slug,title,type,page_kind,compiled_truth,chunker_version,frontmatter)
SELECT CASE WHEN i % 2 = 0 THEN 'source-a' ELSE 'source-b' END, 'filler-' || i, 'Filler ' || i, 'concept',
@@ -77,6 +79,32 @@ describePostgres('projection readiness probe plan on Postgres (GBRA-156)', () =>
}
});
+ // #8033: a remote caller's private-visibility subplans lift the estimate past jit_above_cost, and compiling them
+ // cost nearly all of the probe's time. The session below compiles every statement that keeps JIT on.
+ test('the probe runs with JIT off for a remote scope (#8033)', async () => {
+ const reader = new PostgresEngine();
+ await reader.connect({ database_url: databaseUrl, poolSize: 1 });
+ try {
+ await reader.executeRaw('SET jit = on');
+ await reader.executeRaw('SET jit_above_cost = 0');
+ const explain = async (sql: string, params?: unknown[], opts?: Parameters<BrainEngine['executeRaw']>[2]) =>
+ JSON.stringify((await reader.executeRaw<Record<string, unknown>>(`EXPLAIN (ANALYZE, FORMAT JSON) ${sql}`, params, opts))[0]);
+ const plans: Array<{ asRun: string; jitOn: string }> = [];
+ const recording = { executeRaw: async (sql: string, params?: unknown[], opts?: Parameters<BrainEngine['executeRaw']>[2]) => {
+ if (sql.includes('IS DISTINCT FROM')) plans.push({ asRun: await explain(sql, params, opts), jitOn: await explain(sql, params) });
+ return reader.executeRaw(sql, params, opts);
+ } } as unknown as BrainEngine;
+ const result = await withEnv({ GBRAIN_PROJECTION_READINESS_CACHE: '0' }, () =>
+ probeProjectionReadiness(recording, { sourceIds: ['source-a', 'source-b'], excludePrivate: true, requireSafeChunks: true }));
+ expect(result).toEqual({ status: 'ready', ready: true });
+ expect(plans).toHaveLength(1);
+ expect(plans[0].jitOn.includes('"JIT"')).toBe(true);
+ expect(plans[0].asRun.includes('"JIT"')).toBe(false);
+ } finally {
+ await reader.disconnect();
+ }
+ });
+
test('a brain with many pending pages answers pending without the by_design walk (#8000)', async () => {
await engine.executeRaw("UPDATE pages SET text_projection_revision=NULL WHERE source_id='source-a'");
try {
diff --git a/test/projection-readiness.test.ts b/test/projection-readiness.test.ts
index c55209207f..fe3805f507 100644
--- a/test/projection-readiness.test.ts
+++ b/test/projection-readiness.test.ts
@@ -181,6 +181,16 @@ describe('projection readiness cache', () => {
expect(c.probes()).toBe(scopes.length);
});
+ // #8033: a trust floor filters the probe's pages, so a ready answer under a floor must not answer a caller without one.
+ test('a trust floor is part of the key', async () => {
+ await seed('markdown', 'source-a', 'pending-unknown-tier');
+ const c = counted();
+ expect((await probeProjectionReadiness(c.engine, { sourceId: 'source-a', minTrust: 'user_confirmed' })).status).toBe('ready');
+ expect((await probeProjectionReadiness(c.engine, { sourceId: 'source-a' })).status).toBe('projection_pending');
+ expect((await probeProjectionReadiness(c.engine, { sourceId: 'source-a', minTrust: 'unknown' })).status).toBe('projection_pending');
+ expect(c.probes()).toBe(3);
+ });
+
test('restoring an archived source with pending pages invalidates a cached ready', async () => {
await seed('markdown', 'source-b', 'pending');
await engine.executeRaw("UPDATE sources SET archived=true WHERE id='source-b'");