Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
feat(engine-open): a writer value never widens; storage and AI stay out of settings; cache and upgrade tests
garrytan0bc2cd9b92e3
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 7a33c194ab..492b7f7bcc 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -17,10 +17,11 @@ identifiers and attribution are available in the pre-removal Git revision### Itemized changes- `src/core/engine-open.ts` (new, exported as `./engine-open`): `openEngine`, refusing `embedded_core_required`, `engine_host_missing` and `engine_settings_invalid`. A connect never migrates; the host runs `initSchema()`. Documented in docs/ENGINES.md, "Opening an engine from settings".-- `src/core/persistence/identity.ts`: `hostIdFor(engine)` and `setEngineHostId`, resolved through `engineKey`. Publication, admission, the consumer, worktree ownership, effects and the writer stamp use it; an unmarked engine still gets `localHostId()`. An embedded engine never reads or mints `host.json`, and its consumer heartbeat records `embedded:<host-id>`, which doctor and writer status read as an identity given at open. `registerLocalWriterValue` registers a writer the host holds as a value, and an embedded engine's writes use it instead of a `<brain>.<lane>.json` file.+- `src/core/persistence/identity.ts`: `hostIdFor(engine)` and `setEngineHostId`, resolved through `engineKey`. Every host-id read in `src/core` goes through it or `existingHostIdFor(engine)` (publication, admission, the consumer, worktree ownership and refresh, topology, effects, repair and the writer stamp), except `gbrain migrate`'s engine graduation; an unmarked engine still gets `localHostId()`, so the CLI's behavior is unchanged. An embedded engine never reads or mints `host.json`, and its consumer heartbeat records `embedded:<host-id>`, which doctor and writer status read as an identity given at open. `registerLocalWriterValue` registers a writer the host holds as a value, and an embedded engine's writes use it instead of a `<brain>.<lane>.json` file. It never widens past the settings: the lane is the one given, a new registration gets the default read/write ceiling, and an existing registration keeps its own.- `initSchema()` on an embedded engine seeds the embedding model and width from `settings.embedding` and refuses `engine_embedding_mismatch` on a database that records another one.- The decide spend cache is keyed by engine and held weakly, and a drained feedback queue no longer keeps its engine alive.-- `test/engine-open.test.ts`, `test/engine-open-lifecycle.test.ts`, `test/e2e/engine-open-postgres.test.ts`.+- File storage and AI provider settings are not engine settings yet; they stay process-wide until Wave C.+- `test/engine-open.test.ts`, `test/engine-open-lifecycle.test.ts`, `test/engine-open-upgrade.test.ts` (a brain built by an earlier release boots identically through the CLI path and `openEngine`), `test/e2e/engine-open-postgres.test.ts`.## [0.60.556.0] - 2026-11-02diff --git a/docs/ENGINES.md b/docs/ENGINES.mdindex 137938833f..f9eac930da 100644--- a/docs/ENGINES.md+++ b/docs/ENGINES.md@@ -754,24 +754,30 @@ working directory:The statement-description cache stays in the process instead of `<home>/cache/pg-types`. PGLite skips the`GBRAIN_PGLITE_SNAPSHOT` fast path.- **Host identity.** `hostIdFor(engine)` (`src/core/persistence/identity.ts`) answers `host.id` for the engine,- its page transactions and its read-through views; the consumer, publication, admission stamps and worktree- ownership use it. No `host.json` is read or minted, and an embedded engine without an id refuses- `engine_host_missing`. Its consumer heartbeat row records `embedded:<host-id>` in `host_json_path` and+ its page transactions, its read-through views and every forwarding proxy over it. Every host-id read in+ `src/core` goes through it (or `existingHostIdFor`), except `gbrain migrate`'s engine graduation and the+ coordination-lock fallback for a caller that passes no host id; the CLI layer keeps the file identity. No+ `host.json` is read or minted, and an embedded engine without an id refuses `engine_host_missing`. Its consumer heartbeat row records `embedded:<host-id>` in `host_json_path` and`embedded` in `persistence_home`; doctor and writer status read that as "identity given at open", never as a path.For every other engine `hostIdFor` is `localHostId()`.- **Writer.** An unauthenticated write uses `settings.writer` for its lane, registered in`persistence_local_writers` on first use (`registerLocalWriterValue`: idempotent; another credential or lane under- the same id refuses `permission_denied`; a revoked registration is never replaced). No `<brain>.<lane>.json`- credential file is read or minted; without a writer for the lane the write refuses `writer_registration_required`.+ the same id refuses `permission_denied`; a revoked registration is never replaced). A writer value never widens+ what the engine may write: its lane is the one in the settings (a remote call needs a `stdio` writer, a local one a+ `cli` writer), a new registration gets the default ceiling (read and write), and an existing registration keeps+ its own ceiling. No `<brain>.<lane>.json` credential file is read or minted; without a writer for the lane the write refuses `writer_registration_required`.- **Embedding identity.** `initSchema()` seeds a fresh brain from `settings.embedding` (else the built-in default),never from the process gateway, and refuses `engine_embedding_mismatch` on a database that records another modelor width; `gbrain migrate embeddings --status` previews a migration.-- **Carried for later waves.** `storage`, `storagePrefix` and `ai` are held as given and read back with- `embeddedSettings(engine)` (the writer credential is left out). `disconnect()` drops them.--Still process-wide: the AI gateway, `GBRAIN_*` tuning variables (pool lifetime, session timeouts), the-connection-events audit log, and operation-level config reads (content-sanity screening, schema-pack resolution,-the embedding switch on publication). A source with a git checkout keeps its native coordination lock under the+- **Read back.** `embeddedSettings(engine)` returns the settings without the writer credential; `disconnect()` drops+ them. File storage (backend and object prefix) and AI provider settings are not settings yet (Wave C): file+ operations use the process's storage config and embedding calls use the process AI gateway.++Still process-wide: the AI gateway (the model embedding calls use), `GBRAIN_*` tuning variables (pool lifetime,+connect and session timeouts, `GBRAIN_PREPARE`, `GBRAIN_DIRECT_POOL_SIZE`, `GBRAIN_DISABLE_DIRECT_POOL`,+`GBRAIN_RLS_SCOPE_BINDING`, the PGLite close watchdog), the connection-events audit log, and operation-level+config reads (content-sanity screening, schema-pack resolution, the embedding switch on publication). None of them+picks an engine's database, host identity, writer or embedding identity. A source with a git checkout keeps its native coordination lock under theprocess's persistence home.## Canonical schema sourcesdiff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.mdindex d316d195cf..dbc762a6d1 100644--- a/docs/guides/error-codes.md+++ b/docs/guides/error-codes.md@@ -1489,7 +1489,7 @@ More: [docs/ENGINES.md#opening-an-engine-from-settings-experimental](../../docs/| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable ||---|---|---|---|---|---|---|-| A setting passed to openEngine or registerLocalWriterValue is missing or malformed (engine kind, database url or path, pool size, host or writer id, writer credential or lane, embedding identity), so nothing was opened or registered. | The request itself was wrong or no longer matches the brain; nothing was changed. | Correct the setting the message names and call again. | agent | `repeat the read that failed` | 1 | no |+| A setting passed to openEngine is missing or malformed (engine kind, database url or path, pool size, host or writer id, writer credential or lane, embedding identity), so nothing was opened or registered. | The request itself was wrong or no longer matches the brain; nothing was changed. | Correct the setting the message names and call again. | agent | `repeat the read that failed` | 1 | no |More: [docs/ENGINES.md#opening-an-engine-from-settings-experimental](../../docs/ENGINES.md#opening-an-engine-from-settings-experimental)diff --git a/llms-full.txt b/llms-full.txtindex 058a01bb35..6603a7ff51 100644--- a/llms-full.txt+++ b/llms-full.txt@@ -6170,24 +6170,30 @@ working directory:The statement-description cache stays in the process instead of `<home>/cache/pg-types`. PGLite skips the`GBRAIN_PGLITE_SNAPSHOT` fast path.- **Host identity.** `hostIdFor(engine)` (`src/core/persistence/identity.ts`) answers `host.id` for the engine,- its page transactions and its read-through views; the consumer, publication, admission stamps and worktree- ownership use it. No `host.json` is read or minted, and an embedded engine without an id refuses- `engine_host_missing`. Its consumer heartbeat row records `embedded:<host-id>` in `host_json_path` and+ its page transactions, its read-through views and every forwarding proxy over it. Every host-id read in+ `src/core` goes through it (or `existingHostIdFor`), except `gbrain migrate`'s engine graduation and the+ coordination-lock fallback for a caller that passes no host id; the CLI layer keeps the file identity. No+ `host.json` is read or minted, and an embedded engine without an id refuses `engine_host_missing`. Its consumer heartbeat row records `embedded:<host-id>` in `host_json_path` and`embedded` in `persistence_home`; doctor and writer status read that as "identity given at open", never as a path.For every other engine `hostIdFor` is `localHostId()`.- **Writer.** An unauthenticated write uses `settings.writer` for its lane, registered in`persistence_local_writers` on first use (`registerLocalWriterValue`: idempotent; another credential or lane under- the same id refuses `permission_denied`; a revoked registration is never replaced). No `<brain>.<lane>.json`- credential file is read or minted; without a writer for the lane the write refuses `writer_registration_required`.+ the same id refuses `permission_denied`; a revoked registration is never replaced). A writer value never widens+ what the engine may write: its lane is the one in the settings (a remote call needs a `stdio` writer, a local one a+ `cli` writer), a new registration gets the default ceiling (read and write), and an existing registration keeps+ its own ceiling. No `<brain>.<lane>.json` credential file is read or minted; without a writer for the lane the write refuses `writer_registration_required`.- **Embedding identity.** `initSchema()` seeds a fresh brain from `settings.embedding` (else the built-in default),never from the process gateway, and refuses `engine_embedding_mismatch` on a database that records another modelor width; `gbrain migrate embeddings --status` previews a migration.-- **Carried for later waves.** `storage`, `storagePrefix` and `ai` are held as given and read back with- `embeddedSettings(engine)` (the writer credential is left out). `disconnect()` drops them.--Still process-wide: the AI gateway, `GBRAIN_*` tuning variables (pool lifetime, session timeouts), the-connection-events audit log, and operation-level config reads (content-sanity screening, schema-pack resolution,-the embedding switch on publication). A source with a git checkout keeps its native coordination lock under the+- **Read back.** `embeddedSettings(engine)` returns the settings without the writer credential; `disconnect()` drops+ them. File storage (backend and object prefix) and AI provider settings are not settings yet (Wave C): file+ operations use the process's storage config and embedding calls use the process AI gateway.++Still process-wide: the AI gateway (the model embedding calls use), `GBRAIN_*` tuning variables (pool lifetime,+connect and session timeouts, `GBRAIN_PREPARE`, `GBRAIN_DIRECT_POOL_SIZE`, `GBRAIN_DISABLE_DIRECT_POOL`,+`GBRAIN_RLS_SCOPE_BINDING`, the PGLite close watchdog), the connection-events audit log, and operation-level+config reads (content-sanity screening, schema-pack resolution, the embedding switch on publication). None of them+picks an engine's database, host identity, writer or embedding identity. A source with a git checkout keeps its native coordination lock under theprocess's persistence home.## Canonical schema sourcesdiff --git a/src/core/embedded-engine.ts b/src/core/embedded-engine.tsindex 9a565f06a2..66adbf3855 100644--- a/src/core/embedded-engine.ts+++ b/src/core/embedded-engine.ts@@ -1,5 +1,4 @@import { engineKey } from './engine-key.ts';-import type { StorageConfig } from './storage.ts';import { DEFAULT_EMBEDDING_DIMENSIONS, DEFAULT_EMBEDDING_MODEL } from './ai/defaults.ts';import { opError } from './ops/contract.ts';@@ -22,14 +21,9 @@ export interface EngineSettings {writer?: { id: string; credential: string; lane: 'cli' | 'stdio' };/** The embedding identity `initSchema()` seeds a fresh brain with and checks an existing one against. */embedding?: { model: string; dimensions: number };- /** The file storage backend and the host's object prefix, carried for the file operations. */- storage?: StorageConfig;- storagePrefix?: string;/** `search.keyword_statement_timeout_ms` for this engine (Postgres). */keyword_statement_timeout_ms?: number;pglite?: { shared_buffers?: string };- /** AI provider settings for this engine; opaque here and recorded as given. */- ai?: Record<string, unknown>;}/** The settings `embeddedSettings` returns: everything the host passed except the writer credential. */@@ -84,7 +78,7 @@ export function embeddedSettings(engine: object): EmbeddedSettingsView | undefinreturn Object.freeze({ ...rest, ...(writer ? { writer: { id: writer.id, lane: writer.lane } } : {}) });}-/** Drops the settings (credentials, AI keys, storage) an embedded engine held; it stays marked embedded with its host id. */+/** Drops the settings (the writer credential included) an embedded engine held; it stays marked embedded with its host id. */export function releaseEmbeddedEngine(engine: object): void {const record = recordOf(engine);if (record) record.settings = null;diff --git a/src/core/engine-open.ts b/src/core/engine-open.tsindex 32fa99002e..1751803750 100644--- a/src/core/engine-open.ts+++ b/src/core/engine-open.ts@@ -11,7 +11,7 @@ import { assertLocalWriterValue, setEngineHostId } from './persistence/identity.export type { EngineSettings, EmbeddedSettingsView } from './embedded-engine.ts';export { embeddedSettings, isEmbeddedEngine, processHasEmbeddedEngines } from './embedded-engine.ts';-export { hostIdFor, registerLocalWriterValue } from './persistence/identity.ts';+export { hostIdFor } from './persistence/identity.ts';/** Connections a Postgres engine opened from settings may open when `pool.max` is not given. */export const DEFAULT_EMBEDDED_POOL_MAX = 4;@@ -69,7 +69,6 @@ export async function openEngine(settings: EngineSettings): Promise<BrainEngine>...(settings.pool ? { pool: { ...settings.pool } } : {}),...(settings.writer ? { writer: { ...settings.writer } } : {}),...(settings.embedding ? { embedding: { ...settings.embedding } } : {}),- ...(settings.storage ? { storage: { ...settings.storage } } : {}),...(settings.pglite ? { pglite: { ...settings.pglite } } : {}),};const config: EngineConfig = {diff --git a/src/core/error-registry.ts b/src/core/error-registry.tsindex a018c454bd..83ce18621a 100644--- a/src/core/error-registry.ts+++ b/src/core/error-registry.ts@@ -303,7 +303,7 @@ export const CODES = {embedded_core_required: { class: 'caller', summary: "openEngine (gbrain/engine-open) was called without embedded_core: true, so no engine was opened.", why: 'Opening an engine from settings alone is an experimental embedding surface that is off by default; a host opts in explicitly so no existing caller changes behavior.', docs: 'docs/ENGINES.md#opening-an-engine-from-settings-experimental', suggestion: 'Pass embedded_core: true in the settings; the CLI, gbrain serve and mounts open brains through their own connect path and need nothing.' },engine_embedding_mismatch: { class: 'host_only', actor: 'user', summary: "An engine opened from settings names an embedding model or width that differs from the one its database already records, so initSchema changed nothing.", why: 'The vector column has one width and the brain one embedding model; seeding another over it would make every stored and future embedding unreadable. Changing it is an explicit re-embed the user decides on.', docs: 'docs/ENGINES.md#opening-an-engine-from-settings-experimental', suggestion: "Pass the database's recorded model and width in settings.embedding, or read the recorded identity with gbrain migrate embeddings --status on the brain host and preview a migration from there.", fix: { argv: ['gbrain', 'migrate', 'embeddings', '--status', '--json'], consent: [], actor: 'agent', requires_exclusive: false, why: "Read-only: reports the brain's recorded embedding model and width and what a migration would change." } },engine_host_missing: { class: 'caller', summary: "An engine opened from settings has no host identity, so nothing that needs one ran and no host.json was created.", why: 'An embedded engine publishes and claims work under the host id its host gave at open; minting a host.json under the home directory instead would tie its writes to whatever process happens to share that directory.', docs: 'docs/ENGINES.md#opening-an-engine-from-settings-experimental', suggestion: 'Pass host: { id: <uuid> } to openEngine; keep the same id for the same host across restarts.' },- engine_settings_invalid: { class: 'caller', summary: "A setting passed to openEngine or registerLocalWriterValue is missing or malformed (engine kind, database url or path, pool size, host or writer id, writer credential or lane, embedding identity), so nothing was opened or registered.", docs: 'docs/ENGINES.md#opening-an-engine-from-settings-experimental', suggestion: 'Correct the setting the message names and call again.' },+ engine_settings_invalid: { class: 'caller', summary: "A setting passed to openEngine is missing or malformed (engine kind, database url or path, pool size, host or writer id, writer credential or lane, embedding identity), so nothing was opened or registered.", docs: 'docs/ENGINES.md#opening-an-engine-from-settings-experimental', suggestion: 'Correct the setting the message names and call again.' },engine_graduated: { class: 'caller', summary: "A client opened a PGLite brain that moved to Postgres; its old path holds a tombstone.", docs: 'docs/guides/move-to-postgres.md#graduated-datastore' },// wave 18b (GBRA-106) #4772: onboarding coverage checks read entity types from the active pack(s).entity_types_unavailable: { class: 'unavailable', summary: "A schema pack in scope did not load, so the entity page types are unknown; onboarding's entity_link_coverage and timeline_coverage warn instead of grading the old hardcoded type list.",diff --git a/test/engine-open-upgrade.test.ts b/test/engine-open-upgrade.test.tsnew file mode 100644index 0000000000..5898423f71--- /dev/null+++ b/test/engine-open-upgrade.test.ts@@ -0,0 +1,91 @@+/**+ * GBRA-283 Wave B1 back-compat: a brain built by an earlier release (the pinned PGLite upgrade fixture, see+ * test/pglite-upgrade-replay.test.ts) boots the same way through the CLI's connect path and through openEngine, and+ * openEngine changes nothing an existing brain records: data, schema version, catalog and embedding identity.+ */+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join, relative } from 'node:path';+import { randomUUID } from 'node:crypto';+import { PGLiteEngine } from '../src/core/pglite-engine.ts';+import { openEngine } from '../src/core/engine-open.ts';+import { readStoredEmbeddingIdentity } from '../src/core/stored-embedding-identity.ts';+import { pgliteCatalogQuery } from './helpers/schema-catalog.ts';+import { diffCatalogSnapshots, snapshotCatalog } from './helpers/schema-diff.ts';+import { UPGRADE_FIXTURE_BRAIN_DIR, UPGRADE_FIXTURE_MANIFEST, UPGRADE_FIXTURE_TARBALL, fixtureDataStats, type UpgradeFixtureManifest } from './helpers/pglite-upgrade-fixture.ts';+import { withEnv } from './helpers/with-env.ts';++const scratch = mkdtempSync(join(tmpdir(), 'gbrain-engine-open-upgrade-'));+afterAll(() => { rmSync(scratch, { recursive: true, force: true }); });+const manifest = JSON.parse(readFileSync(UPGRADE_FIXTURE_MANIFEST, 'utf8')) as UpgradeFixtureManifest;++function extract(name: string): string {+ const dir = join(scratch, name);+ mkdirSync(dir, { recursive: true });+ const tar = Bun.spawnSync(['tar', '-xzf', UPGRADE_FIXTURE_TARBALL, '-C', dir], { stderr: 'pipe' });+ if (tar.exitCode !== 0) throw new Error(`extracting ${UPGRADE_FIXTURE_TARBALL} failed: ${tar.stderr.toString()}`);+ return join(dir, UPGRADE_FIXTURE_BRAIN_DIR);+}+function filesUnder(root: string): string[] {+ if (!existsSync(root)) return [];+ return readdirSync(root, { recursive: true, withFileTypes: true }).filter(entry => !entry.isDirectory())+ .map(entry => relative(root, join(entry.parentPath, entry.name))).sort();+}+async function boot(engine: PGLiteEngine) {+ await engine.initSchema();+ return {+ version: Number(await engine.getConfig('version')),+ catalog: await snapshotCatalog(pgliteCatalogQuery(engine)),+ data: await fixtureDataStats(engine),+ embedding: await readStoredEmbeddingIdentity(engine),+ };+}++describe('a brain built by an earlier release', () => {+ let cli: Awaited<ReturnType<typeof boot>>;++ beforeAll(async () => {+ const engine = new PGLiteEngine();+ await engine.connect({ database_path: extract('cli') });+ try { cli = await boot(engine); } finally { await engine.disconnect(); }+ }, 240_000);++ test('boots through openEngine exactly as through the CLI connect path, and records nothing under HOME or GBRAIN_HOME', async () => {+ const home = join(scratch, 'canary-home'), gbrainHome = join(scratch, 'canary-gbrain-home');+ mkdirSync(home, { recursive: true }); mkdirSync(gbrainHome, { recursive: true });+ await withEnv({ HOME: home, GBRAIN_HOME: gbrainHome }, async () => {+ const engine = await openEngine({ embedded_core: true, engine: 'pglite', database: { path: extract('embedded') }, host: { id: randomUUID() } }) as PGLiteEngine;+ try {+ const embedded = await boot(engine);+ expect(embedded.version).toBe(cli.version);+ expect(diffCatalogSnapshots(cli.catalog, embedded.catalog)).toEqual([]);+ expect(embedded.data).toEqual(manifest.data);+ expect(cli.data).toEqual(manifest.data);+ expect(embedded.embedding).toEqual({ model: manifest.embedding_model, dimensions: manifest.embedding_dimensions });+ expect(cli.embedding).toEqual(embedded.embedding);+ } finally {+ await engine.disconnect();+ }+ });+ expect(filesUnder(home)).toEqual([]);+ expect(filesUnder(gbrainHome)).toEqual([]);+ }, 240_000);++ test('openEngine with the recorded embedding identity opens it; another identity refuses and changes nothing', async () => {+ const path = extract('identity');+ const same = await openEngine({ embedded_core: true, engine: 'pglite', database: { path }, host: { id: randomUUID() },+ embedding: { model: manifest.embedding_model, dimensions: manifest.embedding_dimensions } }) as PGLiteEngine;+ try { expect((await boot(same)).data).toEqual(manifest.data); } finally { await same.disconnect(); }+ const other = await openEngine({ embedded_core: true, engine: 'pglite', database: { path }, host: { id: randomUUID() },+ embedding: { model: 'voyage:voyage-4-lite', dimensions: 512 } }) as PGLiteEngine;+ try {+ const refusal = await other.initSchema().then(() => null, (error: unknown) => (error as { code?: string }).code);+ expect(refusal).toBe('engine_embedding_mismatch');+ expect(await readStoredEmbeddingIdentity(other)).toEqual({ model: manifest.embedding_model, dimensions: manifest.embedding_dimensions });+ expect(await fixtureDataStats(other)).toEqual(manifest.data);+ } finally {+ await other.disconnect();+ }+ }, 240_000);+});diff --git a/test/engine-open.test.ts b/test/engine-open.test.tsindex 31778f8e92..30ebc24b49 100644--- a/test/engine-open.test.ts+++ b/test/engine-open.test.ts@@ -8,14 +8,17 @@ import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync }import { tmpdir } from 'node:os';import { join, relative } from 'node:path';import { randomBytes, randomUUID } from 'node:crypto';-import { embeddedSettings, hostIdFor, isEmbeddedEngine, openEngine, processHasEmbeddedEngines, registerLocalWriterValue, type EngineSettings } from '../src/core/engine-open.ts';+import { embeddedSettings, hostIdFor, isEmbeddedEngine, openEngine, processHasEmbeddedEngines, type EngineSettings } from '../src/core/engine-open.ts';import { markEmbeddedEngine } from '../src/core/embedded-engine.ts';-import { existingHostIdFor, existingLocalHostId, hostIdentityPathsFor, localHostId, localHostIdentity, revokeLocalWriter } from '../src/core/persistence/identity.ts';+import { existingHostIdFor, existingLocalHostId, hostIdentityPathsFor, localHostId, localHostIdentity, registerLocalWriter, registerLocalWriterValue, revokeLocalWriter } from '../src/core/persistence/identity.ts';import { operationsByName, type OperationContext } from '../src/core/operations.ts';import { readStoredEmbeddingIdentity } from '../src/core/stored-embedding-identity.ts';import { ConnectionManager } from '../src/core/connection-manager.ts';import type { BrainEngine } from '../src/core/engine.ts';import { withEnv } from './helpers/with-env.ts';+import { engineKey } from '../src/core/engine-key.ts';+import { awaitPendingTelemetryFlush, getTelemetryWriter, recordSearchTelemetry, _telemetryWriterCountForTest } from '../src/core/search/telemetry.ts';+import type { HybridSearchMeta } from '../src/core/types.ts';const scratch = mkdtempSync(join(tmpdir(), 'gbrain-engine-open-'));afterAll(() => { rmSync(scratch, { recursive: true, force: true }); });@@ -77,8 +80,7 @@ describe('openEngine on a clean home', () => {const path = dir('brain');const hostId = randomUUID();const writer = writerValue('stdio');- const settings = settingsFor({ database: { path }, host: { id: hostId }, writer, embedding: { model: 'voyage:voyage-4-lite', dimensions: 512 },- storage: { backend: 'local', bucket: 'files-example', localPath: dir('objects') }, storagePrefix: 'tenant-a/', ai: { provider: 'opaque-example' } });+ const settings = settingsFor({ database: { path }, host: { id: hostId }, writer, embedding: { model: 'voyage:voyage-4-lite', dimensions: 512 } });await withEnv(env, async () => {const first = await openEngine(settings);try {@@ -87,9 +89,7 @@ describe('openEngine on a clean home', () => {expect(processHasEmbeddedEngines()).toBe(true);expect(hostIdFor(first)).toBe(hostId);const held = embeddedSettings(first)!;- expect(held.storage).toEqual(settings.storage!);- expect(held.storagePrefix).toBe('tenant-a/');- expect(held.ai).toEqual({ provider: 'opaque-example' });+ expect(held.embedding).toEqual(settings.embedding!);expect(held.writer).toEqual({ id: writer.id, lane: 'stdio' });expect(JSON.stringify(held)).not.toContain(writer.credential);const [source] = await first.executeRaw<{ local_path: string | null }>("SELECT local_path FROM sources WHERE id='default'");@@ -151,6 +151,57 @@ describe('two engines in one process', () => {}, 180_000);});+describe('per-engine caches', () => {+ const meta: HybridSearchMeta = { vector_enabled: true, detail_resolved: null, expansion_applied: false, intent: 'general', mode: 'balanced' };+ const telemetryCount = async (engine: BrainEngine) => (await engine.executeRaw<{ n: number }>('SELECT COALESCE(SUM(count),0)::int AS n FROM search_telemetry'))[0]!.n;++ test('each opened engine has its own engineKey entry and telemetry writer; its transactions share them', async () => {+ const a = await openEngine(settingsFor({ database: { path: dir('cache-a') } }));+ const b = await openEngine(settingsFor({ database: { path: dir('cache-b') } }));+ try {+ await a.initSchema();+ await b.initSchema();+ expect(engineKey(a)).toBe(a);+ expect(engineKey(b)).toBe(b);+ expect(getTelemetryWriter(a)).not.toBe(getTelemetryWriter(b));+ await a.transaction(async tx => {+ expect(engineKey(tx)).toBe(a);+ expect(getTelemetryWriter(tx)).toBe(getTelemetryWriter(a));+ expect(hostIdFor(tx)).toBe(hostIdFor(a));+ });+ recordSearchTelemetry(a, meta, { results_count: 1 });+ recordSearchTelemetry(b, meta, { results_count: 1 });+ recordSearchTelemetry(b, meta, { results_count: 1 });+ await awaitPendingTelemetryFlush(5000, 'exit');+ expect(await telemetryCount(a)).toBe(1);+ expect(await telemetryCount(b)).toBe(2);+ } finally {+ await Promise.all([a.disconnect(), b.disconnect()]);+ }+ }, 180_000);++ test('a disconnect suspends the telemetry writer; after a reconnect the next record resumes it into the same brain', async () => {+ const engine = await openEngine(settingsFor({ database: { path: dir('cache-reconnect') } }));+ try {+ await engine.initSchema();+ const writer = getTelemetryWriter(engine);+ const live = _telemetryWriterCountForTest();+ recordSearchTelemetry(engine, meta, { results_count: 1 });+ await engine.reconnect();+ expect(_telemetryWriterCountForTest()).toBe(live - 1);+ expect(embeddedSettings(engine)).toBeDefined();+ recordSearchTelemetry(engine, meta, { results_count: 1 });+ expect(getTelemetryWriter(engine)).toBe(writer);+ expect(_telemetryWriterCountForTest()).toBe(live);+ await awaitPendingTelemetryFlush(5000, 'exit');+ expect(await telemetryCount(engine)).toBe(2);+ } finally {+ await engine.disconnect();+ }+ expect(embeddedSettings(engine)).toBeUndefined();+ }, 180_000);+});+describe('host identity', () => {test('an embedded engine with no host id refuses engine_host_missing and never mints host.json', async () => {const { gbrainHome, env } = canaries();@@ -248,18 +299,48 @@ describe('writer given as a value', () => {});expect(filesUnder(gbrainHome)).toEqual([]);}, 180_000);-});-describe('embedding identity', () => {- test('initSchema seeds settings.embedding, not the process gateway, and an existing brain with another width refuses', async () => {- const path = dir('brain-embedding');- const first = await openEngine(settingsFor({ database: { path }, embedding: { model: 'voyage:voyage-4-lite', dimensions: 512 } }));+ test('a writer value never widens past the settings: its own lane, the default ceiling, and an existing ceiling kept', async () => {+ const path = dir('writer-ceiling');+ const writer = writerValue('stdio');+ const ceiling = async (engine: BrainEngine) => (await engine.executeRaw<{ grant_ceiling: unknown }>('SELECT grant_ceiling FROM persistence_local_writers WHERE id=$1::uuid', [writer.id]))[0]?.grant_ceiling;+ const first = await openEngine(settingsFor({ database: { path }, writer }));try {await first.initSchema();- expect(await readStoredEmbeddingIdentity(first)).toEqual({ model: 'voyage:voyage-4-lite', dimensions: 512 });+ await operationsByName.put_page.handler(hostCtx(first), { slug: 'notes/ceiling', content: '---\ntitle: Ceiling\n---\nWritten with the stdio writer.\n' });+ expect(await ceiling(first)).toEqual({ sourceIds: ['*'], operations: null, scopes: ['read', 'write'], slugPrefixes: null });+ expect(await codeOf(registerLocalWriter(first, 'cli'))).toBe('writer_registration_required');+ expect(await codeOf(operationsByName.put_page.handler({ ...hostCtx(first), remote: false } as OperationContext, { slug: 'notes/cli-lane', content: '---\ntitle: CLI lane\n---\nNo cli writer.\n' })))+ .toBe('writer_registration_required');+ expect(await first.getPage('notes/cli-lane')).toBeNull();+ await first.executeRaw(`UPDATE persistence_local_writers SET grant_ceiling='{"sourceIds":["default"],"operations":["put_page"],"scopes":["write"],"slugPrefixes":["notes/"]}'::jsonb WHERE id=$1::uuid`, [writer.id]);} finally {await first.disconnect();}+ const second = await openEngine(settingsFor({ database: { path }, writer: { ...writer } }));+ try {+ await second.initSchema();+ await operationsByName.put_page.handler(hostCtx(second), { slug: 'notes/narrowed', content: '---\ntitle: Narrowed\n---\nStill the narrowed writer.\n' });+ expect(await ceiling(second)).toEqual({ sourceIds: ['default'], operations: ['put_page'], scopes: ['write'], slugPrefixes: ['notes/'] });+ } finally {+ await second.disconnect();+ }+ }, 180_000);+});++describe('embedding identity', () => {+ test('initSchema seeds settings.embedding, not the process gateway, and an existing brain with another width refuses', async () => {+ const path = dir('brain-embedding');+ const { env } = canaries();+ await withEnv({ ...env, GBRAIN_EMBEDDING_MODEL: 'openai:text-embedding-3-large', GBRAIN_EMBEDDING_DIMENSIONS: '3072' }, async () => {+ const first = await openEngine(settingsFor({ database: { path }, embedding: { model: 'voyage:voyage-4-lite', dimensions: 512 } }));+ try {+ await first.initSchema();+ expect(await readStoredEmbeddingIdentity(first)).toEqual({ model: 'voyage:voyage-4-lite', dimensions: 512 });+ } finally {+ await first.disconnect();+ }+ });const wider = await openEngine(settingsFor({ database: { path }, embedding: { model: 'voyage:voyage-4-lite', dimensions: 1024 } }));try {const refusal = await wider.initSchema().then(() => null, (error: unknown) => error as { code?: string; message?: string; suggestion?: string });diff --git a/test/fixtures/goldens/exports/runtime.json b/test/fixtures/goldens/exports/runtime.jsonindex 2488324ed1..c7db0a4404 100644--- a/test/fixtures/goldens/exports/runtime.json+++ b/test/fixtures/goldens/exports/runtime.json@@ -646,8 +646,7 @@"hostIdFor","isEmbeddedEngine","openEngine",- "processHasEmbeddedEngines",- "registerLocalWriterValue"+ "processHasEmbeddedEngines"],"./eval/longmemeval/reader": ["READER_MAX_SESSION_CHARS",diff --git a/test/fixtures/goldens/exports/types.json b/test/fixtures/goldens/exports/types.jsonindex be8e4f4cea..111ce70901 100644--- a/test/fixtures/goldens/exports/types.json+++ b/test/fixtures/goldens/exports/types.json@@ -4433,13 +4433,12 @@"kind": "type","name": "EmbeddedSettingsView","signature": [- "{ readonly pglite?: { shared_buffers?: string; } | undefined; readonly host: { id: string; }; readonly database: { url?: string; directUrl?: string; path?: string; }; readonly embedding?: { model: string; dimensions: number; } | undefined; readonly embedded_core: boolean; readonly engine: \"postgres\" | \"pglite\"; readonly pool?: { max?: number; } | undefined; readonly storage?: StorageConfig | undefined; readonly storagePrefix?: string | undefined; readonly keyword_statement_timeout_ms?: number | undefined; readonly ai?: Record<string, unknown> | undefined; readonly writer?: { id: string; lane: \"cli\" | \"stdio\"; } | undefined; }"+ "{ readonly pglite?: { shared_buffers?: string; } | undefined; readonly host: { id: string; }; readonly database: { url?: string; directUrl?: string; path?: string; }; readonly embedding?: { model: string; dimensions: number; } | undefined; readonly embedded_core: boolean; readonly engine: \"postgres\" | \"pglite\"; readonly pool?: { max?: number; } | undefined; readonly keyword_statement_timeout_ms?: number | undefined; readonly writer?: { id: string; lane: \"cli\" | \"stdio\"; } | undefined; }"]},{"kind": "interface","members": [- "ai?: Record<string, unknown> | undefined","database: { url?: string; directUrl?: string; path?: string; }","embedded_core: boolean","embedding?: { model: string; dimensions: number; } | undefined",@@ -4448,8 +4447,6 @@"keyword_statement_timeout_ms?: number | undefined","pglite?: { shared_buffers?: string; } | undefined","pool?: { max?: number; } | undefined",- "storage?: StorageConfig | undefined",- "storagePrefix?: string | undefined","writer?: { id: string; credential: string; lane: \"cli\" | \"stdio\"; } | undefined"],"name": "EngineSettings"@@ -4488,13 +4485,6 @@"signature": ["() => boolean"]- },- {- "kind": "function",- "name": "registerLocalWriterValue",- "signature": [- "(engine: SqlEngine, local: LocalRegistration, grant?: LocalGrant) => Promise<void>"- ]}],"./eval/longmemeval/reader": [