Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
chore(wave): world-read baseline row for the #7838 per-engine prefix cache; trim core-utilities-2 under its cap
garrytan7cbcbcc0cd89
diff --git a/docs/architecture/key-files/core-utilities-2.md b/docs/architecture/key-files/core-utilities-2.mdindex f72d9c0f08..f77b8f9240 100644--- a/docs/architecture/key-files/core-utilities-2.md+++ b/docs/architecture/key-files/core-utilities-2.md@@ -35,7 +35,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/core/sort-newest-first.ts` — single source of truth for the descending-lex sort that `gbrain import` and `gbrain sync` both apply. Mutates in place (Array.prototype.sort semantics), returns the same array reference for fluent chaining. Empty/single-element inputs short-circuit. Future ordering changes flip one line here instead of touching two CLI commands. Pinned by `test/sort-newest-first.test.ts` (descending order, mixed prefixes, empty, single-element, in-place-mutation contract).- `src/core/sql-query.ts` — engine-aware tagged-template SQL adapter for OAuth/admin/auth infrastructure. `sqlQueryForEngine(engine)` returns a `SqlQuery` (`(strings, ...values) => Promise<rows[]>`) that walks the template, builds `$N` positional SQL, asserts every value is a `SqlValue` (string | number | bigint | boolean | Date | null), and routes through `engine.executeRaw(sql, params)` (Postgres via postgres.js `unsafe(sql, params)`, PGLite via `db.query(sql, params)`). Deliberately narrower than postgres.js's `sql` tag: no nested fragments, `sql.json()`, `sql.unsafe()`, `sql.begin()`, or array binding — the narrow scalar-only surface is the feature (keeps it from drifting into a partial postgres.js clone). JSONB writes go through `executeRawJsonb(engine, sql, scalarParams, jsonbParams)` which composes positional `$N::jsonb` casts and passes JS **objects** through; an object reaches the wire with the correct type oid, so executeRawJsonb is safe (verified by `test/sql-query.test.ts` on PGLite, `test/e2e/auth-permissions.test.ts:67` on Postgres). Positional binding is NOT universally immune, though: binding a `JSON.stringify(x)` **string** to a bare `$N::jsonb` via `unsafe()` double-encodes it into a jsonb string scalar on real Postgres (PGLite hides it). Fixes: pass a raw object (executeRawJsonb / `sql.json`), or cast through `$N::text::jsonb`. `scripts/check-jsonb-pattern.sh` (template grep) doesn't fire on `executeRawJsonb(...)` because it passes objects; the positional `$N::jsonb` + `JSON.stringify` form is caught by `scripts/check-jsonb-params.mjs`. Also exports `FILES_METADATA_MERGE_SQL`, the one `ON CONFLICT (storage_path)` merge fragment every files upsert (`src/commands/files.ts` x4, `src/core/ops/files.ts` `file_upload`) interpolates: it resets a non-object `files.metadata` to `{}` before the jsonb `||` merge, because `||` array-wraps a non-object left operand and would turn a legacy string-scalar row into `["{}", {...}]` that `gbrain repair-jsonb` can no longer see (pinned by `test/file-upload-fail-closed.test.ts`). Consumed by `src/commands/auth.ts`, `src/commands/serve-http.ts`, `src/core/oauth-provider.ts`, `src/commands/files.ts`, `src/mcp/http-transport.ts` so all five work uniformly against PGLite and Postgres.-- `src/core/raw-file-upload.ts` — `gbrain files upload-raw` (`src/commands/files.ts`) refuses `writer_coordinator_required` before writing into a managed worktree (raw files are not published): `managedRawUploadRefusal` (#5963) before a git-storage `mkdir` (fix: `gbrain files upload`), `managedPointerRefusal` (#7346) before an object-storage upload whose `.redirect.yaml` would land there (fix: `--no-pointer`). `rawUploadRefusedFor` keeps `file_upload` (`src/core/ops/files.ts`) from suggesting upload-raw for such a page.+- `src/core/raw-file-upload.ts` — `gbrain files upload-raw` (`src/commands/files.ts`) refuses `writer_coordinator_required` before writing into a managed worktree (raw files are unpublished): `managedRawUploadRefusal` (#5963) before a git-storage `mkdir` (fix: `gbrain files upload`), `managedPointerRefusal` (#7346) before an object-storage upload whose `.redirect.yaml` would land there (fix: `--no-pointer`). `rawUploadRefusedFor` stops `file_upload` (`src/core/ops/files.ts`) suggesting upload-raw there.- `src/core/storage-config.ts` — Storage tiering: `loadStorageConfig` reads `gbrain.yml` (warns once per unknown `storage:` key; an optional `keep_db` prefix list, present only when declared, is normalized like the tiers and matched by `isKeepDbSlug`, consumed by `repair/keep-db-policy.ts`), normalizes deprecated keys (`git_tracked`/`supabase_only`) to (`db_tracked`/`db_only`) with a once-per-process warning, and runs `normalizeAndValidateStorageConfig` (auto-fixes missing trailing `/`, throws `StorageConfigError` on tier overlap). Path-segment matcher: `media/x/` does NOT match `media/xerox/foo`. `isDeclaredDbOnlySlug` matches a lowercase page slug against the declared db_only dirs case-insensitively; managed persistence uses it to publish those pages database-only. `hasUnresolvedDbOnlyDeclaration` detects a db_only key line that resolved no directory (a multi-line flow list, a key outside `storage:`; one-line lists parse, `db_only: []` declares none, #8007); the sync baseline-commit guard refuses on it, and managed persistence turns a missing-file refusal into `storage_error`. Parses `gbrain.yml` itself (gray-matter breaks on delimiter-less YAML). Also carries `DERIVE_PHASE_DB_ONLY_DEFAULTS` (`life/events/`, `atoms/`, `extracts/`, `dream-cycle-summaries/`) + `effectiveDbOnlyDirs` — the engine's derive-phase output prefixes treated as implicitly-declared db_only by the `undeclared_db_only_pages` doctor check but deliberately NOT merged into `loadStorageConfig` (a global merge would auto-gitignore those dirs and silently kill ingestion for brains that file-back them) — and `findDbOnlyCollisions` (pure collector-output vs db_only overlap detector shared by the `db_only_collector_collision` doctor check and sync's `manageGitignore` warning). Pinned by `test/storage-config.test.ts` + `test/doctor-silent-death-checks.test.ts`.diff --git a/scripts/core-world-reads-baseline.tsv b/scripts/core-world-reads-baseline.tsvindex 7017adca30..a8c5446f1c 100644--- a/scripts/core-world-reads-baseline.tsv+++ b/scripts/core-world-reads-baseline.tsv@@ -163,6 +163,7 @@ src/core/brain-resolver.ts process_env 1 W6: settings plane out of the coresrc/core/brain-score-recommendations.ts process_env 1 W6: settings plane out of the coresrc/core/brain-writer.ts fs_import 1 W7: filesystem boundary moves to the local appsrc/core/brainstorm/checkpoint.ts fs_import 1 W7: filesystem boundary moves to the local app+src/core/brainstorm/domain-bank.ts module_collection 1 #7838: the slug-prefix cache is a WeakMap keyed by engine, so mounts never share an entry; W6: per-engine statesrc/core/brainstorm/orchestrator.ts process_global 1 W7: process-wide effects move to src/clisrc/core/budget/budget-tracker.ts fs_import 1 W7: filesystem boundary moves to the local appsrc/core/budget/budget-tracker.ts module_collection 1 W6: per-engine state, or mark as a constant table