Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
docs(rls): scoped-role recipe covers all ten segmented tables; describe the v275 backfill; behavior row says what scoped roles need (GBRA-95)
garrytand1d196470eba
diff --git a/docs/ENGINES.md b/docs/ENGINES.mdindex 619ab8bbe3..3abe6c1eaf 100644--- a/docs/ENGINES.md+++ b/docs/ENGINES.md@@ -292,8 +292,10 @@ keeps its text in `page_segment_texts`, its layout and headings in`page_body_manifest`, uploads in progress in `page_body_stagings` /`page_body_staging_parts` (with the segment texts each one holds in`page_body_staging_texts`), view sizes in `page_view_digests`, and per-segment-derivation results (link candidates, window anchors) in `page_segment_derivations`.-gbrain enables RLS on all seven on every schema replay, as it does on `pages` and+derivation results (link candidates, window anchors) in `page_segment_derivations`,+with each page's derivation spend in `page_derivation_spend` and derivation purges+in progress in `page_segment_derivation_purges` / `page_segment_derivation_purge_pages`.+gbrain enables RLS on all ten on every schema replay, as it does on `pages` and`content_chunks`, so with no policy a role that does not bypass RLS reads no rowof them. Title search, the source-scoped vector scan, the chunk windows searchreads around its hits, `get_chunks` and get_page check a chunk of a page stored@@ -342,6 +344,17 @@ CREATE POLICY page_segment_derivations_scope_filter ON page_segment_derivationsCREATE POLICY content_chunks_scope_filter ON content_chunksUSING (current_setting('app.scopes', true) = '*'OR EXISTS (SELECT 1 FROM pages p WHERE p.id = page_id));+-- A write role books segmented derivation spend and records derivation purges+-- here; without a policy those writes are refused.+CREATE POLICY page_derivation_spend_scope_filter ON page_derivation_spend+ USING (current_setting('app.scopes', true) = '*'+ OR EXISTS (SELECT 1 FROM pages p WHERE p.id = page_id));+CREATE POLICY page_segment_derivation_purges_scope_filter ON page_segment_derivation_purges+ USING (current_setting('app.scopes', true) = '*'+ OR source_id = ANY(string_to_array(current_setting('app.scopes', true), ',')));+CREATE POLICY page_segment_derivation_purge_pages_scope_filter ON page_segment_derivation_purge_pages+ USING (current_setting('app.scopes', true) = '*'+ OR EXISTS (SELECT 1 FROM page_segment_derivation_purges r WHERE r.request_id = page_segment_derivation_purge_pages.request_id));-- A read role that searches and reads pages. The other tables it reads-- (config, timeline_entries, facts, ...) need policies of their own.@@ -356,6 +369,9 @@ ALTER TABLE page_body_staging_parts FORCE ROW LEVEL SECURITY;ALTER TABLE page_body_staging_texts FORCE ROW LEVEL SECURITY;ALTER TABLE page_view_digests FORCE ROW LEVEL SECURITY;ALTER TABLE page_segment_derivations FORCE ROW LEVEL SECURITY;+ALTER TABLE page_derivation_spend FORCE ROW LEVEL SECURITY;+ALTER TABLE page_segment_derivation_purges FORCE ROW LEVEL SECURITY;+ALTER TABLE page_segment_derivation_purge_pages FORCE ROW LEVEL SECURITY;ALTER TABLE content_chunks FORCE ROW LEVEL SECURITY;```<!-- gbrain:segmented-rls-recipe:end -->@@ -365,7 +381,7 @@ default (`ALTER ROLE <reader-role> SET app.scopes = 'source-a,source-b'`). Thepolicies read `app.scopes` only; the app-layer source filters stay layer 1.A write role that does not own the tables needs `SELECT, INSERT, UPDATE, DELETE`-on all six, as on any table a migration adds, even while no page is segmented:+on all ten, as on any table a migration adds, even while no page is segmented:purging soft-deleted pages, fact withdrawal (`forget_fact`, `purge_fact`), themaintenance sweep's facts pass, doctor's credential check and the segmentstorage sweep name them. Its ordinary writes (`put_page`, `remember`, syncdiff --git a/docs/architecture/key-files/core-persistence-graduation.md b/docs/architecture/key-files/core-persistence-graduation.mdindex 5824f39e32..1b1e9fa280 100644--- a/docs/architecture/key-files/core-persistence-graduation.md+++ b/docs/architecture/key-files/core-persistence-graduation.md@@ -18,5 +18,5 @@ Verified engine graduation, PGLite to Postgres ([operator guide](../../guides/mo- `src/commands/doctor/checks/engine-graduation.ts` — `graduationStateCheck`, emitted from the filesystem lane of `local-audits.ts`: `graduation_interrupted` fails when a manifest or marker is non-terminal with no live owner (fix `gbrain migrate --resume`, rollback named) or a stray brain sits at the old path, is `ok` while a live run owns it, exempts the run named by `GBRAIN_GRADUATION_RUN`, and emits nothing on a brain that never graduated. The retained `.graduated-*` copy is reported by `pglite_leftovers` (`src/core/pglite-leftovers-check.ts`), silent while a manifest is non-terminal.- `src/core/repair/missing-tables.ts` — `gbrain repair missing-tables` (#6911), explicit-only and preview-bound (`--apply --expect <hash>`), brain-wide, DDL only. The preview lists the missing rebuildable caches `readMissingTables` reports (`recreate`), plus `user_data_tables` and `other_tables` residuals it never recreates; the hash covers the brain id, `LATEST_VERSION` and the tables. Apply refuses when the brain schema is newer than the client, leaves a table that already exists alone (`already_present`, no DDL), runs `recreateStep` in one transaction per table under the migration statement and lock timeouts (`schemaLockBlockedError` on a lock timeout), maps 42501 to `schema_owner_required` (approval kept) and 23505/42P07 races to `already_present`, and retires the approved set with the last item. Tests: `test/purge-missing-cache-6911.test.ts`, `test/schema-missing-tables.test.ts`.- `src/core/repair/url-clone-fences.ts` — `gbrain repair url-clone-fences` (#6946, GBRA-130 C-2): explicit-only, preview-bound, destructive consent; unmanaged brains only (a managed brain gets a warning naming `sources mirror-readonly`). The survey lists every tracked file of each owned clone in scope that differs from HEAD (`trackedChanges`) and proves per file (`proveFenceRowsOnly`) that HEAD's fence rows are an unchanged prefix of the working copy's and that re-rendering HEAD with the working fence matches byte for byte (`fence_rows_only`); anything else is listed as `non_fence_edit` / `unparsed_fence` / `staged_change` / `deleted` / `not_in_head` / `unreadable_checkout` and never touched. The preview hash binds the approved set (preview-approval, keyed by the command string). The apply, per file under the source filesystem lock and page lock, rechecks both sides (`changed_since_preview`), backs the file up under `~/.gbrain/backups/url-clone-fences/`, clears `row_num`/`source_markdown_slug` on the appended rows in one `maintenanceTransaction` (inserting database-only any row the database lost), imports HEAD's bytes as the page through `importFromContent`, and only then restores the file from HEAD; each step is idempotent. Test: `test/pathological/c2-url-clone-fences.test.ts`.-- `src/core/schema-missing-tables.ts` — #6911 expected-table check. `readMissingTables`: at head every graduation-inventory table for the engine, below head only the recreatable caches whose creating migration (`CREATED_BY`) already ran, `skipped` (`client_behind`) when the brain is newer; each missing table carries its inventory class and `loss_kind`. `recreateStep` (own-key lookup, rebuild class only) rebuilds `query_cache` (v055 DDL sized from the live `facts.embedding` shape, then the v056/v090/v091 statements) and `code_traversal_cache` (v059). `test/schema-missing-tables.test.ts` pins each recreated table's columns and indexes to the migrated brain's on both engines and checks that every inventory rebuild table is either in `RECREATABLE_TABLES` or defined by the base schema (so `init --migrate-only` recreates it). Doctor `schema_missing_tables` (`src/commands/doctor/checks/schema-health.ts`) renders it: warn for caches (repair preview fix) and tables without user data, fail for `user_data` tables.+- `src/core/schema-missing-tables.ts` — #6911 expected-table check. `readMissingTables`: at head every graduation-inventory table for the engine, below head only the recreatable caches whose creating migration (`CREATED_BY`) already ran, `skipped` (`client_behind`) when the brain is newer; each missing table carries its inventory class and `loss_kind`. `recreateStep` (own-key lookup, rebuild class only) rebuilds `query_cache` (v055 DDL sized from the live `facts.embedding` shape, then the v056/v090/v091 statements) and `code_traversal_cache` (v059), then on Postgres enables RLS on the recreated table through v275's `protectTables` (a role that does not bypass RLS or own the table leaves it RLS-off and names it on stderr). `test/schema-missing-tables.test.ts` pins each recreated table's columns and indexes to the migrated brain's on both engines and checks that every inventory rebuild table is either in `RECREATABLE_TABLES` or defined by the base schema (so `init --migrate-only` recreates it). Doctor `schema_missing_tables` (`src/commands/doctor/checks/schema-health.ts`) renders it: warn for caches (repair preview fix) and tables without user data, fail for `user_data` tables.- `src/core/persistence/rebuildable-cache.ts` — #6911 purge-side skip: `isRebuildableCache` (inventory class `rebuild`), `relationExists` (`to_regclass` on the connection's search path), and `clearRebuildableCache(tx, table)`, which returns the rows deleted or null when the cache table is absent; the existence check runs first because a 42P01 aborts a Postgres transaction. Callers: page purge (`purge.missing_caches`) and fact purge.diff --git a/docs/guides/rls-and-you.md b/docs/guides/rls-and-you.mdindex c205dc291c..7b78af865f 100644--- a/docs/guides/rls-and-you.md+++ b/docs/guides/rls-and-you.md@@ -57,11 +57,23 @@ doesn't carry the `GBRAIN:RLS_EXEMPT` exemption (see below) and enables RLSon each. After the upgrade, `gbrain doctor`'s `rls` check should be a no-opon every brain.+**3. The gbrain-table backfill.** Schema migration v275 enables RLS on every+table gbrain itself creates that is still without it. A gbrain table could+miss RLS when its RLS came only from a full schema replay, which+`gbrain apply-migrations --yes` does not run, or only from the event trigger+above, which needs a superuser and is absent on many managed brains. v275+touches only gbrain's own tables, leaves a table that already has RLS or+carries the `GBRAIN:RLS_EXEMPT` comment alone, and reads or writes no row. It+acts only when the migrating role bypasses RLS and owns the table; otherwise+it names the table on stderr and leaves it, and doctor's `rls` check keeps+naming it.+### Keeping a table RLS-off through the backfillIf you have public tables that are intentionally RLS-off and you want themto stay that way, you MUST add the `GBRAIN:RLS_EXEMPT` comment **before**-migration v35 (the RLS backfill) runs on that brain. The backfill flips RLS on for any+migration v35 (the RLS backfill) runs on that brain (for one of gbrain's own+tables, before v275). The backfill flips RLS on for anypublic table that doesn't carry the exact comment contract documented below.There is no `--dry-run` flag on the migration.diff --git a/llms-full.txt b/llms-full.txtindex 049c149726..a134c186ef 100644--- a/llms-full.txt+++ b/llms-full.txt@@ -5738,8 +5738,10 @@ keeps its text in `page_segment_texts`, its layout and headings in`page_body_manifest`, uploads in progress in `page_body_stagings` /`page_body_staging_parts` (with the segment texts each one holds in`page_body_staging_texts`), view sizes in `page_view_digests`, and per-segment-derivation results (link candidates, window anchors) in `page_segment_derivations`.-gbrain enables RLS on all seven on every schema replay, as it does on `pages` and+derivation results (link candidates, window anchors) in `page_segment_derivations`,+with each page's derivation spend in `page_derivation_spend` and derivation purges+in progress in `page_segment_derivation_purges` / `page_segment_derivation_purge_pages`.+gbrain enables RLS on all ten on every schema replay, as it does on `pages` and`content_chunks`, so with no policy a role that does not bypass RLS reads no rowof them. Title search, the source-scoped vector scan, the chunk windows searchreads around its hits, `get_chunks` and get_page check a chunk of a page stored@@ -5788,6 +5790,17 @@ CREATE POLICY page_segment_derivations_scope_filter ON page_segment_derivationsCREATE POLICY content_chunks_scope_filter ON content_chunksUSING (current_setting('app.scopes', true) = '*'OR EXISTS (SELECT 1 FROM pages p WHERE p.id = page_id));+-- A write role books segmented derivation spend and records derivation purges+-- here; without a policy those writes are refused.+CREATE POLICY page_derivation_spend_scope_filter ON page_derivation_spend+ USING (current_setting('app.scopes', true) = '*'+ OR EXISTS (SELECT 1 FROM pages p WHERE p.id = page_id));+CREATE POLICY page_segment_derivation_purges_scope_filter ON page_segment_derivation_purges+ USING (current_setting('app.scopes', true) = '*'+ OR source_id = ANY(string_to_array(current_setting('app.scopes', true), ',')));+CREATE POLICY page_segment_derivation_purge_pages_scope_filter ON page_segment_derivation_purge_pages+ USING (current_setting('app.scopes', true) = '*'+ OR EXISTS (SELECT 1 FROM page_segment_derivation_purges r WHERE r.request_id = page_segment_derivation_purge_pages.request_id));-- A read role that searches and reads pages. The other tables it reads-- (config, timeline_entries, facts, ...) need policies of their own.@@ -5802,6 +5815,9 @@ ALTER TABLE page_body_staging_parts FORCE ROW LEVEL SECURITY;ALTER TABLE page_body_staging_texts FORCE ROW LEVEL SECURITY;ALTER TABLE page_view_digests FORCE ROW LEVEL SECURITY;ALTER TABLE page_segment_derivations FORCE ROW LEVEL SECURITY;+ALTER TABLE page_derivation_spend FORCE ROW LEVEL SECURITY;+ALTER TABLE page_segment_derivation_purges FORCE ROW LEVEL SECURITY;+ALTER TABLE page_segment_derivation_purge_pages FORCE ROW LEVEL SECURITY;ALTER TABLE content_chunks FORCE ROW LEVEL SECURITY;```<!-- gbrain:segmented-rls-recipe:end -->@@ -5811,7 +5827,7 @@ default (`ALTER ROLE <reader-role> SET app.scopes = 'source-a,source-b'`). Thepolicies read `app.scopes` only; the app-layer source filters stay layer 1.A write role that does not own the tables needs `SELECT, INSERT, UPDATE, DELETE`-on all six, as on any table a migration adds, even while no page is segmented:+on all ten, as on any table a migration adds, even while no page is segmented:purging soft-deleted pages, fact withdrawal (`forget_fact`, `purge_fact`), themaintenance sweep's facts pass, doctor's credential check and the segmentstorage sweep name them. Its ordinary writes (`put_page`, `remember`, syncdiff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex 0ab66b843e..06cdb49a2f 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1303,7 +1303,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;{ since: '0.60.460.0', text: '`gbrain repair duplicate-facts` keeps the copy that is a row of a page\'s `## Facts` table over an older database-only copy of the same fact, so the legacy copy is superseded onto the fence row instead of holding it (which left the legacy row unfenced and its page out of fact reconciliation). With no fenced copy it still keeps the oldest row. It stays preview-first and explicit.' },{ since: '0.60.460.0', text: 'Dream consolidation on a managed brain now closes a fenced fact in its page: the closing `valid_until` is written into the fact\'s row in the entity page\'s `## Facts` fence, published with the take, and the database row takes its value from that cell, so a later sync or re-import keeps the fact closed. Before, only the database row was closed and the next re-import of the page reopened it. A fact with no fence row is still closed in the database. A fenced fact whose fence row is on another page is left open. Facts an earlier release closed in the database only are not changed (GBRA-190).' },// GBRA-95 RLS backfill. `since` is stamped at the merge slot.- { since: '0.60.461.0', id: 'rls_backfill_unguarded_tables', text: 'On Postgres, a schema migration now enables row-level security on every gbrain table still without it. A table could be left without RLS because its RLS came only from a full schema replay, which `gbrain apply-migrations --yes` does not run (the four incremental-derivation tables, `page_segment_derivations`, `page_derivation_spend` and the two purge tables), or only from the auto-RLS event trigger, which needs a superuser and is absent on many managed brains. Supabase gives public tables anon and authenticated grants, so with the Data API on such a table was reachable with the anon key. Only a table still without RLS changes; one with a `GBRAIN:RLS_EXEMPT` comment is left alone; no row is read or written. Under a role that does not bypass RLS or does not own a table, the migration names the table on stderr and leaves it, and `gbrain doctor` (rls) keeps naming it with the fix. `gbrain repair missing-tables` now recreates a cache table with RLS on. A role that neither owns a table nor bypasses RLS reads no rows from it once RLS is on (a read-only reporting role, for example): to keep such access on purpose, add the `GBRAIN:RLS_EXEMPT reason=...` comment to that table before upgrading.' },+ { since: 'TBD', id: 'rls_backfill_unguarded_tables', text: 'On Postgres, a schema migration now enables row-level security on every gbrain table still without it. A table could be left without RLS because its RLS came only from a full schema replay, which `gbrain apply-migrations --yes` does not run (the four incremental-derivation tables, `page_segment_derivations`, `page_derivation_spend` and the two purge tables), or only from the auto-RLS event trigger, which needs a superuser and is absent on many managed brains. Supabase gives public tables anon and authenticated grants, so with the Data API on such a table was reachable with the anon key. Only a table still without RLS changes; one with a `GBRAIN:RLS_EXEMPT` comment is left alone; no row is read or written. Under a role that does not bypass RLS or does not own a table, the migration names the table on stderr and leaves it, and `gbrain doctor` (rls) keeps naming it with the fix. `gbrain repair missing-tables` now recreates a cache table with RLS on. A role that neither owns a table nor bypasses RLS reads no rows from it and cannot insert or update it once RLS is on (a read-only reporting role or a scoped write role, for example): give that role policies before upgrading (docs/ENGINES.md has the source-scope recipe), or, to keep a table open to it on purpose, add the `GBRAIN:RLS_EXEMPT reason=...` comment to that table. A write role set up with an earlier copy of that recipe also needs its new policies on `page_derivation_spend` and the two purge tables: without them its segmented derivation writes are refused, and the derivation purge triggers its writes fire read no purge, so they do not hold back a purged claim.' },];/** The newest disclosed change's release: the notice id moves only when a release adds rows. */