Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix(schema-pack): MCP schema inspection resolves the caller source's pack (#7942)
garrytan60f6c90edebf
diff --git a/docs/architecture/key-files/schema-mutation.md b/docs/architecture/key-files/schema-mutation.mdindex 92f6d16d13..7a0cc19a0d 100644--- a/docs/architecture/key-files/schema-mutation.md+++ b/docs/architecture/key-files/schema-mutation.md@@ -16,7 +16,7 @@ Key files:- `src/core/schema-pack/mutate-audit.ts` — ISO-week JSONL at `~/.gbrain/audit/schema-mutations-YYYY-Www.jsonl`. Privacy-redacted: type names → sha8, prefixes → first slug segment only, matches `candidate-audit.ts` privacy posture. Logs BOTH success AND failure events so a future `schema_pack_writability` doctor check has signal. `summarizeMutations()` is the cross-surface parity primitive.- `src/core/schema-pack/registry.ts` — `resolvePack` walks the `extends` chain (depth cap via `EXTENDS_DEPTH_WARN` / `EXTENDS_DEPTH_HARD_CAP`), RETAINS each ancestor manifest, materializes `borrow_from`, and composes all of it into `resolved.manifest` through `mergeInheritedManifest`. Every downstream consumer reads `resolved.manifest`, so doing the merge here is what makes inheritance visible without per-consumer wiring. `borrow_from` is selective (only the named `types` / `link_types`, and only from the target's OWN declarations), non-transitive, and fail-closed — a missing target throws `UnknownPackError` via `loadByName`, matching the extends path; an omitted category borrows none of it. The alias graph + closure hash are computed on the MERGED manifest, so a cross-pack alias cycle surfaces as `AliasCycleError` at resolve. `manifest_sha8` / `packIdentity` stay the CHILD's own bytes — a parent edit does not move the child's identity, so the invalidation path is what keeps a child honest. `invalidatePackCache(name?)` walks the extends-chain reverse-graph (editing a parent pack must not leave children stale). `tryCachedPack(name)` TTL-gated fast path: inside `STAT_TTL_MS` (default 1000ms, env `GBRAIN_PACK_STAT_TTL_MS`) returns cached without statting; outside the window it stats every TRACKED file — the extends chain PLUS every borrowed pack — and cascade-invalidates on mtime change (cross-process detection), so editing a borrowed pack invalidates its borrowers. Pinned by `test/schema-pack-registry.test.ts` + `test/schema-pack-merge.test.ts`.- `src/core/schema-pack/merge.ts` — the pure child-wins composition helper behind `resolvePack`. `mergeInheritedManifest(ancestorsBaseFirst, child, borrowed)` returns the fully-composed manifest; precedence is child → borrowed → nearest parent … → base. SIX ingest/query-shaping fields inherit: `page_types`, `link_types`, `frontmatter_links`, `enrichable_types`, `filing_rules`, `takes_kinds`. `phases` + `calibration_domains` are DELIBERATELY child-only — they gate real cycle execution (`cycle.ts` `packDeclaresPhase`), so inheriting them would silently run phases a pack never declared; `mapping_rules`, `migration_from`, `extends`, `borrow_from`, and the identity fields are child-only too (all ride the `...child` spread). `mergePageTypes` carries the ordering contract `inferTypeFromPack` depends on (first-`path_prefix`-match-wins, array order): the BASE (root, `extends: null`) pack is the ordered foundation/tail; an override of a base type keeps the base POSITION (`Map.set` updates the value, keeps insertion order) so base's curated priority survives; a genuinely-new type from ANY non-base layer — child, borrowed, or a middle pack — is PREPENDED nearest-first, so a more-derived prefix wins regardless of chain depth. `mergeByKey` keeps the first occurrence per key walking highest-precedence-first (the order-insensitive keyed fields); `frontmatter_links` keys on `page_type\x00link_type` — a NUL, not a space, because both are unconstrained strings and a space-join would collide `{"a b","c"}` with `{"a","b c"}`. `mergeUnion` backs `takes_kinds`: UNION not replace, because the Zod default makes an omitted field indistinguishable from an explicit one — so a child can ADD kinds but CANNOT narrow below base ∪ parent. Pure + deterministic: no disk, no engine. Pinned by `test/schema-pack-merge.test.ts`.-- `src/core/schema-pack/engine-resolution.ts` — schema-only live-engine boundary shared by best-effort, write vocabulary, op trust, import/sync, and managed prepared import. `engineSchemaInput` reads selected-engine brain/source schema keys, using file-only config for the fallback while retaining per-call/environment precedence; it never merges model/provider settings. DB lookup failures propagate; only absent/empty keys permit fallback. Best-effort wrappers return null on failure instead of selecting host vocabulary. `approvedSchemaIdentity` hashes the full resolved manifest, including inherited link/inference definitions, independently of the alias-only hash. `checkApprovedSchemaForEngine` bypasses the registry TTL and rejects changed approved identities, untrusted callers, conflicting explicit/environment/per-source overrides, and unreadable DB state. It is read-only: `allowBinding` returns only `{key: 'schema_pack', value, expectedValue}` for the caller's selected-DB admission transaction. The caller must check destination compatibility/emptiness and apply the binding under its lifecycle lock/CAS; this helper neither authorizes that write nor writes host config. Tests: `test/schema-engine-isolation.serial.test.ts`.+- `src/core/schema-pack/engine-resolution.ts` — schema-only live-engine boundary shared by best-effort, write vocabulary, op trust, import/sync, managed prepared import, and the MCP inspection ops (`get_active_schema_pack`, `schema_explain_type`, `schema_graph`, `schema_lint` on the active pack; #7942, `test/schema-pack-source-inspection-7942.test.ts`). `engineSchemaInput` reads selected-engine brain/source schema keys, using file-only config for the fallback while retaining per-call/environment precedence; it never merges model/provider settings. DB lookup failures propagate; only absent/empty keys permit fallback. Best-effort wrappers return null on failure instead of selecting host vocabulary. `approvedSchemaIdentity` hashes the full resolved manifest, including inherited link/inference definitions, independently of the alias-only hash. `checkApprovedSchemaForEngine` bypasses the registry TTL and rejects changed approved identities, untrusted callers, conflicting explicit/environment/per-source overrides, and unreadable DB state. It is read-only: `allowBinding` returns only `{key: 'schema_pack', value, expectedValue}` for the caller's selected-DB admission transaction. The caller must check destination compatibility/emptiness and apply the binding under its lifecycle lock/CAS; this helper neither authorizes that write nor writes host config. Tests: `test/schema-engine-isolation.serial.test.ts`.- `src/core/schema-pack/query-types.ts` — expands scalar/multiple type filters through the selected engine's active alias graph. Scalar and array filters retain intersection semantics; explicit empty arrays deny before any engine/cache access. Missing packs yield an empty filter that consumers return as no results, never as an unrestricted query; DB lookup failures propagate through keyword, hybrid and image readers. Mixed-pack explicit source scopes refuse rather than arbitrarily choosing a closure. Used by hybrid search and the search/query keyword-only/image bypasses; typed hybrid requests bypass semantic result caching. Tests: `test/schema-engine-isolation.serial.test.ts`, `test/ops-search-types.test.ts`.diff --git a/src/core/ops/schema-packs.ts b/src/core/ops/schema-packs.tsindex 9b59b45410..f3b396d08e 100644--- a/src/core/ops/schema-packs.ts+++ b/src/core/ops/schema-packs.ts@@ -35,18 +35,12 @@ const get_active_schema_pack: Operation = {scope: 'read',handler: async (ctx) => {const { loadActivePack, resolveActivePackNameOnly } = await import('../schema-pack/load-active.ts');- const { loadConfig } = await import('../config.ts');- const cfg = loadConfig();- const sourceOpts: Record<string, unknown> = {};- if (ctx.sourceId) sourceOpts.sourceId = ctx.sourceId;- // #3792: thread the DB-plane schema_pack (tier 4) so this identity- // packet reports the SAME pack the engine actually queries with.- let dbConfig: string | undefined;- try {- dbConfig = (await ctx.engine.getConfig('schema_pack')) ?? undefined;- } catch { /* engine.config may not exist on very old brains */ }- const resolution = resolveActivePackNameOnly({ cfg, remote: ctx.remote ?? true, dbConfig, ...sourceOpts });- const pack = await loadActivePack({ cfg, remote: ctx.remote ?? true, dbConfig, ...sourceOpts });+ const { engineSchemaInput } = await import('../schema-pack/engine-resolution.ts');+ // #3792/#7942: the DB-plane tiers (brain-wide and the caller source's+ // override) so this packet reports the pack writes validate against.+ const input = await engineSchemaInput(ctx.engine, { remote: ctx.remote ?? true, sourceId: ctx.sourceId });+ const resolution = resolveActivePackNameOnly(input);+ const pack = await loadActivePack(input);const primitiveSummary: Record<string, number> = {};for (const t of pack.manifest.page_types) {primitiveSummary[t.primitive] = (primitiveSummary[t.primitive] ?? 0) + 1;@@ -122,11 +116,10 @@ const schema_lint: Operation = {scope: 'read',handler: async (ctx, p) => {const { runAllLintRules } = await import('../schema-pack/lint-rules.ts');- const { loadActivePack, resolveLoadedPack } = await import('../schema-pack/load-active.ts');- const { loadConfig, gbrainPath } = await import('../config.ts');+ const { resolveLoadedPack } = await import('../schema-pack/load-active.ts');+ const { gbrainPath } = await import('../config.ts');const { existsSync } = await import('node:fs');const { join } = await import('node:path');- const cfg = loadConfig();let manifest;if (p.pack) {// Locate by name without trust-gating per-call schema_pack opt@@ -153,11 +146,9 @@ const schema_lint: Operation = {// count as declared — parity with the active-pack branch below.manifest = (await resolveLoadedPack(loader(path))).manifest;} else {- // #4653: tier-4 DB-plane schema_pack, same read get_active_schema_pack does.- const { readDbSchemaPack } = await import('../schema-pack/best-effort.ts');- const dbConfig = await readDbSchemaPack(ctx.engine);- const resolved = await loadActivePack({ cfg, remote: ctx.remote ?? true, sourceId: ctx.sourceId, dbConfig });- manifest = resolved.manifest;+ // #4653/#7942: the DB-plane tiers, same resolution get_active_schema_pack does.+ const { loadActivePackForEngine } = await import('../schema-pack/engine-resolution.ts');+ manifest = (await loadActivePackForEngine(ctx.engine, { remote: ctx.remote ?? true, sourceId: ctx.sourceId })).manifest;}// File-plane only over MCP; the engine-aware --with-db opt-in is// CLI-only (Phase 5 wiring). MCP callers get the 9 file-plane rules.@@ -174,13 +165,9 @@ const schema_graph: Operation = {params: {},scope: 'read',handler: async (ctx) => {- const { loadActivePack } = await import('../schema-pack/load-active.ts');- const { loadConfig } = await import('../config.ts');- const { readDbSchemaPack } = await import('../schema-pack/best-effort.ts');- const cfg = loadConfig();- // #4653: tier-4 DB-plane schema_pack, same read get_active_schema_pack does.- const dbConfig = await readDbSchemaPack(ctx.engine);- const pack = await loadActivePack({ cfg, remote: ctx.remote ?? true, sourceId: ctx.sourceId, dbConfig });+ const { loadActivePackForEngine } = await import('../schema-pack/engine-resolution.ts');+ // #4653/#7942: the DB-plane tiers, same resolution get_active_schema_pack does.+ const pack = await loadActivePackForEngine(ctx.engine, { remote: ctx.remote ?? true, sourceId: ctx.sourceId });const nodes = pack.manifest.page_types.map((t) => ({ name: t.name, primitive: t.primitive }));const edges: Array<{ from: string; verb: string; to: string }> = [];for (const lt of pack.manifest.link_types) {@@ -210,13 +197,9 @@ const schema_explain_type: Operation = {},scope: 'read',handler: async (ctx, p) => {- const { loadActivePack } = await import('../schema-pack/load-active.ts');- const { loadConfig } = await import('../config.ts');- const { readDbSchemaPack } = await import('../schema-pack/best-effort.ts');- const cfg = loadConfig();- // #4653: tier-4 DB-plane schema_pack, same read get_active_schema_pack does.- const dbConfig = await readDbSchemaPack(ctx.engine);- const pack = await loadActivePack({ cfg, remote: ctx.remote ?? true, sourceId: ctx.sourceId, dbConfig });+ const { loadActivePackForEngine } = await import('../schema-pack/engine-resolution.ts');+ // #4653/#7942: the DB-plane tiers, same resolution get_active_schema_pack does.+ const pack = await loadActivePackForEngine(ctx.engine, { remote: ctx.remote ?? true, sourceId: ctx.sourceId });const found = pack.manifest.page_types.find((t) => t.name === p.type);if (!found) return { error: 'type_not_found', type: p.type as string, pack: pack.manifest.name };return { schema_version: 1, pack: pack.manifest.name, type: found };diff --git a/test/schema-pack-source-inspection-7942.test.ts b/test/schema-pack-source-inspection-7942.test.tsnew file mode 100644index 0000000000..c3d5791524--- /dev/null+++ b/test/schema-pack-source-inspection-7942.test.ts@@ -0,0 +1,63 @@+// #7942: MCP schema inspection resolves the caller's source pack, the same+// tiers capture and `gbrain schema active --source` use (per-source DB config).++import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';+import { PGLiteEngine } from '../src/core/pglite-engine.ts';+import { operationsByName } from '../src/core/operations.ts';+import type { OperationContext } from '../src/core/ops/contract.ts';+import { engineSchemaInput, loadActivePackForEngine } from '../src/core/schema-pack/engine-resolution.ts';+import { resolveActivePackNameOnly } from '../src/core/schema-pack/load-active.ts';+import { emptyHome, withEnv } from './helpers/with-env.ts';++let engine: PGLiteEngine;+let home: string;++beforeAll(async () => {+ engine = new PGLiteEngine();+ await engine.connect({});+ await engine.initSchema();+ await engine.executeRaw("INSERT INTO sources(id,name) VALUES('source-a','source-a') ON CONFLICT DO NOTHING");+}, 60_000);++afterAll(async () => { await engine.disconnect(); });++beforeEach(async () => {+ home = emptyHome();+ await engine.executeRaw("DELETE FROM config WHERE key LIKE 'schema_pack%'");+});++const isolated = <T>(fn: () => Promise<T>) => withEnv({ GBRAIN_HOME: home, GBRAIN_SCHEMA_PACK: undefined }, fn);+const remoteCtx = (sourceId: string) => ({ engine, config: { engine: 'pglite' }, remote: true, dryRun: false, sourceId,+ logger: { info() {}, warn() {}, error() {} } }) as unknown as OperationContext;+const call = (op: string, sourceId: string, p: Record<string, unknown> = {}) =>+ operationsByName[op]!.handler(remoteCtx(sourceId), p) as Promise<Record<string, unknown>>;++describe('#7942 schema inspection honors the per-source pack', () => {+ test('inspection ops report the pack write-time validation uses for the caller source', async () => {+ await engine.setConfig('schema_pack.source.source-a', 'company-brain');+ await isolated(async () => {+ const writePack = await loadActivePackForEngine(engine, { remote: true, sourceId: 'source-a' });+ const basePack = await loadActivePackForEngine(engine, { remote: true, sourceId: 'default' });+ expect(writePack.manifest.name).toBe('company-brain');+ expect(resolveActivePackNameOnly(await engineSchemaInput(engine, { remote: true, sourceId: 'source-a' })).source).toBe('per-source-db');+ const baseTypes = new Set(basePack.manifest.page_types.map(t => t.name));+ const sourceOnly = writePack.manifest.page_types.find(t => !baseTypes.has(t.name))!;+ expect(sourceOnly).toBeDefined();++ expect(await call('get_active_schema_pack', 'source-a')).toMatchObject({ pack_name: 'company-brain', source_tier: 'per-source-db',+ page_types_count: writePack.manifest.page_types.length });+ expect(await call('schema_explain_type', 'source-a', { type: sourceOnly.name })).toMatchObject({ pack: 'company-brain', type: { name: sourceOnly.name } });+ expect((await call('schema_graph', 'source-a')).pack).toBe('company-brain');+ expect((await call('schema_graph', 'source-a')).nodes).toEqual(writePack.manifest.page_types.map(t => ({ name: t.name, primitive: t.primitive })));+ });+ });++ test('another source keeps the brain-wide pack', async () => {+ await engine.setConfig('schema_pack.source.source-a', 'company-brain');+ await isolated(async () => {+ const active = await call('get_active_schema_pack', 'default');+ expect(active.pack_name).not.toBe('company-brain');+ expect(active.source_tier).not.toBe('per-source-db');+ });+ });+});