Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
12.8 KB
Raw Blame

Reviewed against 608a174dc. This was a static code review; I did not execute tests or read any SKILL.md files. The prior amendments help, but several implementation contracts and acceptance gates remain incomplete.

  1. High — W1-core already contains dialect-specific behavior; inventory cannot be limited to W1-extended.
    PGLite code-edge writes batch below 30,000 parameters because exceeding the driver limit can corrupt the session (code-edges.ts:9); Postgres constructs a single batch (code-edges.ts:29). Postgres fact insertion also probes vector versus halfvec and acquires transaction-scoped advisory locks (facts.ts:60). Selecting either engine’s implementation as canonical can therefore break the other backend.
    Fix: Inventory all five core domains before committing their scope. Define explicit capabilities for bind limits, embedding casts, and locks, with boundary-size and concurrent-write tests gating each conversion.

  2. High — The executor contract omits affected-row metadata.
    executeRaw returns only rows on PGLite (pglite-engine.ts:6006). Core-domain methods depend on metadata outside those rows: code-edge insertion uses affectedRows (code-edges.ts:51), while Postgres fact expiration uses result.count (facts.ts:128). A rows-only executor can successfully mutate data while reporting zero changes or false. The proposed binding matrix would miss this.
    Fix: Specify an internal result envelope containing rows and affected-row count. Test empty updates, successful updates, conflict-skipped inserts, and mixed batches. Preserve the public executeRaw contract separately.

  3. High — A4’s prepare-mode prescription does not preserve direct-Postgres behavior.
    resolvePrepare() normally returns undefined (db.ts:82), but vendored unsafe() defaults to prepare: false (index.js:119). Passing {prepare: undefined} also disables preparation because the driver checks property presence (connection.js:238). Thus “pass {prepare} from resolvePrepare(url)” does not preserve formerly tagged queries. Conversely, forcing preparation globally changes existing unsafe-query behavior.
    Fix: Track the original statement’s preparation policy and resolve the connection default explicitly. Test actual preparation behavior for default direct connections, explicit overrides, transaction handles, and PgBouncer—not merely successful query results.

  4. High — A3 proves scope binding, not isolation, and introduces an unacknowledged behavior change.
    Current fact reads delegate directly to their SQL dependencies (postgres-engine.ts:4444); they do not all use withScopedReadTransaction. Requiring that wrapper adds transactions and RLS filtering when binding is enabled. Moreover, checking current_setting('app.scopes') while connected as a superuser proves no rows were denied. The repository already has a stronger non-bypass-role testing pattern (shared-skills-rls.test.ts:14).
    Fix: Inventory existing scope boundaries and explicitly decide whether expanding them belongs in this behavior-preserving PR. Test with a non-owner, non-superuser, NOBYPASSRLS role; assert cross-source denial, concurrent-request isolation, nested rollback restoration, and connection reuse.

  5. High — Schema acceptance must cover replay paths and security objects, not just fresh end-state parity.
    The cited schema-drift machinery snapshots columns and indexes (schema-diff.ts:18); E4 does not specify whether it additionally captures functions, triggers, constraints, policies, grants, and RLS flags. Those are material schema behavior. There is also a third entry point: db.initSchema() bootstraps and replays the schema without running the migration chain (db.ts:358). Engine initialization subsequently runs migrations that could mask a generator error (pglite-engine.ts:1066).
    Fix: Define E4’s object coverage explicitly. Compare before and after migration replay, exercise all three initialization paths, and include populated historical databases, repeat initialization, embedding configurations, and nondefault FTS language. Make this gate precede W2 and E1.

  6. High — The CLI record does not model connection and teardown ownership.
    Dispatch includes subcommand-sensitive thin-client routing followed by deferred persistence (cli.ts:2103), guards that must run before connecting, and degraded-server recovery (cli.ts:3043). Teardown drains background work and deliberately excludes serve (cli.ts:3595). {load, selfHelp, thinClientRefused, skipStartupHooks} cannot express these decisions by itself. Set equality and help goldens can pass while commands start connecting unnecessarily or disconnect twice.
    Fix: Preserve an explicit ordered dispatch pipeline, with subcommand-aware routing and lifecycle ownership. Add tests recording connect, remote-route, drain, and disconnect calls for representative paths, including failures and help.

  7. High — HTTP route/middleware goldens leave the most sensitive extraction boundary untested.
    The MCP handler supplies remote: true, transport identity, source scope, surface restrictions, and authInfo to dispatch (serve-http.ts:2304); its comments document a previous refactor dropping auth context. Admin login, middleware, and global sign-out share one session map (serve-http.ts:1435). Confidential OAuth handling intentionally falls through to the SDK for public-client PKCE flows (serve-http-oauth.ts:82). All can regress while route names and middleware remain identical.
    Fix: Specify ownership of shared auth state and request context before extraction. Gate the move with owner-versus-OAuth admin denial, session revocation, PKCE and refresh flows, wrong-audience rejection, and source/operation authorization tests. Include HTTP shutdown and IPC cleanup.

  8. High — Sync’s proposed interleaving tests omit checkpoint durability and finalization races.
    Checkpoint flushing coordinates pending paths, an in-flight flush flag, failed-batch restoration, and failure counters (sync.ts:2446). Finalization flushes checkpoints, deregisters signal cleanup, advances the pinned bookmark, and clears checkpoint rows (sync.ts:3577, sync.ts:3642). Testing only phase completion versus watchdog/timeout does not protect these transitions.
    Fix: Define terminal phase outcomes and a single owner for checkpoint and cleanup state. Add controlled failures/interleavings for checkpoint writes, worker completion, SIGTERM cleanup, bookmark advancement, and full-sync fallback. Assert durable state after restarting, not just returned status.

  9. High — A10 can preserve every assertion while weakening the property being tested.
    The specifically named nested-transaction regression test searches only the text preceding the import loop for engine.transaction (sync.test.ts:823). After extraction, the caller could wrap imports(tx) in a transaction while the imports module still passes that unchanged assertion. Repointing the positional test to its new single file creates this blind spot.
    Fix: Classify tests by the invariant they protect, not only containment versus position. Add a cross-file mutation fixture that wraps the phase call in a transaction and must fail, plus a bounded PGLite execution test. “Zero loosened assertions” is insufficient evidence of preserved coverage.

  10. High — ci:ubicloud does not automatically run each parity test against PgBouncer.
    The worker sets DATABASE_URL to direct Postgres and exposes a separate GBRAIN_PGBOUNCER_URL (ci-item.sh:47). Ordinary E2E helpers use only DATABASE_URL (helpers.ts:36). The explicit non-skipping PgBouncer check targets the teardown suite (run-e2e.sh:379). A green full gate therefore does not establish the promised three-backend executor/domain matrix.
    Fix: Add explicit backend parameterization or dedicated matrix jobs for E5 and migrated-domain tests. Assert executed test counts per backend. Configure pooler preparation explicitly: Ubicloud’s pooler ports are not the 6543 auto-detection port.

  11. Medium — Snapshot-cache equality is specified incorrectly.
    There are 13 matching cache-key occurrences: five in e2e.yml, eight in test.yml. Two are intentionally separate default-profile caches; the others use the legacy profile (test.yml:349). The builder gives these profiles different embedding shapes and artifact names (build-pglite-snapshot.ts:21). Making all keys identical risks restoring the wrong artifact family.
    Fix: Discover occurrences dynamically. Require identical dependency-hash inputs while preserving distinct profile namespaces and artifact paths. Land that check with W3’s hash changes, rather than waiting for W7.

  12. Medium — Migration extraction needs a shared-helper dependency design, and the golden misses executable verification logic.
    Handlers close over module-private helpers such as dropInvalidConcurrentIndex (migrate.ts:170) and the mutable notice-suppression state (migrate.ts:39). Moving records independently needs a deliberate home for those dependencies. Also, checking only verify presence would accept a changed v164 verifier (migrate.ts:6647).
    Fix: Establish shared migration support modules before splitting records, without duplicating state or introducing registry-to-runner cycles. Hash verifier bodies and referenced executable helpers. Test fresh-install notice suppression, upgrade notices, and verification failure/retry behavior.

  13. Medium — Doctor’s {name, run} registry needs execution semantics beyond category and order.
    --fix deliberately runs before the corresponding checks (doctor.ts:741); fast mode and unavailable engines return before database checks (doctor.ts:1819). Other checks conditionally emit nothing. Grouping by category can accidentally change these dependencies or perform expensive probes in fast mode. Three JSON fixtures are unlikely to expose that.
    Fix: Preserve ordered execution groups with explicit eligibility, prerequisites, and zero-or-many results. Add mode-matrix tests asserting both output and which probes or mutations were invoked.

  14. Medium — The 300-line acceptance rule expands scope into repointed tests.
    It applies to “any file touched,” while the initial baseline counts production functions. The required edit to test/sync.test.ts touches a file whose describe callback spans lines 408–821 (sync.test.ts:408). Since W5 counts arrow functions, a source-loader correction can force unrelated test-suite decomposition.
    Fix: Specify the scanned roots and exemptions before W0. Restrict this acceptance criterion to an explicit production-file inventory, or baseline test callbacks separately. Produce the complete required-decomposition list before approving the landing scope.

  15. Medium — The performance baseline needs to distinguish cache warming from disabled result reuse.
    Semantic result caching is hard-disabled (query-cache.ts:35), and hybridSearchCached bypasses its setup accordingly (hybrid.ts:2490). A “warm cache” benchmark can misleadingly measure only warmed database or embedding state. Enabling result reuse to exercise that benchmark would exceed scope.
    Fix: Name each cache being warmed, assert result-cache reads/writes remain disabled, and record provider/SQL counts alongside latency. Define numeric budgets and concurrency/corpus sizes before implementation, including the core-domain batch boundaries.

Recommendation: Revise and re-review before implementation because the executor contract omits observable driver behavior, and the current gates can pass despite authorization, lifecycle, and backend-coverage regressions.