Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(access): the unrestricted short form also tests folder_rule_ids (GBRA-218 A2)

garrytan095faa2901d1
diff --git a/docs/architecture/key-files/core-search-1.md b/docs/architecture/key-files/core-search-1.md
index cd1dc4d6ed..75fb4b37a5 100644
--- a/docs/architecture/key-files/core-search-1.md
+++ b/docs/architecture/key-files/core-search-1.md
@@ -66,7 +66,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/core/search/modes-report.ts` — `buildModesReport(engine)` → `SearchModesReport` (`schema_version: 2`), the read-only dashboard behind `gbrain search modes` and the `search_modes` MCP op: `active_mode` + validity, the per-knob `resolved` attribution (`attributeKnob` over `KNOB_DESCRIPTIONS`, including the five `reranker_*` knobs), the three frozen `bundles`, `config_keys`, and `reranker_readiness` — `{model, enabled, ready, required_key, key_present, self_hosted, fix}` from `rerankerReadinessForEngine` + `describeRerankerFix` (a thrown readiness check still yields a `ready: false` verdict whose `fix` says to run `gbrain doctor`; the block never vanishes silently). `redactReadinessForRemote(report)` is what the `search_modes` op returns when `ctx.remote !== false`: `required_key`, `key_present` and `fix` are dropped and `self_hosted` is forced false — which env vars exist on the host is fingerprinting data and the fix names them; `ready` stays because it is observable anyway (reranked results carry `rerank_score`). `src/commands/search.ts:formatModesText` renders the runtime `Reranker:` line (`off (resolved) — …` / `<model> (enabled) — <KEY> present` / `<model> (enabled but NOT running) — <fix>`) and a per-bundle `reranker=… topNIn=… autocut=…` line. Pinned by `test/modes-report-reranker.test.ts`. The CLI dashboard leads with command-specific expansion: `query` follows the mode's expansion default (off in all modes) unless the call passes `expand`, while `search` is off. It discloses provider prerequisites/text flow and distinguishes retained bundle configuration from effective command behavior.
- `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 (`s... (line truncated to 2000 chars)
-- `src/core/access/` (GBRA-218) — per-member read access inside one source. `principals.ts` normalizes frontmatter `readable_by` (bare id = `member:<id>`, `group:<g>`, ASCII case fold, space trim; anything malformed is `['!nobody']`); it is the row twin of the SQL `gbrain_access_readers()` (`test/access-principals.test.ts` holds them equal). A BEFORE trigger keeps `pages.page_readers` equal to that function (direct writes to the column are recomputed), and predicates test the array, never the function, which costs ~0.2 ms per row. A page that names readers with no derived value yet (written before the migration) reads as nobody until `gbrain repair access` (`repair/access.ts`). `members.ts` (members, groups, tombstoned ids never reused, bindings), `token-binding.ts` (the verifiers' join; a credential bound to a disabled, tombstoned or missing member is refused with `access_member_disabled`) and `caller.ts` (`remoteCallerAccess`: the identity dispatch puts on the caller-access record; stdio binds through `mcp.stdio_member`; publication re-resolves from the stored principal). In `search/private-visibility.ts` every page fragment is `accessAllowedSql` AND the privacy part: plain fragments use the empty identity (over-hide, never leak), `*ForCaller` fragments the caller's, and `GBRAIN_REMOTE_PRIVATE_PAGES`, `search.remote_private_pages` and `granted_sources` relax only the privacy part (`privacyForCaller`). A derivative of a page that names readers is hidden from every remote caller (`originAllowedSql`, which calls the SQL function `gbrain_access_origin_restricted()` only for atom, question, concept, event or `derived_from` rows, so each read plans one call instead of four subplans). Both parts lead with column tests (`page_readers IS NULL`, `type`) so row estimates follow column statistics; an expression test such as `->'readable_by' IS NULL` estimates almost no rows and sent restricted vector searches into nested-loop sequential scans. The index walk's page probe (`INDEX_WALK_PAGE_COLUMNS`) projects `page_readers`. Config `access.restrictions_present` (set by a trigger, sticky) keeps every pre-A1 path on a brain with no restriction. `check:remote-privacy-reads` keeps the two relaxations read only in `private-visibility.ts`. Tests: `test/member-read-access.test.ts` (remote matrix, both engines), `test/access-*.test.ts`. Folder rules (A2) keep whole folders of a source to named members. `folder-rules.ts` is the grammar (`.gbrain/access.yml`: `rules:` of `id`, `prefix`, `readable_by`), `classifyRulebook` (each change is narrowing or widening; the target installs only the narrowing part) and `matchingRuleIds`. `policy.ts` owns the one applied rulebook for both stores: `access_rules` (source-qualified ids), the append-only `access_policy_revisions` log, `access_pending_coverage` (prefixes that read as nobody while a narrowing restamps, or while a committed file is invalid) and `sources.config.access_store`, persisted at the first rule and changed only by `policy-migrate.ts` (journaled in `access_policy_migrations`). `proposeRevision` installs narrowing at once under a per-source row lock and holds widening for `applyApproved` (`plan_hash`, `preview_changed`); `restampSource` rewrites `pages.folder_rule_ids` in id windows, then clears pending coverage under the lock; re-proposing the same rulebook finishes an interrupted restamp. A trigger stamps `folder_rule_ids` from the SQL function `gbrain_access_folder_rules()` on insert and on slug or source change, never from git on the serve path. `policy-git.ts` is the git store (files committed through the commit door, applied by `syncAccessPolicyAt` from sync preflight and the managed drain, read with `git show` at the synced commit); `policy-transfer.ts` carries the applied rulebook through `gbrain export` and installs it before any page in `gbrain import`; `policy-notice.ts` is the `access_policy_pending` degraded notice. In `private-visibility.ts`, `folderRulesAllowedSql` sits inside `accessAllowedSql` (`folder_rule_ids IS NULL OR folder_rule_ids <@ <satisfied ids>` plus coverage conjuncts), so no hatch, grant or `--as` relaxes it; `caller.ts`'s `folderAccessFor` fails closed to whole-source coverage. CLI: `src/commands/access-rules.ts`; doctor: `src/commands/doctor/checks/folder-access.ts`. Tests: `test/access-folder-rules.test.ts` (database store, both engines), `test/access-folder-rules-git.test.ts`, `test/access-folder-transfer.test.ts`, `test/access-folder-doctor.test.ts`.
+- `src/core/access/` (GBRA-218) — per-member read access inside one source. `principals.ts` normalizes frontmatter `readable_by` (bare id = `member:<id>`, `group:<g>`, ASCII case fold, space trim; anything malformed is `['!nobody']`); it is the row twin of the SQL `gbrain_access_readers()` (`test/access-principals.test.ts` holds them equal). A BEFORE trigger keeps `pages.page_readers` equal to that function (direct writes to the column are recomputed), and predicates test the array, never the function, which costs ~0.2 ms per row. A page that names readers with no derived value yet (written before the migration) reads as nobody until `gbrain repair access` (`repair/access.ts`). `members.ts` (members, groups, tombstoned ids never reused, bindings), `token-binding.ts` (the verifiers' join; a credential bound to a disabled, tombstoned or missing member is refused with `access_member_disabled`) and `caller.ts` (`remoteCallerAccess`: the identity dispatch puts on the caller-access record; stdio binds through `mcp.stdio_member`; publication re-resolves from the stored principal). In `search/private-visibility.ts` every page fragment is `accessAllowedSql` AND the privacy part: plain fragments use the empty identity (over-hide, never leak), `*ForCaller` fragments the caller's, and `GBRAIN_REMOTE_PRIVATE_PAGES`, `search.remote_private_pages` and `granted_sources` relax only the privacy part (`privacyForCaller`). A derivative of a page that names readers is hidden from every remote caller (`originAllowedSql`, which calls the SQL function `gbrain_access_origin_restricted()` only for atom, question, concept, event or `derived_from` rows, so each read plans one call instead of four subplans). Both parts lead with column tests (`page_readers IS NULL`, `type`) so row estimates follow column statistics; an expression test such as `->'readable_by' IS NULL` estimates almost no rows and sent restricted vector searches into nested-loop sequential scans. The index walk's page probe (`INDEX_WALK_PAGE_COLUMNS`) projects `page_readers`. Config `access.restrictions_present` (set by a trigger, sticky) keeps every pre-A1 path on a brain with no restriction. `check:remote-privacy-reads` keeps the two relaxations read only in `private-visibility.ts`. Tests: `test/member-read-access.test.ts` (remote matrix, both engines), `test/access-*.test.ts`. Folder rules (A2) keep whole folders of a source to named members. `folder-rules.ts` is the grammar (`.gbrain/access.yml`: `rules:` of `id`, `prefix`, `readable_by`), `classifyRulebook` (each change is narrowing or widening; the target installs only the narrowing part) and `matchingRuleIds`. `policy.ts` owns the one applied rulebook for both stores: `access_rules` (source-qualified ids), the append-only `access_policy_revisions` log, `access_pending_coverage` (prefixes that read as nobody while a narrowing restamps, or while a committed file is invalid) and `sources.config.access_store`, persisted at the first rule and changed only by `policy-migrate.ts` (journaled in `access_policy_migrations`). `proposeRevision` installs narrowing at once under a per-source row lock and holds widening for `applyApproved` (`plan_hash`, `preview_changed`); `restampSource` rewrites `pages.folder_rule_ids` in id windows, then clears pending coverage under the lock; re-proposing the same rulebook finishes an interrupted restamp. A trigger stamps `folder_rule_ids` from the SQL function `gbrain_access_folder_rules()` on insert and on slug or source change, never from git on the serve path. `policy-git.ts` is the git store (files committed through the commit door, applied by `syncAccessPolicyAt` from sync preflight and the managed drain, read with `git show` at the synced commit); `policy-transfer.ts` carries the applied rulebook through `gbrain export` and installs it before any page in `gbrain import`; `policy-notice.ts` is the `access_policy_pending` degraded notice. In `private-visibility.ts`, `folderRulesAllowedSql` sits inside `accessAllowedSql` (`folder_rule_ids IS NULL OR folder_rule_ids <@ <satisfied ids>` plus coverage conjuncts), so no hatch, grant or `--as` relaxes it, and the unrestricted short form tests `folder_rule_ids IS NULL` next to `page_readers IS NULL` (v275 triggers set `access.restrictions_present` on the first rule or pending prefix); `caller.ts`'s `folderAccessFor` fails closed to whole-source coverage. CLI: `src/commands/access-rules.ts`; doctor: `src/commands/doctor/checks/folder-access.ts`. Tests: `test/access-folder-rules.test.ts` (database store, both engines), `test/access-folder-rules-git.test.ts`, `test/access-folder-transfer.test.ts`, `test/access-folder-doctor.test.ts`.
- `src/core/search/projection-readiness.ts` — one statement probes visible unsealed pages: ready, projection_pending, by_design (protected/archived only) or unknown; LIMIT 1 arms walk the v161 pending index, not pages. Cached per scope by DB generation (page clock, pages filenode, archive flags, no open tx); `GBRAIN_PROJECTION_READINESS_CACHE=0` disables.
diff --git a/src/core/search/private-visibility.ts b/src/core/search/private-visibility.ts
index a9a7c36258..d1f1c2fbd8 100644
--- a/src/core/search/private-visibility.ts
+++ b/src/core/search/private-visibility.ts
@@ -70,7 +70,7 @@ function privacyPartSql(pageAlias: string): string {
* embedded as literals; anything else empties it (fail closed).
*/
export function accessAllowedSql(pageAlias: string, identity: readonly string[], satisfied: readonly string[] = satisfiedFor(identity)): string {
- if (!currentCallerAccess().restricted) return `(${pageAlias}.page_readers IS NULL)`;
+ if (!currentCallerAccess().restricted) return `(${pageAlias}.page_readers IS NULL AND ${pageAlias}.folder_rule_ids IS NULL)`;
return `(${readersAllowedSql(pageAlias, identity)} AND ${folderRulesAllowedSql(pageAlias, satisfied)} AND ${originAllowedSql(pageAlias)})`;
}
@@ -176,12 +176,13 @@ export function privatePagesFilterFragmentFast(pageAlias: string): string {
* access.restrictions_present was unset when the request began. Then no
* page named readers at that moment and none predates the migration (v274
* sets the flag when one does), so every readers value is in the derived
- * column: accessAllowedSql tests only page_readers IS NULL (live, so a page
- * gaining readers mid-request is still hidden, since the trigger fills the
- * column in that write) and skips lineage, member matching and the
- * frontmatter test, whose per-row JSONB read cost keyword search about 3%.
- * The flag is sticky and set in the same transaction as the first page
- * that names readers.
+ * column: accessAllowedSql tests only page_readers IS NULL and
+ * folder_rule_ids IS NULL (live, so a page gaining readers or a folder rule
+ * mid-request is still hidden, since the triggers fill both columns in that
+ * write) and skips lineage, member matching and the frontmatter test, whose
+ * per-row JSONB read cost keyword search about 3%. The flag is sticky and set
+ * in the same transaction as the first page that names readers, the first
+ * member and the first folder rule or pending folder prefix (v275).
* Outside any record (local CLI, jobs, cycles) the identity is empty, no
* source is private-readable and hidePrivate follows the process's hatch
* state, so caller-aware fragments still fail closed on restricted pages.
diff --git a/test/access-folder-fast-path.test.ts b/test/access-folder-fast-path.test.ts
new file mode 100644
index 0000000000..f78c79aaa6
--- /dev/null
+++ b/test/access-folder-fast-path.test.ts
@@ -0,0 +1,64 @@
+/**
+ * GBRA-218 (A2) folder rules on an unrestricted brain. A1's fast path reads a
+ * brain whose access.restrictions_present flag is unset with the short form of
+ * accessAllowedSql. Creating the first folder rule sets the flag in the same
+ * transaction, so the very next remote request hides pages under the prefix;
+ * and with the flag forced back off the short form still hides them, because
+ * it tests the stamped folder_rule_ids column too. Repo-less PGLite, keyless.
+ */
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { importFromContent } from '../src/core/import-file.ts';
+import { mintLegacyToken } from '../src/core/token-mint.ts';
+import { GBrainOAuthProvider } from '../src/core/oauth-provider.ts';
+import { sqlQueryForEngine } from '../src/core/sql-query.ts';
+import { dispatchToolCall } from '../src/mcp/dispatch.ts';
+import { proposeRevision } from '../src/core/access/policy.ts';
+import type { AuthInfo } from '../src/core/ops/contract.ts';
+
+const SRC = 'fold-fast';
+let engine: PGLiteEngine;
+let token = '';
+const page = (title: string, canary: string) => ['---', 'type: note', 'title: ' + title, '---', '# ' + title, '', 'Canary ' + canary + '.'].join('\n');
+const flagSet = async () => (await engine.executeRaw("SELECT 1 FROM config WHERE key = 'access.restrictions_present' AND value = '1'")).length === 1;
+
+async function seen(slug: string, canary: string): Promise<boolean> {
+ const auth = await new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) })
+ .verifyAccessToken(token) as unknown as AuthInfo;
+ const read = async (op: string, params: Record<string, unknown>) => (await dispatchToolCall(engine, op, params, { remote: true, transport: 'http', auth, sourceId: SRC, takesHoldersAllowList: ['world'] }))
+ .content.map(c => c.text).join('\n');
+ return (await read('search', { query: canary, match: 'keyword', fields: 'full' })).includes(canary)
+ || (await read('get_page', { slug })).includes(canary)
+ || (await read('list_pages', { limit: 50 })).includes(slug);
+}
+
+describe('folder rules on an unrestricted brain (pglite, repo-less)', () => {
+ beforeAll(async () => {
+ engine = new PGLiteEngine();
+ await engine.connect({ engine: 'pglite' } as never);
+ await engine.initSchema();
+ await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1)', [SRC]);
+ await importFromContent(engine, 'partners/alice-example/plan', page('Plan', 'foldfastplan'), { sourceId: SRC, noEmbed: true });
+ await importFromContent(engine, 'notes/open', page('Open', 'foldfastopen'), { sourceId: SRC, noEmbed: true });
+ token = (await mintLegacyToken(engine, { name: 'unbound', scopes: ['read'], takesHolders: ['world'], sourceGrant: [SRC] })).token;
+ }, 120_000);
+ afterAll(async () => { await engine.disconnect(); });
+
+ test('the first narrowing rule hides its folder on the next request, and the flag forced off keeps it hidden', async () => {
+ expect(await flagSet()).toBe(false);
+ expect(await seen('partners/alice-example/plan', 'foldfastplan')).toBe(true);
+ await proposeRevision(engine, SRC, [{ id: 'alice', prefix: 'partners/alice-example/', readable_by: ['member:alice-example'] }], { origin: 'cli', store: 'database' });
+ expect(await flagSet()).toBe(true);
+ expect(await seen('partners/alice-example/plan', 'foldfastplan')).toBe(false);
+ expect(await seen('notes/open', 'foldfastopen')).toBe(true);
+ await engine.executeRaw("DELETE FROM config WHERE key = 'access.restrictions_present'");
+ expect(await seen('partners/alice-example/plan', 'foldfastplan')).toBe(false);
+ expect(await seen('notes/open', 'foldfastopen')).toBe(true);
+ }, 120_000);
+
+ test('an invalid policy file on an unrestricted brain sets the flag', async () => {
+ await engine.executeRaw("DELETE FROM config WHERE key = 'access.restrictions_present'");
+ await engine.executeRaw("INSERT INTO access_pending_coverage (source_id, prefix, reason) VALUES ($1, 'hr/', 'invalid')", [SRC]);
+ expect(await flagSet()).toBe(true);
+ }, 60_000);
+});
diff --git a/test/access-unrestricted-fast-path.test.ts b/test/access-unrestricted-fast-path.test.ts
index da83bf826c..7b529bbcff 100644
--- a/test/access-unrestricted-fast-path.test.ts
+++ b/test/access-unrestricted-fast-path.test.ts
@@ -47,7 +47,7 @@ describe('unrestricted fast path (pglite, repo-less)', () => {
const short = withCallerAccess({ restricted: false }, () => accessAllowedSql('p', ['member:alice-example']));
expect(full).toContain('gbrain_access_origin_restricted');
expect(short).not.toContain('gbrain_access_origin_restricted');
- expect(short).toBe('(p.page_readers IS NULL)');
+ expect(short).toBe('(p.page_readers IS NULL AND p.folder_rule_ids IS NULL)');
expect(accessAllowedSql('p', [])).toContain('gbrain_access_origin_restricted');
});