Garry's Opinionated OpenClaw/Hermes Agent Brain
Eng Review (Phase 3, primary voice): GBrain Refactor Wave 1
- Target:
~/.gstack/projects/garrytan-gbrain/autoplan-eng-M2VyUI/eng-implementation.md(plan already amended by CEO and DX phases). - Baseline:
garrytan/gbrainmaster @608a174dc(v0.60.10.0), clean tree. Read-only review: nothing in the repo was modified. - Methodology: gstack
/plan-eng-review(full file read, 2,256 lines), executed at full depth with the autoplan overrides: skipped Preamble, Scope gate, AskUserQuestion format, Completeness Principle, Search Before Building, Completion Status, Telemetry, base-branch detection, Readiness Dashboard, Plan File Review Report, Prerequisite Skill Offer, Outside Voice. No questions asked; every issue auto-decided with the 6 principles (P1 completeness, P2 boil lakes, P3 pragmatic, P4 DRY, P5 explicit over clever, P6 bias to action). Eng tiebreak: P5 + P3. Scope never reduced. - Prior phases (accepted, not re-litigated): CEO
ceo-primary.md(A1-A19, E1-E5, E9, T1 include, T2 flat, T3 defer, UC1 pending), DXdx-primary.md(D1-D37, O1-O20). - Owner constraints honored: ONE integrated PR, PATCH release, generic placeholders only in public artifacts.
- Evidence: every finding below quotes the code line it rests on (file:line at 608a174). Function sizes re-measured with a TS AST
scan (
~/.capy/work/refactor/scratch/fnsize.ts); import-graph reachability with a static relative-import walk.
Verdict in two sentences: the amended plan is buildable and the workstream order is right, but five engineering facts the CEO
and DX phases did not see would make W1/W2/W4 silently wrong: the engine transaction clone (an executor cached on the engine
escapes transaction()), RLS scoping that the W1-core domains never had, every existing PGLite brain replaying the regenerated
schema blob on its next boot, a CLI command table that loses the pre-connect dispatch phase, and a goal (b) that drags ~133
re-pointed test files into mandatory decomposition. All five are closed below by concrete obligations with tests; two are
CRITICAL GAPs in the plan as written.
Step 0: Scope Challenge
A. Assess the target
What already solves each sub-problem (read in code, not assumed)
| Sub-problem | Existing code (608a174) | Evidence | How the plan should use it |
|---|---|---|---|
| Cross-engine positional executor | sqlQueryForEngine, executeRawJsonb, SqlValue |
src/core/sql-query.ts:17-41,111-143 |
Keep the scalar-only tag untouched. executeRawJsonb(engine: BrainEngine, ...) takes an engine, so "reuse" requires widening its first parameter to Pick<BrainEngine,'executeRaw'> (structural; all 18 callers unchanged). |
| Postgres raw path with cancellation | runUnsafe(conn, sql, params, {signal}) -> conn.unsafe(sql, params, { cancelFence: !!signal }) |
postgres-engine.ts:5340-5376 |
The Postgres adapter calls runUnsafe directly (no checkoutGauge, see CQ6) with an added {prepare: true, simple: false} pass-through. |
| Prepared-statement policy | Resolved once per pool: const prepare = db.resolvePrepare(url) at postgres-engine.ts:331; postgres.js ANDs the per-call option with it: q.prepare = options.prepare && ('prepare' in q.options ? q.options.prepare : true) |
vendor/postgres/src/connection.js:238; unsafe() defaults prepare: false, simple: args.length === 0 at vendor/postgres/src/index.js:119-125 |
Per-call resolvePrepare(url) (CEO A4 wording) is unnecessary: pass prepare: true always and the connection option gates it. |
| RLS scope binding | withScopedReadTransaction(sourceIds, sourceId, cb, {alwaysTransaction}): flag off returns callback(this.sql); flag on opens this.transaction and set_config('app.scopes', ...) |
postgres-engine.ts:281-312; 23 call sites; pinned by test/postgres-engine-rls-scope.test.ts (fake sql, #1794 no per-read pool hold) |
Scoping status must be preserved per method (AR2). |
| Transaction clone | const txEngine = Object.create(this); Object.defineProperty(txEngine, 'sql', { get: () => tx }) |
postgres-engine.ts:585-588; PGLite Object.defineProperty(txEngine, 'db', { get: () => tx }) at pglite-engine.ts:1725 |
The executor must be resolved through the same getter on every call (AR1). Existing peeled deps already do this: return { get sql() { return self.sql; } } at postgres-engine.ts:5566-5569. |
| Per-domain peeled modules | src/core/{pglite,postgres}-engine/{facts,takes,salience,code-edges,cjk-search}.ts (5,058 lines total with the other modules) |
ls; narrow deps interfaces e.g. PgSalienceDeps { readonly sql } |
W1-core converts these pairs into one engine-sql/<domain>.ts. |
| Shared SQL fragment builders | pageReadFilter, buildRecencyComponentSql, privatePagesFilterFragment, currentCodeEdgeFilter, buildCJKKeywordSql |
search/sql-ranking.ts:381-406 inlines LIKE literals and numeric coefficients; postgres-engine/takes.ts:303; code-edges.ts:99 |
These are the vetted builder registry for A2b (CQ3). |
| Migrations | MIGRATIONS array migrate.ts:196-6780; module-private interface Migration (:61, not exported); private helpers migrationNotice (:43, 4 uses in the array), dropInvalidConcurrentIndex (:170, 16 uses), module state quietMigrationNotices (:39) |
sed/grep counts |
Helpers move to a leaf module (SC2); the type moves to schema-migrations/types.ts (SC1). |
| Schema text | build-schema.sh (sed of src/schema.sql into schema-embedded.generated.ts); getPGLiteSchema(dims, model) applies applyChunkEmbeddingIndexPolicy, applyFtsLanguagePolicy, __EMBEDDING_DIMS__/__EMBEDDING_MODEL__ at runtime |
scripts/build-schema.sh:1-18; pglite-schema.ts:1297-1312 |
The generator output stays a template with runtime policy (SC20). |
| Schema replay on every boot | PGLite initSchema: applyForwardReferenceBootstrap(), db.exec(getPGLiteSchema(dims, model)), runMigrations(this) |
pglite-engine.ts:1042-1070 |
Every existing PGLite brain replays the regenerated blob on first boot after upgrade (AR3). |
| Bootstrap callers | PostgresEngine.initSchema, db.ts:initSchema (applyPostgresForwardReferenceBootstrap(conn); await conn.unsafe(SCHEMA_SQL) at db.ts:369-371), PGLite applyForwardReferenceBootstrap (pglite-engine.ts:1100-1703) |
read | E1's single bootstrap must accept a raw executor for the db.ts caller. |
| Snapshot hash | computeSnapshotSchemaHash hard list of 31 files; does NOT include pglite-engine.ts (where the PGLite bootstrap lives) |
pglite-engine.ts:334-366; the 11 CI keys DO include src/core/pglite-engine.ts (e2e.yml:71) |
Derive inputs from the import closure (AR7). |
| Schema end-state gate | test/e2e/schema-drift.test.ts + test/helpers/schema-diff.ts (columns by name, ORDER BY table_name, ordinal_position but diff by name) |
schema-diff.ts:59-62,224,291 |
E4 extends; add ordinal for PGLite master-vs-branch (T-G13). |
| Forward-reference coverage | test/schema-bootstrap-coverage.test.ts parser-driven checks over both blobs + REQUIRED_BOOTSTRAP_COVERAGE; reads POSTGRES_BOOTSTRAP_PATH = 'src/core/postgres-engine/forward-reference-bootstrap.ts' (:52) |
read | Must be re-pointed by E1 (CEO wrote "unchanged"; impossible because it reads the moved path). |
| Doctor | buildChecks doctor.ts:662-4105: shared let schemaVersion (:2017), early return checks (:1850, :1886), 235 pushes incl. loops; test/helpers/doctor-source.ts containment vs positional loaders |
read | Registry entries return `Check[] |
| CLI | handleCliOnly cli.ts:2095-3609: ~69 if (command === ...) branches (most dispatched before the generic connectEngine() terminator at cli.ts:3012, several opening their own connection with probeOnly or a timeout), then switch (command) at :3074 (62 cases); thin-client pre-guard cli.ts:2103 (`THIN_CLIENT_REFUSED_COMMANDS.has(command) |
command === 'cache' | |
| Flag registry generator | generate-flag-registry.ts:257 segments on ^[ \t]*if \(\s*command === '...' and ^ case '...':; facadeExpansion() :113 |
read | Re-target to the table in the same commit (DX O6). |
| serve-http | runServeHttp serve-http.ts:858-3108, function requireAdmin declared inside it (:1435), 44 app.* registrations, no app-returning seam |
read | Route golden cannot be runtime on master (AR6). |
| Admin route guard | test/serve-http-admin-route-guard.test.ts (structural, 7-entry allowlist) |
exists | Extend (DX D32). |
| Module-size ratchet | check-module-size.sh:46-57 measure_region_exempt; migrate row ceiling 722 region-exempt |
read | Drop policy in W3. |
| Generated-file convention | build-schema.sh:3-4: ".generated.ts suffix: module-size ratchet + other source-file guards exempt generated files by that naming convention" |
read | Name the migrations registry registry.generated.ts (SC3). |
| E2E selection | select-e2e.ts:63-92 escape hatches (src/core/migrate.ts); e2e-test-map.ts:252-346 engine and per-domain rows |
read | Add engine-sql/** and schema-migrations/** (DX O16). |
| Scanner guards naming moved paths | check-jsonb-pattern.sh:53 (src/core/migrate.ts in the max_stalled schema scan); check-engine-dynamic-import.sh:26-33 (engines + migrate + peeled dirs); check-jsonb-params.mjs:45 scans all src (covers engine-sql automatically) |
read | Extend the first two; the third needs no change. |
Minimum changes that achieve the goal
The goal is five behaviors: one SQL copy per migrated domain, one schema DDL copy, one file per migration, no god functions in touched src files, and a ratchet. Every workstream is needed for at least one of them; the only deferrable work is already on the plan's cut line (jobs, hybrid, autopilot) and UC1's W1-extended. Per P2 nothing is cut here.
Complexity check (counted, labelled estimates)
| Kind | Count | Basis |
|---|---|---|
| New src files | ~210-240 | 170 migration files + registry + helpers + types (W3); engine-sql executor + 2 adapters + normalizer + 5 core domains + bootstrap (~10, up to ~17 with W1-extended); sync phases ~6; doctor check modules ~10-20 (finishing peel); serve-http 3 new modules; CLI table + command modules ~5-10 |
| New scripts/guards | 6 | check-function-size.ts, engine-sql ratchet, engine-sql dynamic-SQL scanner, schema freshness, migrations registry generator/freshness, verify-move-only.ts |
| Changed existing files | ~200+ | 2 engines, migrate.ts, schema.sql, pglite-schema.ts (deleted -> generated), doctor.ts, sync.ts, serve-http.ts + 2 modules, cli.ts, jobs.ts, hybrid.ts, autopilot.ts, ~133 source-reading tests, 11 workflow cache keys, ~35 path consumers, ~12 docs |
| New classes/services | 4+ | engine-sql executor, schema generator, migration registry generator, doctor registry runner, CLI command table, SyncRun |
This trips the 8-file / 2-service gate. Under autoplan the gate is auto-decided: no feature cuts (P2, owner's one-PR rule), and
the structure question resolves to Original arrangement with three naming/placement corrections that keep every contract
(SC1, SC2, SC3). Scope record: feature answers: none (autoplan, P2); structure: A Original arrangement (auto); accepted scope: amended plan as written + Eng obligations EO1-EO22; pending remedies: none (UC1 is the owner's, not an Eng remedy).
Search check
Skipped per the autoplan override (Search Before Building). Layer labels applied from in-distribution knowledge: raw SQL with
positional params behind a thin dialect adapter is [Layer 1] (same shape as Kysely dialect adapters without the builder);
generated static-import registries with freshness guards are [Layer 1] in this repo (check-tool-catalog-fresh.sh);
branded types for capability-scoped handles are [Layer 1] TypeScript practice. No [EUREKA].
TODOS cross-reference
- Closes when its workstream lands:
TODOS.md:1868(3-way schema parity; W2+E4),:1956(Wave 4a sync),:1962(Wave 4b doctor hoist),:~1976(migrate-runner extraction),:~4445(TODO-V19-C doctor registry). - Interacts:
TODOS.md"Test-audit follow-ups (filed 2026-09-29)" item "Extract a testable autopilot tick function, then retire the 8 autopilot wiring greps": if autopilot stays on the cut line, leave it; if it lands, do the extraction the TODO names in the same commit instead of re-pointing 8 grep files twice. - Interacts: same section, "
gbrain auth rescope-client ... --dry-runfail with unknown flag" (flag-registry generator drops--dry-runforauth). DX O6 requires the regenerated registry to be byte-identical, which deliberately preserves this bug. Correct for a behavior-preserving PR; do not fix it here, do not let the generator rewrite "fix" it silently. - Deferred D3 (T3 phase-named sync errors,
TODOS.md:5338) stays deferred.
Distribution check
No new artifact is published. Compiled binary must keep bundling: 170 migration modules (static imports only), engine-sql modules
(static), command modules (lazy but with string-literal specifiers, AR8). Existing gates: check-compile-autoload.sh,
check-pglite-embedded.sh, check-cli-executable.sh. The dominant install path bun install -g github:garrytan/gbrain runs
source, so module count does affect engine-connect cold start (PF3).
C. Scope Challenge findings
| # | Sev | Conf | Evidence (quoted) | Finding | Disposition |
|---|---|---|---|---|---|
| SC1 | P1 | 9 | migrate.ts:61 interface Migration { (no export) |
Plan says migrate.ts "keeps re-exporting MIGRATIONS, LATEST_VERSION, Migration"; Migration is not exported today, and 170 files now need it. |
Accepted: move to src/core/schema-migrations/types.ts; migrate.ts export type { Migration } (type-only; runtime export golden unchanged, .d.ts snapshot gains one type, recorded as intended). |
| SC2 | P1 | 8 | migrate.ts:43 function migrationNotice(line: string); :39 let quietMigrationNotices = false;; :170 async function dropInvalidConcurrentIndex( (16 uses inside the array) |
Moved handlers importing these from migrate.ts create a migrate.ts -> registry -> vNNN -> migrate.ts cycle; a future top-level const reference hits TDZ at module load, including in the compiled binary. |
Accepted: leaf schema-migrations/helpers.ts owns both helpers and the quiet flag (setter called by the runner); a test asserts no file under schema-migrations/ imports migrate.ts. |
| SC3 | P2 | 8 | build-schema.sh:3-4 ".generated.ts suffix: module-size ratchet + other source-file guards exempt generated files" |
Plan names the generated registry schema-migrations/index.ts. |
Accepted: src/core/schema-migrations/registry.generated.ts, marked in .gitattributes linguist-generated. |
| SC4 | P1 | 9 | AST scan: test/doctor.test.ts anonymous callback 724 lines (17-740); test/sync.test.ts 414 lines (408-821) |
Goal (b) "any file touched by this PR" includes ~133 re-pointed test files whose describe callbacks exceed 300 lines, forcing test restructuring that risks the zero-loosened-assertion rule. |
Accepted: goal (b) and the W5 guard scope = src/**/*.ts minus *.generated.ts; tests and scripts excluded, stated in the guard's TESTING.md section. |
| SC5 | P1 | 9 | index.js:119-125 prepare: false, ...options, simple: 'simple' in options ? options.simple : args.length === 0; connection.js:238 |
CEO A4 "passes {prepare} from db.resolvePrepare(url)" is over-specified and can diverge from the pool actually used (instance pool, dual-pool ddl, tx clone). Zero-arg converted queries would silently switch to the simple protocol (unprepared, multi-statement allowed). |
Accepted: adapter always passes {prepare: true, simple: false}; connection option gates prepare; contract test T-G4. |
| SC6 | P1 | 9 | postgres-engine.ts:5566-5569 return { get sql() { return self.sql; } }; (salience), same for facts :4361-4366; zero withScoped hits in postgres-engine/*.ts; cjk-search runs inside withScopedReadTransaction at :1923 |
A3 "store read functions accept only a branded ScopedExecutor" would newly wrap 4 domains' reads (behavior change with the flag on: BEGIN + set_config + pool hold per read, the #1794 class) or force unscopedExecutor() everywhere (vacuous brand). |
Accepted (AR2): preserve master's per-method scoping status exactly; W0 inventory golden; extending scoping is a TODO. |
| SC7 | P1 | 9 | postgres-engine.ts:585-588 const txEngine = Object.create(this) as PostgresEngine; ... Object.defineProperty(txEngine, 'sql', { get: () => tx }); |
An executor stored on the engine instance at connect time is inherited by txEngine and still bound to the pool: writes inside engine.transaction() commit outside it. Silent atomicity loss. Not raised by CEO or DX. |
Accepted (AR1): CRITICAL GAP closed by EO1. |
| SC8 | P2 | 9 | sql-query.ts:118 export async function executeRawJsonb<R>(engine: BrainEngine, ...) |
Cannot be reused on a scoped tx handle as written. | Accepted: widen to Pick<BrainEngine,'executeRaw'>. |
| SC9 | P2 | 8 | postgres-engine.ts:5388 this.checkoutGauge.acquire('raw'); in executeRaw; tagged sites call sql\...`` with no gauge |
Routing converted sites through executeRaw inflates the raw gauge that doctor pool checks read. |
Accepted (CQ6). |
| SC10 | P1 | 9 | sql-ranking.ts:405 branches.push(`WHEN ${slugColumn} LIKE ${literal} THEN ${c} * ${h}.0 / (${h}.0 + ${daysOldSql})`); postgres-engine/facts.ts:489 ORDER BY embedding <=> ${sql.unsafe(`'${lit}'::vector`)} |
A2b "only identifiers/ordering from constant allowlists may be concatenated" rejects the existing vetted builders; complying would rewrite them and change SQL text and plans. | Accepted (CQ3). |
| SC11 | P1 | 8 | cli.ts:3012 generic engine = await connectEngine(...) terminator after ~900 lines of pre-connect if (command === ...) branches; cli.ts:2103 thin-client pre-guard incl. cache/quarantine; cli.ts:2113 subcommand routing |
Plan's record {name, load, selfHelp, thinClientRefused, skipStartupHooks, aliases} cannot express pre-connect vs post-connect dispatch or route-then-refuse. Engine-free commands (status, db-repair must answer with the DB down) would silently start connecting. |
Accepted (AR5). |
| SC12 | P1 | 8 | serve-http.ts:858 export async function runServeHttp(engine, options) builds and listens; requireAdmin declared inside at :1435 |
W0 "route table with per-route ordered middleware" captured on master cannot be runtime introspection (no app handle). | Accepted (AR6): AST golden on master, runtime golden after a move-only extraction; both must agree. |
| SC13 | P1 | 9 | pglite-engine.ts:1066-1069 await this.applyForwardReferenceBootstrap(); await this.db.exec(getPGLiteSchema(dims, model)); ... await runMigrations(this); |
E4 proves fresh-install equality only. Every existing PGLite brain replays the regenerated blob on its next boot. | Accepted (AR3): CRITICAL GAP closed by EO3. |
| SC14 | P1 | 8 | pglite-engine.ts:347-356 hash list lacks pglite-engine.ts; CI keys include it |
Moving the bootstrap to engine-sql/ leaves it covered by neither; plan's A6 lists only migrations and generated schema. |
Accepted (AR7). |
| SC15 | P2 | 8 | A11 "handler source-text hash"; moving handler: async (engine) => {...} from array indentation to a top-level const re-indents the body; Function.prototype.toString preserves whitespace |
Golden fails on a correct move, inviting someone to regenerate it and lose the proof. | Accepted: hash the whitespace-normalized token stream (shared normalizer with E3). |
| SC16 | P2 | 8 | E3 "normalized token multisets preserved"; W3 turns { version: 2, ... }, into export const v002: Migration = { version: 2, ... }; |
Every W3 file fails a naive move-only check. SyncRun conversion (foo -> run.foo) is not move-only at all. |
Accepted (CQ7): wrapper mode + rename-map mode; SyncRun commits carry Mechanical-Rename: yes, not Move-Only: yes. |
| SC17 | P2 | 8 | doctor.ts:2017 let schemaVersion = 0; read by later checks; :1850/:1886 return checks; |
{name, run} entries that each return one Check cannot express shared state, multi-push loops or early stop. |
Accepted (CQ4). |
| SC18 | P2 | 7 | Plan W7 lists the path-consumer inventory "before the first move" and the 11-key snapshot test, but W7 lands last | Intermediate commits (each gated by the full parity run per W1 rule) would run with guards scanning empty files and stale cache keys. | Accepted: inventory + scanner re-point in W0; snapshot test lands with W3 (ordering fix, AR9). |
| SC19 | P2 | 8 | E5 "green on both engines before any W1 conversion"; executor does not exist on master | Ambiguous what E5 runs against on master. | Accepted: on master E5 drives engine.executeRaw (the same unsafe() path); after C10 the same table runs against the executor adapters. |
| SC20 | P2 | 8 | pglite-schema.ts:1305-1309 runtime applyFtsLanguagePolicy(applyChunkEmbeddingIndexPolicy(TEMPLATE, dims)).replace(/__EMBEDDING_DIMS__/g, ...); blob interpolates TS fragments (${PAGE_STATE_SCHEMA_SQL} etc.) |
The generator must evaluate TS fragment modules (so build:schema becomes a Bun TS script, not sed) and emit a template, not a finished string. |
Accepted: scripts/build-schema.ts (the .sh becomes a one-line wrapper to keep build:schema stable); generated PGLite output keeps placeholders; getPGLiteSchema signature unchanged. |
| SC21 | P3 | 8 | Import walk from src/cli.ts: 555 modules, migrate.ts not reachable |
170 migration files do not touch gbrain --version; they do load on every engine connect for source installs. |
Accepted (PF3). |
| SC22 | P3 | 7 | TODOS.md test-audit item on auth --dry-run |
Byte-identical flag registry preserves a known bug. | Noted, no change. |
Scope Challenge result: scope accepted as-is (MODE: FULL_REVIEW). 22 findings, all accepted as amendments; none reduce scope.
Section 1: Architecture review
Component graph after the amended plan (new components in [ ], existing in plain text)
ENTRY POINTS
src/cli.ts main() src/commands/serve-http.ts runServeHttp()
| [CLI_COMMANDS table: name, phase, | [buildServeHttpApp(engine, opts)] (move-only extract, AR6)
| thinClient, selfHelp, skipHooks, | app.use order (cookie, CORS gates, metrics, json)
| aliases, load: () => import('lit')] | mountOAuth ........ serve-http-oauth.ts (existing, extended)
| derives CLI_ONLY / CLI_ONLY_SELF_HELP / | [mountAdminApi] ... [serve-http-admin-api.ts] (requireAdmin passed in)
| THIN_CLIENT_REFUSED / STARTUP_HOOK_SKIP | mountMetrics ...... serve-http-metrics.ts (existing, extended)
| pre-connect branch -> load().run(args) | [mountSpa] ........ [serve-http-spa.ts] (/admin static + {*path})
| connectEngine() terminator | [mountMcp] ........ [serve-http-mcp.ts] (/mcp GET/POST, 415-line handler split)
| post-connect -> load().run(engine,args) |
v v
scripts/generate-flag-registry.ts <--reads-- CLI_COMMANDS table (+ facadeExpansion: commands/sync/, doctor/)
|
src/commands/doctor.ts buildChecks() | src/commands/sync.ts performSync()
-> [DOCTOR_REGISTRY: ordered {name, run(ctx)}] | -> [SyncRun state] -> [commands/sync/{preflight,deletes,
run returns Check[] | STOP; category from | renames,imports,finalize,args}.ts]
doctor-categories.ts categorizeCheck() | phases read/write run.<field> only
v
src/core/operations.ts (unchanged contract) ---> BrainEngine interface (engine.ts, unchanged surface)
|
+----------------------------------------+----------------------------------------+
| |
PGLiteEngine (facade) PostgresEngine (facade)
get db() / tx clone getter get sql() / tx clone getter
one-line delegations for migrated domains withScopedReadTransaction (RLS)
dialect-specific methods (baseline TSV) dialect-specific methods (baseline TSV)
| get engineSql() -> new executor per call (AR1) |
v v
[engine-sql/dialect-pglite.ts] [engine-sql/dialect-postgres.ts]
db.query(sql, params) via the same runUnsafe(conn, sql, params,
checkpoint admission / PgliteStatementCache {signal?, prepare:true, simple:false})
affectedRows from result no checkoutGauge (CQ6); count -> affectedRows
\ /
+-------------------> [engine-sql/executor.ts] <-----------------------------+
Executor { query(sql, params, opts) -> {rows, affectedRows} }
ScopedRead / LegacyUnscopedRead brands (AR2)
[engine-sql/normalize.ts] declared column kinds (A5)
reuses SqlValue + executeRawJsonb(Pick<BrainEngine,'executeRaw'>) from sql-query.ts
|
[engine-sql/{facts,takes,salience,code-edges,cjk-search}.ts] (+ W1-extended domains if UC1 includes them)
[engine-sql/bootstrap.ts] E1 single forward-reference bootstrap (callers: both engines' initSchema, db.ts:initSchema)
imports only: executor types, search/read-policy-sql, search/sql-ranking, cjk-keyword-sql, types.ts
NEVER imports pglite-engine.ts / postgres-engine.ts (layering test, AR4)
SCHEMA TEXT (W2)
src/schema.sql (canonical, non-fragment tables) --+
TS fragment modules (canonical, 20 tables) -------+--> [scripts/build-schema.ts] --> schema-embedded.generated.ts (PG blob)
PGLite-only rules (slug_aliases, page_aliases) ---+ (T1: also writes schema.sql --> [pglite-schema.generated.ts]
BEGIN/END GENERATED regions) template w/ placeholders
getPGLiteSchema(dims, model) unchanged
MIGRATIONS (W3)
[schema-migrations/v002-...v175-*.ts] --> [scripts/build-schema-migrations.ts] --> [schema-migrations/registry.generated.ts]
[schema-migrations/types.ts, helpers.ts] (leaf) static imports, sorted
src/core/migrate.ts (runner ~720 lines): imports registry; re-exports MIGRATIONS, LATEST_VERSION, type Migration
TEST-ONLY HASH (AR7)
computeSnapshotSchemaHash inputs == static-import closure of {pglite-schema.generated.ts, registry.generated.ts,
engine-sql/bootstrap.ts, migrate.ts} (asserted by a unit test; same list feeds all 11 CI cache keys)
GUARDS (W5/W7)
[check-function-size.ts] (src only, name-path keys) ; [engine-sql ratchet + baseline TSV] ; [engine-sql dynamic-SQL scanner]
[schema freshness] ; [migrations registry freshness/duplicate/filename] ; [verify-move-only.ts] (reviewer tool)
existing, re-pointed: check-jsonb-pattern.sh, check-engine-dynamic-import.sh, select-e2e.ts, e2e-test-map.ts,
serve-http-admin-route-guard.test.ts, test/helpers/*-source.ts loaders
Workstream dependency and ordering
W0 gates on master (goldens, inventories, E5 via executeRaw, loaders, path-consumer re-point) <- must precede every move
|
+--> W5 function-size guard (baseline 77 rows, src only) -- each later commit updates baseline rows it moves
|
+--> W3 migrations split (+ AR7 hash-closure test + 11 CI keys, same commit) <- before W2: the generated
| registry is a hash input
+--> W2 schema generation (+E4, +T1, + EO3 upgrade-replay) <- before E1: bootstrap probe
| sets follow the new blob
+--> W1 executor (C10) -> W1-core domains, one commit each, full parity run each -> E1 bootstrap last
| (W1-extended domains after, only if UC1 includes them and each passes its inventory)
|
+--> W4 (independent of W1 code; ordered after it to keep engine files stable while W4 edits commands/)
| sync (move, then mechanical-rename, then behavior) -> doctor -> serve-http (AR6 extract first) -> cli (+generator)
| -> cut line: jobs, hybrid, autopilot
|
+--> W6 moved-symbol map from AST (merge-base..head), porting kit, rebase, final goldens
+--> W7 docs (CLAUDE.md, CONTRIBUTING, ENGINES, key-files) + build:llms ; ceilings lowered ; PATCH bump via /ship
Ordering verdict: the plan's order W0, W5, W3, W2, W1, W4, W6, W7 is correct with one fix (AR9: path-consumer re-pointing and the snapshot-key test belong to W0/W3, not W7).
Findings
AR1 [P1] (confidence 9/10) CRITICAL GAP. src/core/postgres-engine.ts:585-588, src/core/pglite-engine.ts:1725: executor lifetime vs transaction clone.
Quoted: const txEngine = Object.create(this) as PostgresEngine; ... Object.defineProperty(txEngine, 'sql', { get: () => tx });.
If the engine-sql executor is constructed once (in connect() or the constructor) and stored in a field, txEngine inherits that
field through the prototype chain and every migrated write inside engine.transaction() runs on the pool, commits immediately, and
survives the rollback. Nothing errors; data integrity breaks silently. Realistic trigger: putPage + facts write inside one
transaction, followed by a failure. Fix: the executor is a getter that wraps this.sql / this.db at call time (the pattern the
peeled deps already use, get sql() { return self.sql; }), plus contract test EO1 on both engines. Auto-decided: accept (P1, P5).
AR2 [P1] (9/10) RLS scoping status must be preserved per method, not imposed. postgres-engine.ts:281-312, :5566-5569.
The brand in A3 is right in spirit and wrong in rule. Master scopes 23 read sites; the W1-core salience/facts/takes/code-edges reads
are unscoped. Fix: two brands, ScopedRead (only from withScopedReadTransaction) and LegacyUnscopedRead (from
legacyUnscopedRead(reason)), both accepted by read functions whose master counterpart used that mode; a W0 inventory golden lists
every engine read method and its master mode; a unit test fails if a migrated method's mode differs. Casting to either brand is
banned by the guard. Extending RLS scoping to the unscoped reads is a security improvement and a behavior change: TODO (E-TODO-1).
Auto-decided: preserve (P5, plan's behavior-preserving goal). Taste TE3 recorded.
AR3 [P1] (9/10) CRITICAL GAP. Existing PGLite brains replay the regenerated blob. pglite-engine.ts:1066-1069.
E4 compares fresh installs. An existing brain built by master runs the new generated blob plus bootstrap on first boot after the
upgrade: any forward reference the old template did not have, any ALTER from schema.sql that is not a no-op on that shape, or
any CREATE OR REPLACE FUNCTION body that differs would mutate or wedge real user brains (the #239-#396 incident class the
bootstrap exists for). Fix EO3: an upgrade-replay test that builds a PGLite data dir with master's blob (the committed
test/fixtures/pglite-snapshot.tar of master, pinned as a golden fixture in W0), opens it with the branch, runs initSchema, and
asserts success, identical E4 catalog, and an idempotent second boot. Plus the existing schema-bootstrap-coverage.test.ts runs
unchanged against the generated blob.
AR4 [P2] (8/10) Layering: no back-edges. engine-sql/** must never import either engine file (would recreate the god class
through the back door and create cycles with the facades); schema-migrations/** must never import migrate.ts (SC2). Fix: one
layering unit test over the static import graph (reuse the orphan-module walker in scripts/check-orphan-modules.mjs), bad/good
fixtures. Accept (P5).
AR5 [P1] (8/10) CLI table must carry the dispatch phase and thin-client mode. cli.ts:2103, :2113, :3012.
Record shape becomes { name, phase: 'pre-connect' | 'post-connect', thinClient: 'none' | 'refuse' | 'route-then-refuse', selfHelp, skipStartupHooks, aliases, load }. Subcommand-specific routing (sources writer|..., takes add|..., capture,
forget, call to the persistence delegate; agent register pre-guards) stays as explicit ordered code before table dispatch,
because it depends on args, not the command name (P5: explicit beats a clever predicate field). W0 golden (static extraction on
master): per command, its phase (branch position relative to the connectEngine() terminator), its thin-client mode, and each
subcommand routing rule; the table test asserts equality. Behavioral proof: EO5 runs every engine-free command with an unreachable
DATABASE_URL and asserts the master exit code and output.
AR6 [P1] (8/10) serve-http route golden needs a feasible capture method. serve-http.ts:858.
Decision: W0 captures an AST golden on master (ordered app.use/get/post/all(path, ...handlers) calls across serve-http*.ts,
following mount*(app, ...) calls, recording handler identifiers or <inline:N>). The first W4 serve-http commit is move-only and
extracts buildServeHttpApp(engine, options) which runServeHttp calls (a production caller exists, so no test-only seam). From
then on a runtime golden reads Express 5 app.router.stack (method, path, handler names, including requireAdmin which is a named
function declaration). At the extraction commit both goldens must describe the same order; afterwards the runtime golden is
authoritative and the extended admin-route guard (DX D32/O8) uses the same introspection plus its structural scan. Taste TE1.
AR7 [P1] (8/10) Snapshot hash inputs derived from the import closure, not hand lists. pglite-engine.ts:334-366.
Fix EO7: a unit test computes the static relative-import closure of pglite-schema.generated.ts, registry.generated.ts,
engine-sql/bootstrap.ts and migrate.ts, and asserts (a) computeSnapshotSchemaHash hashes every file in it (directory reads
are fine: readdirSync over schema-migrations/ sorted), and (b) each of the 11 CI keys covers the same set (globs allowed:
src/core/schema-migrations/**, src/core/engine-sql/**). Supersedes the hand-list parts of CEO A6 and DX O7 while keeping their
verifications. This also closes today's gap where the PGLite bootstrap in pglite-engine.ts is not hashed at runtime.
AR8 [P2] (8/10) Compiled binary: command loaders must stay statically analyzable. Switch cases were literal
await import('./commands/x.ts') by construction; a table invites import(\./commands/${name}.ts`), which bun build --compilecannot bundle. Fix: table test asserts everyloadis an arrow returning anImportCallwith aStringLiteralargument;check-compile-autoload.sh` stays the backstop. Accept (P1).
AR9 [P2] (7/10) Ordering of guard re-points. See SC18. Accept.
Security summary: RLS (AR2), admin auth (AR6 + DX O8), OAuth/CORS order (plan's authenticated request-outcome tests + route golden),
trust boundary (remote:false set in cli.ts stays in main; the table never constructs OperationContext), SQL injection (CQ3).
No new secrets, dependencies or network surfaces.
One realistic production failure per new path: executor in tx (AR1), RLS-on host (AR2), PGLite upgrade (AR3), cyclic import at load
(AR4), DB-down status (AR5), admin route without auth (AR6), stale snapshot false-green (AR7), missing command in compiled binary
(AR8). Each has an obligation below.
Section 2: Code quality review
CQ1 [P1] (9/10) Prepare and protocol parity. postgres-engine.ts:5363 pending = conn.unsafe(sql, params as ..., { cancelFence: !!signal });
Extend runUnsafe's opts with prepare?: boolean; simple?: boolean forwarded to unsafe(). The engine-sql adapter always passes
{prepare: true, simple: false}; executeRaw/executeRawDirect keep passing nothing (unchanged). Accept (P5, P3).
CQ2 [P2] (9/10) DRY on JSONB. sql-query.ts:118. Widen executeRawJsonb(engine: Pick<BrainEngine,'executeRaw'>, ...); the
engine-sql executor implements executeRaw so the same helper (and its top-level-array refusal) serves both. No second JSONB
helper; verify with rg -n "function executeRawJsonb" src = 1 hit. Accept (P4).
CQ3 [P1] (9/10) Dynamic-SQL rule that matches the code. sql-ranking.ts:405, postgres-engine/facts.ts:489.
Amend A2b: in engine-sql/**, a ${...} inside a SQL template (or + string concatenation into SQL) is allowed only when the
expression is (1) a member of a constant as const identifier/ORDER allowlist, (2) a call to a registered vetted builder
(pageReadFilter, buildRecencyComponentSql, privatePagesFilterFragment, currentCodeEdgeFilter, buildCJKKeywordSql,
ENRICH_ORDER_SQL; registry lives in the scanner with a one-line reason each), or (3) a numeric expression guarded by
Number.isFinite in the same function (the vector-literal case). Everything else fails with FAIL/Why/Fix/See. Inlined literals on
master stay inlined (planner behavior). Accept (P1, P5).
CQ4 [P2] (8/10) Doctor registry contract. doctor.ts:2017, :1850, :1886.
type DoctorEntry = { name: string; run(ctx: DoctorContext): Promise<Check[] | typeof STOP_DOCTOR> }. DoctorContext carries the
parsed flags (jsonOutput, fastMode, doFix, dryRun, scope, orphanRatioSourceId), engine, progress, skillsDir, and the
explicitly named cross-check values (schemaVersion, autoFixReport), written by the entry that computes them. The runner stops
on STOP_DOCTOR exactly where master returned early. name is the entry's primary check name for the ordered-names golden; entries
that emit several checks list them in emits: readonly string[] so the category test covers all. Accept (P5). Taste TE4.
CQ5 [P2] (8/10) Generated file naming. SC3. Accept.
CQ6 [P2] (8/10) Pool diagnostics parity. postgres-engine.ts:5388. The adapter calls runUnsafe directly, not executeRaw,
so checkoutGauge accounting matches master (tagged sites never touched it). Pool-diagnostics golden: gauge snapshot after a fixed
op sequence equals master. Accept (P5).
CQ7 [P2] (8/10) One token normalizer for two proofs. A11's handler hash and E3's move-only verifier both need "tokens with
whitespace and comments normalized". Put it once in scripts/lib/normalize-tokens.ts (TS scanner based). E3 gains two modes:
--wrapper migration (compare the object-literal expression per version, ignoring the export const vNNN: Migration = wrapper)
and --rename-map <file> (identifier rewrites such as pullFailed -> run.pullFailed), used by commits tagged
Mechanical-Rename: yes. Accept (P4, P5). Taste TE5.
CQ8 [P2] (9/10) Explicit row-count contract. postgres-engine/facts.ts:128 return (result.count ?? 0) > 0; vs
pglite-engine/facts.ts:123 return (result.affectedRows ?? 0) > 0;. Executor returns { rows, affectedRows } from both adapters
(Postgres RowList.count, PGLite affectedRows); domain code reads only affectedRows. E5 adds UPDATE/DELETE/INSERT ... ON
CONFLICT DO NOTHING rows. Accept (P5).
Error-handling gaps: executor and domains never catch (CEO rule kept); runUnsafe already throws synchronously on a pre-aborted
signal, and adapters must use try/finally, not .finally (the pattern documented at postgres-engine.ts:5385-5387).
Stale diagrams in touched files: pglite-schema.ts:9-28 header (removed by W2), schema-drift.test.ts:1-23 (update with E4),
doctor-categories.ts header, check-module-size.sh:12 region-exempt comment, schema-bootstrap-coverage.test.ts:26-31 "When you
add a new schema-blob forward reference" steps (must name engine-sql/bootstrap.ts after E1).
Shared-code rubric applied: CQ2 (callers: 18 existing executeRawJsonb sites + engine-sql adapters; net savings ~0 lines, reliability
gain: one JSONB rule) and CQ7 (callers: A11 golden test + verify-move-only.ts; ~60 lines once instead of twice) pass. Rejected: a
shared "route table extractor" used by both the AST and runtime goldens (different inputs, no common contract).
Section 3: Test review
Test framework
CLAUDE.md routes to docs/TESTING.md: Bun test (bun test), tiers bun run test (unit shards + serial), bun run verify (guards,
scripts/run-verify-parallel.sh CHECKS), test:e2e (real Postgres, DATABASE_URL), ci:local / ci:ubicloud (full gate incl.
PgBouncer). Guard fixtures under test/fixtures/guards/<guard>/{bad,good}/ via GBRAIN_GUARD_ROOT; registry
scripts/guards-manifest.tsv; source reads need test-reads-source-ok[<category>] markers (test/test-reads-source-smell.test.ts).
No LLM/prompt files are touched: no eval suites required (CEO's optional LongMemEval-mini smoke stays optional).
Coverage diagram (codepaths and user flows; planned code, traced against current code)
CODE PATHS USER FLOWS
[+] engine-sql/executor.ts + adapters (W1, C10) [+] Storage call through engine (every op)
|- query(sql, params, opts) |- [GAP->EO1 ★★★] write in transaction() then throw -> rolled back
| |- params: text[]/int[]/real[], jsonb obj, jsonb top-level array | (PGLite + Postgres) [->E2E]
| | (refused), bigint>2^53, Date tz, null, bool, vector literal |- [★★★ EXISTS] 28 parity/drift files, engine-parity.test.ts,
| | [GAP->E5 ★★★ planned] both engines; on master via executeRaw | operations-source-isolation-matrix.test.ts (run per domain)
| |- empty array [GAP->E5 row] |- [GAP->EO4 ★★★] RLS flag ON: scoped reads bind app.scopes;
| |- affectedRows (UPDATE/DELETE/ON CONFLICT) [GAP->CQ8 row] | legacy-unscoped reads open no tx [->E2E]
| |- errors 23505 / 57014 / 40P01 pass-through [DX O14 planned] |- [GAP->EO6 ★★] direct PG reuses prepared stmt; PgBouncer none
| |- signal: pre-aborted (sync throw) / mid-query cancel | [->E2E]
| | [★★★ EXISTS for executeRaw: postgres-engine cancellation tests; |
| | GAP: same matrix through adapter -> E5 row] [+] Upgrade and init
| |- prepare:true, simple:false forwarded [GAP->EO6] |- [★★ EXISTS] fresh init schema-drift (cols+indexes)
| |- no checkoutGauge on adapter path [GAP->EO9 golden] |- [GAP->E4 ★★★ planned] catalog-level incl. PGLite ordinal (T-G13)
|- get engineSql() per call (tx clone) [GAP->EO1 CRITICAL] |- [GAP->EO3 ★★★ CRITICAL] master-built PGLite brain -> branch boot
|- brands ScopedRead / LegacyUnscopedRead |- [GAP->W3 planned ★★★] PG brain at older version -> apply split
| |- typecheck rejects plain executor [A3 @ts-expect-error] | registry -> E4 catalog [->E2E]
| |- mode per method == master inventory [GAP->EO4 unit] |
|- normalize(row, kinds) jsonb/bigint/date/vector/text[] [A5 planned] [+] CLI (thin client, DB down, help)
| |- unknown kind throws [A5 planned] |- [GAP->EO5 ★★★] engine-free cmds with unreachable DB: status,
[+] engine-sql/<domain>.ts x5 (+W1-extended) | db-repair, pglite-repair, bootstrap, hook (exit + output)
|- SQL text byte-equal to master modulo $N renumbering [GAP->EO8] |- [GAP->A16b planned ★★★] --help, --tools-json, unknown cmd,
|- inlined literals stay inlined (vector, decay map) [GAP->EO8] | thin-client refusal matrix (command AND subcommand level)
|- dynamic fragments only via vetted builders [GAP->CQ3 scanner] |- [★★ EXISTS] test/cli-flag-validation.test.ts; regenerated
[+] engine-sql/bootstrap.ts (E1) | registry zero diff (DX O6)
|- 3 callers: PG initSchema, db.ts initSchema, PGLite initSchema |- [GAP->EO5b] synthetic table command: flag ok / unknown rejected
|- per-engine probe sets preserved [★★★ EXISTS | / help engine-free (plan W4 item, keep)
| schema-bootstrap-coverage.test.ts, re-pointed not rewritten] |
|- legacy-shape boot both engines [★★ EXISTS [+] serve-http
| test/e2e/postgres-bootstrap.test.ts; PGLite via test:382] |- [★★ EXISTS] test/e2e/serve-http-oauth.test.ts (revocation, PKCE,
[+] schema-migrations/ (W3) | CORS, DCR)
|- registry.generated.ts sorted, static imports [GAP->W3 planned ★★★] |- [GAP->A16/AR6 ★★★] route table golden (AST@master, runtime after)
| |- duplicate version -> FAIL names both files [DX O10 planned] |- [★★ EXISTS->extend] admin-route-guard: scan every module +
| |- filename/version mismatch [DX O4 planned] | runtime; mutation test in moved module [->E2E-ish unit]
| |- file missing from registry (freshness) [W3 planned] |- [GAP->plan] authenticated outcome: OAuth preflight/CORS order,
| |- gaps 17-19,100 preserved; 170 entries [A11 planned] | admin 401 vs 200 on every /admin/api route
|- helpers.ts leaf; no import of migrate.ts [GAP->EO10 layering] |
|- handler token hash normalized [GAP->CQ7] [+] doctor
|- migrate.ts re-exports (MIGRATIONS, LATEST_VERSION, type Migration) |- [GAP->W0 planned ★★★] normalized --json goldens PGLite/PG/degraded
| [DX O13 export golden] |- [GAP->EO11] null engine / connection failure / --fast early stop
|- snapshot hash closure incl. bootstrap [GAP->EO7 CRITICAL |- [GAP->DX O5] uncategorized entry fails with FAIL/Why/Fix/See
| silent false-green otherwise] |
[+] scripts/build-schema.ts (W2) [+] sync
|- evaluates TS fragments; template placeholders preserved [GAP->EO12] |- [★★★ EXISTS] test/sync.test.ts, sync-* tests (re-pointed per A10)
|- BEGIN/END GENERATED banners; freshness guard names source file |- [GAP->A17 ★★★] phase-await vs watchdog / vs timeout, both orders,
| [W2 planned + DX O9] | latch-wrapped BrainEngine + fake timers (seam=none)
|- capability rules (PG-only, PGLite-only tables) not subtraction |- [GAP->A17 guard] no destructuring of run fields
| [W2 planned; proven by E4] |- [★★ EXISTS] resume-from-checkpoint tests
|- unknown construct -> exit !=0 [GAP->fixture] |
[+] DOCTOR_REGISTRY runner (W4) [+] search
|- ordered names == master AST order [GAP->W0 planned] |- [GAP->A13 planned ★★★] hybrid golden cold+warm exact (id,score)
|- Check[] | STOP semantics [GAP->EO11] |- [★★ EXISTS] hybrid-*.test.ts, hybrid-arm-rethrow.test.ts
|- category from categorizeCheck, emits[] covered [DX O5] |
[+] SyncRun + commands/sync/* phases (W4) [+] jobs (cut line)
|- run.<field> only (guard) [A17 planned] |- [GAP->A15 planned] 24 names same order; supervisor probe
|- controlled-order tests [A17 planned] | (supervisor.ts:859 dynamic import) keeps working
[+] CLI_COMMANDS table + derived sets (W4) |
|- derived sets == master sets [plan W0 golden] [+] Contributor flows (W7)
|- phase + thinClient per command == master [GAP->EO5 golden] |- [GAP->DX O18] timed dry-run, six change kinds
|- load is literal import() [GAP->EO13] |- [★ smoke only] docs-cli-commands truth check for new recipes
|- generator reads table; registry zero diff [DX O6]
[+] buildServeHttpApp + serve-http-*.ts modules (W4)
|- global app.use order + per-route chain [AR6 goldens]
|- 415-line /mcp handler split: same responses [★★ EXISTS e2e oauth/mcp; runtime golden]
[+] guards: function-size / engine-sql ratchet / dynamic-SQL / freshness x2 / verify-move-only
|- bad+good fixtures, FAIL/Why/Fix/See, manifest rows [DX O9 planned]
|- function-size: arrow/obj-method/class-prop/anon handler forms [A18 planned]
|- function-size: src-only scope, tests excluded [GAP->SC4 fixture]
|- verify-move-only: wrapper + rename-map modes [GAP->CQ7 fixtures]
[+] perf budgets (f) [GAP->EO14 bench incl. engine-connect cold start]
COVERAGE (planned codepaths + flows): 58 paths | existing ★★/★★★ owners: 13 (22%) | planned by CEO/DX/plan: 29 | new Eng gaps: 16
QUALITY of existing owners: ★★★:5 ★★:8 ★:1 (docs truth check)
GAPS after all accepted obligations: 0 unowned (2 CRITICAL closed: EO1, EO3; 1 silent CI false-green closed: EO7)
E2E-marked: 8 ([->E2E]); EVAL: 0 (no prompt/LLM change)
Legend: ★★★ behavior + edge + error | ★★ happy path | ★ smoke | [->E2E] needs real Postgres / PgBouncer | [GAP->X] gap closed by obligation X.
Regression rule (IRON RULE) applied
Every rewrite that puts existing behavior at risk has a named regression contract (auto-approved under autoplan, recorded in the
audit trail): storage behavior (28 parity files unchanged + E5 + EO1 + EO4 + EO6 + EO8), schema end state (E4 + EO3), migration
content and apply (A11 + W3 apply-from-older), CLI (A16b + EO5), HTTP auth (A16 + AR6 + O8), doctor (W0 goldens + EO11), sync
(A17), hybrid (A13), export surface (O13). Intentional differences: none, except the .d.ts gaining export type { Migration }.
Missing tests added to the plan (Eng; each with a value card)
| ID | File (naming follows repo) | Type | Assertion | Value card |
|---|---|---|---|---|
| T-G1 (EO1) | test/e2e/engine-sql-transaction-parity.test.ts + PGLite arm in test/engine-sql-transaction.test.ts |
unit + E2E | inside engine.transaction(): migrated write (facts insert, takes upsert, code-edges insert) then throw; afterwards rows absent; a concurrent pool read during the tx does not see them |
protects=transaction atomicity for engine-sql writes; fails_when=executor bound to pool at connect time; why_new=no test writes through a peeled module inside transaction(); seam=none |
| T-G2 (EO3) | test/pglite-upgrade-replay.test.ts |
unit (PGLite) | master-built data dir fixture -> branch initSchema succeeds; catalog == master catalog; second initSchema changes nothing |
protects=existing PGLite users' first boot after upgrade; fails_when=generated blob adds a non-idempotent statement or forward ref; why_new=E4 is fresh-install only; seam=none |
| T-G3 (EO4) | test/engine-sql-read-scope.test.ts (extends fake-sql pattern of postgres-engine-rls-scope.test.ts) + test/e2e/engine-sql-rls-scope.test.ts |
unit + E2E | per migrated read method: flag ON -> scoped methods show set_config in the tx lane, legacy-unscoped methods show pool lane only; e2e asserts current_setting('app.scopes') inside a scoped store read |
protects=RLS layer 2 and #1794 no-pool-hold; fails_when=a method gains or loses the scoped tx; why_new=existing test pins the helper, not each migrated method; seam=none |
| T-G4 (EO6) | row in E5 contract test + test/e2e/engine-sql-prepare-parity.test.ts |
E2E | direct PG: after 2 calls pg_prepared_statements on that backend contains the statement; PgBouncer: none; zero-arg query never simple protocol (fake-conn unit asserts options) |
protects=no Describe round trip regression on direct Postgres; fails_when=adapter drops prepare:true or lets args.length===0 pick simple; why_new=tagged templates prepared implicitly; seam=none |
| T-G5 (EO9) | row in test/postgres-engine.test.ts pool diagnostics section |
unit | gauge snapshot after fixed op sequence == master golden | protects=doctor pool-check inputs; fails_when=adapter routes via executeRaw; why_new=gauge untested for peeled domains; seam=none |
| T-G6 (EO5) | test/cli-dispatch-phase.test.ts (golden) + test/cli-engine-free-db-down.serial.test.ts |
unit + serial CLI | per command phase/thinClient == master extraction; engine-free commands with unreachable DB give master exit code and first output line | protects=DB-down contract and thin-client routing; fails_when=table drops phase; why_new=no test pins dispatch phase; seam=none |
| T-G7 (EO13) | inside the CLI table test | unit | every load is () => import('<literal>') |
protects=compiled binary includes every command; fails_when=computed specifier; why_new=switch made it structural; seam=none |
| T-G8 (EO7) | test/snapshot-inputs-closure.test.ts (merged with DX O7's cache-key test, one file) |
unit | closure ⊆ hash inputs; closure ⊆ each of 11 CI keys; failure names file + both places | protects=unit suite never runs on stale snapshot; fails_when=bootstrap or a migration helper omitted; why_new=hash list omits pglite-engine.ts today; seam=none |
| T-G9 (EO10) | test/scripts/layering.test.ts + guard fixtures |
unit | engine-sql imports no engine file; schema-migrations imports no migrate.ts | protects=acyclic load order (TDZ-safe in compiled binary); fails_when=a handler imports migrationNotice from migrate.ts; why_new=new dirs; seam=none |
| T-G10 (EO11) | extend test/doctor.test.ts buildChecks cases |
unit | buildChecks(null, ...), connection failure, --fast: returned check names and statuses == master golden |
protects=doctor early-stop contract; fails_when=runner ignores STOP; why_new=registry runner new; seam=none |
| T-G11 | test/fixtures/guards/check-engine-sql-dynamic/{bad,good} |
guard fixture | raw string interpolation fails; vetted builder and finite numeric pass | protects=no injection via conversion; fails_when=allowlist too loose or too strict; why_new=new scanner; seam=none |
| T-G12 | test/scripts/verify-move-only.test.ts |
unit | wrapper mode passes a real W3 move; rename-map mode passes SyncRun rewrite; single edited token fails both | protects=move proof usable at ~50k lines; fails_when=normalizer ignores a changed token; why_new=new tool; seam=none |
| T-G13 | extend test/helpers/schema-diff.ts + E4 test |
E2E | PGLite master-vs-branch includes ordinal_position; PG-vs-PGLite stays name-based |
protects=column order for SELECT * consumers; fails_when=generator reorders columns; why_new=diff is name-based; seam=none |
| T-G14 (CQ8) | rows in E5 | unit + E2E | UPDATE/DELETE/ON CONFLICT DO NOTHING affectedRows equal across engines | protects=boolean/count results of write methods; fails_when=adapter reads wrong field; why_new=per-engine code read different fields; seam=none |
| T-G15 (EO14) | perf harness under scripts/ (bench, not a test) |
bench | PGLite connect+initSchema cold (snapshot on/off), gbrain --version, hot paths; within noise / +20 ms |
protects=cold start and hot-path latency; fails_when=170-module load or lost prepare; why_new=no budget exists; seam=none |
| T-G16 (EO8) | test/engine-sql-sql-text.test.ts (W0 golden per converted Postgres method) |
unit | SQL text emitted by each converted method == master tagged-template text with $N renumbering (captured with fake sql on master) |
protects=no semantic SQL drift during tagged-to-positional conversion; fails_when=a clause, literal or cast changes; why_new=parity tests check results on fixtures, not text; seam=none |
Rejected (value bar): a separate "executor unit test with mocked driver" beyond E5 (covered_elsewhere: E5 runs both real engines). Tests made obsolete by this plan: none (retirement requires evidence per TESTING.md; not proposed).
Test plan artifact: (autoplan scratch).
Section 4: Performance review
PF1 [P1] (9/10) Prepared statements and protocol (direct Postgres). Covered by CQ1/SC5. Without prepare: true, every converted
hot query (searchVector, searchKeyword, _upsertChunksOnce, getPage if W1-extended) takes a Parse+Describe round trip
(connection.js:244 q.describeFirst = q.onlyDescribe || (parameters.length && !q.prepared)), 30-80 ms on hosted Postgres.
Budget: T-G4 + EO14 bench, no regression beyond noise.
PF2 [P2] (8/10) RLS wrap would add a pool hold per read. Avoided by AR2 (preserve).
PF3 [P2] (8/10) Cold start. gbrain --version does not load migrate.ts (import walk: 555 modules from src/cli.ts, migrate.ts
absent), so the CEO budget holds trivially there. Every DB-touching command on source installs now loads ~175 extra modules through
engine-factory -> engine -> migrate -> registry. Budget (EO14): PGLite connect + initSchema (snapshot path) cold start ≤ +20 ms
on the 4-core machine; if exceeded, fallback is a single generated bundle module for the registry, not dynamic imports (engine
dynamic-import rule).
PF4 [P3] (7/10) Checkpoint gauge / connection reservation. Adapter forwards signal only where master did (A4); runUnsafe
reserves a connection only when a signal is present (postgres-engine.ts:5358). No change if A4 is followed; T-G5 guards gauge.
PF5 [P3] (8/10) N+1 and batching. Batch writes use unnest / jsonb_to_recordset today (code-edges.ts:42,65,
salience.ts setEmotionalWeightBatch). EO8's SQL-text golden prevents a per-row loop sneaking in during conversion.
PF6 [P3] (7/10) Memory. 170 module records + closures are already allocated today inside one array; no growth. Prepared statement cache per backend grows with distinct SQL text exactly as today (vetted builders produce the same variants).
PF7 [P2] (8/10) CI wall time and cost. W1 rule "full e2e parity run after each domain commit": 5 core + E1 + up to 7 extended =
up to 13 ci:ubicloud runs at 5 min wall + 70-90 s setup each, against a 256 vCPU project quota shared with PR CI (TESTING.md
"Ubicloud fan-out"). Run them with the default 4 VMs, never 2-3 s measured by CEO scratch run), engine-sql scanners over a small dir.
DX O15 (<15 s each, verify +<20%) holds.--vms 10, and batch W4 commits into one gate per god function.
New verify guards: TS-AST function-size over ~1,473 files (
PF8 [P3] (7/10) Caching. PgliteStatementCache and checkpoint admission kept by the PGLite adapter (A4); snapshot fixture stays
valid across the PR because hash inputs change only when schema inputs change (AR7).
NOT in scope
- D1 (CEO): the ~60 other >300-line functions outside touched src files (
runCycle1,227,applyHarness1,167,runPhaseSynthesizeInner1,043,runImport956,importFromContent910,makeSubagentHandler884,runConfig834). W5 freezes them. - D2 (CEO):
src/core/regroup,ai/gateway.tsadapters, cycle/extract/embed/import-file/init. - T3 (CEO): phase-named sync errors (keeps goldens byte-identical).
- Engine table-set reconciliation (a real schema change for existing PGLite brains).
- Extending RLS scoping to reads that master leaves unscoped (AR2): security improvement, separate behavior change (E-TODO-1).
- Fixing the flag-registry
auth --dry-rundrop (existing TODO): byte-identical registry preserves it. - Timestamp migration versions, router-level
requireAdmin, scaffolders beyond the migration scaffold (DX). - Replacing the 28 parity tests with executor contract tests (E-TODO-3): only after every domain is migrated.
- Decomposing test-file
describecallbacks over 300 lines (SC4): tests are outside goal (b) and W5. - Rejected: cyclomatic guard, store-vs-legacy feature flag, ORM/query builder, migration renumbering, runtime-computed command loaders.
What already exists
Reuse (not rebuild): sql-query.ts (SqlValue, widened executeRawJsonb), runUnsafe (extended opts), withScopedReadTransaction
(unchanged), peeled-deps getter pattern (executor lifetime), vetted SQL fragment builders (A2b registry), build-schema.sh (becomes a
wrapper over build-schema.ts), schema-drift.test.ts + schema-diff.ts (E4, ordinal), schema-bootstrap-coverage.test.ts
(re-pointed, logic unchanged), computeSnapshotSchemaHash (closure-derived inputs), doctor-source.ts (generalized loaders),
doctor/checks/* + categorizeCheck (registry), serve-http-{oauth,metrics,...}.ts mount* convention, existing
serve-http-admin-route-guard.test.ts (extended), generate-flag-registry.ts facadeExpansion (re-targeted),
check-module-size.sh semantics (copied by the new ratchets), check-engine-dynamic-import.ts (AST guard pattern),
check-orphan-modules.mjs import walker (layering test), guards-manifest.tsv + guard-self-test.sh,
test/postgres-engine-rls-scope.test.ts fake-sql pattern (T-G3), check-test-discriminates.sh.
Accepted shared-code choices: CQ2 and CQ7 (rubric evidence in Section 2).
Failure modes registry
CODEPATH | FAILURE MODE | TEST (after obligations) | ERROR HANDLING | USER SEES | FLAG
---------------------------------|------------------------------------------------|-----------------------------|---------------------|--------------------|-------------------------------
engine-sql executor in tx clone | cached executor bound to pool; writes escape tx| none in plan -> EO1/T-G1 | none | silent data change | CRITICAL GAP (closed by EO1)
PGLite upgrade boot (W2) | regenerated blob mutates/wedges existing brain | none in plan -> EO3/T-G2 | initSchema throws | boot failure or | CRITICAL GAP (closed by EO3)
| | | only on wedge | silent drift |
snapshot hash inputs (W3/E1) | bootstrap/helper not hashed; stale snapshot | partial (A6/O7) -> EO7/T-G8 | none | CI false green | CRITICAL GAP (closed by EO7)
RLS scoping (W1) | method gains/loses scoped tx | partial (A3) -> EO4/T-G3 | none | silent cross-scope | HIGH (closed by EO4)
| | | | read / pool hold |
prepare/simple (W1, PG direct) | unprepared + Describe RTT; simple protocol | none -> EO6/T-G4 | n/a | slower search | WARNING (closed)
converted SQL text (W1) | clause/literal/cast drift in conversion | parity files -> EO8/T-G16 | driver error or | wrong results | HIGH (closed)
| | | silent | |
dynamic SQL (W1) | raw value concatenated into SQL | none -> CQ3/T-G11 | none | injection risk | HIGH (closed)
row counts (W1) | affectedRows read from wrong field | none -> CQ8/T-G14 | none | false/0 results | MEDIUM (closed)
pool gauge (W1) | raw gauge inflated | none -> EO9/T-G5 | none | misleading doctor | LOW (closed)
schema-migrations load (W3) | import cycle -> TDZ at load | none -> EO10/T-G9 | module-load throw | CLI crash on | MEDIUM (closed)
| | | | engine connect |
migration registry (W3) | dup/dropped/mis-sorted version | A11 + DX O10 | generator exit 1 | CI red | covered
build-schema.ts (W2) | TS fragment eval fails / placeholder lost | EO12 + E4 | exit !=0 / E4 diff | CI red | covered
CLI table (W4) | engine-free command connects first | none -> EO5/T-G6 | connect error | `status` fails | HIGH (closed)
| | | | when DB is down |
CLI table (W4) | computed import specifier | none -> EO13/T-G7 | module not found | command missing in | MEDIUM (closed)
| | | at runtime | compiled binary |
serve-http modules (W4) | requireAdmin/limiter dropped or order changed | O8 + AR6 goldens | none | auth bypass | covered (was CRITICAL in CEO)
doctor registry (W4) | continues after STOP / drops check | W0 goldens + EO11/T-G10 | per-check catch | changed output | covered
SyncRun (W4) | stale destructured field across await | A17 guard + ordering tests | none | partial sync | covered
hybrid stages (W4 cut line) | rank/score change | A13 golden | existing rethrow | different results | covered
function-size guard (W5) | syntax form not counted / tests pulled in | A18 fixtures + SC4 fixture | exit 1 | CI red | covered
verify-move-only (W6) | false failures on wrappers; reviewers skip it | CQ7/T-G12 | exit 1 | none (review aid) | covered
Plan as written: 3 CRITICAL GAPS (no test, no error handling, silent): executor in transaction clone, PGLite upgrade replay (silent drift case), snapshot inputs false-green. All three closed by accepted obligations EO1, EO3, EO7.
Worktree parallelization strategy (lanes integrate into the ONE PR branch; no PR stack)
| Step | Modules touched | Depends on |
|---|---|---|
| S0 W0 goldens, inventories, loaders, path-consumer re-point | test/, test/helpers/, scripts/, .github/ | — |
| S1 W5 function-size guard | scripts/, test/fixtures/guards/ | S0 |
| S2 W3 migrations split | src/core/ (migrate, schema-migrations/), scripts/, .github/ | S0 |
| S3 W2 schema generation | src/ (schema.sql), src/core/ (pglite-schema, fragments), scripts/ | S2 |
| S4 W1 executor + domains + E1 | src/core/ (engines, engine-sql/, sql-query) | S3 |
| S5a W4 sync | src/commands/ (sync, sync/) | S0 |
| S5b W4 doctor | src/commands/ (doctor, doctor/) | S0 |
| S5c W4 serve-http | src/commands/ (serve-http*) | S0 |
| S5d W4 cli + generator | src/cli.ts, scripts/ (generate-flag-registry) | S0 |
| S6 W6/W7 docs, map, porting kit, ceilings | docs/, CLAUDE.md, CONTRIBUTING.md, scripts/module-size-limits.tsv | S1-S5 |
Lanes: Lane A: S2 -> S3 -> S4 (shared src/core/ schema+engine). Lane B: S5a. Lane C: S5b. Lane D: S5c. Lane E: S5d.
Execution order: land S0 then S1 on the branch. Launch Lane A and Lanes B-E in parallel worktrees. Merge B-E into the branch in
any order (disjoint command files), then Lane A. Then S6, final rebase, full gate.
Conflict flags: scripts/module-size-limits.tsv and the function-size baseline TSV are touched by every lane (resolve by
re-running the generators/guards after each merge, never by hand-merging rows); .github/workflows/* touched by S0 and S2
(sequence S0 first); scripts/guards-manifest.tsv touched by S0, S1, S2, S4 (append-only rows, sorted).
Completion Summary
+====================================================================+
| ENG PLAN REVIEW - COMPLETION SUMMARY (primary voice) |
+====================================================================+
| Step 0: Scope Challenge | scope accepted as-is (22 findings, all |
| | accepted as amendments; no reduction) |
| Architecture Review | 9 issues found (2 CRITICAL: AR1, AR3) |
| Code Quality Review | 8 issues found |
| Test Review | diagram produced, 16 gaps identified |
| Performance Review | 8 issues found (1 P1: prepare/protocol) |
| NOT in scope | written (10 items + rejected list) |
| What already exists | written |
| TODOS.md updates | 13 items proposed (all phases) |
| Failure modes | 20 rows, 3 critical gaps flagged |
| | (all closed by EO1/EO3/EO7) |
| Unresolved decisions | 0 in this review (UC1 stays the owner's) |
| Outside voice | skipped (autoplan override; driver owns) |
| Parallelization | 5 lanes, 5 parallel / 3 sequential steps |
| Lake Score | N/A (no coverage choices asked; Y=0) |
+====================================================================+
issues_found (Arch+CQ+Perf+Test gaps) = 9 + 8 + 8 + 16 = 41 ; critical_gaps = 3 ; mode = FULL_REVIEW
TODOS.md updates (proposed entries from all phases; NOT written to the repo)
Format: What / Why / Pros / Cons / Context / Depends on. Disposition auto-decided (A = add, C = build now, B = skip).
- P2 (CEO D1) Wave 2: decompose the remaining >300-line functions outside wave-1 files. What:
runCycle1,227,applyHarness1,167,runPhaseSynthesizeInner1,043,runImport956,importFromContent910,makeSubagentHandler884,runConfig834 and the rest of the W5 baseline. Why: W5 only freezes them. Pros: shrinks the baseline, same bug-farm class. Cons: path churn vs open PRs. Context: baseline TSV rows name each function; W4 patterns (state object, registry, stages) apply. Depends on: wave 1 merged + 72-hour revert window. A. - P3 (CEO D2)
src/core/regroup andai/gateway.tsprovider adapters. Why: next layer of structure. Pros: navigability. Cons: large path churn; adapter design question. Context: plan NOT-in-scope. Depends on: D1 partly. A. - P2 (CEO T3) Phase-named sync errors (
TODOS.md:5338). What: SyncRun phases name the failing phase in error/timeout text. Why: debuggability. Pros: small once SyncRun exists. Cons: changes golden text (intentional). Context:src/commands/sync/*. Depends on: wave 1 W4 sync. A (first follow-up). - P3 (DX) Timestamp-based migration versions. Why: sequential numbers collide under ~50 concurrent PRs. Pros: no rebase
renumbering. Cons:
schema_versionsemantics and runner changes. Context: generator's duplicate diagnostic is the stopgap. Depends on: W3. A. - P3 (DX) Router-level admin auth (
express.Router+router.use(requireAdmin)). Why: structural auth. Pros: impossible to forget per route. Cons: changes middleware order pinned by goldens. Context:serve-http-admin-api.ts. Depends on: W4 serve-http. A. - P2 (DX, conditional) Land jobs / hybrid / autopilot decomposition if cut from the window. What: the plan's cut-line items with their goldens (A13, A15). Context: plan W4 cut line. Depends on: wave 1. A only if cut.
- P3 (DX O19) +3-month re-measure. What: fix-commit causes (plan e) plus share of storage PRs editing both engines, conflicts on target paths per merged PR, remaining baseline rows (engine-sql, function-size), median rebase-to-merge. Context: git/GitHub queries recorded in the PR. Depends on: merge date + 3 months. A.
- Closure edits (DX) for
TODOS.md:1868,:1956,:1962,:~1976,:~4445when their workstream lands. C (in this PR). - P3 (DX) Scaffolders for doctor check / route / command. Decision: B (skip until O18 dry-run shows the need).
- P2 (Eng E-TODO-1) Extend RLS scope binding to reads master leaves unscoped. What: move
LegacyUnscopedReadmethods (salience, facts, takes, code-edges reads and others in the inventory) toScopedRead. Why: RLS layer 2 covers only 23 sites today. Pros: defense in depth on hosted Postgres. Cons: withGBRAIN_RLS_SCOPE_BINDING=1, adds a tx + pool hold per read (the #1794 class); needs PgBouncer load test. Context: W0 inventory golden lists them; brand makes the change a type edit. Depends on: wave 1 W1. A. - P3 (Eng E-TODO-2) Autopilot tick extraction coordination. What: if W4 autopilot lands, do the existing test-audit TODO
("Extract a testable autopilot tick function, then retire the 8 autopilot wiring greps") in the same change. Why: avoids
re-pointing 8 grep files twice. Context:
TODOS.mdTest-audit follow-ups. Depends on: cut-line decision. A (annotation on the existing TODO, not a new entry). - P3 (Eng E-TODO-3) Collapse per-domain parity tests into executor contract tests. What: once every domain is in engine-sql, replace duplicated per-domain PGLite/Postgres parity scenarios with executor contract + one shared scenario suite per domain. Why: 28 parity files exist because of dual SQL. Pros: less test maintenance. Cons: retirement needs TESTING.md evidence per file. Context: TESTING.md "Retiring a test". Depends on: all domains migrated (W1-extended or wave 2). A.
- P2 (Eng E-TODO-4, conditional) W1-extended domains not landed in wave 1. What:
pages, links, tags, timeline, sources, files, chunkson the proven executor, each with its per-method inventory and baseline-row removal in the same commit (DX D35). Context: UC1 outcome. Depends on: UC1. A only if UC1 = W1-core.
Decision Audit Trail (Eng phase)
| # | Phase | Decision | Classification | Principle | Rationale | Rejected |
|---|---|---|---|---|---|---|
| E1 | Step 0 B | Scope accepted as-is; Original arrangement with naming fixes | Mechanical | P2, P6 | Owner's one-PR rule; every workstream serves a goal | Feature cuts; smaller arrangement that drops E1/T1 |
| E2 | SC1 | Move Migration type to schema-migrations/types.ts, type re-export from migrate.ts |
Mechanical | P5 | Type is module-private today (migrate.ts:61) |
Exporting from each migration file |
| E3 | SC2 | Leaf schema-migrations/helpers.ts for migrationNotice, quiet flag, dropInvalidConcurrentIndex |
Mechanical | P5 | Avoids migrate.ts cycle and TDZ | Importing helpers from migrate.ts |
| E4 | SC3 | Registry file registry.generated.ts |
Mechanical | P5 | Repo convention (build-schema.sh:3-4) |
index.ts |
| E5 | SC4 | Goal (b) and W5 scoped to src/** minus generated |
Mechanical | P3, P5 | Tests have >300-line describe callbacks | "Any touched file" |
| E6 | SC5/CQ1 | Adapter passes {prepare:true, simple:false}; no per-call resolvePrepare |
Mechanical | P5, P3 | connection.js:238 gates per-call prepare |
CEO A4's per-call resolvePrepare(url) |
| E7 | AR1 | Executor resolved per call via getter; tx rollback contract test | Mechanical | P1, P5 | Object.create(this) tx clone |
Instance field executor |
| E8 | AR2 | Preserve per-method RLS scoping; two brands; inventory golden | Taste (TE3) | P5 | Behavior-preserving goal; #1794 | Scope every migrated read now |
| E9 | AR3 | PGLite upgrade-replay test with master-built fixture | Mechanical | P1 | initSchema replays blob every boot | Fresh-install E4 only |
| E10 | AR4 | Layering test (no back-edges) via orphan-module walker | Mechanical | P5, P4 | Cycles and god-class regrowth | Review-only rule |
| E11 | AR5 | CLI records carry phase + thinClient mode; subcommand routing stays explicit code |
Mechanical | P5 | cli.ts:2103,2113,3012 |
Plan's 6-field record; predicate fields for subcommands |
| E12 | AR6 | AST route golden on master + runtime golden after move-only buildServeHttpApp extract |
Taste (TE1) | P5, P1 | No app handle on master | Test-only seam on master; AST only |
| E13 | AR7 | Snapshot inputs = import closure, asserted by test, feeds 11 CI keys | Mechanical | P1, P4 | Bootstrap not hashed today | Hand lists (A6/O7 wording) |
| E14 | AR8 | Command loaders must be literal import() (test) |
Mechanical | P1 | bun --compile bundling | Computed specifiers |
| E15 | AR9/SC18 | Path-consumer re-point in W0; snapshot test with W3 | Mechanical | P6 | Per-commit gates need live guards | Doing it in W7 |
| E16 | CQ2 | Widen executeRawJsonb to Pick<BrainEngine,'executeRaw'> |
Mechanical | P4 | One JSONB rule | Second JSONB helper |
| E17 | CQ3 | A2b via vetted builder registry + finite numerics; inlined literals stay | Mechanical | P1, P5 | sql-ranking.ts:405, facts.ts:489 |
Constant-allowlist-only rule; rewriting builders |
| E18 | CQ4 | Doctor entries return Check[] or STOP with explicit DoctorContext, emits[] |
Taste (TE4) | P5 | Shared schemaVersion, early returns |
One-check-per-entry registry |
| E19 | CQ6 | Adapter bypasses checkoutGauge; gauge golden | Mechanical | P5 | Tagged sites never counted | Route via executeRaw |
| E20 | CQ7 | One token normalizer; E3 wrapper + rename-map modes; Mechanical-Rename trailer |
Taste (TE5) | P4, P5 | W3 wrappers and SyncRun rewrites | Naive token multiset only |
| E21 | CQ8 | Executor returns {rows, affectedRows} |
Mechanical | P5 | .count vs .affectedRows |
Per-domain driver checks |
| E22 | SC15 | A11 handler hash on normalized tokens | Mechanical | P5 | Re-indent changes toString |
Raw source hash |
| E23 | SC19 | E5 runs through executeRaw on master, adapters after C10 |
Mechanical | P5 | Executor absent on master | Undefined E5 target |
| E24 | SC20 | build-schema.ts evaluates fragments; template output keeps placeholders |
Mechanical | P1 | Runtime policy in getPGLiteSchema |
sed-based generation |
| E25 | T-G13 | Ordinal positions in PGLite master-vs-branch catalog | Mechanical | P1 | Name-based diff misses reorder | Name-only |
| E26 | T-G16 | Per-method SQL-text golden for converted Postgres methods | Mechanical | P1 | Parity fixtures miss clause drift | Result-only parity |
| E27 | PF3 | Engine-connect cold-start budget ≤ +20 ms; fallback = generated bundle, not dynamic import | Mechanical | P1, P5 | 175 modules on connect path | --version budget only |
| E28 | PF7 | Per-domain gates on default 4-VM Ubicloud fleet | Mechanical | P3 | Shared 256 vCPU quota | --vms 10 |
| E29 | TODO | 13 TODO proposals dispositions as listed | Mechanical | P6 | Collected from all phases | Silent drops |
| E30 | SC22 | Preserve flag-registry auth --dry-run bug byte-identically |
Mechanical | P5 | Behavior-preserving PR; existing TODO owns fix | Fixing inside the refactor |
Taste decisions (for the final gate; all auto-chosen as recommended)
- TE1 Route golden: AST golden on master + runtime golden after a move-only
buildServeHttpAppextraction (recommended) vs adding a test-only seam on master first. Recommended because the extraction has a production caller and the AST golden proves the extract. - TE3 RLS: preserve master's per-method scoping (recommended) vs scope every migrated read now. Preserve keeps the PR behavior-preserving and avoids the #1794 pool-hold class; the improvement is E-TODO-1.
- TE4 Doctor registry:
Check[] | STOPentries with an explicit context (recommended) vs splitting doctor into fixed phases. - TE5 Move proof: normalizer with wrapper and rename-map modes plus a
Mechanical-Rename: yestrailer (recommended) vs tagging only pure moves and leaving mechanical rewrites unverified.
User Challenges: none new. UC1 (W1 breadth) remains the owner's decision; Eng input: the executor, E5, EO1, EO4, EO6 and EO8 must be green on W1-core before any W1-extended domain starts, whatever UC1 decides.
ACCEPTED OBLIGATIONS (Eng; add to the plan)
| ID | Requirement | Verification |
|---|---|---|
| EO1 | Engine-sql executor is obtained through a getter over this.sql / this.db on every call (never stored in a field); adapters are cheap wrappers. |
T-G1: write-then-throw inside engine.transaction() rolls back on PGLite and Postgres; a mutation that caches the executor at connect makes it fail (check-test-discriminates.sh). |
| EO2 | Postgres adapter calls runUnsafe(conn, sql, params, { signal?, prepare: true, simple: false }); runUnsafe forwards the two new opts to unsafe(); executeRaw/executeRawDirect unchanged. |
Unit with fake conn asserts the options; T-G4 on direct PG + PgBouncer. |
| EO3 | PGLite upgrade replay: W0 pins master's PGLite data dir (snapshot tar + version) as a golden fixture; branch initSchema on it succeeds, catalog equals master, second boot is a no-op; schema-bootstrap-coverage.test.ts logic unchanged against the generated blob. |
T-G2 in the unit lane; runs in every W2/E1 commit gate. |
| EO4 | W0 inventory golden of every Postgres engine read method's scoping mode (23 scoped sites vs unscoped). Engine-sql read functions accept ScopedRead or LegacyUnscopedRead matching master; brand casts banned by the engine-sql guard. |
T-G3 unit (fake sql lanes per method) + e2e with GBRAIN_RLS_SCOPE_BINDING=1; @ts-expect-error fixture for a plain executor. |
| EO5 | CLI records carry phase and thinClient (none, refuse, route-then-refuse); subcommand routing stays explicit pre-dispatch code; W0 static golden of phase/thinClient/subcommand rules on master. |
T-G6 golden equality + engine-free commands with unreachable DB match master exit code and first output line. |
| EO6 | Prepared-statement and protocol parity for converted queries. | T-G4 (pg_prepared_statements on direct PG, none on PgBouncer, no simple protocol for zero-arg). |
| EO7 | Snapshot hash inputs and all 11 CI cache keys cover the static import closure of the PGLite schema, migration registry, engine-sql bootstrap and migrate.ts. | T-G8 fails naming the missing file and both places; discrimination by removing one closure file. |
| EO8 | W0 captures the SQL text of every Postgres method converted in W1 (fake sql on master); converted method emits identical text modulo $N renumbering; inlined literals stay inlined. |
T-G16; parity suite unchanged per domain commit. |
| EO9 | Adapter bypasses checkoutGauge; gauge snapshot golden after a fixed op sequence equals master. |
T-G5. |
| EO10 | Layering: engine-sql/** imports no engine facade; schema-migrations/** imports no migrate.ts; helpers live in schema-migrations/helpers.ts; Migration type in schema-migrations/types.ts. |
T-G9 with bad/good fixtures; bun build --compile smoke (check-cli-executable.sh). |
| EO11 | Doctor registry: run(ctx) returning Check[] or STOP, explicit DoctorContext, emits[]; ordered-name golden from a master AST extraction; null-engine / connection-failure / --fast goldens. |
T-G10; W0 doctor --json goldens byte-identical. |
| EO12 | scripts/build-schema.ts evaluates TS fragment modules, emits pglite-schema.generated.ts as a template with __EMBEDDING_DIMS__/__EMBEDDING_MODEL__ and policy hooks intact; getPGLiteSchema(dims, model) signature unchanged; build:schema command name unchanged; unknown construct exits non-zero. |
E4 on dims 1536 and one non-default dims/model; fixture with an unknown construct fails; freshness guard fixtures. |
| EO13 | Every command table load is () => import('<string literal>'). |
T-G7; check-compile-autoload.sh, check-cli-executable.sh green. |
| EO14 | Perf budgets add PGLite engine connect + initSchema cold start (snapshot on and off) ≤ +20 ms; hot paths within noise on PGLite, direct PG, PgBouncer. | T-G15 bench numbers in the PR body, master vs candidate, same machine. |
| EO15 | Goal (b) and check-function-size.ts scope = src/**/*.ts excluding *.generated.ts. |
Guard fixture: a >300-line test callback is ignored; a >300-line src arrow fails. |
| EO16 | executeRawJsonb first param widened to Pick<BrainEngine,'executeRaw'>; engine-sql uses it for JSONB. |
Typecheck; rg -n "function executeRawJsonb" src = 1; test/sql-query.test.ts unchanged and green. |
| EO17 | A2b scanner semantics per CQ3 (constant allowlist, vetted builder registry with reasons, Number.isFinite numerics). |
T-G11 fixtures; FAIL/Why/Fix/See text (DX O9). |
| EO18 | Executor result contract { rows, affectedRows }; domain code never reads driver-specific count fields. |
T-G14 rows in E5 on both engines; grep guard: no .count/.affectedRows under engine-sql/<domain>.ts. |
| EO19 | Token normalizer in scripts/lib/normalize-tokens.ts shared by A11 hash and verify-move-only.ts; wrapper and rename-map modes; Mechanical-Rename: yes trailer for SyncRun-style rewrites. |
T-G12. |
| EO20 | E5 runs on master through engine.executeRaw, then the identical table against the adapters from C10 on. |
E5 receipts on master commit and C10. |
| EO21 | Guard re-points and path-consumer inventory land in W0; snapshot-closure test lands in the W3 commit. | Per-commit gate logs show the guards scanning new dirs from their first commit. |
| EO22 | schema-bootstrap-coverage.test.ts re-pointed to engine-sql/bootstrap.ts via a single-file positional loader; its "When you add a forward reference" steps updated; assertions unchanged. |
A10 before/after listing in the PR; test green on both blobs. |
Final aggregated implementation task list (commit sequence, ONE PR)
Effort assumptions (human ÷ CC): scaffolding ~100x, tests ~50x, features ~30x, refactor with regression proof ~20x, architecture ~5x. Sources: C = CEO task, D = DX task, E = Eng obligation. P1 blocks ship, P2 same branch, P3 follow-up.
- C0 (P1, human ~1d / CC ~1.5h) — baseline — Outcome baseline (plan e): classify 6 months of fix commits; perf baselines (f + EO14) on PGLite, direct PG, PgBouncer. Files: PR body,
scripts/bench. Verify: numbers recorded. - C1 (P1, human ~2d / CC ~2.5h) — W0 goldens — migrations full-record golden (A11, normalized handler tokens EO19), E4 catalog snapshot both engines (+ordinal T-G13), hybrid golden (A13), doctor ordered names (AST) +
--jsongoldens + early-stop goldens (EO11), serve-http AST route golden (AR6), CLI goldens incl. phase/thinClient/subcommand matrix (A16b, EO5), SQL-text goldens for W1-core Postgres methods (EO8), RLS scoping inventory (EO4), gauge golden (EO9), export-surface golden (O13), PGLite master data-dir fixture (EO3). Files:test/fixtures/goldens/*, new golden tests. Verify: all green on master. - C2 (P1, human ~1d / CC ~1h) — W0 contracts — E5 binding matrix via
executeRaw(EO20) incl. empty arrays, affectedRows, error pass-through (O14). Verify: green on PGLite, direct PG, PgBouncer. - C3 (P1, human ~1d / CC ~1h) — W0 loaders + re-points — generalize
doctor-source.tsper surface (A10, O17 markers); path-consumer inventory and scanner re-point with new-dir fixtures (O16, EO21); layering test (EO10). Verify:test-reads-source-smellcounts only drop; guard self-test. - C4 (P1, human ~1d / CC ~1h) — W5 —
check-function-size.ts(src-only EO15, name-path keys D19, all function forms A18), 77-row baseline, manifest row, fixtures, TESTING.md section; trim touched TSV notes. Verify:bun run check:guard-self-test; verify timing <15 s. - C5 (P1, human ~4h / CC ~30m) — W3 prep —
schema-migrations/types.ts,helpers.ts(SC1, SC2);normalize-tokens.ts+verify-move-only.tswrapper mode (E3, EO19). Verify: T-G12. - C6 (P1, human ~1d / CC ~1h, Move-Only) — W3 split — 170 files
v<NNN>-<name>.ts, generatorbuild:schema-migrations+registry.generated.ts(SC3), duplicate/filename diagnostics (O10),new:migrationscaffold (D8), migrate.ts runner only + re-exports; dropregion-exempt; snapshot-closure test + 11 CI keys (EO7, O7). Verify: A11 golden, apply-from-empty and apply-from-older both engines == E4, verify-move-only receipt. - C7 (P1, human ~1.5d / CC ~2h) — W2a —
scripts/build-schema.ts(EO12),pglite-schema.generated.tstemplate, capability rules, banners, freshness guard. Verify: E4 master==branch (PGLite, dims default + non-default), EO3 upgrade replay, schema-bootstrap-coverage unchanged. - C8 (P2, human ~1d / CC ~1.5h) — W2 T1 — generate schema.sql's 20 fragment-table regions. Verify: E4, freshness guard names source file.
- C9 (P1, human ~1d / CC ~1h) — W1 executor —
engine-sql/executor.ts,dialect-{pglite,postgres}.ts,normalize.ts, brands (EO4), per-call getters (EO1),runUnsafeopts (EO2), gauge bypass (EO9),{rows, affectedRows}(EO18),executeRawJsonbwidening (EO16), dynamic-SQL scanner (EO17), engine-sql ratchet + baseline TSV (D18). Verify: E5 on adapters, T-G1, T-G3, T-G4, T-G5, T-G14. - C10-C14 (P1, human ~1d each / CC ~1h each) — W1-core domains, one commit each:
salience,facts,takes,code-edges,cjk-search. Verify per commit: EO8 SQL-text golden, 28 parity files unchanged, source-isolation matrix,ci:ubicloudfull gate (4 VMs), perf check. - C15 (P1, human ~1d / CC ~1.5h) — E1 —
engine-sql/bootstrap.tssingle implementation, three callers incl.db.ts:initSchema; hash closure updated (EO7); coverage test re-pointed (EO22). Verify: legacy-shape boots both engines, EO3, full gate. - C16+ (P2, human ~1-2d each / CC ~1-2h each, only if UC1 includes) — W1-extended per domain after its inventory; baseline rows removed in the same commit (D35). Verify: same as C10.
- C17 (P1, human ~2d / CC ~2.5h) — W4 sync — move-only to
src/commands/sync/(Move-Only), SyncRun conversion (Mechanical-Rename: yes), behavior commit; destructuring guard; controlled-order tests (A17);performFullSync,runSyncInner->sync/args.ts. Verify: sync suites, A17 tests, full gate. - C18 (P1, human ~1.5d / CC ~2h) — W4 doctor — registry runner (EO11, D15, O5). Verify: W0 doctor goldens byte-identical, T-G10.
- C19 (P1, human ~1.5d / CC ~2h) — W4 serve-http — move-only
buildServeHttpAppextract; runtime golden == AST golden (AR6); modulesserve-http-admin-api.ts,-mcp.ts,-spa.ts, extend oauth/metrics (D10); split/mcphandler; extend admin-route guard (O8). Verify: route goldens, mutation test,test/e2e/serve-http-oauth.test.ts, authenticated outcome tests. - C20 (P1, human ~2d / CC ~2.5h) — W4 cli — command table with
phase/thinClient(EO5), literal loaders (EO13), derived sets,maindecomposition; re-targetgenerate-flag-registry.ts(O6). Verify: A16b + T-G6/T-G7 goldens, registry/TOOL_CATALOG/admin build zero diff, synthetic command test. - C21-C23 (P2, human ~1-1.5d each / CC ~1.5h each, cut line) — jobs (A15, 24 handlers, supervisor probe), hybrid stages (A13), autopilot dispatch (+E-TODO-2). Verify: respective goldens.
- C24 (P1, human ~4h / CC ~30m) — ceilings — lower every touched
module-size-limits.tsvceiling; goal (b) check over touched src files. Verify:check:module-size, function-size report zero >300 in touched src. - C25 (P1, human ~1d / CC ~1h) — W7 docs — CLAUDE.md invariants, CONTRIBUTING "Where does my change go?" (O1, O2), ENGINES, rls-and-you, infra-layer, key-files (split pages, D26), executor decision table (D14), ASCII diagram;
build:llms. Verify: stale-phrasergempty,test/build-llms.test.ts,check-key-files-current-state.sh. - C26 (P2, human ~4h / CC ~40m) — W6 porting kit — AST moved-symbol map markdown + JSON (E2, O11), recipes, agent prompt, announcement (D34), squash-body summary (O12). Verify: every JSON
oldresolves to anewsymbol on the candidate. - C27 (P2, human ~4h / CC ~1h) — DX dry-run (O18) and new-guard timings (O15). Verify: six timings ≤ 30 min; each guard <15 s.
- C28 (P1, human ~2h / CC ~20m) — release — rebase, re-run all W0 goldens and full
ci:ubicloudgate on the final candidate, PATCH bump via/ship(five-file version lockstep), CHANGELOG with generic placeholders (O20), TODOS entries 1-13 per dispositions. Verify: version gate,check-privacy.sh, full gate green.
Total estimate (whole amended wave, W1-core, cut-line items included): human team ~7-9 weeks; CC+gstack ~5-7 working days (W0 ~1d, W5 ~0.2d, W3 ~0.3d, W2 ~0.5d, W1-core+E1 ~1.5d, W4 in-line ~1.2d, cut line ~0.6d, W6/W7 + release ~0.7d), plus up to ~1.5d for W1-extended if UC1 includes it.
Unresolved decisions that may bite you later
None from this review. Every Eng issue was auto-decided (4 taste decisions above). UC1 (W1 breadth) is the owner's open User Challenge from the CEO phase and gates C16+.
Appendix: suppressed findings (confidence ≤ 4, not in the main report)
- (4/10) Express 5
app.router.stackis an internal structure; a minor Express upgrade could change its shape and break the runtime route golden. Mitigation if it happens: pin the introspection helper to the installed Express version in one test helper. - (4/10) PGLite may bind JS
bigintparams differently from postgres.js forint8[]; E5 already coversbigint > 2^53scalars but not bigint arrays. Add a row if any W1-extended domain bindsint8[]. - (3/10) Generated
registry.generated.tswith 170 static imports could slowtsc --incrementaltypecheck noticeably on Windows (verify's 120 s per-check cap). Measure during C6.
No durable learnings logged by this voice (read-only phase). Candidate learnings for the driver: "GBrain engine transaction()
clones the engine with Object.create(this) and a sql/db getter; any per-engine helper must resolve the connection per call"
(observed, confidence 9) and "postgres.js unsafe() per-call prepare is ANDed with the connection option
(vendor/postgres/src/connection.js:238); zero-arg unsafe() uses the simple protocol unless simple:false" (observed, 9).