Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Owner's remote agents read private facts in five more operations; Postgres file sizes are numbers; one-command Rust engine dev setup (GST-2951) (#9630)
Garry Tandd2f111a4e17
diff --git a/behavior-changes.d/owner_remote_fact_ops_gst2951.md b/behavior-changes.d/owner_remote_fact_ops_gst2951.mdnew file mode 100644index 0000000000..5d478ea105--- /dev/null+++ b/behavior-changes.d/owner_remote_fact_ops_gst2951.md@@ -0,0 +1,4 @@+---+kind: fix+---+The brain owner's own remote agents (a credential bound to the member gbrain access owner set names, speaking for itself) now read the owner's private facts through find_trajectory, ontology_get, ontology_conflicts and volunteer_chronicle, and get_write_attribution now finds a private fact for the owner's admin credential, as recall, query and think already did. Facts taken from a private page the owner can read come through too. Before, these operations returned only world facts to every remote caller, so a trajectory or ontology built from private facts came back empty for the owner. Every other remote caller reads no private fact it did not read before: another member, a labelled-only member, an unbound token, a call with no credential and the owner's credential speaking for an audience of several still get world facts only, and a private-facts grant still works on find_trajectory only. Page rules still apply to the owner, so a fact taken from a page whose readers leave the owner out stays hidden, withdrawn facts stay out of every read, and ontology from life/diary pages stays redacted for remote callers. Diary observations are now left out before each value resolves, so a newer diary note no longer hides the older value a remote caller may read.diff --git a/changelog.d/dev-rust-engine-bootstrap-fixes.md b/changelog.d/dev-rust-engine-bootstrap-fixes.mdnew file mode 100644index 0000000000..a4723a010a--- /dev/null+++ b/changelog.d/dev-rust-engine-bootstrap-fixes.md@@ -0,0 +1,6 @@+**The Rust engine setup script is safer on shared and already-used machines: each run logs to its own private folder, it ignores `PGHOST`, `PGHOSTADDR` and `PGSERVICE`, and it no longer resets an existing `gbrain` database role.**++### Fixed+- `scripts/dev/rust-engine-bootstrap.sh` now writes each run's step logs to a new private folder, and refuses a `GBRAIN_DEV_LOG_DIR` that another user can write to.+- The script unsets `PGHOST`, `PGHOSTADDR` and `PGSERVICE` for itself, so its database steps always reach the local Postgres 16 cluster.+- The script creates the `gbrain` role only when it is missing. An existing role keeps its password and flags; if it cannot be used, the step fails with a message that names the setting to change.diff --git a/changelog.d/dev-rust-engine-bootstrap.md b/changelog.d/dev-rust-engine-bootstrap.mdnew file mode 100644index 0000000000..cecb9bafe7--- /dev/null+++ b/changelog.d/dev-rust-engine-bootstrap.md@@ -0,0 +1,5 @@+**Contributors working on the Rust engine can now set up an Ubuntu machine with one command: `scripts/dev/rust-engine-bootstrap.sh` installs the pinned Bun, Postgres 16 with pgvector, Rust and the napi-rs CLI, and prints a pass/fail line per step.**++### Added+- `scripts/dev/rust-engine-bootstrap.sh`: a non-interactive, rerunnable dev setup for Ubuntu. It installs the Bun version from `package.json`, starts Postgres 16 with pgvector and a test database, installs the Rust stable toolchain and the napi-rs CLI, runs `bun install`, and writes `~/.gbrain-rust-dev.env`. It does not change gbrain itself.+- `docs/research/rust-engine/dev-environment.md`: how to run the script, what each step does, how to run the engine parity tests, measured timings and known problems.diff --git a/changelog.d/owner-remote-private-facts-gst2951.md b/changelog.d/owner-remote-private-facts-gst2951.mdnew file mode 100644index 0000000000..ca1365a28f--- /dev/null+++ b/changelog.d/owner-remote-private-facts-gst2951.md@@ -0,0 +1,9 @@+**The brain owner's own remote agents now get the owner's private facts from trajectories, ontology reads and write attribution, as they already did from recall, query and think.**++<!-- behavior-change: owner_remote_fact_ops_gst2951 -->++### Fixed+- `find_trajectory`, `ontology_get`, `ontology_conflicts` and `volunteer_chronicle` decided fact visibility from the raw remote flag, so a credential bound to the brain owner got world facts only and a trajectory built from private facts came back empty. They now use the same owner rule as recall and think. `get_write_attribution` finds a private fact for the owner's admin credential the same way.+- The owner also gets facts taken from a private page it can read on the ontology reads and in write attribution, as `find_trajectory` and recall already allowed.+- A newer observation from a diary page no longer hides the older value behind it on `ontology_get` and `volunteer_chronicle`, and no longer makes a false conflict on `ontology_conflicts`. Diary observations are left out before each value resolves, for every remote caller, and still never reach one.+- Nothing widens for anyone else: another member, a labelled-only member, an unbound token, a call with no credential and the owner speaking for an audience of several read no private fact they did not read before. Page rules, member access and source grants still apply to the owner, and withdrawn facts stay out of every read.diff --git a/changelog.d/vorflux-pg-file-size-and-disconnect.md b/changelog.d/vorflux-pg-file-size-and-disconnect.mdnew file mode 100644index 0000000000..5b12fdffbf--- /dev/null+++ b/changelog.d/vorflux-pg-file-size-and-disconnect.md@@ -0,0 +1,5 @@+**On Postgres, file records now report their size as a plain number, and closing the engine a second time no longer runs its shutdown steps again. PGLite already worked this way.**++### Fixed+- On Postgres, `getFile` and `listFilesForPage` returned `size_bytes` as a BigInt. PGLite returned a number, and the declared type is a number. Both engines now return a number. The output of the `gbrain files` CLI and the MCP file operations does not change, because those paths already converted the value.+- On Postgres, a second `disconnect()` of an engine that was already closed ran the registered shutdown hooks again. A second `disconnect()` now does nothing, as on PGLite.diff --git a/docs/architecture/key-files/core-services-1.md b/docs/architecture/key-files/core-services-1.mdindex 85d00eb013..c11b31df91 100644--- a/docs/architecture/key-files/core-services-1.md+++ b/docs/architecture/key-files/core-services-1.md@@ -31,7 +31,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/core/budget/cap-flag.ts` — the one USD cost-cap flag parser (D19): `parseCapFlag(flag, raw, { zero })` returns `{ flag, usd }` (`usd: null` for `off`/`unlimited`/`none`) or throws `CapFlagError`; a bare `0` is refused unless the command declares it (`zero: 'off'` for skillopt's legacy `--max-cost-usd 0`, `'cap'` for eval longmemeval's $0 judge cap); `mergeCapFlag` refuses two disagreeing cap flags; `capNotice` renders the one `cap: $X (source; how to remove)` line. Used by brainstorm/lsd, skillopt, enrich, onboard and eval longmemeval. Pinned by `test/budget/cap-flag.test.ts`.- `src/core/budget/no-pricing.ts` — the one `no_pricing` refusal builder. `noPricingGuidance(model, kind)` returns the structured fields (`code`, `model`, `provider`, `kind`, `units`, `lookup`, `register_command`, `register_scope: 'local_cli'`, `docs` = the `ERROR_CATALOGUE.no_pricing` anchor); `noPricingMessage` renders the one-line cause plus `noPricingSteps` (look up the provider's price, run the `gbrain pricing set` command on the brain host, retry; remote MCP callers ask the operator); `pricingSetCommand` gives the command alone for warnings (chat: `--input`/`--output`, other kinds: `--rate`), rendered from `pricingSetArgv`; `noPricingFix(guidance, transport)` is the agent-contract `fix` for a user-cap refusal (the registration argv with `inputs` for each rate and the pricing page). Used by BudgetTracker, enrich, conversation facts (CLI and cycle phase), skillopt receipts, the embedding migration authorization and the extract-atoms, budget-meter, embed-backfill and conversation-budget warnings. Pinned by `test/budget/no-pricing-registration.test.ts`.-- `src/core/chronicle/{contract,eligibility,config,reasons,ledger,ledger-stats,execute,publish,event-identity,invite-projection,backfill,campaign,job,upgrade-notice,extract-events,proposal-diagnostics,ontology,narrative}.ts` + `src/core/cycle/chronicle.ts` + `src/eval/chronicle/harness.ts` + `src/commands/eval-chronicle.ts` — Life Chronicle: the temporal spine. `contract.ts` holds the ledger columns, the extractor version (part of the ledger key: a bump makes extracted content new to discovery and backfill), the phase bounds and the phase result details. `reasons.ts` is the one reason table (`CHRONICLE_REASONS`: stage, meaning, stored fix Action with argv/preview_argv/consent/actor, never a stored `next`; `auto_chronicle_off` has no fix because it is off by choice) and builds the `chronicle_backstop` receipt field (`{pending:'next_cycle', daily_remaining}` or `{skipped, stage, why, fix}`, omitted for pages that are not chronicle-shaped); `docs/guides/life-chronicle.md` renders its table from it. `eligibility.isChronicleEligible` is the one eligibility function (meeting/conversation/calendar-event + directory rescue; diary and event pages NEVER eligible — privacy + anti-loop); with a time policy it also applies the invite end (`not_yet_happened`), the recency window on the page's own date (an authored `effective_date`, else frontmatter `date`/`start`; a `fallback` date counts as undated) and the settle window. `config.ts` owns the switch and knobs: `autoChronicleSetting` reads `auto_chronicle` as on when unset, on/off for true/false words, and `invalid` (off) for any other word; `chronicleSettings` reads `chronicle.job_budget_usd`/`auto_daily_limit`/`auto_recent_days`/`auto_settle_seconds`/`judge_max_tokens`/`max_events_per_page` (#5329, default 25) with ranges (`CHRONICLE_NUMERIC_KEYS`, enforced by `config set`; a malformed stored row falls back and is listed in `invalid`) and `chronicle.activated_at` (stamped by the first write decision or phase run; earlier revisions are history); `autoChronicleNeedsAcknowledgement` is true while on and `chronicle.default_on_acknowledged` is unset (stamped by `config set auto_chronicle`). The opt-out is `gbrain config set auto_chronicle false` everywhere. `ledger.ts` owns `chronicle_page_state` (one row per source/page/content hash/extractor version: state, reason, trigger, deciding writer and request, `no_extract`, attempts, `next_attempt_at`, cost/unpriced, event slugs and hashes): `recordChronicleDecision` runs inside every coordinated publication that imports a page (from `queuePublicationEffects`), applies the shared writer-confinement predicate, `--no-extract`, the opt-out and eligibility, and puts `chronicle_backstop` on the outcome through `reasons.ts`; `reserveChronicleSlot` is the rolling 24 h reservation under a transaction advisory lock. `ledger-stats.ts` rolls up the ledger and reservations for doctor and the advisor; `readChronicleDuplicateEvents` counts the live events from earlier extraction runs that a page's newest extraction did not produce (doctor `chronicle_duplicate_events`, #8972: info, read-only, counts `pages` and `surplus_events`; the preview-first repair is #9012). `upgrade-notice.ts` is the one-shot post-upgrade notice (`chronicle.default_on_notice_shown`). The global `chronicle` cycle phase (`cycle/chronicle.ts`) supersedes rows whose content is no longer live, discovers pages changed since activation with no row (unmanaged brains decide there; managed ones record `no_write_decision`), and executes settled rows round-robin across sources (≤50 judged items and a wall-time bound per run; automatic rows only while `auto_chronicle` is on, backfill rows always); no chat provider → no calls; the extract_atoms cost gate refuses an explicit cap on an unpriced model. `execute.ts` runs one row: live-content check, time rules, the reservation (automatic rows; attempts count), the judge in a `chronicle:<trigger>` BudgetTracker scope with the per-page cap and an explicit post-call cap check, failure classes (chat_error/budget → failed with backoff, no provider/no_pricing → failed until config changes, refused → skipped, only a parsed `[]` is `no_events`). Before the judge runs (#8972), `execute.ts` hashes the judged input (`extract-events.chronicleJudgedInput`: the window the judge reads, the page's visibility and incarnation, `chronicle.tz` and `chronicle.max_events_per_page`): a revision whose input matches the page's newest extracted generation is `skipped`/`judge_input_unchanged` with no call, so a long page whose tail grew past the window is not paid for again; a generation that dropped future-dated proposals records `cutoffInputHash` (the input plus the cutoff day) instead, so it is judged once more when the cutoff day moves. An automatic row whose input already spent the attempt limit in paid failures is `failed`/`judge_input_failed` with no call (a refused input stays `judge_refused`); only `judge_truncated`, `judge_parse_failed`, `malformed_proposal`, `budget_exhausted` and `judge_refused` count, summed over the page's rows with the same input in `judge_input_failures`, and backfill rows are exempt. A truncated generation (a body longer than the window) with at least one event and no dropped proposal replaces the previous one when its window re-read the text of every live event (`windowCoversLiveEvents`, which fails closed on rows recorded before the window was stored). Migration v297 `chronicle_judge_window` adds `judge_input_hash`, `judge_window_chars`, `judge_window_hash` and `judge_input_failures` (default 0, no backfill) to `chronicle_page_state`. `invite-projection.ts` stands in for the judge on an ended calendar invite (slug under `calendar/`/`cal/` or type `calendar-event`, with a title, `start` and `end`): one `Scheduled: <title>` event (`kind: meeting`, `captured_via: life-chronicle:invite`, not proof of attendance) with no chat call, no daily reservation and zero cost, through the same publication and ledger path. `publish.ts` publishes one generation against the pinned depth snapshot: each event write re-validates the depth revision, content hash, source incarnation, privacy and the deciding writer's grant (events also read as private when their `event.depth` origin is private by field or declared lineage, or missing, `search/private-visibility.ts`) (`managed_maintenance_chronicle_event`/`_retire` intents on managed brains, one transaction per event otherwise), stamps the depth's visibility, never overwrites an operator-edited event (live hash not in the ledger) or resurrects an operator-deleted one, and retires the previous generation's owned events it did not reproduce (`retired_by: life-chronicle`; restored when produced again) only when the caller passes `replaces`: `execute.ts` and `runChronicleExtract` pass it for a complete judged generation (`extract-events.replacesPreviousGeneration`: at least one event, no proposal dropped by the date screen or the per-page cap, and a body no longer than the JUDGE_BODY_CHARS the judge reads, except the `execute.ts` window rule below; a segmented page's truth lead is read one character past it to tell) and for an ineligible revision's empty generation, so an empty or partial generation publishes what it has, retires nothing and still records its ledger outcome (#7013). `event-identity.ts` assigns final slugs before publication: events sharing a base slug `life/events/<day>-<hash8>` (who, what, depth) are told apart by instant, `where` and `kind`; one keeps the base slug and the rest get `-<hash6>` (identical copies `-2`…); assignment reads the pages already at the candidate slugs, so it is order-independent, keeps a page's existing slug across corrections and re-extractions, and a page extracted before disambiguation keeps its base slug. `extract-events.runChronicleExtract` is the direct-caller body over the same snapshot and publication path: deterministic when/who, injectable judge (default = chat gateway; output cap 4000 tokens by default, operator override `chronicle.judge_max_tokens`), an ALL-or-nothing parse barrier (`isValidProposal` requires a real parseable date; a refused batch carries `proposal-diagnostics.diagnoseMalformedProposals`: a fixed code, the schema field and JSON type found, and counts, never a value, from at most 50 proposals, 50 `who` entries and 256 characters per string, on the direct result's `malformed`, the row outcome and the phase's warning line), then `screenChronicleProposals` drops, never writes, each proposal without a day (`date_imprecise`: `when` is a year or month) or dated after the page's own day (`future_dated`: `chronicleEventCutoff` is the latest of the page's own date, a meeting's `end` and a conversation's last parsed message, as a day in `chronicle.tz`, capped at today), then keeps at most `chronicle.max_events_per_page` of the survivors in the judge's order (#5329, the rest `over_cap`, no model call to count); drops are counted in `events_dropped` (phase details, row outcome, direct result) and a page whose every proposal was dropped records the drop reason on its extracted ledger row instead of `no_events`; content-addressed `life/events/` pages + a `timeline_entries` projection. An unusable judge response is never recorded as `no_events`: truncation, unparseable output, a provider error and a refusal surface as `judge_truncated`/`judge_parse_failed`/`judge_chat_error`/`judge_refused`. `backfill.ts` (`chronicle_backfill`) queues `trigger='backfill'` ledger rows, exempt from the daily limit and recency (unless `--recent`), across types and rescue prefixes under one global `--limit`; `--since` is the update date, `--dated-since` the page date; a dry run reports `estimated_usd` and skip reasons; a live run needs `--yes`; content already extracted or queued is never re-queued, even after `gbrain jobs prune`. `--max-usd` (#6199, `campaign.ts`) is a queue-time bound: a page queues only while queued × (per-attempt cap + `chronicleCallCeilingUsd`) × max attempts fits, rows are stamped (`campaign_id`, `attempt_cap_usd`, `max_attempts`, `pricing_policy`, `campaign_max_usd`; migration `chronicle_campaign_stamps`) and `queueCampaignRow` never takes a row another backfill queued or an executor holds; an unpriced model under the cap refuses with `no_pricing`. Executors obey the stamp: `claimChronicleRow` consumes a campaign row's attempt with the lease and refuses it past `max_attempts`, the tracker uses the stamped cap, `finish` sums spend per attempt (`cost_attempts`, so a replay adds nothing) and applies the outcome only while its attempt is the latest (a stale completion is fenced), and `failExhaustedCampaignRows` fails a crashed row whose attempts are spent as `campaign_exhausted`; any other ledger write clears the stamp. `job.ts` drains `chronicle_extract` jobs from older releases through the same executor. `ontology.ts` carries the deterministic pieces of the bi-temporal per-entity ontology that RIDES THE `facts` TABLE (migration v122 adds `dimension`/`value`/`value_hash`/`dim_status`): `valueHash` (normalized, timestamp-free; the v188 dedup index adds the stint's `valid_from`, so a crash-retry conflicts while a same-provenance return to an earlier value records a new interval), `normalizeDimension` (seed alias lexicon), `isNovelDimension` (novel → quarantined, excluded from resolution/context until confirmed). The engine methods (`mergeOntologyFact` — corroborate on same value (noop when the same provenance already observed it during the current stint), forward-supersede via `valid_until`+`superseded_by` on a new value, backdated conflicts kept + flagged; `getOntology` with `--asof` valid-time travel; `discoverOntologyDimensions`; `findOntologyConflicts` — currently-open rows only) live in BOTH engines; both engines are on the R8 `valid_until` write allow-list (engine-layer, `dimension IS NOT NULL` rows only). Chronicle reads (`getTimelineForDate`/`getSince`/`getLastSeen`/`getOnThisDay`) JOIN the depth page (`deleted_at IS NULL`), hide soft-deleted event projections at READ time, and order by event `effective_date` for intra-day sequence. Ops: `chronicle_day`/`chronicle_since`/`chronicle_last_seen`/`chronicle_on_this_day`/`ontology_*`/`volunteer_chronicle` (agent orientation via `src/core/context/chronicle-context.ts`)/`chronicle_backfill` (admin, localOnly). Diary privacy: fail-closed for `ctx.remote !== false` callers — diary-sourced ontology + conflict values are redacted, the four timeline read ops (`chronicle_day`/`chronicle_since`/`chronicle_on_this_day` + `volunteer_chronicle`'s `recent_timeline`) drop rows whose depth page, event page, or `source` provenance lives under `life/diary/`, and `chronicle_last_seen` answers the never-seen shape (`last_date`/`last_event_slug`/`days_ago` all null) when the latest sighting is diary-sourced or a diary page is queried as the entity. Remote callers read only `visibility = 'world'` observations, like recall: `getOntology`/`findOntologyConflicts` take a `visibility` filter applied before resolution and the conflict HAVING. `ontology_propose` commits through `coordinatedDatabaseWrite` on a managed brain. Page visibility rides the same policy: `ontology_get`/`ontology_conflicts`/`volunteer_chronicle`'s ontologies resolve through `readPolicyOpts`, and both engines' `getOntology`/`findOntologyConflicts` apply `privateProvenanceFilterFragment` (an observation whose provenance page, looked up in the fact's own source, is `visibility: private` is dropped BEFORE per-dimension resolution and before the conflict HAVING, so an untrusted caller resolves the newest value they may see rather than a private value or a hole). The chronicle reads' event-page LEFT JOIN carries the caller's source scope in BOTH engines, so a scoped read can't surface another source's event pages through the join. Search: `applyChronicleTypeBoost` in `search/hybrid.ts` (bounded [1.0,1.25], fires only inside the `recency !== 'off'` post-fusion branch → non-temporal search bit-for-bit unchanged). Advisor collector `collect-chronicle.ts` (conflicts; coverage gap with a scoped `chronicle-backfill --since <date> --limit 50 --dry-run`; `auto_chronicle_default_on` ask_user until acknowledged; `auto_chronicle_invalid`; `chronicle_chat_unavailable`; `chronicle_extraction_failing`; `chronicle_daily_limit`); doctor `chronicle_projection_health` and `auto_chronicle` (`checks/auto-chronicle.ts`; BRAIN category). Eval: `gbrain eval chronicle` — deterministic, own in-memory PGLite, 6 gold tasks (day order, last-seen, supersession, asof, conflict, isolation), exit 0 iff 6/6. Tests: `test/chronicle-*.test.ts` (automatic path: `chronicle-auto-{decision,phase,unmanaged}`, `chronicle-date-quality`, `chronicle-event-privacy`, `chronicle-event-identity`, `chronicle-invite-projection`, `chronicle-backfill`, `chronicle-backfill-max-usd`, `chronicle-reasons-5876`, `chronicle-max-events-5329`, `chronicle-long-conversation-8972`; Postgres arms in `test/e2e/chronicle-*-postgres.test.ts`), `test/eval-chronicle.test.ts`, `test/auto-chronicle-surfaces-5876.test.ts`.+- `src/core/chronicle/{contract,eligibility,config,reasons,ledger,ledger-stats,execute,publish,event-identity,invite-projection,backfill,campaign,job,upgrade-notice,extract-events,proposal-diagnostics,ontology,narrative}.ts` + `src/core/cycle/chronicle.ts` + `src/eval/chronicle/harness.ts` + `src/commands/eval-chronicle.ts` — Life Chronicle: the temporal spine. `contract.ts` holds the ledger columns, the extractor version (part of the ledger key: a bump makes extracted content new to discovery and backfill), the phase bounds and the phase result details. `reasons.ts` is the one reason table (`CHRONICLE_REASONS`: stage, meaning, stored fix Action with argv/preview_argv/consent/actor, never a stored `next`; `auto_chronicle_off` has no fix because it is off by choice) and builds the `chronicle_backstop` receipt field (`{pending:'next_cycle', daily_remaining}` or `{skipped, stage, why, fix}`, omitted for pages that are not chronicle-shaped); `docs/guides/life-chronicle.md` renders its table from it. `eligibility.isChronicleEligible` is the one eligibility function (meeting/conversation/calendar-event + directory rescue; diary and event pages NEVER eligible — privacy + anti-loop); with a time policy it also applies the invite end (`not_yet_happened`), the recency window on the page's own date (an authored `effective_date`, else frontmatter `date`/`start`; a `fallback` date counts as undated) and the settle window. `config.ts` owns the switch and knobs: `autoChronicleSetting` reads `auto_chronicle` as on when unset, on/off for true/false words, and `invalid` (off) for any other word; `chronicleSettings` reads `chronicle.job_budget_usd`/`auto_daily_limit`/`auto_recent_days`/`auto_settle_seconds`/`judge_max_tokens`/`max_events_per_page` (#5329, default 25) with ranges (`CHRONICLE_NUMERIC_KEYS`, enforced by `config set`; a malformed stored row falls back and is listed in `invalid`) and `chronicle.activated_at` (stamped by the first write decision or phase run; earlier revisions are history); `autoChronicleNeedsAcknowledgement` is true while on and `chronicle.default_on_acknowledged` is unset (stamped by `config set auto_chronicle`). The opt-out is `gbrain config set auto_chronicle false` everywhere. `ledger.ts` owns `chronicle_page_state` (one row per source/page/content hash/extractor version: state, reason, trigger, deciding writer and request, `no_extract`, attempts, `next_attempt_at`, cost/unpriced, event slugs and hashes): `recordChronicleDecision` runs inside every coordinated publication that imports a page (from `queuePublicationEffects`), applies the shared writer-confinement predicate, `--no-extract`, the opt-out and eligibility, and puts `chronicle_backstop` on the outcome through `reasons.ts`; `reserveChronicleSlot` is the rolling 24 h reservation under a transaction advisory lock. `ledger-stats.ts` rolls up the ledger and reservations for doctor and the advisor; `readChronicleDuplicateEvents` counts the live events from earlier extraction runs that a page's newest extraction did not produce (doctor `chronicle_duplicate_events`, #8972: info, read-only, counts `pages` and `surplus_events`; the preview-first repair is #9012). `upgrade-notice.ts` is the one-shot post-upgrade notice (`chronicle.default_on_notice_shown`). The global `chronicle` cycle phase (`cycle/chronicle.ts`) supersedes rows whose content is no longer live, discovers pages changed since activation with no row (unmanaged brains decide there; managed ones record `no_write_decision`), and executes settled rows round-robin across sources (≤50 judged items and a wall-time bound per run; automatic rows only while `auto_chronicle` is on, backfill rows always); no chat provider → no calls; the extract_atoms cost gate refuses an explicit cap on an unpriced model. `execute.ts` runs one row: live-content check, time rules, the reservation (automatic rows; attempts count), the judge in a `chronicle:<trigger>` BudgetTracker scope with the per-page cap and an explicit post-call cap check, failure classes (chat_error/budget → failed with backoff, no provider/no_pricing → failed until config changes, refused → skipped, only a parsed `[]` is `no_events`). Before the judge runs (#8972), `execute.ts` hashes the judged input (`extract-events.chronicleJudgedInput`: the window the judge reads, the page's visibility and incarnation, `chronicle.tz` and `chronicle.max_events_per_page`): a revision whose input matches the page's newest extracted generation is `skipped`/`judge_input_unchanged` with no call, so a long page whose tail grew past the window is not paid for again; a generation that dropped future-dated proposals records `cutoffInputHash` (the input plus the cutoff day) instead, so it is judged once more when the cutoff day moves. An automatic row whose input already spent the attempt limit in paid failures is `failed`/`judge_input_failed` with no call (a refused input stays `judge_refused`); only `judge_truncated`, `judge_parse_failed`, `malformed_proposal`, `budget_exhausted` and `judge_refused` count, summed over the page's rows with the same input in `judge_input_failures`, and backfill rows are exempt. A truncated generation (a body longer than the window) with at least one event and no dropped proposal replaces the previous one when its window re-read the text of every live event (`windowCoversLiveEvents`, which fails closed on rows recorded before the window was stored). Migration v297 `chronicle_judge_window` adds `judge_input_hash`, `judge_window_chars`, `judge_window_hash` and `judge_input_failures` (default 0, no backfill) to `chronicle_page_state`. `invite-projection.ts` stands in for the judge on an ended calendar invite (slug under `calendar/`/`cal/` or type `calendar-event`, with a title, `start` and `end`): one `Scheduled: <title>` event (`kind: meeting`, `captured_via: life-chronicle:invite`, not proof of attendance) with no chat call, no daily reservation and zero cost, through the same publication and ledger path. `publish.ts` publishes one generation against the pinned depth snapshot: each event write re-validates the depth revision, content hash, source incarnation, privacy and the deciding writer's grant (events also read as private when their `event.depth` origin is private by field or declared lineage, or missing, `search/private-visibility.ts`) (`managed_maintenance_chronicle_event`/`_retire` intents on managed brains, one transaction per event otherwise), stamps the depth's visibility, never overwrites an operator-edited event (live hash not in the ledger) or resurrects an operator-deleted one, and retires the previous generation's owned events it did not reproduce (`retired_by: life-chronicle`; restored when produced again) only when the caller passes `replaces`: `execute.ts` and `runChronicleExtract` pass it for a complete judged generation (`extract-events.replacesPreviousGeneration`: at least one event, no proposal dropped by the date screen or the per-page cap, and a body no longer than the JUDGE_BODY_CHARS the judge reads, except the `execute.ts` window rule below; a segmented page's truth lead is read one character past it to tell) and for an ineligible revision's empty generation, so an empty or partial generation publishes what it has, retires nothing and still records its ledger outcome (#7013). `event-identity.ts` assigns final slugs before publication: events sharing a base slug `life/events/<day>-<hash8>` (who, what, depth) are told apart by instant, `where` and `kind`; one keeps the base slug and the rest get `-<hash6>` (identical copies `-2`…); assignment reads the pages already at the candidate slugs, so it is order-independent, keeps a page's existing slug across corrections and re-extractions, and a page extracted before disambiguation keeps its base slug. `extract-events.runChronicleExtract` is the direct-caller body over the same snapshot and publication path: deterministic when/who, injectable judge (default = chat gateway; output cap 4000 tokens by default, operator override `chronicle.judge_max_tokens`), an ALL-or-nothing parse barrier (`isValidProposal` requires a real parseable date; a refused batch carries `proposal-diagnostics.diagnoseMalformedProposals`: a fixed code, the schema field and JSON type found, and counts, never a value, from at most 50 proposals, 50 `who` entries and 256 characters per string, on the direct result's `malformed`, the row outcome and the phase's warning line), then `screenChronicleProposals` drops, never writes, each proposal without a day (`date_imprecise`: `when` is a year or month) or dated after the page's own day (`future_dated`: `chronicleEventCutoff` is the latest of the page's own date, a meeting's `end` and a conversation's last parsed message, as a day in `chronicle.tz`, capped at today), then keeps at most `chronicle.max_events_per_page` of the survivors in the judge's order (#5329, the rest `over_cap`, no model call to count); drops are counted in `events_dropped` (phase details, row outcome, direct result) and a page whose every proposal was dropped records the drop reason on its extracted ledger row instead of `no_events`; content-addressed `life/events/` pages + a `timeline_entries` projection. An unusable judge response is never recorded as `no_events`: truncation, unparseable output, a provider error and a refusal surface as `judge_truncated`/`judge_parse_failed`/`judge_chat_error`/`judge_refused`. `backfill.ts` (`chronicle_backfill`) queues `trigger='backfill'` ledger rows, exempt from the daily limit and recency (unless `--recent`), across types and rescue prefixes under one global `--limit`; `--since` is the update date, `--dated-since` the page date; a dry run reports `estimated_usd` and skip reasons; a live run needs `--yes`; content already extracted or queued is never re-queued, even after `gbrain jobs prune`. `--max-usd` (#6199, `campaign.ts`) is a queue-time bound: a page queues only while queued × (per-attempt cap + `chronicleCallCeilingUsd`) × max attempts fits, rows are stamped (`campaign_id`, `attempt_cap_usd`, `max_attempts`, `pricing_policy`, `campaign_max_usd`; migration `chronicle_campaign_stamps`) and `queueCampaignRow` never takes a row another backfill queued or an executor holds; an unpriced model under the cap refuses with `no_pricing`. Executors obey the stamp: `claimChronicleRow` consumes a campaign row's attempt with the lease and refuses it past `max_attempts`, the tracker uses the stamped cap, `finish` sums spend per attempt (`cost_attempts`, so a replay adds nothing) and applies the outcome only while its attempt is the latest (a stale completion is fenced), and `failExhaustedCampaignRows` fails a crashed row whose attempts are spent as `campaign_exhausted`; any other ledger write clears the stamp. `job.ts` drains `chronicle_extract` jobs from older releases through the same executor. `ontology.ts` carries the deterministic pieces of the bi-temporal per-entity ontology that RIDES THE `facts` TABLE (migration v122 adds `dimension`/`value`/`value_hash`/`dim_status`): `valueHash` (normalized, timestamp-free; the v188 dedup index adds the stint's `valid_from`, so a crash-retry conflicts while a same-provenance return to an earlier value records a new interval), `normalizeDimension` (seed alias lexicon), `isNovelDimension` (novel → quarantined, excluded from resolution/context until confirmed). The engine methods (`mergeOntologyFact` — corroborate on same value (noop when the same provenance already observed it during the current stint), forward-supersede via `valid_until`+`superseded_by` on a new value, backdated conflicts kept + flagged; `getOntology` with `--asof` valid-time travel; `discoverOntologyDimensions`; `findOntologyConflicts` — currently-open rows only) live in BOTH engines; both engines are on the R8 `valid_until` write allow-list (engine-layer, `dimension IS NOT NULL` rows only). Chronicle reads (`getTimelineForDate`/`getSince`/`getLastSeen`/`getOnThisDay`) JOIN the depth page (`deleted_at IS NULL`), hide soft-deleted event projections at READ time, and order by event `effective_date` for intra-day sequence. Ops: `chronicle_day`/`chronicle_since`/`chronicle_last_seen`/`chronicle_on_this_day`/`ontology_*`/`volunteer_chronicle` (agent orientation via `src/core/context/chronicle-context.ts`)/`chronicle_backfill` (admin, localOnly). Diary privacy: fail-closed for `ctx.remote !== false` callers — diary-sourced ontology + conflict values are redacted, the four timeline read ops (`chronicle_day`/`chronicle_since`/`chronicle_on_this_day` + `volunteer_chronicle`'s `recent_timeline`) drop rows whose depth page, event page, or `source` provenance lives under `life/diary/`, and `chronicle_last_seen` answers the never-seen shape (`last_date`/`last_event_slug`/`days_ago` all null) when the latest sighting is diary-sourced or a diary page is queried as the entity. Remote callers other than the brain owner read only `visibility = 'world'` observations, like recall (`worldOnlyFacts`, GST-2951): `getOntology`/`findOntologyConflicts` take a `visibility` filter applied before resolution and the conflict HAVING, plus `excludeDiary` (set for every remote caller), which drops `life/diary/` observations before each dimension resolves so a newer diary note cannot hide the older readable value or make a false conflict. `ontology_propose` commits through `coordinatedDatabaseWrite` on a managed brain. Page visibility rides the same policy: `ontology_get`/`ontology_conflicts`/`volunteer_chronicle`'s ontologies resolve through `readPolicyOpts`, and both engines' `getOntology`/`findOntologyConflicts` apply `privateProvenanceFilterFragment` (an observation whose provenance page, looked up in the fact's own source, is `visibility: private` is dropped BEFORE per-dimension resolution and before the conflict HAVING, so an untrusted caller resolves the newest value they may see rather than a private value or a hole). The chronicle reads' event-page LEFT JOIN carries the caller's source scope in BOTH engines, so a scoped read can't surface another source's event pages through the join. Search: `applyChronicleTypeBoost` in `search/hybrid.ts` (bounded [1.0,1.25], fires only inside the `recency !== 'off'` post-fusion branch → non-temporal search bit-for-bit unchanged). Advisor collector `collect-chronicle.ts` (conflicts; coverage gap with a scoped `chronicle-backfill --since <date> --limit 50 --dry-run`; `auto_chronicle_default_on` ask_user until acknowledged; `auto_chronicle_invalid`; `chronicle_chat_unavailable`; `chronicle_extraction_failing`; `chronicle_daily_limit`); doctor `chronicle_projection_health` and `auto_chronicle` (`checks/auto-chronicle.ts`; BRAIN category). Eval: `gbrain eval chronicle` — deterministic, own in-memory PGLite, 6 gold tasks (day order, last-seen, supersession, asof, conflict, isolation), exit 0 iff 6/6. Tests: `test/chronicle-*.test.ts` (automatic path: `chronicle-auto-{decision,phase,unmanaged}`, `chronicle-date-quality`, `chronicle-event-privacy`, `chronicle-event-identity`, `chronicle-invite-projection`, `chronicle-backfill`, `chronicle-backfill-max-usd`, `chronicle-reasons-5876`, `chronicle-max-events-5329`, `chronicle-long-conversation-8972`; Postgres arms in `test/e2e/chronicle-*-postgres.test.ts`), `test/eval-chronicle.test.ts`, `test/auto-chronicle-surfaces-5876.test.ts`.- `src/core/chunkers/` — markdown chunking (`recursive.ts`) and code chunking. `code.ts` is a tree-sitter-based semantic chunker for 30 languages (plus SQL via DerekStride/tree-sitter-sql) with embedded-asset WASMs (`src/assets/wasm/`), `@dqbd/tiktoken` cl100k_base tokenizer, small-sibling merging. `CHUNKER_VERSION` is folded into `importCodeFile`'s `content_hash` so chunker shape changes force clean re-chunks across releases; `GRAMMAR_REVISIONS` (per-language chunker revisions: `lua: 1` after the tree-sitter-grammars v0.3.0 swap that ended the `gbrain serve` Lua-fence hang; `typescript`/`tsx`/`javascript`/`python`/`ruby: 2` for the #5001 `__module__` chunks; `elixir: 1` for #7080) folds into that language's hash only, and `chunkerStamp()` (`8;lua=1;typescript=2;…`) is the `sources.chunker_version` gate value every sync path reads and writes, so a per-language change walks each source once and re-imports only that language's files while the cost gate (`grammarOnlyDrift`, `grammar_drift`) prices those files alone. Top-level statements that contain a call (`describe(...)`, `app.use(...)`, `print(f())`, Ruby `RSpec.describe ... do`) are chunked through `code-module-chunks.ts` (below) so their call edges have a chunk to hang on. Grammar provenance and the vendoring scripts: `src/assets/wasm/README.md`; pinned by `test/chunkers/code-lua.test.ts`. `extractSymbolName` has an inline SQL branch (`extractSqlSymbolName`) diving through DerekStride's `statement` wrapper into the inner DDL child (`create_table`/`create_function`/`create_view`/`create_index`/`create_procedure`/`create_type`/`create_schema`/`create_database`/`create_trigger`/`alter_table`/`alter_view`) and extracting the target identifier via the `name` field with identifier-shaped fallback; DML kinds (`select`/`insert`/`update`/`delete`/`merge`/`with`) deliberately return null so chunks emit unnamed (code-def is a DDL signal). `normalizeSymbolType` has parallel SQL branches mapping `create_table → 'table'`, `create_view → 'view'`, etc. `DEF_TYPES` (owned by `src/core/chunkers/def-types.ts`, re-exported by `src/commands/code-def.ts` — see that entry) carries the SQL kinds (`'table' | 'view' | 'index' | 'procedure' | 'schema' | 'database' | 'trigger'`) so the new chunks surface in `gbrain code-def <name>` queries.diff --git a/docs/architecture/key-files/core-services-2.md b/docs/architecture/key-files/core-services-2.mdindex e2b579825c..3dc4cb950d 100644--- a/docs/architecture/key-files/core-services-2.md+++ b/docs/architecture/key-files/core-services-2.md@@ -30,7 +30,7 @@ Fact and page purge modules (`src/core/facts/purge*.ts`, `deletion-inventory.ts`- `src/core/ops/read-paging.ts` — paging for the two by-slug row reads that would otherwise return everything: `get_chunks` (`chunks.ts`: `from_index` default 0, `limit` default 50, MCP cap 500; the engine's `getChunkPage` returns the chunk_index range [from_index, from_index + limit) plus `total_chunks` and the highest index) and `get_versions` (`admin.ts`: default 20, MCP cap 100). Both keep a bare-array result; `pagingLimit` resolves the limit (trusted local CLI honors any explicit value; a non-positive-integer is `invalid_params`), and `reportChunkPage` / `reportVersionPage` emit `_meta.pagination` (`from_index`, `limit`, `returned`, `total_chunks`, `next_from_index` / `limit`, `truncated`, `clamped_from`), the model-visible `listing_truncated` notice for remote callers when rows remain (its fix is the next call), and one stderr line for a local call with no limit. Tests: `test/get-chunks-paging.test.ts`, `test/get-versions-defaults.test.ts`.- `src/core/ops/admin.ts` — the admin/diagnostics domain module (`get_stats`, `get_health`, `get_brain_identity`, …). `get_health` adds `embedding_column`, the registry-active vector column its coverage counts were measured on (legacy `embedding` when the registry is unreadable), on both engines (`test/get-health-embedding-column.test.ts` + its Postgres arm). `get_versions` reads an explicit column list (`PAGE_VERSION_COLUMNS` in `engine-sql/pages.ts`), so the write attribution columns never reach a plain `read` caller; trusted local callers and `admin` holders (`canReadWriteAttribution`) also get `written_by` and `archived_by` from `attributeVersions`. It filters protected facts/takes from both canonical body and timeline, preserves legacy missing timeline fields, and retains engine-side current/historical page privacy predicates for every snapshot field. By default it returns metadata only (no `compiled_truth`/`timeline`) for the newest 20 versions; `include_body: true` adds the bodies (remote-sanitized), and `limit` (a positive safe integer; any other explicit value is `invalid_params` without echoing it) takes the newest N, capped at 100 for every caller but the trusted local CLI. The handler probes one row past the limit and reports a cut history through `read-paging.ts`. The bound and the projection run in `engine-sql/pages.ts` `getVersions` (one query, scope and privacy predicates in WHERE before `LIMIT`, `ORDER BY pv.snapshot_at DESC, pv.id DESC`, metadata mode selects no body columns, typed `PageVersionRows`), so hidden versions never shift the prefix; trusted and admin callers keep `written_by`/`archived_by` (`test/get-versions-response-bounds.test.ts`). All three aggregate ops confine remote callers via the same ladder reads use: `ctx.remote === false` keeps the trusted brain-wide view; every other caller gets `sourceScopeOpts(ctx)` (federated array > scalar > the unmatchable `__all__` sentinel, which fail-closes to zeros) threaded into `engine.getStats(scope)`/`getHealth(scope)` — aggregates leak by subtraction, so they scope exactly like reads, and read-scope `get_brain_identity` is confined the same way. `get_health`'s `migrations {pending, pending_fresh_install, partial, wedged, declined, skipped_future}` block (`declined` since #6466: versions the brain's config turns off, read through `declinedMigrations(engine)`) stays GLOBAL for scoped callers by decision: it is a host filesystem ledger with no per-source semantics, a wedged host migration is exactly what a remote agent needs to see to explain degraded behavior, and it is composed at the op layer (not in `BrainEngine.getHealth` — growing the engine interface would force both engines to duplicate a file read). `get_health` serves repeat calls from `src/core/health-memo.ts` and returns `computed_at`, the time its counters were read.-- `src/core/ops/attribution.ts` — write attribution reads (Foundations 1, F1b). `resolveWriteAttributions` turns stored (request id, principal kind, principal id) snapshots into `WriteAttributionView`s (`types.ts`), joining `persistence_requests` (operation, `completed_at`, `agent_label`), `oauth_clients.client_name`, `access_tokens.name` and the `persistence_local_writers` lane at read time, one query each; `origin` is `request`, `maintenance` (principal without request) or `unrecorded` (all NULL). `get_write_attribution` (scope `admin`, `localOnly: false`, CLI `gbrain attribution <slug> [--fact <id>] [--take <row>] [--timeline <id>] [--versions]`) returns `{ target, created, last, live_revision, versions? }`; a page's `created` is the origin of its oldest version snapshot. The page lookup uses `readPolicyOpts`, so remote admins stay inside their source grant; remote fact targets are `world` only and take targets follow `readHolders`. Tests: `test/write-attribution-read.test.ts` (PGLite) and `test/e2e/write-attribution-read-parity.test.ts` (Postgres and PgBouncer).+- `src/core/ops/attribution.ts` — write attribution reads (Foundations 1, F1b). `resolveWriteAttributions` turns stored (request id, principal kind, principal id) snapshots into `WriteAttributionView`s (`types.ts`), joining `persistence_requests` (operation, `completed_at`, `agent_label`), `oauth_clients.client_name`, `access_tokens.name` and the `persistence_local_writers` lane at read time, one query each; `origin` is `request`, `maintenance` (principal without request) or `unrecorded` (all NULL). `get_write_attribution` (scope `admin`, `localOnly: false`, CLI `gbrain attribution <slug> [--fact <id>] [--take <row>] [--timeline <id>] [--versions]`) returns `{ target, created, last, live_revision, versions? }`; a page's `created` is the origin of its oldest version snapshot. The page lookup uses `readPolicyOpts`, so remote admins stay inside their source grant; remote fact targets are `world` only except for a credential bound to the brain owner (`worldOnlyFacts`, GST-2951), and take targets follow `readHolders`. Tests: `test/write-attribution-read.test.ts` (PGLite), `test/access-owner-fact-ops-gst2951.test.ts` (owner reads, both engines) and `test/e2e/write-attribution-read-parity.test.ts` (Postgres and PgBouncer).- `src/core/ops/trust.ts` — `confirm_memory` (#5575 A4, CEO-9, DX-20): the one MCP-visible owner action. Raises a fact, take or page to `user_confirmed` through `trust/owner-actions.ts` after `requireOwnerConfirmation` (a `memory_confirm` connection, or the local CLI's typed-token TTY prompt); agent tokens get `insufficient_scope` with a `tell_user_to_run` fix naming `gbrain trust confirm <ref>`. Trust proposals and holds are not reachable here; the other owner actions are CLI or resident-owner administration only (`trust/owner-ipc.ts`). It also holds `promote_guest_note` (GBRA-504), whose logic is `guests/promote.ts`.- `src/core/guests/{promote,owner-credentials}.ts`, `src/commands/doctor/checks/guest-source.ts` — GBRA-504 slice 4. `promote.ts` is `promote_guest_note` (CLI `gbrain guests promote`): `isGuestPromotionOwner` admits the trusted local CLI (not under `GBRAIN_ENFORCED_MEMBER`, not `--as`) and a remote or stdio caller whose `CallerAccess.owner` is set with no attested actor, anyone else is `guest_promotion_owner_only`; it writes the owner page with `submitPageMutation` put_page (git first where the target has a repo), carrying the note's type, title, body and `readable_by` plus `promoted_from: <guest source>:<slug>`, then inserts `guest_promotions`, which `marker.ts` `loadGuestMarks` reads as `guest.promoted` and `admission.ts` `refuseRemoteGuestDelete` reads to refuse a remote delete `guest_page_promoted`; it also refuses `permission_denied` when the note's guest mark names a writer other than the caller (both at submission in `page-mutations.ts`, again in the delete's publication in `page-prepare.ts`). `owner-credentials.ts` lists tokens and OAuth clients bound to `access.owner_member` with their read lists, the exact `gbrain auth rescope ... --if-version` command and whether `min_trust` hides guest notes; `grantOwnerCredentials` (`gbrain guests grant-owner-clients --yes`) adds the guest source as a compare-and-set on the grant revision. The doctor check `guest_source` reads both and changes nothing. Tests: `test/guest-notes-promotion.test.ts`, `test/doctor-guest-source.test.ts`, `test/guests-grant-owner-clients.test.ts`.diff --git a/docs/research/rust-engine/dev-environment.md b/docs/research/rust-engine/dev-environment.mdnew file mode 100644index 0000000000..e98cd32657--- /dev/null+++ b/docs/research/rust-engine/dev-environment.md@@ -0,0 +1,126 @@+# Rust engine: dev machine setup++One script sets up an Ubuntu machine for Rust engine parity work: the right+Bun, a local Postgres with pgvector, the Rust toolchain and the napi-rs CLI.+It serves the Rust engine plan (`docs/designs/RUST_ENGINE.md`, proposed in+https://github.com/garrytan/gbrain/pull/9593 and not yet merged).++## Run it++From the repository root:++```bash+bash scripts/dev/rust-engine-bootstrap.sh && . ~/.gbrain-rust-dev.env+```++It needs Ubuntu and root or passwordless sudo. It never prompts. Run it again+at any time: it skips what is already there, and after a machine restart it+only starts Postgres again. It ends with one line per step and+`RESULT: PASS` or `RESULT: FAIL`. Each run writes every step's full output to+a new private folder, `~/.gbrain-rust-dev/logs/run-<time>-<random>/<step>.log`,+and prints that folder's path first. Old run folders stay until you delete them.++The script ignores `PGHOST`, `PGHOSTADDR` and `PGSERVICE` (it unsets them for+itself), so it always works on the local `16/main` cluster.++## What it does++| Step | What happens |+|---|---|+| `preflight` | Checks for Ubuntu and sudo. Installs `ca-certificates`, `curl`, `unzip`, `git`, `pkg-config`, `python3`, `procps` and a C compiler if they are missing. The e2e wrapper needs `python3` and `pgrep`. |+| `bun` | Installs the Bun version in `package.json` `engines.bun` (1.4.4 today) into `~/.bun`, and links `bun` and `bunx` into `/usr/local/bin`, so it wins over an older system Bun in every shell. |+| `postgres` | Installs `postgresql-16` and `postgresql-16-pgvector` from the PostgreSQL apt archive if they are missing. `pg_trgm` and `pgcrypto` come with the server. |+| `pg-start` | Creates the `16/main` cluster if there is none and starts it. It uses `pg_ctlcluster`, so it works without systemd. |+| `pg-database` | Creates the role `gbrain` (password `gbrain`, superuser) if it does not exist, and the database `gbrain_test`, and enables `vector`, `pg_trgm` and `pgcrypto` in it. It never changes a role that already exists. If that role cannot log in with the configured password or is not a superuser, the step fails and tells you to set `GBRAIN_DEV_PG_USER` or `GBRAIN_DEV_PG_PASSWORD`. |+| `rust` | Installs rustup with the stable toolchain, `rustfmt` and `clippy`, and links `cargo`, `rustc`, `rustup`, `rustfmt`, `cargo-fmt`, `cargo-clippy`, `clippy-driver` and `rustdoc` into `/usr/local/bin`. |+| `napi-cli` | Installs the napi-rs CLI (`@napi-rs/cli` 3.x) as a global Bun tool, plus a small `napi` wrapper in `~/.gbrain-rust-dev/bin` that runs it on Bun. Node is not needed: Ubuntu's Node 18 is too old for the CLI. Nothing is added to `package.json`. |+| `bun-install` | Runs `bun install --frozen-lockfile` in the repository. |+| `env-file` | Writes `~/.gbrain-rust-dev.env` (mode 600). |++The role is a superuser because the tests run `CREATE DATABASE` and+`CREATE EXTENSION vector`. It is for a throwaway dev machine only.++## Environment variables++The env file sets these:++| Variable | Value |+|---|---|+| `PATH` | `~/.gbrain-rust-dev/bin`, `~/.cargo/bin` and `~/.bun/bin` in front, in that order |+| `BUN_INSTALL`, `CARGO_HOME`, `RUSTUP_HOME` | `~/.bun`, `~/.cargo`, `~/.rustup` |+| `RUST_ENGINE_DATABASE_URL` | A `postgresql://` URL for role `gbrain` (password `gbrain`) on `127.0.0.1:5432`, database `gbrain_test` |++The env file does not set `DATABASE_URL`, on purpose. The tests read+`DATABASE_URL`, but the test preload+(`test/helpers/database-url-guard-preload.ts`) stops every plain `bun test`+while it is set, to protect real brains. So you pass it on the command line of+the e2e wrapper only, as shown below. The database name must contain `test` as+a word (`gbrain_test` does), or `test/helpers/db-guard.ts` refuses it.++You can change the defaults before the run with `GBRAIN_DEV_BUN_VERSION`,+`GBRAIN_DEV_PG_PORT`, `GBRAIN_DEV_PG_USER`, `GBRAIN_DEV_PG_PASSWORD`,+`GBRAIN_DEV_PG_DB` (letters, digits and `_` only), `GBRAIN_DEV_ENV_FILE`,+`GBRAIN_DEV_BIN` and `GBRAIN_DEV_LOG_DIR`. Set `GBRAIN_DEV_LINK_BINS=0` to+leave `/usr/local/bin` alone, and `GBRAIN_DEV_SKIP_RUST=1` to skip Rust.++## Run the parity tests++PGLite (no database needed):++```bash+. ~/.gbrain-rust-dev.env+bun test --timeout=60000 test/pglite-engine.test.ts+```++Postgres against PGLite, through the e2e wrapper (it isolates `HOME` and opts in+to the database guard):++```bash+. ~/.gbrain-rust-dev.env+DATABASE_URL="$RUST_ENGINE_DATABASE_URL" bash scripts/run-e2e.sh test/e2e/engine-parity.test.ts+```++Run `bun test test/e2e/engine-parity.test.ts` without `DATABASE_URL` and the+Postgres half is skipped. Bun then reports about 108 tests, because it also+counts the skipped setup hooks; the real count is 76.++Pass `--timeout=60000` to a direct `bun test`. Bun ignores the timeout in+`bunfig.toml`, and PGLite's first start can take longer than Bun's 5 seconds.++## Measured runs++On 2026-11-17, at master `0d78dcfa2e`, 8 CPUs:++| Run | Result | Time |+|---|---|---|+| Script, fresh `ubuntu:24.04` container (no Bun, Postgres, Rust or Node; user with passwordless sudo) | PASS | 52 s |+| Script again, same container | PASS | 0 s |+| `test/pglite-engine.test.ts`, same container | 110 pass, 0 fail | 6 s |+| `test/e2e/engine-parity.test.ts`, same container, Postgres 16.16 + pgvector 0.8.7 | 76 pass, 0 fail | 56 s |+| Script, dev VM (Postgres 16 installed but stopped, Bun 1.3.14) | PASS | 36 s |+| Script again, same VM | PASS | 1 s |+| `test/pglite-engine.test.ts`, same VM | 110 pass, 0 fail | 5 s |+| `test/e2e/engine-parity.test.ts`, same VM, Postgres 16.14 + pgvector 0.8.2 | 76 pass, 0 fail | 53 s |++In the fresh container, most of the 52 s went to apt: base packages 20 s,+Postgres 17 s. Rust took 8 s.++## Known problems++- Port 5432 taken: some machines also carry a Postgres 17 cluster on 5432. The+ script stops with a plain message if another server holds the port. Stop that+ server, or move one cluster to another port (`pg_lsclusters` lists them).+- A machine restart stops Postgres. Run the script again; it takes seconds.+- Each new shell needs `. ~/.gbrain-rust-dev.env` for `RUST_ENGINE_DATABASE_URL`.+ `bun`, `cargo`, `rustc` and `napi` work without it, through `/usr/local/bin`.+- The script installs the Rust stable toolchain. When the Rust workspace adds+ `rust/rust-toolchain.toml`, cargo will pick that pin up by itself.+- Ubuntu only. macOS and other Linux distributions are not supported.+- If you set `GBRAIN_DEV_LOG_DIR`, it must be a folder you own that no other+ user can write to. The script stops otherwise.+- Run the tests with `PGHOSTADDR` and `PGSERVICE` unset. The script clears them+ only for itself, not in your shell, and either one could send the test+ connection to a different server.+- An existing `gbrain` role from other work is kept. If its password is not+ `gbrain`, set `GBRAIN_DEV_PG_PASSWORD` to its password or pick another name+ with `GBRAIN_DEV_PG_USER`.diff --git a/scripts/dev/rust-engine-bootstrap.sh b/scripts/dev/rust-engine-bootstrap.shnew file mode 100755index 0000000000..caad2e90bd--- /dev/null+++ b/scripts/dev/rust-engine-bootstrap.sh@@ -0,0 +1,394 @@+#!/usr/bin/env bash+# scripts/dev/rust-engine-bootstrap.sh — one-shot dev machine setup for Rust+# engine parity work (docs/research/rust-engine/dev-environment.md).+#+# Installs, on Ubuntu, without prompts:+# 1. the Bun version gbrain pins (package.json engines.bun),+# 2. Postgres 16 + pgvector (pg_trgm and pgcrypto ship with the server),+# started, with a superuser role and a test database for the e2e tests,+# 3. the Rust stable toolchain (rustfmt, clippy) and the napi-rs CLI,+# 4. the repository's dependencies (bun install --frozen-lockfile).+# Then writes an env file and prints a pass/fail summary.+#+# Idempotent: a second run skips what is already in place and only starts+# Postgres if the machine restarted. Needs root or passwordless sudo.+#+# Knobs (all optional):+# GBRAIN_DEV_BUN_VERSION Bun version (default: read from package.json)+# GBRAIN_DEV_PG_PORT Postgres port when the script creates the cluster (default 5432)+# GBRAIN_DEV_PG_USER / GBRAIN_DEV_PG_PASSWORD / GBRAIN_DEV_PG_DB+# role, password and database (default gbrain / gbrain / gbrain_test;+# letters, digits and _ only)+# GBRAIN_DEV_ENV_FILE env file to write (default ~/.gbrain-rust-dev.env)+# GBRAIN_DEV_LINK_BINS=0 do not link bun, cargo, rustc and napi into /usr/local/bin+# GBRAIN_DEV_SKIP_RUST=1 skip the Rust toolchain and napi-rs CLI+# GBRAIN_DEV_BIN where the napi wrapper goes (default ~/.gbrain-rust-dev/bin)+# GBRAIN_DEV_LOG_DIR parent of the per-run log folders (default ~/.gbrain-rust-dev/logs)+#+# Each run writes its step logs to a new private folder, run-<time>-XXXXXX,+# under GBRAIN_DEV_LOG_DIR. The script unsets PGHOST, PGHOSTADDR and PGSERVICE+# for itself, so every Postgres call reaches the local 16/main cluster. It+# creates the database role only when it is missing and never changes an+# existing role; when an existing role cannot be used, it stops and says why.+#+# The script never exports DATABASE_URL into your shell: the test preload+# (test/helpers/database-url-guard-preload.ts) refuses every plain `bun test`+# while DATABASE_URL is set. The env file exports RUST_ENGINE_DATABASE_URL+# instead; pass it as DATABASE_URL to the e2e wrapper only.+set -uo pipefail++REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"+LOG_ROOT="${GBRAIN_DEV_LOG_DIR:-$HOME/.gbrain-rust-dev/logs}"+ENV_FILE="${GBRAIN_DEV_ENV_FILE:-$HOME/.gbrain-rust-dev.env}"+PG_MAJOR=16+PG_USER="${GBRAIN_DEV_PG_USER:-gbrain}"+PG_PASSWORD="${GBRAIN_DEV_PG_PASSWORD:-gbrain}"+PG_DB="${GBRAIN_DEV_PG_DB:-gbrain_test}"+PG_PORT="${GBRAIN_DEV_PG_PORT:-5432}"+LINK_BINS="${GBRAIN_DEV_LINK_BINS:-1}"+SKIP_RUST="${GBRAIN_DEV_SKIP_RUST:-0}"+export BUN_INSTALL="${BUN_INSTALL:-$HOME/.bun}"+export CARGO_HOME="${CARGO_HOME:-$HOME/.cargo}"+export RUSTUP_HOME="${RUSTUP_HOME:-$HOME/.rustup}"+DEV_BIN="${GBRAIN_DEV_BIN:-$HOME/.gbrain-rust-dev/bin}"+export PATH="$DEV_BIN:$BUN_INSTALL/bin:$CARGO_HOME/bin:$PATH"+export DEBIAN_FRONTEND=noninteractive+# These would send psql, createdb and pg_isready to another server than the+# local cluster the script set up. Clear them for this script only.+unset PGHOST PGHOSTADDR PGSERVICE++# Each run logs to a folder that mktemp creates new, mode 700, so no file or+# link another user put in a shared parent folder can be written through.+mkdir -p -m 700 "$LOG_ROOT" || { echo "cannot create log directory $LOG_ROOT" >&2; exit 1; }+# Others could still rename the run folder inside a parent they can write to.+if [ -L "$LOG_ROOT" ] || [ ! -O "$LOG_ROOT" ] || [ $((8#$(stat -c %a "$LOG_ROOT") & 8#022)) -ne 0 ]; then+ echo "log directory $LOG_ROOT must be a real directory owned by $(id -un) that only it can write to" >&2+ exit 1+fi+LOG_DIR="$(mktemp -d "$LOG_ROOT/run-$(date +%Y%m%dT%H%M%S)-XXXXXX")" ||+ { echo "cannot create a run log folder under $LOG_ROOT" >&2; exit 1; }++# Role, password and database go into SQL, a URL and the env file, so keep+# them to characters that need no quoting anywhere.+for _v in PG_USER PG_PASSWORD PG_DB; do+ case "${!_v}" in+ ''|*[!A-Za-z0-9_]*) echo "GBRAIN_DEV_${_v}: use letters, digits and _ only" >&2; exit 1 ;;+ esac+done+case "$PG_PORT" in ''|*[!0-9]*) echo "GBRAIN_DEV_PG_PORT must be a number" >&2; exit 1 ;; esac+T0=$SECONDS+SUMMARY=()+FAILED=0+APT_UPDATED=0++say() { printf '[bootstrap] %s\n' "$*"; }++# Run one step: its output goes to $LOG_DIR/<name>.log; on failure the last+# lines are printed. Records PASS/FAIL with seconds and an optional detail+# the step writes to $STEP_DETAIL.+run_step() {+ local name="$1"; shift+ local log="$LOG_DIR/$name.log" start=$SECONDS+ STEP_DETAIL=""+ say "$name ..."+ if "$@" >"$log" 2>&1; then+ SUMMARY+=("PASS $(printf '%-12s %4ss' "$name" $((SECONDS - start))) ${STEP_DETAIL:-}")+ else+ FAILED=1+ SUMMARY+=("FAIL $(printf '%-12s %4ss' "$name" $((SECONDS - start))) see $log")+ say "$name failed; last lines of $log:"+ tail -n 15 "$log" | sed 's/^/ /'+ return 1+ fi+}++# Steps run in this shell (only their output is redirected), so a step can+# set STEP_DETAIL and DB_URL for later steps.+detail() { STEP_DETAIL="$*"; }++if [ "$(id -u)" -eq 0 ]; then+ SUDO=()+else+ SUDO=(sudo -n)+fi++as_root() { "${SUDO[@]}" "$@"; }+as_postgres() {+ if [ "$(id -u)" -eq 0 ]; then+ runuser -u postgres -- "$@"+ else+ sudo -n -u postgres "$@"+ fi+}++apt_install() {+ if [ "$APT_UPDATED" -eq 0 ]; then+ as_root apt-get update -q || return 1+ APT_UPDATED=1+ fi+ as_root apt-get install -y -q --no-install-recommends "$@"+}++# ---------------------------------------------------------------- preflight+preflight() {+ if ! grep -qi '^ID=ubuntu' /etc/os-release 2>/dev/null; then+ echo "This script supports Ubuntu only (found: $(. /etc/os-release 2>/dev/null; echo "${PRETTY_NAME:-unknown}"))."+ return 1+ fi+ if [ "$(id -u)" -ne 0 ] && ! sudo -n true 2>/dev/null; then+ echo "Needs root or passwordless sudo (sudo -n true failed)."+ return 1+ fi+ local missing=()+ for tool in curl unzip git cc pkg-config python3 pgrep; do+ command -v "$tool" >/dev/null 2>&1 || missing+=("$tool")+ done+ [ -e /etc/ssl/certs/ca-certificates.crt ] || missing+=(ca-certificates)+ if [ "${#missing[@]}" -gt 0 ]; then+ local pkgs=(ca-certificates curl unzip git pkg-config python3 procps)+ case " ${missing[*]} " in *" cc "*) pkgs+=(build-essential) ;; esac+ apt_install "${pkgs[@]}" || return 1+ detail "installed ${pkgs[*]}"+ else+ detail "$(. /etc/os-release; echo "$PRETTY_NAME")"+ fi+}++# ---------------------------------------------------------------------- bun+pinned_bun_version() {+ if [ -n "${GBRAIN_DEV_BUN_VERSION:-}" ]; then+ echo "$GBRAIN_DEV_BUN_VERSION"+ return+ fi+ # package.json: "engines": { "bun": ">=1.4.4" } — the floor CI also pins.+ sed -n 's/.*"bun"[[:space:]]*:[[:space:]]*"[^0-9]*\([0-9][0-9.]*\)".*/\1/p' "$REPO_ROOT/package.json" | head -n 1+}++install_bun() {+ local want have+ want="$(pinned_bun_version)"+ [ -n "$want" ] || { echo "could not read engines.bun from package.json"; return 1; }+ have="$("$BUN_INSTALL/bin/bun" --version 2>/dev/null || true)"+ if [ "$have" != "$want" ]; then+ curl -fsSL https://bun.com/install | bash -s "bun-v$want" || return 1+ have="$("$BUN_INSTALL/bin/bun" --version 2>/dev/null || true)"+ [ "$have" = "$want" ] || { echo "installed bun reports '$have', wanted $want"; return 1; }+ fi+ if [ "$LINK_BINS" = "1" ]; then+ as_root ln -sfn "$BUN_INSTALL/bin/bun" /usr/local/bin/bun || return 1+ as_root ln -sfn "$BUN_INSTALL/bin/bun" /usr/local/bin/bunx || return 1+ fi+ detail "bun $have ($BUN_INSTALL/bin/bun)"+}++# ----------------------------------------------------------------- postgres+pg_installed() {+ [ -x "/usr/lib/postgresql/$PG_MAJOR/bin/postgres" ] &&+ [ -f "/usr/share/postgresql/$PG_MAJOR/extension/vector.control" ] &&+ [ -f "/usr/share/postgresql/$PG_MAJOR/extension/pg_trgm.control" ]+}++install_postgres() {+ if ! pg_installed; then+ apt_install postgresql-common || return 1+ # Ubuntu's own archive carries postgresql-16 and an older pgvector; the+ # PGDG archive matches CI's pgvector/pgvector:pg16 image more closely.+ if ! grep -rqs 'apt.postgresql.org' /etc/apt/sources.list /etc/apt/sources.list.d/; then+ as_root /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y || return 1+ APT_UPDATED=0+ fi+ apt_install "postgresql-$PG_MAJOR" "postgresql-$PG_MAJOR-pgvector" || return 1+ fi+ pg_installed || { echo "postgres $PG_MAJOR or its extensions are still missing"; return 1; }+ detail "$("/usr/lib/postgresql/$PG_MAJOR/bin/postgres" --version)"+}++# Port of the existing 16/main cluster, or empty when there is none.+cluster_port() {+ pg_lsclusters --no-header 2>/dev/null | awk -v v="$PG_MAJOR" '$1 == v && $2 == "main" { print $3 }'+}++cluster_status() {+ pg_lsclusters --no-header 2>/dev/null | awk -v v="$PG_MAJOR" '$1 == v && $2 == "main" { print $4 }'+}++start_postgres() {+ if [ -z "$(cluster_port)" ]; then+ as_root pg_createcluster "$PG_MAJOR" main --port "$PG_PORT" || return 1+ fi+ PG_PORT="$(cluster_port)"+ if [ "$(cluster_status)" != "online" ]; then+ # Another server (for example a Postgres 17 cluster) on the same port+ # would make the start fail with a confusing message; say it plainly.+ if pg_isready -q -h 127.0.0.1 -p "$PG_PORT" 2>/dev/null; then+ echo "Port $PG_PORT already has a server that is not Postgres $PG_MAJOR/main."+ echo "Stop it (pg_lsclusters lists clusters) or move one cluster to another port."+ return 1+ fi+ as_root pg_ctlcluster "$PG_MAJOR" main start || return 1+ fi+ local i+ for i in $(seq 1 30); do+ pg_isready -q -h 127.0.0.1 -p "$PG_PORT" && break+ sleep 1+ done+ pg_isready -h 127.0.0.1 -p "$PG_PORT" || return 1+ detail "16/main online on port $PG_PORT"+}++create_database() {+ # Every admin call names the 16/main port: with a second cluster on the+ # machine, Ubuntu's psql wrapper would otherwise pick the default one.+ PG_PORT="$(cluster_port)"+ [ -n "$PG_PORT" ] || { echo "no $PG_MAJOR/main cluster"; return 1; }+ # cd / so `sudo -u postgres` does not warn about an unreadable cwd.+ # The password goes in on stdin, never in argv where `ps` shows it.+ # PG_USER and PG_PASSWORD are already limited to [A-Za-z0-9_].+ # An existing role is kept as it is: something else may use it.+ # Superuser: the tests CREATE DATABASE and CREATE EXTENSION vector. Local dev only.+ (cd / && as_postgres psql -p "$PG_PORT" -v ON_ERROR_STOP=1 -q -d postgres) <<SQL || return 1+SELECT format('CREATE ROLE %I WITH LOGIN SUPERUSER PASSWORD %L', '$PG_USER', '$PG_PASSWORD')+WHERE NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '$PG_USER') \\gexec+SQL+ local flags+ flags="$(cd / && as_postgres psql -p "$PG_PORT" -tAq -d postgres -c "SELECT rolcanlogin::text || ' ' || rolsuper::text FROM pg_roles WHERE rolname = '$PG_USER'")" || return 1+ if [ "$flags" != "true true" ]; then+ echo "Role $PG_USER already exists and is not a login superuser; the script does not change existing roles."+ echo "Set GBRAIN_DEV_PG_USER to an unused role name and run the script again."+ return 1+ fi+ if ! (cd / && as_postgres psql -p "$PG_PORT" -tAq -d postgres -c "SELECT 1 FROM pg_database WHERE datname = '$PG_DB'") | grep -q 1; then+ (cd / && as_postgres createdb -p "$PG_PORT" -O "$PG_USER" "$PG_DB") || return 1+ fi+ local url="postgresql://$PG_USER:[email protected]:$PG_PORT/$PG_DB"+ # Connect with the password in the environment, not on the command line.+ local conn="postgresql://[email protected]:$PG_PORT/$PG_DB"+ if ! PGPASSWORD="$PG_PASSWORD" psql "$conn" -tAq -c 'SELECT 1' >/dev/null; then+ echo "Cannot log in as $PG_USER with the configured password. The role existed before and the"+ echo "script keeps its password. Set GBRAIN_DEV_PG_PASSWORD to that role's password, or set"+ echo "GBRAIN_DEV_PG_USER to an unused role name, and run the script again."+ return 1+ fi+ PGPASSWORD="$PG_PASSWORD" psql "$conn" -v ON_ERROR_STOP=1 -q \+ -c 'CREATE EXTENSION IF NOT EXISTS vector' \+ -c 'CREATE EXTENSION IF NOT EXISTS pg_trgm' \+ -c 'CREATE EXTENSION IF NOT EXISTS pgcrypto' || return 1+ local exts+ exts="$(PGPASSWORD="$PG_PASSWORD" psql "$conn" -tA -c "SELECT string_agg(extname || ' ' || extversion, ', ' ORDER BY extname) FROM pg_extension WHERE extname IN ('vector','pg_trgm','pgcrypto')")" || return 1+ echo "extensions: $exts"+ case "$exts" in *vector*pg_trgm*|*pg_trgm*vector*) ;; *) echo "vector or pg_trgm missing"; return 1 ;; esac+ DB_URL="$url"+ detail "$PG_DB as $PG_USER ($exts)"+}++# --------------------------------------------------------------------- rust+install_rust() {+ if ! command -v rustup >/dev/null 2>&1; then+ curl --proto '=https' --tlsv1.2 -fsSL https://sh.rustup.rs |+ sh -s -- -y --no-modify-path --profile minimal --default-toolchain stable || return 1+ else+ rustup toolchain install stable --profile minimal || return 1+ rustup default stable || return 1+ fi+ rustup component add rustfmt clippy || return 1+ if [ "$LINK_BINS" = "1" ]; then+ local bin+ for bin in cargo rustc rustup rustfmt cargo-fmt cargo-clippy clippy-driver rustdoc; do+ [ -e "$CARGO_HOME/bin/$bin" ] && { as_root ln -sfn "$CARGO_HOME/bin/$bin" "/usr/local/bin/$bin" || return 1; }+ done+ fi+ detail "$(rustc --version | cut -d' ' -f1-2), $(cargo --version | cut -d' ' -f1-2)"+}++install_napi_cli() {+ # Global CLI only; nothing is added to package.json (RUST_ENGINE.md: no npm+ # dependency). The CLI is a Node script, and Ubuntu's own nodejs (18) is too+ # old for it, so a small wrapper runs it on the Bun runtime instead. That+ # keeps Node off the machine entirely.+ local cli="$BUN_INSTALL/install/global/node_modules/@napi-rs/cli/dist/cli.js"+ if [ ! -f "$cli" ]; then+ bun add -g @napi-rs/cli@3 || return 1+ fi+ mkdir -p "$DEV_BIN" || return 1+ printf '#!/bin/sh\n# Written by scripts/dev/rust-engine-bootstrap.sh: run the napi-rs CLI on Bun.\nexec "%s" --bun "%s" "$@"\n' \+ "$BUN_INSTALL/bin/bun" "$cli" >"$DEV_BIN/napi" || return 1+ chmod 755 "$DEV_BIN/napi" || return 1+ if [ "$LINK_BINS" = "1" ]; then+ as_root ln -sfn "$DEV_BIN/napi" /usr/local/bin/napi || return 1+ fi+ local v+ v="$("$DEV_BIN/napi" --version 2>&1 | head -n 1)" || true+ case "$v" in [0-9]*) ;; *) echo "napi --version printed: $v"; return 1 ;; esac+ detail "napi-rs CLI $v (runs on bun)"+}++# -------------------------------------------------------------- bun install+install_deps() {+ (cd "$REPO_ROOT" && bun install --frozen-lockfile) || return 1+ detail "node_modules ready (bun $(bun --version))"+}++write_env_file() {+ local url="${DB_URL:-postgresql://$PG_USER:[email protected]:$PG_PORT/$PG_DB}"+ local dir tmp d+ dir="$(dirname "$ENV_FILE")"+ mkdir -p "$dir" || return 1+ tmp="$(mktemp "$dir/.gbrain-rust-dev.env.XXXXXX")" || return 1+ {+ echo "# Written by scripts/dev/rust-engine-bootstrap.sh. Source it: . $ENV_FILE"+ printf 'export BUN_INSTALL=%q\n' "$BUN_INSTALL"+ printf 'export CARGO_HOME=%q\n' "$CARGO_HOME"+ printf 'export RUSTUP_HOME=%q\n' "$RUSTUP_HOME"+ for d in "$BUN_INSTALL/bin" "$CARGO_HOME/bin" "$DEV_BIN"; do+ printf 'case ":$PATH:" in *:%q:*) ;; *) export PATH=%q:"$PATH" ;; esac\n' "$d" "$d"+ done+ echo "# Local test database. Not exported as DATABASE_URL on purpose: the test"+ echo "# preload refuses a direct test run while DATABASE_URL is set. Use:"+ echo '# DATABASE_URL="$RUST_ENGINE_DATABASE_URL" bash scripts/run-e2e.sh <files>'+ printf 'export RUST_ENGINE_DATABASE_URL=%q\n' "$url"+ } >"$tmp" || { rm -f "$tmp"; return 1; }+ chmod 600 "$tmp" || { rm -f "$tmp"; return 1; }+ mv -f "$tmp" "$ENV_FILE" || { rm -f "$tmp"; return 1; }+ detail "$ENV_FILE"+}++# ---------------------------------------------------------------------- run+say "repo: $REPO_ROOT logs: $LOG_DIR"+run_step preflight preflight+if [ "$FAILED" -eq 0 ]; then+ run_step bun install_bun+ # Each Postgres step needs the one before it: never touch roles or+ # databases on a server this script did not verify.+ if run_step postgres install_postgres; then+ if run_step pg-start start_postgres; then+ run_step pg-database create_database+ else+ SUMMARY+=("SKIP pg-database (pg-start failed)")+ fi+ else+ SUMMARY+=("SKIP pg-start (postgres failed)" "SKIP pg-database (postgres failed)")+ fi+ if [ "$SKIP_RUST" = "1" ]; then+ SUMMARY+=("SKIP rust (GBRAIN_DEV_SKIP_RUST=1)")+ else+ run_step rust install_rust+ run_step napi-cli install_napi_cli+ fi+ run_step bun-install install_deps+ run_step env-file write_env_file+fi++echo+echo "== rust-engine bootstrap summary ($((SECONDS - T0))s total) =="+printf '%s\n' "${SUMMARY[@]}"+echo+if [ "$FAILED" -eq 0 ]; then+ echo "RESULT: PASS"+ echo "Next:"+ echo " . $ENV_FILE"+ echo " bun test --timeout=60000 test/pglite-engine.test.ts"+ echo " DATABASE_URL=\"\$RUST_ENGINE_DATABASE_URL\" bash scripts/run-e2e.sh test/e2e/engine-parity.test.ts"+ exit 0+fi+echo "RESULT: FAIL (logs in $LOG_DIR)"+exit 1diff --git a/scripts/module-size-limits.tsv b/scripts/module-size-limits.tsvindex a040d7efc9..edff034ca7 100644--- a/scripts/module-size-limits.tsv+++ b/scripts/module-size-limits.tsv@@ -23,7 +23,7 @@ src/core/operations.ts 250 ratchet +1 #7168: graphRankOperations import (ops/grasrc/core/pglite-engine.ts 3103 ratchet +9 #7191: findPages/countPagesBy delegates and imports (SQL in engine-sql/page-lookup.ts); +4 GBRA-283 B1 (#8455): initSchema seeds an engine opened from settings with settings.embedding and refuses a mismatch, and its open skips the snapshot fast path (logic in embedded-engine.ts; engine methods cannot move); +5 agent operator gate fixes: repair-failed marker gate before the lock and the marker record after a failed auto-repair (logic in pglite-repair.ts, refusal in pglite-repair-consent.ts); +1 System One v1 evals: search arms clamp to searchLimitCap() (import of search/eval-pool-depth.ts; eval-only --eval-pool-depth, production cap unchanged); refactor wave 1 split target (W1 engine-sql); E1 bootstrap moved to engine-sql/bootstrap.ts; ceiling rationale: docs/architecture/key-files/engines-1.md entry for src/core/pglite-engine.ts; evidence delivery: getChunkWindows delegate + type import (+3; SQL in engine-sql/chunks.ts); #5761: +4 markPagesAttendanceBlocked delegate (SQL in engine-sql/pages.ts); +12 eval wave N1-2/N1-3: mergeOntologyFact same-stint noop check + ontology visibility filter in the grandfathered ontology methods; lowered to 3213 #5824: searchVector SQL moved to search/vector-statement.ts (-166); lowered to 3117 #5889: searchTitles SQL moved to engine-sql/titles.ts (-108); lowered to 2915 F4a: getHealth SQL moved to engine-sql/health.ts (-202); +6 F4b: planner-sensitive reads call beforePlannerRead/plannerRead (logic in planner-stats.ts); +52 engine graduation (GBRA-50 G2a): marker/tombstone checks before and after the kernel lock (logic in persistence/graduation-custody.ts), lock-retaining close and held-lock open (engine lifecycle methods cannot move); 4 Foundations 2 Lane F: autocommit write statements take the WAL checkpoint guard (classifier writesWal in pglite-engine/checkpoint-guard.ts); +5 agent operator gate fixes: repair-failed marker gate before the lock and the marker record after a failed auto-repair (logic in pglite-repair.ts, refusal in pglite-repair-consent.ts); +1 System One v1 evals: search arms clamp to searchLimitCap() (import of search/eval-pool-depth.ts; eval-only --eval-pool-depth, production cap unchanged); refactor wave 1 split target (W1 engine-sql); E1 bootstrap moved to engine-sql/bootstrap.ts; ceiling rationale: docs/architecture/key-files/engines-1.md entry for src/core/pglite-engine.ts; evidence delivery: getChunkWindows delegate + type import (+3; SQL in engine-sql/chunks.ts); #5761: +4 markPagesAttendanceBlocked delegate (SQL in engine-sql/pages.ts); +12 eval wave N1-2/N1-3: mergeOntologyFact same-stint noop check + ontology visibility filter in the grandfathered ontology methods; lowered to 3213 #5824: searchVector SQL moved to search/vector-statement.ts (-166); lowered to 3117 #5889: searchTitles SQL moved to engine-sql/titles.ts (-108); lowered to 2915 F4a: getHealth SQL moved to engine-sql/health.ts (-202); +6 F4b: planner-sensitive reads call beforePlannerRead/plannerRead (logic in planner-stats.ts); +5 agent operator gate fixes: repair-failed marker gate before the lock and the marker record after a failed auto-repair (logic in pglite-repair.ts, refusal in pglite-repair-consent.ts); +1 System One v1 evals: search arms clamp to searchLimitCap() (import of search/eval-pool-depth.ts; eval-only --eval-pool-depth, production cap unchanged); refactor wave 1 split target (W1 engine-sql); E1 bootstrap moved to engine-sql/bootstrap.ts; ceiling rationale: docs/architecture/key-files/engines-1.md entry for src/core/pglite-engine.ts; evidence delivery: getChunkWindows delegate + type import (+3; SQL in engine-sql/chunks.ts); #5761: +4 markPagesAttendanceBlocked delegate (SQL in engine-sql/pages.ts); +12 eval wave N1-2/N1-3: mergeOntologyFact same-stint noop check + ontology visibility filter in the grandfathered ontology methods; lowered to 3213 #5824: searchVector SQL moved to search/vector-statement.ts (-166); lowered to 3117 #5889: searchTitles SQL moved to engine-sql/titles.ts (-108); lowered to 2915 F4a: getHealth SQL moved to engine-sql/health.ts (-202); +6 F4b: planner-sensitive reads call beforePlannerRead/plannerRead (logic in planner-stats.ts); +52 engine graduation (GBRA-50 G2a): marker/tombstone checks before and after the kernel lock (logic in persistence/graduation-custody.ts), lock-retaining close and held-lock open (engine lifecycle methods cannot move); 4 Foundations 2 Lane F: autocommit write statements take the WAL checkpoint guard (classifier writesWal in pglite-engine/checkpoint-guard.ts); +5 agent operator gate fixes: repair-failed marker gate before the lock and the marker record after a failed auto-repair (logic in pglite-repair.ts, refusal in pglite-repair-consent.ts); +1 System One v1 evals: search arms clamp to searchLimitCap() (import of search/eval-pool-depth.ts; eval-only --eval-pool-depth, production cap unchanged); refactor wave 1 split target (W1 engine-sql); E1 bootstrap moved to engine-sql/bootstrap.ts; ceiling rationale: docs/architecture/key-files/engines-1.md entry for src/core/pglite-engine.ts; evidence delivery: getChunkWindows delegate + type import (+3; SQL in engine-sql/chunks.ts); #5761: +4 markPagesAttendanceBlocked delegate (SQL in engine-sql/pages.ts); +12 eval wave N1-2/N1-3: mergeOntologyFact same-stint noop check + ontology visibility filter in the grandfathered ontology methods; lowered to 3213 #5824: searchVector SQL moved to search/vector-statement.ts (-166); lowered to 3117 #5889: searchTitles SQL moved to engine-sql/titles.ts (-108); lowered to 2915 F4a: getHealth SQL moved to engine-sql/health.ts (-202); +6 F4b: planner-sensitive reads call beforePlannerRead/plannerRead (logic in planner-stats.ts); +5 agent operator gate fixes: repair-failed marker gate before the lock and the marker record after a failed auto-repair (logic in pglite-repair.ts, refusal in pglite-repair-consent.ts); +1 System One v1 evals: search arms clamp to searchLimitCap() (import of search/eval-pool-depth.ts; eval-only --eval-pool-depth, production cap unchanged); refactor wave 1 split target (W1 engine-sql); E1 bootstrap moved to engine-sql/bootstrap.ts; ceiling rationale: docs/architecture/key-files/engines-1.md entry for src/core/pglite-engine.ts; evidence delivery: getChunkWindows delegate + type import (+3; SQL in engine-sql/chunks.ts); #5761: +4 markPagesAttendanceBlocked delegate (SQL in engine-sql/pages.ts); +12 eval wave N1-2/N1-3: mergeOntologyFact same-stint noop check + ontology visibility filter in the grandfathered ontology methods; lowered to 3213 #5824: searchVector SQL moved to search/vector-statement.ts (-166); lowered to 3117 #5889: searchTitles SQL moved to engine-sql/titles.ts (-108); lowered to 2915 F4a: getHealth SQL moved to engine-sql/health.ts (-202); +6 F4b: planner-sensitive reads call beforePlannerRead/plannerRead (logic in planner-stats.ts); +52 engine graduation (GBRA-50 G2a): marker/tombstone checks before and after the kernel lock (logic in persistence/graduation-custody.ts), lock-retaining close and held-lock open (engine lifecycle methods cannot move); +1 #5984: upsertChunks guards pass the per-transaction config memo (transactionMemo in page-state/transactions.ts); v0.60.58.0 merge: #5984 diet growth re-summed over v0.60.57.0 (2983 measured); 4 Foundations 2 Lane F: autocommit write statements take the WAL checkpoint guard (classifier writesWal in pglite-engine/checkpoint-guard.ts); +5 agent operator gate fixes: repair-failed marker gate before the lock and the marker record after a failed auto-repair (logic in pglite-repair.ts, refusal in pglite-repair-consent.ts); +1 System One v1 evals: search arms clamp to searchLimitCap() (import of search/eval-pool-depth.ts; eval-only --eval-pool-depth, production cap unchanged); refactor wave 1 split target (W1 engine-sql); E1 bootstrap moved to engine-sql/bootstrap.ts; ceiling rationale: docs/architecture/key-files/engines-1.md entry for src/core/pglite-engine.ts; evidence delivery: getChunkWindows delegate + type import (+3; SQL in engine-sql/chunks.ts); #5761: +4 markPagesAttendanceBlocked delegate (SQL in engine-sql/pages.ts); +12 eval wave N1-2/N1-3: mergeOntologyFact same-stint noop check + ontology visibility filter in the grandfathered ontology methods; lowered to 3213 #5824: searchVector SQL moved to search/vector-statement.ts (-166); lowered to 3117 #5889: searchTitles SQL moved to engine-sql/titles.ts (-108); lowered to 2915 F4a: getHealth SQL moved to engine-sql/health.ts (-202); +6 F4b: planner-sensitive reads call beforePlannerRead/plannerRead (logic in planner-stats.ts); +5 agent operator gate fixes: repair-failed marker gate before the lock and the marker record after a failed auto-repair (logic in pglite-repair.ts, refusal in pglite-repair-consent.ts); +1 System One v1 evals: search arms clamp to searchLimitCap() (import of search/eval-pool-depth.ts; eval-only --eval-pool-depth, production cap unchanged); refactor wave 1 split target (W1 engine-sql); E1 bootstrap moved to engine-sql/bootstrap.ts; ceiling rationale: docs/architecture/key-files/engines-1.md entry for src/core/pglite-engine.ts; evidence delivery: getChunkWindows delegate + type import (+3; SQL in engine-sql/chunks.ts); #5761: +4 markPagesAttendanceBlocked delegate (SQL in engine-sql/pages.ts); +12 eval wave N1-2/N1-3: mergeOntologyFact same-stint noop check + ontology visibility filter in the grandfathered ontology methods; lowered to 3213 #5824: searchVector SQL moved to search/vector-statement.ts (-166); lowered to 3117 #5889: searchTitles SQL moved to engine-sql/titles.ts (-108); lowered to 2915 F4a: getHealth SQL moved to engine-sql/health.ts (-202); +6 F4b: planner-sensitive reads call beforePlannerRead/plannerRead (logic in planner-stats.ts); +52 engine graduation (GBRA-50 G2a): marker/tombstone checks before and after the kernel lock (logic in persistence/graduation-custody.ts), lock-retaining close and held-lock open (engine lifecycle methods cannot move); +1 #5984: upsertChunks guards pass the per-transaction config memo (transactionMemo in page-state/transactions.ts); v0.60.58.0 merge: #5984 diet growth re-summed over v0.60.57.0 (2983 measured); +4 P7 relationalChainHop delegate; +8 contributor audit wave P0: listFactsKeyset delegate (SQL in engine-sql/facts.ts); +1 #5375: get_versions limit/include_body type import (GetVersionsOpts, PageVersionRows); +2 #5984 lane apply diet: putPage/setPageAliases write inline in the caller's page transaction (engine methods cannot move); +4 GBRA-69: replaceDerivedLinksBatch delegate (logic in derived-links.ts); +5 GBRA-67: readPageSnapshotsBatch delegate (batch logic in page-snapshot-batch.ts); +1 GBRA-75 wave 10: findDuplicatePages delegate (SQL in engine-sql/pages.ts); +2 GBRA-76: transaction/transactionDirect take TransactionOptions and refuse an already-aborted signal before BEGIN; +2 #4772 (W14 PR3): entityTypes HealthDeps delegate + import (policy in schema-pack/entity-types.ts, SQL in engine-sql/health.ts); +2 W14 P3.12 (#4772): entityTypes HealthDeps delegate + import on top of W13; +11 Cat 40 Hard fix wave F2 (#6271) on top: countKeywordPages/searchKeywordPages delegations (SQL in engine-sql/keyword-pages.ts) and the rankQuery score parameter (3023 measured); +3 W15 P1.2 (#6454): three one-line stale-frontmatter-key delegates (SQL in engine-sql/pages.ts); +6 large pages Wave A sub-a: getChunkPage delegate (SQL in engine-sql/chunks.ts); +11 #6696 B3: readEmbeddingStateCounts/listEmbeddingStateRows delegations + type import; +22 Wave B lane 1a: segmented page storage delegations (allocateBodyOccurrenceIds..sweepSegments, SQL in engine-sql/page-body.ts) and their imports; +7 LHF wave 2 item 5: request config snapshot delegate lines in getConfig/getAllConfig/setConfig/unsetConfig (logic in config-snapshot.ts); +3 PR2 fix lane B: logIngest stamps writer_version/writer_host_id/writer_segment_reader and getIngestLog names its columns (engine methods cannot move); integrated at the Wave B PR 2 master merge (v0.60.264.0): master 3072 + 3; +5 PR2 fix lane X: keywordBoundedRead runs the read on the engine itself (engine methods cannot move): 3075 + 5; +2 GBRA-130 B-6 (#6860): putDreamVerdict passes its payload through wellFormedJson (engine methods cannot move); +1 GBRA-130 A-1: held option on the stale-page list/count signatures (SQL in engine-sql/pages.ts); +1 GBRA-130 integration: the A-1 (links_extract_failure) and B-6 (wellFormedJson putDreamVerdict) engine hunks composed at the lane merge; +2 #6948: putPage runs assertOriginUnclaimed in its page transaction and restorePage runs assertRevivalUnclaimed (logic in persistence/origin-guard.ts; engine methods cannot move): 3080 + 2; GBRA-130 composed with #6948 at the master 0e0cd27b merge: re-summed to the merged line count (3085); +2 #7159: the frontmatter where clause in searchKeyword and its import (SQL in search/frontmatter-where.ts; engine methods cannot move); +2 GBRA-156 keyword OR rarity: the import and the searchKeyword OR retry through rankOrFallbackByRarity with an orFallback rank parameter like Postgres (logic in search/keyword-or-rarity.ts; engine methods cannot move); +5 agent operator gate fixes: repair-failed marker gate before the lock and the marker record after a failed auto-repair (logic in pglite-repair.ts, refusal in pglite-repair-consent.ts); re-summed at the Wave B PR 4 merge with v0.60.452.0 (3097 measured); +2 GBRA-283 Wave A (#8460): the ENGINE_ROOT import and field (engine identity for per-engine caches; class fields cannot move)src/core/postgres-engine.ts 3188 ratchet +9 #7191: findPages/countPagesBy scoped-read delegates and imports (SQL in engine-sql/page-lookup.ts); +6 GBRA-283 B1 (#8455): an engine opened from settings routes its direct URL and statement-description cache from its settings, and initSchema seeds settings.embedding and refuses a mismatch (logic in embedded-engine.ts; engine methods cannot move); +1 System One v1 evals: search arms clamp to searchLimitCap() (import of search/eval-pool-depth.ts; eval-only --eval-pool-depth, production cap unchanged); refactor wave 1 split target (W1 engine-sql); ceiling rationale: docs/architecture/key-files/engines-2.md entry for src/core/postgres-engine.ts; evidence delivery: getChunkWindows scoped-read delegate + type import (+5; SQL in engine-sql/chunks.ts); #5761: +4 markPagesAttendanceBlocked delegate (SQL in engine-sql/pages.ts); +10 eval wave N1-2/N1-3: mergeOntologyFact same-stint noop check + ontology visibility filter in the grandfathered ontology methods; lowered to 3242 #5824: searchVector SQL moved to search/vector-statement.ts, +explainVectorSearch/runVectorAttempt (-156); +6 #5730: onpoisoned wiring on the instance/module/connection-manager pools + poisonedDiscards in getPoolDiagnostics (counter in pool-gauge.ts); +5 #5801: onCheckout observer seam (fires after reserve resolution / transaction-callback entry; listeners in pool-gauge.ts); lowered to 3119 #5889: searchTitles SQL moved to engine-sql/titles.ts (-133); lowered to 2914 F4a: getHealth SQL moved to engine-sql/health.ts (-216); +2 #5984: transactions track held page guards like PGLite (withHeldPageKeys), so repeated guards in one transaction cost no round trips; +1 #5984: traceSqlOptions import for the env-gated GBRAIN_SQL_TRACE bench hook (src/core/sql-trace.ts); v0.60.48.0 merge: #5984 growth re-summed over v0.60.47.0 (2917 measured); +2 engine graduation (GBRA-50 G2a): initSchema sizing parameter (the source embedding layout sizes a fresh target); +1 #5984: upsertChunks guards pass the per-transaction config memo (transactionMemo in page-state/transactions.ts); v0.60.58.0 merge: #5984 diet growth re-summed over v0.60.57.0 (2920 measured); +4 P7 relationalChainHop delegate; +8 contributor audit wave P0: listFactsKeyset delegate (SQL in engine-sql/facts.ts); +1 #5375: get_versions limit/include_body type import (GetVersionsOpts, PageVersionRows); 6 #6085: initSchema pins advisory lock 42, bootstrap, schema replay and unlock to one reserved backend when the DDL pool has more than one slot (gauge only, no long-hold permit), released in finally; wave 10 collector: lane E (#6085), lane G (#5375) and master compose at 2939; +2 #6110: search transactions pass jitOff to withScopedReadTransaction (SET LOCAL jit = off in postgres-engine/search-settings.ts); +2 #5984 lane apply diet: putPage/setPageAliases write inline in the caller's page transaction (engine methods cannot move); +1 #5984 single-write fast path composes with the lane apply diet at 2944; +2 #5984 shared parameter types: the instance pool passes shared_types and initSchema clears them after migrations (helpers in db.ts); +2 #6276: the remote alias-resolving readPageSnapshot runs with JIT off (withScopedReadTransaction jitOff); +5 #6278: executeRaw timeoutMs delegate (statement in postgres-engine/bounded-statement.ts); +23 #6278 PR 1.5: cancelSettleMs() and the settle timer in runUnsafe that discards a reserved connection whose cancel a transaction-mode pooler never completed; +3 #6317 lane 2: getPoolDiagnostics().pool from the vendored driver (postgres-engine/pool-stats.ts) and the prepare mark; +4 GBRA-69: replaceDerivedLinksBatch delegate (logic in derived-links.ts); +1 GBRA-69 extract batching: replaceDerivedLinksBatch delegate (batch logic in derived-links.ts); +9 GBRA-75: getBacklinkCounts and getHealth statements run JIT-off through the private jitOffRead transaction helper (engine methods cannot move); +3 GBRA-75 wave 7: searchKeyword and searchVector start the once-per-engine background search statistics guard (logic in search/projection-statistics.ts); +7 GBRA-67: readPageSnapshotsBatch scoped-read delegate (batch logic in page-snapshot-batch.ts); +1 GBRA-75 wave 10: findDuplicatePages scoped-read delegate (SQL in engine-sql/pages.ts); +7 #6383: poolIncidents hooks on the instance/module/connection-manager pools (counter and lines in pool-gauge.ts, budget in db.ts) and stuckDiscards/buildFailures in getPoolDiagnostics; +3 GBRA-76: transaction/transactionDirect take TransactionOptions; transactionOn attaches the begin handle to withTransactionAbort (logic in postgres-engine/transaction-abort.ts); +2 W14 P3.12 (#4772): entityTypes HealthDeps delegate + import on top of W13; +1 #5227: schema.sql replay under withSchemaLockTimeout (wave 14 PR1); +1 driver desync tripwire: desyncDiscards in getPoolDiagnostics (counter and line in pool-gauge.ts); +11 Cat 40 Hard fix wave F2 (#6271) on top: countKeywordPages/searchKeywordPages scoped-read delegations (SQL in engine-sql/keyword-pages.ts) and the rankQuery score parameter (3027 measured); +3 W15 P1.2 (#6454): three one-line stale-frontmatter-key delegates, reads scoped (SQL in engine-sql/pages.ts); +12 wave 16 G5.1 (#6495): keywordStatementTimeout memo field, its connect/disconnect resets and the keywordStatementTimeoutSetting accessor, plus one awaited setting per keyword/chunk/CJK transaction (resolver in postgres-engine/keyword-statement-timeout.ts); wave 16 G5.1 gate fix: keywordStatementTimeoutSetting resolves the knob once per connection on the first keyword statement from the saved connect config (connect issues no statement for it; 3042 measured); +7 large pages Wave A sub-a: getChunkPage scoped-read delegate (SQL in engine-sql/chunks.ts); +11 #6696 B3: readEmbeddingStateCounts/listEmbeddingStateRows delegations + type import; +22 Wave B lane 1a: segmented page storage delegations (allocateBodyOccurrenceIds..sweepSegments, SQL in engine-sql/page-body.ts) and their imports; +3 wave 18b lane 2 (#6495): keywordTimeouts negative-cache field and the searchKeyword runner wrap (logic in postgres-engine/keyword-timeout-cache.ts); integrated at wave 18b: master 3082 + 3; +3 PR2 fix lane B: logIngest stamps writer_version/writer_host_id/writer_segment_reader and getIngestLog names its columns (engine methods cannot move); integrated at the Wave B PR 2 master merge (v0.60.264.0): master 3085 + 3; +3 PR2 fix lane E (E1): getChunks/getChunkPage/getChunkWindows run the manifest privilege probe in their scoped transaction (chunkManifestReads in search/safe-chunks.ts); integrated at the lane E merge onto b75a69a6d: 3088 + 3; +6 PR2 fix lane X: searchVector, explainVectorSearch, the hasMore witness and runVectorAttempt pick the chunk-manifest statement form inside each bounded attempt transaction, so its statement_timeout bounds the probe (form memo vectorStatementForms in search/vector-statement.ts; engine methods cannot move): 3091 + 6; +5 PR2 fix lane X: keywordBoundedRead runs the read in withScopedReadTransaction under the keyword statement timeout setting (engine methods cannot move): 3097 + 5; +2 GBRA-130 B-6 (#6860): putDreamVerdict passes its payload through wellFormedJson (engine methods cannot move); +1 GBRA-130 A-1: held option on the stale-page list/count signatures (SQL in engine-sql/pages.ts); +1 GBRA-130 integration: the A-1 (links_extract_failure) and B-6 (wellFormedJson putDreamVerdict) engine hunks composed at the lane merge; +2 #6948: putPage runs assertOriginUnclaimed in its page transaction and restorePage runs assertRevivalUnclaimed (logic in persistence/origin-guard.ts; engine methods cannot move): 3102 + 2; GBRA-130 composed with #6948 at the master 0e0cd27b merge: re-summed to the merged line count (3107); +3 #7159: the frontmatter where clause in the two keyword typesClause sites and its import (SQL in search/frontmatter-where.ts; engine methods cannot move); GBRA-156 retrieval wave (#7201) composed with #7194 at the merge: re-summed (3114 measured); +2 warm CLI socket (#7218): connectedDatabaseUrl getter (the URL the engine connected with, bound into the socket identity), composed over the GBRA-156 retrieval wave (3116 measured); +1 GBRA-133 PR 2b: transactionOn hands the outermost transaction its commit checks (page-state/transactions.ts withCommitChecks), composed with the warm CLI socket at the merge (3117 measured); +18 GBRA-156: the private readTransaction helper behind withScopedReadTransaction and jitOffRead answers a top-level read before its COMMIT settles (engine methods cannot move; 3135 measured); +1 GBRA-156: transactionOn and runUnsafe hold a per-search connection slot (import of search/connection-budget.ts; 3136 measured); +2 GBRA-156: transactionOn passes TransactionOptions.pipelineFirst to the pool begin as { first } (driver gate in vendor/postgres index.js begin); an engine method cannot move; composed with the warm CLI socket and GBRA-133 PR 2b at the master v0.60.344.0 merge (3119 measured); GBRA-151 #7183/#7187/#7188 re-summed at the v0.60.402.0 merge (3135 measured); +2 #7183 (GBRA-151) at the v0.60.412.0 merge: read-write-transactions import and transactionOn wraps its connection in readWriteTransactions (logic in postgres-engine/read-write-transactions.ts; engine methods cannot move): 3135 + 2; +7 GBRA-156: transactionOn opens readOnly transactions as BEGIN READ ONLY and a top-level read inherits its request signal, runUnsafe refuses an aborted request (logic in request-signal.ts; engine methods cannot move): 3137 + 7; +3 GBRA-156 keyword OR rarity: the import and the searchKeyword OR retry through rankOrFallbackByRarity (logic in search/keyword-or-rarity.ts; engine methods cannot move); +2 wave-b PR 4 merged with #7218 (both sides added imports); re-summed at the Wave B PR 4 merge with v0.60.452.0 (3155 measured); +2 GBRA-283 Wave A (#8460): the ENGINE_ROOT import and field (engine identity for per-engine caches; class fields cannot move); +7 GBRA-283 B1 review: the instance pool passes settings connection fields explicitly, initSchema reads the embedding identity again under the schema lock, and reconnect ends the superseded manager (engine methods cannot move); re-summed at the train R merge with v0.60.574.0: 3170 + 4; +4 #6318: withScopedReadTransaction runs a bounded preparation's read under its deadline (read-deadline.ts; reserved-connection envelope runDeadlineRead in postgres-engine/bounded-statement.ts) and adds statement_timeout to the transaction settings (engine methods cannot move): re-summed at the 0.60.583.0 merge: 3174 + 4; +2 TLS default: the pg-tls import and the instance pool builds its options through withPgTls and turns a no-TLS refusal into postgres_tls_required (logic in pg-tls.ts; engine methods cannot move): 3178 + 2; +2 #7776 (GBRA-404 salvage): the schema-client-behind import and its assertSchemaNotAhead call in initSchema, re-summed on master 78419f76 (3179 + 2); +1 #9295: wantedProducers option on the listStalePagesForExtraction delegate signature (engine methods cannot move); +6 GBRA-574 B2: mergeOntologyFact clears the slot of a conversation fact that holds the observation's exact stint key before it inserts (engine methods cannot move; predicate in chronicle/ontology.ts)src/core/search/hybrid.ts 1562 ratchet +5 GBRA-81 item 5 per-stage search timings: HybridSearchOpts._timings (interface field) and the timer bindings and import in hybridSearch/hybridSearchCached (collector logic in search/stage-timings.ts); +2 W5 page-unit ranking cut: HybridSearchOpts.pageRankCut (logic in search/page-rank-cut.ts); +9 W3 confidence-gated reranking: HybridSearchOpts.rerankGate and the gate/lookup threading through rerankAndPin and sizeReturnPool (logic in search/hybrid/rerank-gate.ts, crag.ts gradePreRerank); re-summed at the W3 merge onto master v0.60.168.0 (1641 measured); +2 System One v1: HybridSearchOpts.decide (search/decide-stage.ts); refactor wave 1 split target (W4 hybrid, cut line); ceiling rationale: docs/architecture/key-files/core-search-1.md entry for src/core/search/hybrid.ts; +10 #5691: per-request embedding_query_prefix read once and threaded to the embeds and cache key; +5 green master wave (embedding opt-out): HybridSearchOpts._embeddingOptedOut (interface field) read once per request and threaded to the cache-lookup embed and the keyword-only gate; +24 P2 explain RRF attribution stamp in rrfFusionWeighted, backlink_count stamp, explain_target stage observations, explain/explainTarget opts; +14 fix wave 13 P4.8 #6400: lazyQueryEmbedDeadline (the query-embed deadline starts when the embed starts) and the _queryEmbedDeadline getter; +1 query facts arm: HybridSearchOpts.onQueryEmbedding (interface field; its one-line call is paid inside the ceiling) after the vector arms, so the facts arm reuses the query embedding without a second model call; re-summed at the master a08578ca5 merge (1591 master lines + 3 integration lines: the onQueryEmbedding hook); lowered to 1562: LHF wave 2 item 3 peeled cosineReScore into search/cosine-rescore.ts-src/core/types.ts 2363 ratchet +2 GBRA-504 slice 3: SearchResult.guest (interface field; logic in guests/marker.ts); +2 #8664 agent label: WriteAttributionView.agent_label (+ its doc line; the header, record and read live in persistence/attribution.ts and ops/attribution.ts) +3 train R: #7491 SearchOpts identifier-probe field and #7175 keywordPhrase option (interface fields); +2 GBRA-154 #7175: SearchOpts.keywordPhrase (opt-in phrase factor); +4 Wave B PR 1 (1c): Page.body_storage/body_bytes (interface fields; guard logic in page-body/page-shape.ts); +8 W3 confidence-gated reranking: HybridSearchMeta.rerank_gate (RerankGateMeta in search/hybrid/rerank-gate.ts); re-summed at the W3 merge onto master v0.60.168.0 (2279 measured); +7 fix wave 11 W6.2/W6.3 (#5989, #6132): SearchOpts.hnswIterativeScan and cjkKeyword, the keyword_candidates_incomplete stage and HybridSearchMeta.keyword_candidates (logic in engine-sql/cjk-search.ts); +5 System One v1 retrieval lane: SearchResult injection_p/injection_suspected, HybridSearchMeta answerability, egress_denied degraded reason; +4 System One v1: SearchResult rerank_score_kind/decide_evidence, HybridSearchMeta decide/rerank; +3 wave review: PAGE_SORT_SQL.updated_asc source_id + id tiebreakers (total order under federated scopes); +5 #4881: OntologyReadOpts extends PageReadScope doc; +3 #4857: PAGE_SORT_SQL.slug total-order tiebreaker comment; grown v0.46.26.0 megawave: EvidenceOpts, pacing/usage result fields, PageFilters growth (#4352 #4218); wave-k: +9 SalienceOpts/AnomaliesOpts source scope (#3867); +20 2026-09 adversarial batch 2: keyword_relaxed_carried stage + relaxed_dropped meta field docs; +16 2026-09 fix wave: SearchResult.keyword_relaxed field + full fusion-demotion doc; (#3867); +9: #4648 rerank_passthrough degraded stage + empty_result_set/malformed_shape reasons | merged v0.48.1.0 true-up; +master v0.48 merge true-up (reranker succession: no_key preflight, reranker_skipped stage, readiness); corrective release: shared internal PageReadScope and PageReadPolicy; ranker wave v0.48.4.0: HybridSearchMeta relational_rerank_pin / keyword_arm_confidence / metadata_boost_gate + SearchResult.relational_pinned (+48 over master's peel); +12: #4681 Page.updated_at_iso + keyset cursor precision docs; #5105: canonical page state shared module and transaction/snapshot delegates; #5105: public page revision fields; upstream integration: preserve independently reviewed master additions with branch facade extraction; #5252 wave: typed vector pool and readiness metadata; merged company ingestion/schema routing changes; retired provider integration removed; +1 write-path wave: 'created' effective-date source; +3 read-path wave: rerank_failed degraded stage + budget reason (closed vocabularies) and its recall classification note; +8 fw3-search: SearchOpts.source_boosts + keyword_arm_failed/title_arm_failed stages; +2 wave-2 W4: ChunkInput.embedding_input_hash (#5553); fix wave 3 x fix wave 2 (v0.60.5.0) composition: +2 at the merge; evidence delivery: optional SearchResult.delivered (+2; shape in search/evidence-delivery.ts); +2 eval wave N1-3: OntologyReadOpts.visibility (remote world-only ontology reads); +4 #5827: GraphNode.source_id and GraphPath from_source_id/to_source_id; +2 #5824: SearchOpts.vectorLegacyGuard rollback switch; +7 #5154: PageFilters.listColumnsOnly (interface field); +11 Foundations 1 F1b: WriteAttributionView + AttributedPageVersion (get_versions / get_write_attribution read shapes); +1 #5988: SearchResult.stale carries the held-file detail (interface field); +6 retrieval feedback: SearchResult feedback_boost/content_hash/relational_path_edges stamps and RelationalFanoutRow.path_edges (interface fields); +2 RelationalFanoutOpts.wide (interface field); 1 GBRA-49: temporal annotation field on link rows; 1 GBRA-49: temporal annotation field on link rows; 1 GBRA-49: temporal annotation field on link rows; +44 P7 ChainHopOpts/ChainHopEdge chain-hop contract types; P7 SearchResult.relational evidence + RelationalEvidence type + relational_plan meta + planner per-call overrides; +2 P7 SearchOpts.relationalChainSlots per-call override; +1 P7 ChainHopOpts.temporal (relationship-validity policy per hop); P3 x P7 (v0.60.60.0) composition: deltas re-summed at the merge; 1 GBRA-49: temporal annotation field on link rows; +44 P7 ChainHopOpts/ChainHopEdge chain-hop contract types; P7 SearchResult.relational evidence + RelationalEvidence type + relational_plan meta + planner per-call overrides; +2 P7 SearchOpts.relationalChainSlots per-call override; +1 P7 ChainHopOpts.temporal (relationship-validity policy per hop); +1 green master wave: embedding_disabled degraded reason (closed vocabulary); +2 #5951: Chunk.source_id (get_chunks names each row's source); 1 P2 SearchResult explain fields (rrf attribution, blend_norm_rrf, score_details, backlink_count) + RrfAttribution (interface fields); +11 #5575 (L1b): PageReadScope minTrust/suppressFlagged, SearchResult trust_tier/origin/unconfirmed, TimelineOpts eligibility (interface fields cannot move); +8 #4772 (W14 PR3): BrainHealth.entity_types_status field (interface fields cannot move); +1 C4: question page type row; +6 entity anchoring: optional SearchResult.entity_anchored row stamp (logic in search/entity-anchor.ts); +4 query facts arm: optional SearchResult.fact_row and superseded_claim row fields (logic in search/facts-arm.ts); +2 query facts arm: SearchResult result_type/fact_id/page_slug/follow_up (fact rows are never page-shaped); +9 Cat 40 Hard fix wave (#6271): SearchResult matched_alias/evidence_omitted/provenance, SearchOpts.rankQuery, keyword_count_unavailable stage and rerank_failed reasons; +12 fix wave 15 P2.1 (#6500): PageFilters.slugAfter (single-source slug keyset, interface field + doc) and the updated_desc tiebreaker comment (the keyset walk lives in facts/conversation-enumeration.ts); +2 wave 16 G5.1 (#6495): EngineConfig.keyword_statement_timeout_ms (interface field + doc); +2 GBRA-92: EngineConfig.pglite_shared_buffers (interface field + doc); +11 large pages (Wave A): Chunk/ChunkInput projected_byte_start/end interface fields (span logic in chunkers/recursive.ts, page-window/document.ts); +4 wave 18b lane 2 (#6495): SearchOpts.keywordTimeoutCache, the skipped_after_timeout degraded reason and the useCache doc line; integrated at wave 18b: master 2319 + 4; +2 LHF wave 2 item 3: retrieval meta cosine_rescore field (js_fallback disclosure; logic in search/cosine-rescore.ts); +14 GBRA-154 ranking wave (#4612 #7153 #7156 #7162 #7164): SearchResult collapsed/redirect_to/image_page/rank_prior/rank_score/fused_score stamps and HybridSearchMeta.collapse (interface fields; logic in search/collapse.ts, rank-priors.ts, score-contract.ts); GBRA-151 retrieval P0 x operability wave merge: both sides grew the file, re-summed (2343 measured); GBRA-156 retrieval wave (#7201) composed with #7194 at the merge: re-summed (2345 measured); GBRA-151 #7147 follow-up re-summed at the v0.60.338.0 merge (2347 measured); +2 GBRA-95 G7a follow-up: Page.withheld_source_path field; +2 #7600: SearchResult.quoted (interface field; logic in search/transcript-quote.ts); +1 #8377: ChronicleTimelineRow.trust_tier (interface field; chronicle reads quote rows by tier); re-summed at the train R merge with v0.60.574.0: 2354 + 1; re-measured at the Train A merge of #8943: 2361+src/core/types.ts 2365 ratchet +2 GST-2951: OntologyReadOpts.excludeDiary (interface field + doc; diary rows dropped before resolution in both engines); +2 GBRA-504 slice 3: SearchResult.guest (interface field; logic in guests/marker.ts); +2 #8664 agent label: WriteAttributionView.agent_label (+ its doc line; the header, record and read live in persistence/attribution.ts and ops/attribution.ts) +3 train R: #7491 SearchOpts identifier-probe field and #7175 keywordPhrase option (interface fields); +2 GBRA-154 #7175: SearchOpts.keywordPhrase (opt-in phrase factor); +4 Wave B PR 1 (1c): Page.body_storage/body_bytes (interface fields; guard logic in page-body/page-shape.ts); +8 W3 confidence-gated reranking: HybridSearchMeta.rerank_gate (RerankGateMeta in search/hybrid/rerank-gate.ts); re-summed at the W3 merge onto master v0.60.168.0 (2279 measured); +7 fix wave 11 W6.2/W6.3 (#5989, #6132): SearchOpts.hnswIterativeScan and cjkKeyword, the keyword_candidates_incomplete stage and HybridSearchMeta.keyword_candidates (logic in engine-sql/cjk-search.ts); +5 System One v1 retrieval lane: SearchResult injection_p/injection_suspected, HybridSearchMeta answerability, egress_denied degraded reason; +4 System One v1: SearchResult rerank_score_kind/decide_evidence, HybridSearchMeta decide/rerank; +3 wave review: PAGE_SORT_SQL.updated_asc source_id + id tiebreakers (total order under federated scopes); +5 #4881: OntologyReadOpts extends PageReadScope doc; +3 #4857: PAGE_SORT_SQL.slug total-order tiebreaker comment; grown v0.46.26.0 megawave: EvidenceOpts, pacing/usage result fields, PageFilters growth (#4352 #4218); wave-k: +9 SalienceOpts/AnomaliesOpts source scope (#3867); +20 2026-09 adversarial batch 2: keyword_relaxed_carried stage + relaxed_dropped meta field docs; +16 2026-09 fix wave: SearchResult.keyword_relaxed field + full fusion-demotion doc; (#3867); +9: #4648 rerank_passthrough degraded stage + empty_result_set/malformed_shape reasons | merged v0.48.1.0 true-up; +master v0.48 merge true-up (reranker succession: no_key preflight, reranker_skipped stage, readiness); corrective release: shared internal PageReadScope and PageReadPolicy; ranker wave v0.48.4.0: HybridSearchMeta relational_rerank_pin / keyword_arm_confidence / metadata_boost_gate + SearchResult.relational_pinned (+48 over master's peel); +12: #4681 Page.updated_at_iso + keyset cursor precision docs; #5105: canonical page state shared module and transaction/snapshot delegates; #5105: public page revision fields; upstream integration: preserve independently reviewed master additions with branch facade extraction; #5252 wave: typed vector pool and readiness metadata; merged company ingestion/schema routing changes; retired provider integration removed; +1 write-path wave: 'created' effective-date source; +3 read-path wave: rerank_failed degraded stage + budget reason (closed vocabularies) and its recall classification note; +8 fw3-search: SearchOpts.source_boosts + keyword_arm_failed/title_arm_failed stages; +2 wave-2 W4: ChunkInput.embedding_input_hash (#5553); fix wave 3 x fix wave 2 (v0.60.5.0) composition: +2 at the merge; evidence delivery: optional SearchResult.delivered (+2; shape in search/evidence-delivery.ts); +2 eval wave N1-3: OntologyReadOpts.visibility (remote world-only ontology reads); +4 #5827: GraphNode.source_id and GraphPath from_source_id/to_source_id; +2 #5824: SearchOpts.vectorLegacyGuard rollback switch; +7 #5154: PageFilters.listColumnsOnly (interface field); +11 Foundations 1 F1b: WriteAttributionView + AttributedPageVersion (get_versions / get_write_attribution read shapes); +1 #5988: SearchResult.stale carries the held-file detail (interface field); +6 retrieval feedback: SearchResult feedback_boost/content_hash/relational_path_edges stamps and RelationalFanoutRow.path_edges (interface fields); +2 RelationalFanoutOpts.wide (interface field); 1 GBRA-49: temporal annotation field on link rows; 1 GBRA-49: temporal annotation field on link rows; 1 GBRA-49: temporal annotation field on link rows; +44 P7 ChainHopOpts/ChainHopEdge chain-hop contract types; P7 SearchResult.relational evidence + RelationalEvidence type + relational_plan meta + planner per-call overrides; +2 P7 SearchOpts.relationalChainSlots per-call override; +1 P7 ChainHopOpts.temporal (relationship-validity policy per hop); P3 x P7 (v0.60.60.0) composition: deltas re-summed at the merge; 1 GBRA-49: temporal annotation field on link rows; +44 P7 ChainHopOpts/ChainHopEdge chain-hop contract types; P7 SearchResult.relational evidence + RelationalEvidence type + relational_plan meta + planner per-call overrides; +2 P7 SearchOpts.relationalChainSlots per-call override; +1 P7 ChainHopOpts.temporal (relationship-validity policy per hop); +1 green master wave: embedding_disabled degraded reason (closed vocabulary); +2 #5951: Chunk.source_id (get_chunks names each row's source); 1 P2 SearchResult explain fields (rrf attribution, blend_norm_rrf, score_details, backlink_count) + RrfAttribution (interface fields); +11 #5575 (L1b): PageReadScope minTrust/suppressFlagged, SearchResult trust_tier/origin/unconfirmed, TimelineOpts eligibility (interface fields cannot move); +8 #4772 (W14 PR3): BrainHealth.entity_types_status field (interface fields cannot move); +1 C4: question page type row; +6 entity anchoring: optional SearchResult.entity_anchored row stamp (logic in search/entity-anchor.ts); +4 query facts arm: optional SearchResult.fact_row and superseded_claim row fields (logic in search/facts-arm.ts); +2 query facts arm: SearchResult result_type/fact_id/page_slug/follow_up (fact rows are never page-shaped); +9 Cat 40 Hard fix wave (#6271): SearchResult matched_alias/evidence_omitted/provenance, SearchOpts.rankQuery, keyword_count_unavailable stage and rerank_failed reasons; +12 fix wave 15 P2.1 (#6500): PageFilters.slugAfter (single-source slug keyset, interface field + doc) and the updated_desc tiebreaker comment (the keyset walk lives in facts/conversation-enumeration.ts); +2 wave 16 G5.1 (#6495): EngineConfig.keyword_statement_timeout_ms (interface field + doc); +2 GBRA-92: EngineConfig.pglite_shared_buffers (interface field + doc); +11 large pages (Wave A): Chunk/ChunkInput projected_byte_start/end interface fields (span logic in chunkers/recursive.ts, page-window/document.ts); +4 wave 18b lane 2 (#6495): SearchOpts.keywordTimeoutCache, the skipped_after_timeout degraded reason and the useCache doc line; integrated at wave 18b: master 2319 + 4; +2 LHF wave 2 item 3: retrieval meta cosine_rescore field (js_fallback disclosure; logic in search/cosine-rescore.ts); +14 GBRA-154 ranking wave (#4612 #7153 #7156 #7162 #7164): SearchResult collapsed/redirect_to/image_page/rank_prior/rank_score/fused_score stamps and HybridSearchMeta.collapse (interface fields; logic in search/collapse.ts, rank-priors.ts, score-contract.ts); GBRA-151 retrieval P0 x operability wave merge: both sides grew the file, re-summed (2343 measured); GBRA-156 retrieval wave (#7201) composed with #7194 at the merge: re-summed (2345 measured); GBRA-151 #7147 follow-up re-summed at the v0.60.338.0 merge (2347 measured); +2 GBRA-95 G7a follow-up: Page.withheld_source_path field; +2 #7600: SearchResult.quoted (interface field; logic in search/transcript-quote.ts); +1 #8377: ChronicleTimelineRow.trust_tier (interface field; chronicle reads quote rows by tier); re-summed at the train R merge with v0.60.574.0: 2354 + 1; re-measured at the Train A merge of #8943: 2361src/core/minions/queue.ts 2574 ratchet grown #4078 + megawave probe-liveness unlatch (#4310) + master private-queue lifecycle: recovery classifier + monotonic lease; security: durable queued authority and confined filesystem dispatch; master integration: grown #4078 + megawave probe-liveness unlatch (#4310) + master private-queue lifecycle: recovery classifier + monotonic lease; harness support: boundary wiring to shared grants, isolated setup, withdrawal and delegated guards; merged v0.49: durable authority and delegated admission both enforced; typed readiness, configuration-blocked lifecycle and bounded release; +9: prune archives completed dream synthesis keys; +18 Lane D: deferJob (a deferral returns a job to delayed with no attempt counted and no stacktrace growth); the ceiling had 17 lines of slack; +5 agent operator follow-up Item 5 merged over master: claim-time spend fence token and legacy_default stamp (logic in minions/spend-authorization.ts); +5 GBRA-130 A-30: claim excludeWatchdogSuspects option (signature, doc and the mark parameter), the releaseWatchdogClaim delegate, and the co-runner stall call site in handleStalled (logic in minions/watchdog-attribution.ts); +5 GBRA-158 #7239/#7240: failJob result parameter (the #7216 hunk), jsonbSafeJson import and its call in add (sanitizer in text-safe.ts); +2 #7242 lane reservation: claim excludeNames option (doc line and the bound array; policy in minions/lanes.ts); +1 #7241 submitter label import (job-insight.ts) + 1 queue-families type import; #7252 x #7249 merge: both sides grew the file, re-summed (2544 measured); +3 GBRA-133: the stall sweep deletes a drain-lease holder record whose lease lock is gone or expired; +1 GST-2260: retryOnStalePlan import for completeJob/failJob (helper in retry-matcher.ts); +1 persistence train: add refuses a child under a finished parent (#8909); +9 GST-2529: the claim builds its parameters once for the overdue-suspect drain (a marked job past the worker's wait stops a busy worker claiming and leads an idle one's order); +16 GST-2529: hasOverdueWatchdogSuspect and overdueSuspectSql, the probe the worker runs every 5 s so a claim with no overdue marked job keeps the claim index ordersrc/commands/init.ts 1892 ratchet +2 fix wave 9 lane F #5253: leaving deferred setup also clears the DB-plane embedding_disabled row (both init branches); grown v0.46.x keyless capability notices; grown db-availability loop: initPostgresCore typed-failure extraction + --prefer-postgres ladder hook + pgvector rethrow fix; +1 at megawave/wave-k merge; +master-merge true-up; wave-k: merge; #3753 --force re-init engine-preservation guard; +1 wave-k merge-union brace (--prefer-postgres close); +10 ambient-writeback WP8: runWritebackNudge consent ask in both engine epilogues (logic lives in core/onboard/writeback-nudge.ts); +4: v0.48.2 reranker readiness at init + test seam; +1: v0.48.2 provider normalization; +3: v0.48.2 review fixes; master integration: +2: preserve typed PGLite busy errors in schema-only init; shared-skills integration on company-ingestion base; retired provider integration removed; retain stored-vector identity on re-init; -14: first-run bundle + quickstart registration helpers live in init-first-run.ts (writeback/skills asks folded into the bundle); +5 agent operator follow-up Item 2: --surface flag (value flag, parse, help line, module-level registration surface, type import) for the printed harness registration; +2 fix wave lane B3: both engine paths stamp a database init created as a fresh install for the behavior_changes notice (core/behavior-change-notice.ts); +4 GBRA-81 item 1: --search-mode value flag, its parse line, module-level choice, help line (picker logic lives in init-mode-picker.ts); +2 D8 funnel: a fresh init counts one clean_install when the opt-in funnel is on (core/funnel.ts); +1 GBRA-199: --surface help line names the default verbs listing; +7 GBRA-248 W0b: the implicit-keyless marker on both zero-key fallbacks, the deferred-hint gate on both engine paths and the kept-identity call in both (logic in commands/init-embedding-plane.ts)src/commands/integrations.ts 1739 ratchet grown v0.46.26.0 megawave (#4039 connector compat) + 1 nosemgrep dataflow annotation (path-traversal audit); wave-k: exported heartbeatPath seam (#3900)diff --git a/src/core/context/chronicle-context.ts b/src/core/context/chronicle-context.tsindex 6afc3f02b4..d5220475d6 100644--- a/src/core/context/chronicle-context.ts+++ b/src/core/context/chronicle-context.ts@@ -6,6 +6,7 @@// Pure composition of engine.getSince + engine.getOntology — no new SQL.import type { BrainEngine } from '../engine.ts';import type { ChronicleTimelineRow, OntologyValue, PageReadScope } from '../types.ts';+import { worldOnlyFacts } from '../search/private-visibility.ts';export interface ChronicleContextOpts extends PageReadScope {/** Lookback window in days for the recent timeline (default 7). */@@ -14,7 +15,7 @@ export interface ChronicleContextOpts extends PageReadScope {entities?: string[];/** Cap on timeline rows (default 50). */limit?: number;- /** Untrusted caller → only world-visibility ontology, diary-sourced rows redacted. */+ /** Untrusted caller → diary-sourced rows redacted, and world-visibility ontology only unless it is the brain owner (worldOnlyFacts). */remote?: boolean;sourceId?: string;sourceIds?: string[];@@ -44,7 +45,7 @@ export async function loadChronicleContext(const ontologies: Record<string, OntologyValue[]> = {};for (const slug of opts.entities ?? []) {- let vals = await engine.getOntology(slug, { ...scope, excludePrivate: opts.excludePrivate, visibility: opts.remote ? ['world'] : undefined });+ let vals = await engine.getOntology(slug, { ...scope, excludePrivate: opts.excludePrivate, visibility: worldOnlyFacts(opts.remote) ? ['world'] : undefined, excludeDiary: opts.remote !== false });if (opts.remote) vals = vals.filter((v) => !(v.source ?? '').startsWith('life/diary/'));if (vals.length) ontologies[slug] = vals;}diff --git a/src/core/engine-sql/facts.ts b/src/core/engine-sql/facts.tsindex e80f571849..6bbc26a87b 100644--- a/src/core/engine-sql/facts.ts+++ b/src/core/engine-sql/facts.ts@@ -691,9 +691,10 @@ export async function findTrajectory(exec: LegacyUnscopedRead, opts: import('../const useArray = Array.isArray(opts.sourceIds) && opts.sourceIds.length > 0;const sourceIds = useArray ? opts.sourceIds! : null;const sourceId = opts.sourceId ?? 'default';- // Fail-closed (CV6 / v0.26.9 F7b posture): anything not strictly local- // is remote. An omitted flag (cast-bypassed context, caller that forgot- // to thread it) degrades to world-only reads, never to a private-fact leak.+ // Fail-closed (CV6 / v0.26.9 F7b posture): `remote` means world-only facts here+ // (callers pass worldOnlyFacts(ctx.remote), so the brain owner's remote read passes+ // false); it gates only the visibility clause. An omitted flag degrades to+ // world-only reads, never to a private-fact leak.const remoteFilter = opts.remote !== false;// Source-scope predicate: array path (federated) wins over scalar.diff --git a/src/core/engine-sql/files.ts b/src/core/engine-sql/files.tsindex f4fa8869c0..e9e888e949 100644--- a/src/core/engine-sql/files.ts+++ b/src/core/engine-sql/files.ts@@ -12,6 +12,10 @@ import type { FileRow, FileSpec } from '../engine.ts';import { jsonbParam, type SqlExecutor } from './executor.ts';import type { LegacyUnscopedRead } from './brands.ts';import { sqlFragment } from './fragment.ts';+import { compileRowNormalizer } from './normalize.ts';++/** files.size_bytes is BIGINT, which postgres.js decodes as a BigInt; FileRow says number on every engine. */+const fileRow = compileRowNormalizer<FileRow>({ size_bytes: 'bigint' });export async function upsertFile(exec: SqlExecutor, spec: FileSpec): Promise<{ id: number; created: boolean }> {const sourceId = spec.source_id ?? 'default';@@ -34,21 +38,21 @@ export async function upsertFile(exec: SqlExecutor, spec: FileSpec): Promise<{ i}export async function getFile(exec: LegacyUnscopedRead, sourceId: string, storagePath: string): Promise<FileRow | null> {- const { rows } = await exec.run<FileRow>(sqlFragment`+ const { rows } = await exec.run(sqlFragment`SELECT id, source_id, page_slug, page_id, filename, storage_path, mime_type, size_bytes, content_hash, metadata, created_atFROM filesWHERE source_id = ${sourceId} AND storage_path = ${storagePath}LIMIT 1`);- return rows.length > 0 ? rows[0] : null;+ return rows.length > 0 ? fileRow(rows[0]) : null;}export async function listFilesForPage(exec: LegacyUnscopedRead, pageId: number): Promise<FileRow[]> {- const { rows } = await exec.run<FileRow>(sqlFragment`+ const { rows } = await exec.run(sqlFragment`SELECT id, source_id, page_slug, page_id, filename, storage_path, mime_type, size_bytes, content_hash, metadata, created_atFROM filesWHERE page_id = ${pageId}ORDER BY created_at ASC`);- return rows;+ return rows.map(row => fileRow(row));}diff --git a/src/core/engine.ts b/src/core/engine.tsindex 903fd04052..94a6c48b7e 100644--- a/src/core/engine.ts+++ b/src/core/engine.ts@@ -746,8 +746,8 @@ export interface FactsHealth {** `remote` (D-CDX-1) gates the visibility filter: when true the engine* adds `AND visibility = 'world'`, mirroring `recall`'s posture for- * untrusted callers. Local CLI keeps `remote: false` and sees both- * private + world facts.+ * untrusted callers. Callers pass worldOnlyFacts(ctx.remote), so the local+ * CLI and the brain owner see both private + world facts.*/export interface TrajectoryOpts {entitySlug: string;@@ -1933,7 +1933,7 @@ export interface BrainEngine {/** Meta-ontology: which dimensions exist across the brain, and how widely. */discoverOntologyDimensions(opts?: { sourceId?: string; sourceIds?: string[] }): Promise<OntologyDimensionStat[]>;/** Dimensions with ≥2 distinct current-open values from ≥2 provenances. */- findOntologyConflicts(opts?: PageReadScope & { minConfidence?: number; visibility?: OntologyReadOpts['visibility'] }): Promise<OntologyConflict[]>;+ findOntologyConflicts(opts?: PageReadScope & Pick<OntologyReadOpts, 'minConfidence' | 'visibility' | 'excludeDiary'>): Promise<OntologyConflict[]>;// Raw data/**diff --git a/src/core/operation-manifest.generated.ts b/src/core/operation-manifest.generated.tsindex 3dfaa988ef..eca9926bfa 100644--- a/src/core/operation-manifest.generated.ts+++ b/src/core/operation-manifest.generated.ts@@ -2791,7 +2791,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = ["mutating": false,"idempotent": true,"outputRedaction": "no_stored_text",- "description": "Admin read: who created and who last changed a page, or one of its facts, takes or timeline entries. Each attribution names the request id, operation, principal (kind, id, current name), time and origin (request, maintenance or unrecorded), plus the row's trust_tier and write_origin (for derived rows, the inputs that set the tier). Remote callers stay inside their source grant and see only world facts.",+ "description": "Admin read: who created and who last changed a page, or one of its facts, takes or timeline entries. Each attribution names the request id, operation, principal (kind, id, current name), time and origin (request, maintenance or unrecorded), plus the row's trust_tier and write_origin (for derived rows, the inputs that set the tier). Remote callers stay inside their source grant and see only world facts, except credentials bound to the brain owner.","params": {"slug": {"type": "string",diff --git a/src/core/ops/attribution.ts b/src/core/ops/attribution.tsindex b891567d90..55e60f3ec9 100644--- a/src/core/ops/attribution.ts+++ b/src/core/ops/attribution.ts@@ -18,7 +18,7 @@ import type { McpCall } from '../agent-output.ts';import { opTransport, paramUse, readFix } from './op-fix.ts';import { readHolders, readPolicyOpts } from './context.ts';import { storedTrustTier, type TrustTier, type WriteOrigin } from '../trust/tier.ts';-import { privateFactFilterForCaller } from '../search/private-visibility.ts';+import { privateFactFilterForReader, worldOnlyFacts } from '../search/private-visibility.ts';const DOCS = 'docs/mcp/ADMIN.md#write-attribution';@@ -138,7 +138,7 @@ const get_write_attribution: Operation = {description: 'Admin read: who created and who last changed a page, or one of its facts, takes or timeline entries. '+ 'Each attribution names the request id, operation, principal (kind, id, current name), time and origin '+ '(request, maintenance or unrecorded), plus the row\'s trust_tier and write_origin (for derived rows, the inputs that set the tier). '- + 'Remote callers stay inside their source grant and see only world facts.',+ + 'Remote callers stay inside their source grant and see only world facts, except credentials bound to the brain owner.',params: {slug: { type: 'string', required: true, description: 'Slug of the page to attribute (or the page that holds the fact, take or timeline entry).' },fact: { type: 'number', minimum: 1, description: 'Attribute this fact id (a fact about or fenced on the page) instead of the page.' },@@ -222,7 +222,7 @@ function rowTarget(ctx: OperationContext, pageId: number, slug: string, sourceIdif (ids.fact !== undefined) {return { kind: 'fact', label: `fact #${ids.fact}`, list: { tool: 'recall', arguments: { entity: slug } },sql: `SELECT id, ${cols} FROM facts WHERE id = $1 AND source_id = $2 AND (entity_slug = $3 OR source_markdown_slug = $3)- ${ctx.remote === false ? '' : "AND visibility = 'world'"} ${excludePrivate ? `AND ${privateFactFilterForCaller('facts')}` : ''}`, params: [ids.fact, sourceId, slug] };+ ${worldOnlyFacts(ctx.remote) ? "AND visibility = 'world'" : ''} ${excludePrivate ? `AND ${privateFactFilterForReader('facts')}` : ''}`, params: [ids.fact, sourceId, slug] };}if (ids.take !== undefined) {const holders = readHolders(ctx);diff --git a/src/core/ops/chronicle.ts b/src/core/ops/chronicle.tsindex 9c98dbeb38..7d20f92921 100644--- a/src/core/ops/chronicle.ts+++ b/src/core/ops/chronicle.ts@@ -10,7 +10,7 @@import type { Operation, OperationContext } from './contract.ts';import type { ChronicleTimelineRow, OntologyValue } from '../types.ts';import { readPolicyOpts, requireWritablePage, sourceScopeOpts } from './context.ts';-import { withFolderRestricted } from '../search/private-visibility.ts';+import { withFolderRestricted, worldOnlyFacts } from '../search/private-visibility.ts';import { invalidParam } from './op-fix.ts';import { quoteTimelineRows } from './timeline-quote.ts';import { quoteFacts, quotePageText, quotesStored, unquoteAnyTranscriptText, unquoteFactText } from '../search/transcript-quote.ts';@@ -184,10 +184,11 @@ const ontology_get: Operation = {asof: typeof p.asof === 'string' ? p.asof : undefined,minConfidence: typeof p.min_confidence === 'number' ? p.min_confidence : undefined,includeQuarantined: p.include_quarantined === true,- visibility: ctx.remote === false ? undefined : ['world'],+ visibility: worldOnlyFacts(ctx.remote) ? ['world'] : undefined,+ excludeDiary: ctx.remote !== false,...await readPolicyOpts(ctx),});- // Remote redaction: world-visibility rows only (as recall), resolved before+ // Remote redaction: the visibility recall reads (worldOnlyFacts), resolved before// DISTINCT ON; never surface diary-sourced ontology to untrusted callers.return ctx.remote !== false ? remoteOntology(ctx, rows.filter((r) => !(r.source ?? '').startsWith('life/diary/'))) : rows;},@@ -296,7 +297,8 @@ const ontology_conflicts: Operation = {handler: async (ctx, p) => {const conflicts = await ctx.engine.findOntologyConflicts({minConfidence: typeof p.min_confidence === 'number' ? p.min_confidence : undefined,- visibility: ctx.remote === false ? undefined : ['world'],+ visibility: worldOnlyFacts(ctx.remote) ? ['world'] : undefined,+ excludeDiary: ctx.remote !== false,...await readPolicyOpts(ctx),});if (ctx.remote === false) return conflicts;diff --git a/src/core/ops/insights.ts b/src/core/ops/insights.tsindex 6849698a50..4959c9e623 100644--- a/src/core/ops/insights.ts+++ b/src/core/ops/insights.ts@@ -347,14 +347,14 @@ const find_trajectory: Operation = {const until = typeof p.until === 'string' ? p.until : undefined;const limit = typeof p.limit === 'number' ? p.limit : undefined;const scope = sourceScopeOpts(ctx);- const { resolveExcludePrivatePages } = await import('../search/private-visibility.ts');+ const { resolveExcludePrivatePages, worldOnlyFacts } = await import('../search/private-visibility.ts');- // D-CDX-1: thread ctx.remote into the engine so visibility filtering- // happens at SQL level. Mirrors recall's posture for untrusted callers.+ // D-CDX-1: the engine filters visibility in SQL. GST-2951: world-only for every remote caller but the brain owner,+ // as recall and think's trajectory (worldOnlyFacts); page rules still apply through excludePrivate.const points = await ctx.engine.findTrajectory({entitySlug: p.entity_slug,...scope,- remote: ctx.remote !== false, // fail-closed: anything not strictly false is untrusted (CLAUDE.md invariant)+ remote: worldOnlyFacts(ctx.remote),excludePrivate: await resolveExcludePrivatePages(ctx.engine, ctx.remote),metric,kind,diff --git a/src/core/pglite-engine.ts b/src/core/pglite-engine.tsindex 56d1975d24..850abfe2a5 100644--- a/src/core/pglite-engine.ts+++ b/src/core/pglite-engine.ts@@ -126,7 +126,7 @@ import { resolveBoostMap, resolveHardExcludes } from './search/source-boost.ts';import { buildSourceFactorCase, buildHardExcludeClause, buildVisibilityClause, buildBestPerPagePoolCte, buildOrFallbackWebsearchQuery, boundWebsearchQuery, collapseWebsearchDashRuns, keywordPhraseFactorSql } from './search/sql-ranking.ts';import { RARE_TERM_CHUNK_CAP, rankOrFallbackByRarity, rareTermPagesSql, type RareTermPages } from './search/keyword-or-rarity.ts';import { keywordArmRows } from './search/keyword-identifier-probe.ts';-import { privatePagesFilterFragment, privateSnapshotFilterFragment, privateLinkOriginFilterFragment, privateTimelineEventFilterFragment, privateFactFilterForCaller, privatePagesFilterForCaller } from './search/private-visibility.ts';+import { privatePagesFilterFragment, privateSnapshotFilterFragment, privateLinkOriginFilterFragment, privateTimelineEventFilterFragment, privateFactFilterForReader, privatePagesFilterForCaller } from './search/private-visibility.ts';import { deletedPageProjectionHiddenSql } from './eligibility/sql.ts';import { EMBED_SKIP_FILTER_FRAGMENT } from './embed-skip.ts';import {@@ -2216,7 +2216,7 @@ export class PGLiteEngine implements BrainEngine {else { params.push(opts?.sourceId ?? null); scope = `AND ($${params.length}::text IS NULL OR source_id = $${params.length})`; }// Page-visibility gate on the provenance and entity pages, applied BEFORE DISTINCT ON// so the untrusted caller resolves the newest value they may see; a deleted page's observations are hidden for everyone.- const privacy = `AND ${deletedPageProjectionHiddenSql('facts', 'facts')}${opts?.excludePrivate ? ` AND ${privateFactFilterForCaller('facts')}` : ''}`;+ const privacy = `AND ${deletedPageProjectionHiddenSql('facts', 'facts')}${opts?.excludePrivate ? ` AND ${privateFactFilterForReader('facts')}` : ''}${opts?.excludeDiary ? ` AND NOT starts_with(COALESCE(source_markdown_slug, ''), 'life/diary/')` : ''}`;params.push(opts?.visibility ?? null);const visibility = `AND ($${params.length}::text[] IS NULL OR visibility = ANY($${params.length}::text[]))`;const r = await this.db.query(@@ -2252,7 +2252,7 @@ export class PGLiteEngine implements BrainEngine {});}- async findOntologyConflicts(opts?: PageReadScope & { minConfidence?: number; visibility?: OntologyReadOpts['visibility'] }): Promise<OntologyConflict[]> {+ async findOntologyConflicts(opts?: PageReadScope & Pick<OntologyReadOpts, 'minConfidence' | 'visibility' | 'excludeDiary'>): Promise<OntologyConflict[]> {const minConf = opts?.minConfidence ?? 0;const params: unknown[] = [minConf];let scope: string;@@ -2260,7 +2260,7 @@ export class PGLiteEngine implements BrainEngine {else { params.push(opts?.sourceId ?? null); scope = `AND ($${params.length}::text IS NULL OR source_id = $${params.length})`; }// Same page gates as getOntology, inside the CTE so a conflict// that only exists because of a hidden provenance is never reported.- const privacy = `AND ${deletedPageProjectionHiddenSql('facts', 'facts')}${opts?.excludePrivate ? ` AND ${privateFactFilterForCaller('facts')}` : ''}`;+ const privacy = `AND ${deletedPageProjectionHiddenSql('facts', 'facts')}${opts?.excludePrivate ? ` AND ${privateFactFilterForReader('facts')}` : ''}${opts?.excludeDiary ? ` AND NOT starts_with(COALESCE(source_markdown_slug, ''), 'life/diary/')` : ''}`;params.push(opts?.visibility ?? null);const visibility = `AND ($${params.length}::text[] IS NULL OR visibility = ANY($${params.length}::text[]))`;const r = await this.db.query(diff --git a/src/core/postgres-engine.ts b/src/core/postgres-engine.tsindex d26062a8cb..d699180086 100644--- a/src/core/postgres-engine.ts+++ b/src/core/postgres-engine.ts@@ -124,7 +124,7 @@ import { commonOrTokens, narrowedOrFallbackText, readOrTokenShares } from './seaimport { keywordArmRows } from './search/keyword-identifier-probe.ts';import { RARE_TERM_CHUNK_CAP, rankOrFallbackByRarity, rareTermPagesSql, type RareTermPages } from './search/keyword-or-rarity.ts';import { buildKeywordChunkMatch, keywordCandidatesSql, KEYWORD_RANK_CANDIDATES, KEYWORD_RANKED_ROWS_CTE, KEYWORD_STATEMENT_SETTINGS } from './search/keyword-chunk-match.ts';-import { privatePagesFilterFragment, privateSnapshotFilterFragment, privateLinkOriginFilterFragment, privateTimelineEventFilterFragment, privateFactFilterForCaller, privatePagesFilterForCaller } from './search/private-visibility.ts';+import { privatePagesFilterFragment, privateSnapshotFilterFragment, privateLinkOriginFilterFragment, privateTimelineEventFilterFragment, privateFactFilterForReader, privatePagesFilterForCaller } from './search/private-visibility.ts';import { deletedPageProjectionHiddenSql } from './eligibility/sql.ts';import { DEFAULT_EMBEDDING_MODEL, DEFAULT_EMBEDDING_DIMENSIONS } from './ai/defaults.ts';import { readStoredEmbeddingIdentity } from './stored-embedding-identity.ts';@@ -524,7 +524,8 @@ export class PostgresEngine implements BrainEngine {}private async disconnectInternal(): Promise<void> {- for (const stop of this._beforeDisconnect) await stop();+ const open = !!this.connectionManager || !!this._sql || this._connectionStyle === 'module';+ if (open) for (const stop of this._beforeDisconnect) await stop(); // hooks run once, as PGLite's early return does// v0.41.25.0 (#1570) — instrument disconnect calls to identify the// mid-process caller behind the singleton-null bug. The audit log// captures connection_style so we can tell instance-pool teardowns@@ -541,9 +542,7 @@ export class PostgresEngine implements BrainEngine {// residual telemetry buffers are dropped on BOTH engines (symmetric lossy// semantics; the CLI-exit drain is where residuals flush). Guarded so a// no-op disconnect (never connected / already torn down) skips the drain.- if (this.connectionManager || this._sql || this._connectionStyle === 'module') {- await drainBackgroundWorkBeforeDisconnect();- }+ if (open) await drainBackgroundWorkBeforeDisconnect();// v0.30.1: tear down the direct pool first if the manager owns one.if (this.connectionManager) {await this.connectionManager.disconnect();@@ -2037,7 +2036,7 @@ export class PostgresEngine implements BrainEngine {? sql`AND source_id = ANY(${opts.sourceIds})`: sql`AND (${opts?.sourceId ?? null}::text IS NULL OR source_id = ${opts?.sourceId ?? null})`;// Provenance/entity page gates and the deleted-page hide, BEFORE DISTINCT ON: the caller gets the newest value they may see.- const privacy = sql.unsafe(`AND ${deletedPageProjectionHiddenSql('facts', 'facts')}${opts?.excludePrivate ? ` AND ${privateFactFilterForCaller('facts')}` : ''}`);+ const privacy = sql.unsafe(`AND ${deletedPageProjectionHiddenSql('facts', 'facts')}${opts?.excludePrivate ? ` AND ${privateFactFilterForReader('facts')}` : ''}${opts?.excludeDiary ? ` AND NOT starts_with(COALESCE(source_markdown_slug, ''), 'life/diary/')` : ''}`);const visibility = opts?.visibility ? sql`AND visibility = ANY(${opts.visibility})` : sql``;const rows = await sql<OntologyValue[]>`SELECT DISTINCT ON (dimension)@@ -2068,7 +2067,7 @@ export class PostgresEngine implements BrainEngine {return rows.map((r) => ({ dimension: r.dimension, entities: Number(r.entities), observations: Number(r.observations) }));}- async findOntologyConflicts(opts?: PageReadScope & { minConfidence?: number; visibility?: OntologyReadOpts['visibility'] }): Promise<OntologyConflict[]> {+ async findOntologyConflicts(opts?: PageReadScope & Pick<OntologyReadOpts, 'minConfidence' | 'visibility' | 'excludeDiary'>): Promise<OntologyConflict[]> {const sql = this.sql;const minConf = opts?.minConfidence ?? 0;const scope = opts?.sourceIds && opts.sourceIds.length@@ -2076,7 +2075,7 @@ export class PostgresEngine implements BrainEngine {: sql`AND (${opts?.sourceId ?? null}::text IS NULL OR source_id = ${opts?.sourceId ?? null})`;// Same page gates as getOntology, inside the CTE so a conflict// that only exists because of a hidden provenance is never reported.- const privacy = sql.unsafe(`AND ${deletedPageProjectionHiddenSql('facts', 'facts')}${opts?.excludePrivate ? ` AND ${privateFactFilterForCaller('facts')}` : ''}`);+ const privacy = sql.unsafe(`AND ${deletedPageProjectionHiddenSql('facts', 'facts')}${opts?.excludePrivate ? ` AND ${privateFactFilterForReader('facts')}` : ''}${opts?.excludeDiary ? ` AND NOT starts_with(COALESCE(source_markdown_slug, ''), 'life/diary/')` : ''}`);const visibility = opts?.visibility ? sql`AND visibility = ANY(${opts.visibility})` : sql``;const rows = await sql<{ entity_slug: string; dimension: string; values: OntologyConflict['values'] }[]>`WITH cur AS (diff --git a/src/core/search/private-visibility.ts b/src/core/search/private-visibility.tsindex 96f27aea30..ce95fdb24a 100644--- a/src/core/search/private-visibility.ts+++ b/src/core/search/private-visibility.ts@@ -1013,6 +1013,15 @@ export function privateFactFilterForCaller(factAlias: string, perCandidate = falreturn `(${privateProvenanceFilterFragment(factAlias)} AND ${privateEntityFilterForCaller(factAlias, perCandidate)}${labelledOnlyFactSql(factAlias)})`;}+/**+ * GST-2951: the page gate for a fact read whose visibility follows worldOnlyFacts. The brain owner's read is judged by+ * the policy recall and find_trajectory use (privateProvenanceFilterUnderPolicy), so the owner keeps facts taken from a+ * private page it reads, while member access still applies; every other caller keeps privateFactFilterForCaller.+ */+export function privateFactFilterForReader(factAlias: string): string {+ return callerIsOwner() ? privateProvenanceFilterUnderPolicy(factAlias) : privateFactFilterForCaller(factAlias);+}+/** True only inside a remote caller record whose read an operator relaxed (the env hatch or the config opt-out). */export function callerRelaxesPrivacy(): boolean {return callerAccessStore.getStore()?.hidePrivate === false;diff --git a/src/core/types.ts b/src/core/types.tsindex 41b2d379a7..7d277d7cb8 100644--- a/src/core/types.ts+++ b/src/core/types.ts@@ -1866,6 +1866,8 @@ export interface OntologyReadOpts extends PageReadScope {sourceIds?: string[];/** Fact visibility tiers the caller may read; undefined reads every tier. */visibility?: Array<'private' | 'world'>;+ /** Leave out observations whose provenance is a life/diary/ page, before each dimension resolves (remote callers). */+ excludeDiary?: boolean;}// Raw datadiff --git a/test/access-owner-fact-ops-gst2951.test.ts b/test/access-owner-fact-ops-gst2951.test.tsnew file mode 100644index 0000000000..3ff4602606--- /dev/null+++ b/test/access-owner-fact-ops-gst2951.test.ts@@ -0,0 +1,252 @@+/**+ * GST-2951: the brain owner's own remote agents read private facts through find_trajectory, get_write_attribution,+ * ontology_get, ontology_conflicts and volunteer_chronicle, as they already do through recall, query and think+ * (GST-2089, access-owner-reads.test.ts).+ *+ * 1. Protects: a credential bound to the member access.owner_member names gets the owner's private facts from each of+ * those operations. Every other caller reads exactly what it read before: another member, a labelled-only member, an+ * unbound token, a call with no credential, and the owner's credential speaking for an audience of several get+ * world-only facts; a credential with the private-facts grant keeps it on find_trajectory (the one of these operations+ * that honours it) and gains nothing on the others. Page rules stay: the owner reads no fact taken from another+ * person's readable_by page, and no caller reads a withdrawn fact.+ * 2. Fails when: these operations decide fact visibility from the raw remote flag again (the owner gets world-only+ * facts), or a non-owner caller reads a private fact.+ * 3. Existing coverage: access-owner-reads pins recall, query, hot memory, delta, context_pack and think's trajectory;+ * none of these five operations is in it.+ * 4. Real seams: tokens minted by the token service and verified by the serve --http verifier, dispatched through MCP+ * dispatch as serve-http-mcp does (remote: true), on a repo-less brain; PGLite, and Postgres when DATABASE_URL is set.+ */+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+import type { BrainEngine } from '../src/core/engine.ts';+import { PGLiteEngine } from '../src/core/pglite-engine.ts';+import { importFromContent } from '../src/core/import-file.ts';+import { GBrainOAuthProvider } from '../src/core/oauth-provider.ts';+import { sqlQueryForEngine } from '../src/core/sql-query.ts';+import { mintLegacyToken } from '../src/core/token-mint.ts';+import { noGrantFederatedScope } from '../src/core/source-resolver.ts';+import { dispatchToolCall } from '../src/mcp/dispatch.ts';+import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';+import { setOwner } from '../src/core/access/owner.ts';+import { bindCredential } from '../src/core/access/members.ts';+import { setMemberLabelledOnly } from '../src/core/access/labelled-only.ts';+import { parseRescopeTokenArgs, rescopeLegacyToken } from '../src/core/grants/legacy-token.ts';+import type { AuthInfo } from '../src/core/ops/contract.ts';+import { testBackends } from './helpers/test-backends.ts';+import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';+import { readsUnscopedOnPurpose } from './helpers/reads-unscoped.ts';++const SRC = 'own-src';+const OWNER = 'owner-example';+const ENTITY = 'people/dana-example';+const WORLD_PAGE = 'notes/open-ledger';+const BOBS_PAGE = 'notes/bob-ledger';+/** Private facts the owner reads and no other caller does. */+const OWN = { trajectory: 'canaryowntrajpoint', ontology: 'canaryownontology' } as const;+/** Facts nobody remote reads: one taken from another person's readable_by page, and withdrawn ones. */+const BOBS = { trajectory: 'canarybobtrajpoint', ontology: 'canarybobontology' } as const;+const WITHDRAWN = { trajectory: 'canarygonetrajpoint', ontology: 'canarygoneontology' } as const;+/** A private fact on a world page: the private-facts grant admits it. */+const GRANTED = 'canarygrantedtrajpoint';+const WORLD = 'canaryworldtrajpoint';+/** Private facts taken from a private page the owner reads (visibility: private, no readers). */+const OWNERS_PAGE = 'notes/owner-ledger';+const OWN_PAGE = { trajectory: 'canaryownpagetrajpoint', ontology: 'canaryownpageontology' } as const;+/** A newer private observation from a diary page and the older one beside it that a remote reader still gets. */+const DIARY = 'canarydiarysleep';+const BEHIND_DIARY = 'canaryvisiblesleep';++type Surface = 'find_trajectory' | 'ontology_get' | 'ontology_conflicts' | 'volunteer_chronicle';+const SURFACES: Surface[] = ['find_trajectory', 'ontology_get', 'ontology_conflicts', 'volunteer_chronicle'];+const READS: Record<Surface, [string, Record<string, unknown>]> = {+ find_trajectory: ['find_trajectory', { entity_slug: ENTITY }],+ ontology_get: ['ontology_get', { entity: ENTITY }],+ ontology_conflicts: ['ontology_conflicts', {}],+ volunteer_chronicle: ['volunteer_chronicle', { entities: ENTITY }],+};+const CANARY: Record<Surface, keyof typeof OWN> = { find_trajectory: 'trajectory', ontology_get: 'ontology', ontology_conflicts: 'ontology', volunteer_chronicle: 'ontology' };++for (const kind of testBackends()) {+ describe(`owner fact operations (${kind}, repo-less)`, () => {+ let engine: BrainEngine;+ let close: () => Promise<void>;+ const tokens: Record<string, string> = {};+ const ids: Record<string, number> = {};+ const provider = () => new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });++ /** One MCP call as serve --http makes it; `anonymous` carries no credential at all. */+ async function call(who: string, op: string, params: Record<string, unknown>, header?: string): Promise<{ isError: boolean; text: string }> {+ __resetPrivateVisibilityCacheForTests();+ if (who === 'anonymous') {+ const out = await dispatchToolCall(engine, op, { ...params }, { remote: true, transport: 'http', sourceId: SRC, takesHoldersAllowList: ['world'] });+ return { isError: out.isError === true, text: out.content.map(c => c.text).join('\n') };+ }+ const auth = await provider().verifyAccessToken(tokens[who]!) as unknown as AuthInfo;+ const sourceId = auth.sourceId ?? 'default';+ const localFederated = await noGrantFederatedScope(engine, auth.hasSourceGrant, sourceId);+ const out = await dispatchToolCall(engine, op, { ...params }, {+ remote: true, transport: 'http', auth, sourceId, takesHoldersAllowList: auth.takesHoldersAllowList ?? ['world'],+ ...(localFederated ? { localFederatedSourceIds: localFederated } : {}), ...(header ? { onBehalfOf: { header } } : {}),+ });+ return { isError: out.isError === true, text: out.content.map(c => c.text).join('\n') };+ }++ /** The surfaces on which `who` reads the private fact of `set`. */+ async function seenBy(who: string, set: Record<keyof typeof OWN, string>, header?: string): Promise<Surface[]> {+ const seen: Surface[] = [];+ for (const surface of SURFACES) {+ const [op, params] = READS[surface];+ const out = await call(who, op, params, header);+ if (out.isError) throw new Error(`${who} ${op}: ${out.text}`);+ if (out.text.includes(set[CANARY[surface]])) seen.push(surface);+ }+ return seen;+ }++ /** `who` (an admin credential) asks for the write attribution of fact `id`: true, or the refusal's code. */+ async function attributes(who: string, id: number, header?: string): Promise<true | string> {+ const out = await call(who, 'get_write_attribution', { slug: ENTITY, fact: id }, header);+ return out.isError ? String((JSON.parse(out.text) as { code?: unknown }).code) : true;+ }++ const insertFact = async (canary: string, visibility: 'private' | 'world', provenance: string | null, validFrom: string) => {+ const [row] = await engine.executeRaw<{ id: number | string }>(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, valid_from, source, event_type, source_markdown_slug)+ VALUES ($1, $2, $3, 'event', $4, $5, 'fixture', 'job_change', $6) RETURNING id`, [SRC, ENTITY, `Dana switched jobs ${canary}`, visibility, validFrom, provenance]);+ return Number(row!.id);+ };+ const insertObservation = async (dimension: string, value: string, provenance: string, validFrom: string) => {+ const [row] = await engine.executeRaw<{ id: number | string }>(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, dimension, value, value_hash, confidence, source, source_markdown_slug, valid_from)+ VALUES ($1, $2, $3, 'fact', 'private', $4, $5, md5($5), 0.8, $6, $6, $7) RETURNING id`, [SRC, ENTITY, `${dimension}: ${value}`, dimension, value, provenance, validFrom]);+ return Number(row!.id);+ };++ beforeAll(async () => {+ if (kind === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));+ else { engine = new PGLiteEngine(); await engine.connect({ engine: 'pglite' } as never); await engine.initSchema(); close = () => engine.disconnect(); }+ __resetPrivateVisibilityCacheForTests();+ await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1) ON CONFLICT (id) DO NOTHING', [SRC]);+ const page = (title: string, fm: string[] = []) => ['---', 'type: note', `title: ${title}`, ...fm, '---', `# ${title}`, '', 'Ledger notes.'].join('\n');+ await importFromContent(engine, ENTITY, ['---', 'type: person', 'title: Dana Example', '---', '# Dana Example', '', 'Dana is a founder.'].join('\n'), { sourceId: SRC });+ await importFromContent(engine, WORLD_PAGE, page('Open ledger'), { sourceId: SRC });+ await importFromContent(engine, BOBS_PAGE, page('Bob ledger', ['readable_by: [bob-example]']), { sourceId: SRC });+ await importFromContent(engine, OWNERS_PAGE, page('Owner ledger', ['visibility: private']), { sourceId: SRC });++ ids.own = await insertFact(OWN.trajectory, 'private', null, '2026-05-01T00:00:00Z');+ ids.bobs = await insertFact(BOBS.trajectory, 'private', BOBS_PAGE, '2026-05-02T00:00:00Z');+ ids.withdrawn = await insertFact(WITHDRAWN.trajectory, 'private', null, '2026-05-03T00:00:00Z');+ ids.withdrawnWorld = await insertFact('canarygoneworldpoint', 'world', null, '2026-05-03T00:00:00Z');+ ids.granted = await insertFact(GRANTED, 'private', WORLD_PAGE, '2026-05-04T00:00:00Z');+ ids.world = await insertFact(WORLD, 'world', null, '2026-05-05T00:00:00Z');+ // Two current values from two provenances: ontology_conflicts reports the pair.+ await insertObservation('risk_tolerance', `low ${OWN.ontology}`, 'notes/source-a-example', '2026-01-01T00:00:00Z');+ await insertObservation('risk_tolerance', `high ${OWN.ontology}`, 'notes/source-b-example', '2026-02-01T00:00:00Z');+ await insertObservation('mood', `calm ${BOBS.ontology}`, BOBS_PAGE, '2026-02-01T00:00:00Z');+ await insertObservation('mood', 'tense', 'notes/source-c-example', '2026-01-01T00:00:00Z');+ ids.withdrawnObservation = await insertObservation('status', `gone ${WITHDRAWN.ontology}`, 'notes/source-d-example', '2026-02-01T00:00:00Z');+ ids.ownPage = await insertFact(OWN_PAGE.trajectory, 'private', OWNERS_PAGE, '2026-05-06T00:00:00Z');+ await insertObservation('focus', `climbing ${OWN_PAGE.ontology}`, OWNERS_PAGE, '2026-02-01T00:00:00Z');+ await insertObservation('focus', 'running', 'notes/source-e-example', '2026-01-01T00:00:00Z');+ await insertObservation('sleep', `early ${BEHIND_DIARY}`, 'notes/source-f-example', '2026-01-01T00:00:00Z');+ await insertObservation('sleep', `late ${DIARY}`, 'life/diary/2026-02-01', '2026-02-01T00:00:00Z');+ for (const id of [ids.withdrawn, ids.withdrawnWorld, ids.withdrawnObservation]) {+ const forgot = await dispatchToolCall(engine, 'forget_fact', { id }, { remote: false, sourceId: SRC });+ if (forgot.isError) throw new Error(`fixture forget: ${forgot.content.map(c => c.text).join(' ')}`);+ }++ for (const id of [OWNER, 'bob-example', 'lab-example']) await engine.executeRaw('INSERT INTO access_members (id) VALUES ($1)', [id]);+ await setMemberLabelledOnly(engine, 'lab-example', true, { remote: false });+ const mint = async (name: string, scopes: string[], member?: string, mayActFor?: string[]) => {+ const minted = await mintLegacyToken(engine, { name, scopes, takesHolders: ['world'], sourceGrant: [SRC] });+ tokens[name] = minted.token;+ if (member) await bindCredential(engine, { kind: 'token', id: minted.id }, { member, ...(mayActFor ? { mayActFor } : {}) });+ else await readsUnscopedOnPurpose(engine, minted.id);+ };+ const audience = [`member:${OWNER}`, 'member:bob-example'];+ for (const [suffix, scopes] of [['', ['read']], ['-admin', ['read', 'admin']]] as const) {+ await mint(`owner${suffix}`, [...scopes], OWNER, audience);+ await mint(`delegate${suffix}`, [...scopes], OWNER);+ await mint(`bob${suffix}`, [...scopes], 'bob-example');+ await mint(`lab${suffix}`, [...scopes], 'lab-example');+ await mint(`unbound${suffix}`, [...scopes]);+ await mint(`granted${suffix}`, [...scopes]);+ await rescopeLegacyToken(engine, parseRescopeTokenArgs([`granted${suffix}`, '--private-facts', 'granted-sources']));+ }+ await setOwner(engine, OWNER);+ }, 240_000);++ afterAll(async () => { await close?.(); }, 60_000);++ const AUDIENCE = `member:${OWNER},member:bob-example`;++ test('fixture control: a trusted local caller reads every private fact but the withdrawn ones on every surface', async () => {+ for (const surface of SURFACES) {+ const [op, params] = READS[surface];+ const text = (await dispatchToolCall(engine, op, params, { remote: false, sourceId: SRC })).content.map(c => c.text).join('\n');+ const k = CANARY[surface];+ expect({ surface, own: text.includes(OWN[k]), bobs: text.includes(BOBS[k]), withdrawn: text.includes(WITHDRAWN[k]) }).toEqual({ surface, own: true, bobs: true, withdrawn: false });+ }+ }, 120_000);++ test('the owner and a delegate bound to the owner read their private facts on every surface', async () => {+ for (const who of ['owner', 'delegate']) expect({ who, seen: await seenBy(who, OWN) }).toEqual({ who, seen: SURFACES });+ expect(await seenBy('owner', OWN, `member:${OWNER}`)).toEqual(SURFACES);+ }, 240_000);++ test('the owner\'s admin credential gets the write attribution of a private fact', async () => {+ for (const who of ['owner-admin', 'delegate-admin']) expect({ who, attributed: await attributes(who, ids.own!) }).toEqual({ who, attributed: true });+ }, 120_000);++ test('another member, a labelled-only member, an unbound token, no credential and the owner for an audience read no private fact', async () => {+ for (const who of ['bob', 'lab', 'unbound', 'anonymous']) expect({ who, seen: await seenBy(who, OWN) }).toEqual({ who, seen: [] });+ expect(await seenBy('owner', OWN, AUDIENCE)).toEqual([]);+ for (const who of ['bob-admin', 'unbound-admin', 'granted-admin']) expect({ who, attributed: await attributes(who, ids.own!) }).toEqual({ who, attributed: 'fact_not_found' });+ // A labelled-only member reads no page that does not name it, so the entity page itself reads as missing.+ expect(await attributes('lab-admin', ids.own!)).toBe('page_not_found');+ expect(await attributes('owner-admin', ids.own!, AUDIENCE)).toBe('fact_not_found');+ expect((await call('bob', 'find_trajectory', { entity_slug: ENTITY })).text).toContain(WORLD);+ expect(await attributes('bob-admin', ids.world!)).toBe(true);+ }, 240_000);++ test('the private-facts grant still admits a private fact on a world page to find_trajectory, and nothing else changes for it', async () => {+ const trajectory = (await call('granted', 'find_trajectory', { entity_slug: ENTITY })).text;+ expect({ granted: trajectory.includes(GRANTED), own: trajectory.includes(OWN.trajectory) }).toEqual({ granted: true, own: false });+ expect(await seenBy('granted', OWN)).toEqual([]);+ for (const who of ['bob', 'unbound']) expect({ who, granted: (await call(who, 'find_trajectory', { entity_slug: ENTITY })).text.includes(GRANTED) }).toEqual({ who, granted: false });+ }, 120_000);++ test('member access stays mandatory for the owner: no fact taken from another person\'s readable_by page', async () => {+ expect(await seenBy('owner', BOBS)).toEqual([]);+ expect(await attributes('owner-admin', ids.bobs!)).toBe('fact_not_found');+ }, 240_000);++ test('the owner reads private facts taken from a private page it reads, on every surface and in write attribution', async () => {+ for (const who of ['owner', 'delegate']) expect({ who, seen: await seenBy(who, OWN_PAGE) }).toEqual({ who, seen: SURFACES });+ expect(await attributes('owner-admin', ids.ownPage!)).toBe(true);+ for (const who of ['bob', 'unbound']) expect({ who, seen: await seenBy(who, OWN_PAGE) }).toEqual({ who, seen: [] });+ expect(await seenBy('owner', OWN_PAGE, AUDIENCE)).toEqual([]);+ expect(await attributes('bob-admin', ids.ownPage!)).toBe('fact_not_found');+ }, 240_000);++ test('a newer diary observation neither reaches the owner nor hides the older value behind it', async () => {+ for (const who of ['owner', 'delegate']) {+ for (const [op, params] of [READS.ontology_get, READS.volunteer_chronicle]) {+ const text = (await call(who, op, params)).text;+ expect({ who, op, behind: text.includes(BEHIND_DIARY), diary: text.includes(DIARY) }).toEqual({ who, op, behind: true, diary: false });+ }+ expect((await call(who, ...READS.ontology_conflicts)).text).not.toContain(DIARY);+ }+ const local = (await dispatchToolCall(engine, 'ontology_get', READS.ontology_get[1], { remote: false, sourceId: SRC })).content.map(c => c.text).join('\n');+ expect(local).toContain(DIARY);+ }, 240_000);++ test('no caller reads a withdrawn fact', async () => {+ for (const who of ['owner', 'delegate', 'bob', 'unbound']) expect({ who, seen: await seenBy(who, WITHDRAWN) }).toEqual({ who, seen: [] });+ }, 240_000);++ test('write attribution keeps its audit reach: it names who wrote a withdrawn row, never its text, for the owner as for any admin on a world row', async () => {+ const owner = await call('owner-admin', 'get_write_attribution', { slug: ENTITY, fact: ids.withdrawn! });+ expect({ isError: owner.isError, text: owner.text.includes(WITHDRAWN.trajectory) }).toEqual({ isError: false, text: false });+ expect(await attributes('bob-admin', ids.withdrawnWorld!)).toBe(true);+ expect(await attributes('bob-admin', ids.withdrawn!)).toBe('fact_not_found');+ }, 120_000);+ });+}diff --git a/test/e2e/multimodal-postgres.test.ts b/test/e2e/multimodal-postgres.test.tsindex 6f254a4822..336bc13dd1 100644--- a/test/e2e/multimodal-postgres.test.ts+++ b/test/e2e/multimodal-postgres.test.ts@@ -135,6 +135,9 @@ describe.skipIf(skip)('multimodal v0.27.1 against real Postgres', () => {const fetched = await pg.getFile('default', 'originals/photos/whiteboard.jpg');expect(fetched).not.toBeNull();expect(fetched!.filename).toBe('whiteboard.jpg');+ // files.size_bytes is BIGINT; postgres.js reads it as a BigInt, and FileRow says number on every engine.+ expect(typeof fetched!.size_bytes).toBe('number');+ expect(fetched!.size_bytes).toBe(12345);// Re-upsert same path → no-op (created=false)const r2 = await pg.upsertFile({@@ -307,9 +310,11 @@ describe.skipIf(skip)('multimodal v0.27.1 against real Postgres', () => {expect(pgFile).not.toBeNull();expect(pgliteFile!.filename).toBe(pgFile!.filename);expect(pgliteFile!.mime_type).toBe(pgFile!.mime_type);- // PGLite returns size_bytes as BigInt, Postgres as Number — both are- // valid for a BIGINT column. Compare numerically.- expect(Number(pgliteFile!.size_bytes)).toBe(Number(pgFile!.size_bytes));+ // Both engines return size_bytes as a number.+ expect(pgFile!.size_bytes).toBe(pgliteFile!.size_bytes);+ const pgListed = await pg.listFilesForPage(pgPage.id);+ expect(pgListed.map(f => f.size_bytes)).toEqual([999]);+ expect(typeof pgListed[0]!.size_bytes).toBe('number');expect(pgliteFile!.content_hash).toBe(pgFile!.content_hash);expect(pgliteFile!.source_id).toBe(pgFile!.source_id);diff --git a/test/e2e/postgres-engine-disconnect-idempotency.test.ts b/test/e2e/postgres-engine-disconnect-idempotency.test.tsindex ef3b603a3d..c6f2ed807e 100644--- a/test/e2e/postgres-engine-disconnect-idempotency.test.ts+++ b/test/e2e/postgres-engine-disconnect-idempotency.test.ts@@ -111,6 +111,22 @@ describe.skipIf(skip)('PostgresEngine.disconnect idempotency + module-singletonawait expect(engine.disconnect()).resolves.toBeUndefined();});+ test('a second disconnect() does not run the before-disconnect hooks again, as on PGLite', async () => {+ for (const connect of [+ (e: PostgresEngine) => e.connect({ database_url: DATABASE_URL!, poolSize: 2 }), // instance pool+ (e: PostgresEngine) => e.connect({ database_url: DATABASE_URL! }), // module singleton+ ]) {+ const engine = new PostgresEngine();+ await connect(engine);+ let runs = 0;+ engine.registerBeforeDisconnect(async () => { runs++; });+ await engine.disconnect();+ expect(runs).toBe(1);+ await engine.disconnect();+ expect(runs).toBe(1);+ }+ });+test('owner reconnect with a live borrower: borrower resolves the rebuilt singleton', async () => {const owner = new PostgresEngine();await owner.connect({ database_url: DATABASE_URL! }); // ownsdiff --git a/test/fixtures/goldens/cli/tools-json.json b/test/fixtures/goldens/cli/tools-json.jsonindex ff7ead0da9..5d6e618735 100644--- a/test/fixtures/goldens/cli/tools-json.json+++ b/test/fixtures/goldens/cli/tools-json.json@@ -2,8 +2,8 @@"golden": {"exitCode": 0,"stderr": "",- "stdoutBytes": 300735,- "stdoutSha256": "33eac5e04d5362ecb7175edec8781ab33558a5dbad8061e781550f43cbc415ac",+ "stdoutBytes": 300780,+ "stdoutSha256": "8f97f2de38e80665f2b4290a0c7b3235c552b728d3957ed59861c8c0a49bbc96","toolNames": ["remember","entity",@@ -3280,7 +3280,7 @@"scope": "admin"},{- "description": "Admin read: who created and who last changed a page, or one of its facts, takes or timeline entries. Each attribution names the request id, operation, principal (kind, id, current name), time and origin (request, maintenance or unrecorded), plus the row's trust_tier and write_origin (for derived rows, the inputs that set the tier). Remote callers stay inside their source grant and see only world facts.",+ "description": "Admin read: who created and who last changed a page, or one of its facts, takes or timeline entries. Each attribution names the request id, operation, principal (kind, id, current name), time and origin (request, maintenance or unrecorded), plus the row's trust_tier and write_origin (for derived rows, the inputs that set the tier). Remote callers stay inside their source grant and see only world facts, except credentials bound to the brain owner.","idempotent": true,"local_only": false,"mutating": false,diff --git a/test/fixtures/goldens/exports/types.json b/test/fixtures/goldens/exports/types.jsonindex 39234e7603..abfda30e28 100644--- a/test/fixtures/goldens/exports/types.json+++ b/test/fixtures/goldens/exports/types.json@@ -92,7 +92,7 @@"findCandidateDuplicates: (source_id: string, entitySlug: string, factText: string, opts?: { k?: number; embedding?: Float32Array; embeddingModel?: string | null; arm?: \"keyword\"; attributedTo?: FactAttribution | null; excludeMemberPages?: boolean; onlyPage?: string; }) => Promise<FactRow[]>","findDuplicatePage?: ((sourceId: string, opts: { hash: string; frontmatterId?: string | null; excludeSlug?: string; }) => Promise<{ slug: string; id: number; } | null>) | undefined","findDuplicatePages?: ((sourceId: string, inputs: ReadonlyArray<{ hash: string; frontmatterId?: string | null; excludeSlug?: string; }>) => Promise<Array<{ slug: string; id: number; } | null>>) | undefined",- "findOntologyConflicts: (opts?: PageReadScope & { minConfidence?: number; visibility?: OntologyReadOpts[\"visibility\"]; }) => Promise<OntologyConflict[]>",+ "findOntologyConflicts: (opts?: PageReadScope & Pick<OntologyReadOpts, \"minConfidence\" | \"visibility\" | \"excludeDiary\">) => Promise<OntologyConflict[]>","findOrphanPages: (opts?: PageReadScope & { sourceId?: string; sourceIds?: string[]; mode?: \"inbound\" | \"islanded\"; scopeInbound?: boolean; }) => Promise<Array<{ slug: string; title: string; domain: string | null; type?: string | null; quarantined?: boolean; source_id?: string; }>>","findPages: (query: FindPagesQuery) => Promise<FoundPages>","findTrajectory: (opts: TrajectoryOpts) => Promise<TrajectoryPoint[]>",@@ -885,6 +885,7 @@"kind": "interface","members": ["asof?: string | undefined",+ "excludeDiary?: boolean | undefined","excludePrivate?: boolean | undefined","includeQuarantined?: boolean | undefined","minConfidence?: number | undefined",@@ -1109,7 +1110,7 @@"findCandidateDuplicates: (source_id: string, entitySlug: string, factText: string, opts?: { k?: number; embedding?: Float32Array; embeddingModel?: string | null; arm?: \"keyword\"; attributedTo?: FactAttribution | null; excludeMemberPages?: boolean; onlyPage?: string; }) => Promise<FactRow[]>","findDuplicatePage: (sourceId: string, opts: { hash: string; frontmatterId?: string | null; excludeSlug?: string; }) => Promise<{ slug: string; id: number; } | null>","findDuplicatePages: (sourceId: string, inputs: Parameters<typeof findDuplicatePages>[2]) => Promise<({ slug: string; id: number; } | null)[]>",- "findOntologyConflicts: (opts?: PageReadScope & { minConfidence?: number; visibility?: OntologyReadOpts[\"visibility\"]; }) => Promise<OntologyConflict[]>",+ "findOntologyConflicts: (opts?: PageReadScope & Pick<OntologyReadOpts, \"minConfidence\" | \"visibility\" | \"excludeDiary\">) => Promise<OntologyConflict[]>","findOrphanPages: (opts?: { sourceId?: string; sourceIds?: string[]; excludePrivate?: boolean; mode?: \"inbound\" | \"islanded\"; scopeInbound?: boolean; }) => Promise<Array<{ slug: string; title: string; domain: string | null; type?: string | null; quarantined?: boolean; source_id?: string; }>>","findPages: (query: FindPagesQuery) => Promise<FoundPages>","findTrajectory: (opts: TrajectoryOpts) => Promise<TrajectoryPoint[]>",@@ -3665,7 +3666,7 @@"findCandidateDuplicates: (source_id: string, entitySlug: string, factText: string, opts?: { k?: number; embedding?: Float32Array; embeddingModel?: string | null; arm?: \"keyword\"; attributedTo?: FactAttribution | null; excludeMemberPages?: boolean; onlyPage?: string; }) => Promise<FactRow[]>","findDuplicatePage?: ((sourceId: string, opts: { hash: string; frontmatterId?: string | null; excludeSlug?: string; }) => Promise<{ slug: string; id: number; } | null>) | undefined","findDuplicatePages?: ((sourceId: string, inputs: ReadonlyArray<{ hash: string; frontmatterId?: string | null; excludeSlug?: string; }>) => Promise<Array<{ slug: string; id: number; } | null>>) | undefined",- "findOntologyConflicts: (opts?: PageReadScope & { minConfidence?: number; visibility?: OntologyReadOpts[\"visibility\"]; }) => Promise<OntologyConflict[]>",+ "findOntologyConflicts: (opts?: PageReadScope & Pick<OntologyReadOpts, \"minConfidence\" | \"visibility\" | \"excludeDiary\">) => Promise<OntologyConflict[]>","findOrphanPages: (opts?: PageReadScope & { sourceId?: string; sourceIds?: string[]; mode?: \"inbound\" | \"islanded\"; scopeInbound?: boolean; }) => Promise<Array<{ slug: string; title: string; domain: string | null; type?: string | null; quarantined?: boolean; source_id?: string; }>>","findPages: (query: FindPagesQuery) => Promise<FoundPages>","findTrajectory: (opts: TrajectoryOpts) => Promise<TrajectoryPoint[]>",@@ -7133,7 +7134,7 @@"findCandidateDuplicates: (source_id: string, entitySlug: string, factText: string, opts?: { k?: number; embedding?: Float32Array; embeddingModel?: string | null; arm?: \"keyword\"; attributedTo?: FactAttribution | null; excludeMemberPages?: boolean; onlyPage?: string; }) => Promise<FactRow[]>","findDuplicatePage: (sourceId: string, opts: { hash: string; frontmatterId?: string | null; excludeSlug?: string; }) => Promise<{ slug: string; id: number; } | null>","findDuplicatePages: (sourceId: string, inputs: Parameters<typeof pagesImpl.findDuplicatePages>[2]) => Promise<({ slug: string; id: number; } | null)[]>",- "findOntologyConflicts: (opts?: PageReadScope & { minConfidence?: number; visibility?: OntologyReadOpts[\"visibility\"]; }) => Promise<OntologyConflict[]>",+ "findOntologyConflicts: (opts?: PageReadScope & Pick<OntologyReadOpts, \"minConfidence\" | \"visibility\" | \"excludeDiary\">) => Promise<OntologyConflict[]>","findOrphanPages: (opts?: { sourceId?: string; sourceIds?: string[]; excludePrivate?: boolean; mode?: \"inbound\" | \"islanded\"; scopeInbound?: boolean; }) => Promise<Array<{ slug: string; title: string; domain: string | null; type?: string | null; quarantined?: boolean; source_id?: string; }>>","findPages: (query: FindPagesQuery) => Promise<FoundPages>","findTrajectory: (opts: TrajectoryOpts) => Promise<TrajectoryPoint[]>",@@ -9998,6 +9999,7 @@"kind": "interface","members": ["asof?: string | undefined",+ "excludeDiary?: boolean | undefined","excludePrivate?: boolean | undefined","includeQuarantined?: boolean | undefined","minConfidence?: number | undefined",diff --git a/test/postgres-unit-arms.txt b/test/postgres-unit-arms.txtindex 729e8c2e12..cbd81aee38 100644--- a/test/postgres-unit-arms.txt+++ b/test/postgres-unit-arms.txt@@ -29,6 +29,7 @@ test/access-members-read-lineage.test.tstest/access-members.test.tstest/access-on-behalf-of.test.tstest/access-owner-default-writes.test.ts+test/access-owner-fact-ops-gst2951.test.tstest/access-owner-reads.test.tstest/access-page-indexes-online.test.tstest/access-page-rule-fileless.test.ts