Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
41.8 KB
Raw Blame
/**
 * put_page write-through tests (v0.38).
 *
 * Verifies that put_page writes the markdown file to disk alongside the
 * DB row when sync.repo_path is configured. Trust gating: subagent
 * sandbox writes stay DB-only; dry-run stays DB-only; missing-repo
 * stays DB-only, with a loud warning for remote callers.
 */

import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
import * as fs from 'node:fs';
import * as path from 'node:path';
import * as os from 'node:os';
import { randomUUID } from 'node:crypto';
import { PGLiteEngine } from '../../src/core/pglite-engine.ts';
import { resetPgliteState } from '../helpers/reset-pglite.ts';
import { operations, OperationError } from '../../src/core/operations.ts';
import type { OperationContext } from '../../src/core/operations.ts';
import { configureGateway, resetGateway, __setEmbedTransportForTests } from '../../src/core/ai/gateway.ts';
import { disposePersistenceConsumer } from '../../src/core/persistence/service.ts';
import { withEnv } from '../helpers/with-env.ts';
import { parseMarkdown, serializePageToMarkdown } from '../../src/core/markdown.ts';
import { upsertFactRow } from '../../src/core/facts-fence.ts';

let engine: PGLiteEngine;
let tmpRoot: string;
let brainDir: string;

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
}, 60_000);

afterAll(async () => {
  await disposePersistenceConsumer(engine);
  await engine.disconnect();
  // Don't leak the reset-state to sibling files in the same bun shard
  // (the v0.40.4.1 gateway state-leak class). beforeEach already reset
  // for our own tests; this is defense for the next file's siblings.
  resetGateway();
});

beforeEach(async () => {
  await disposePersistenceConsumer(engine);
  await resetPgliteState(engine);
  // CI fix: put_page's handler at src/core/operations.ts:622 computes
  // `noEmbed = !isAvailable('embedding')`. When the gateway has been
  // configured by a sibling test (or by the cli.ts module-load path
  // reading .env.testing) with a fake/stale VOYAGE_API_KEY,
  // isAvailable returns true → put_page tries to embed → the real
  // Voyage API returns 401 in CI. This test exercises write-through
  // behavior, not embedding. Reset the gateway so isAvailable returns
  // false → noEmbed=true → no network call.
  resetGateway();
  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'gbrain-wt-'));
  brainDir = path.join(tmpRoot, 'brain');
  fs.mkdirSync(brainDir, { recursive: true });
  // Wire sync.repo_path so write-through can find the repo.
  await engine.setConfig('sync.repo_path', brainDir);
});

afterEach(async () => {
  await disposePersistenceConsumer(engine);
  fs.rmSync(tmpRoot, { recursive: true, force: true });
});

const captureLogger = () => {
  const messages: Array<{ level: string; msg: string }> = [];
  return {
    logger: {
      info: (msg: string) => messages.push({ level: 'info', msg }),
      warn: (msg: string) => messages.push({ level: 'warn', msg }),
      error: (msg: string) => messages.push({ level: 'error', msg }),
    },
    messages,
  };
};

function makeCtx(overrides: Partial<OperationContext> = {}): OperationContext {
  const { logger } = captureLogger();
  return {
    engine,
    config: { engine: 'pglite' as const, embedding_disabled: true },
    logger,
    dryRun: false,
    remote: false,
    sourceId: 'default',
    ...overrides,
  };
}

const putPageOperation = operations.find((o) => o.name === 'put_page')!;
const putPage = { ...putPageOperation,
  handler: (ctx: OperationContext, params: Record<string, unknown>) =>
    withEnv({ GBRAIN_HOME: path.join(tmpRoot, 'home') }, () => putPageOperation.handler(ctx, params)),
};

describe('put_page write-through — happy path', () => {
  test('MCP writes commit before any embedding and queue it durably (#5100)', async () => {
    let embedCalls = 0;
    configureGateway({ embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: 1536, env: { OPENAI_API_KEY: 'sk-test' } });
    __setEmbedTransportForTests(async ({ values }: { values: string[] }) => {
      embedCalls++;
      return { embeddings: values.map(() => new Array(1536).fill(0)), usage: { tokens: 1 } } as any;
    });
    try {
      const ctx = makeCtx({ remote: true });
      const result = (await putPage.handler(ctx, {
        slug: 'inbox/mcp-deferred-embed',
        content: '---\ntitle: Deferred\n---\n\nThis page must be durable before its embedding runs.',
      })) as { embedding_state?: string; persistence?: { embedding_state?: string } };
      expect(embedCalls).toBe(0);
      expect(result.embedding_state ?? result.persistence?.embedding_state).toBe('queued');
      expect(await engine.getPage('inbox/mcp-deferred-embed', { sourceId: 'default' })).not.toBeNull();
      const [chunks] = await engine.executeRaw<{ n: number }>(
        `SELECT COUNT(*)::int AS n FROM content_chunks c JOIN pages p ON p.id = c.page_id WHERE p.slug = 'inbox/mcp-deferred-embed' AND c.embedding IS NULL`);
      expect(Number(chunks.n)).toBeGreaterThan(0);
    } finally {
      __setEmbedTransportForTests(null);
      resetGateway();
    }
  });

  test('writes the markdown file to disk at brainDir/<slug>.md', async () => {
    const ctx = makeCtx();
    const content = '---\ntitle: Test\n---\n\n# WT body';
    const result = (await putPage.handler(ctx, { slug: 'inbox/test-wt-1', content })) as {
      slug: string;
      write_through?: { written: boolean; path?: string };
    };
    expect(result.write_through?.written).toBe(true);
    const expectedPath = path.join(brainDir, 'inbox/test-wt-1.md');
    expect(JSON.stringify(result)).not.toContain(brainDir);
    expect(fs.existsSync(expectedPath)).toBe(true);
    const onDisk = fs.readFileSync(expectedPath, 'utf8');
    expect(onDisk).toContain('WT body');
  });

  test("remote writes infer a custom type from the active pack through no-op and file checks", async () => {
    const packDir = path.join(
      tmpRoot,
      "home",
      ".gbrain",
      "schema-packs",
      "route-test",
    );
    fs.mkdirSync(packDir, { recursive: true });
    fs.writeFileSync(
      path.join(packDir, "pack.yaml"),
      `api_version: gbrain-schema-pack-v1
name: route-test
version: 1.0.0
extends: gbrain-base-v2
page_types:
  - name: goal
    primitive: concept
    path_prefixes: [goals/]
    aliases: []
    extractable: false
    expert_routing: false
`,
    );
    await withEnv({ GBRAIN_SCHEMA_PACK: "route-test" }, async () => {
      const ctx = makeCtx({ remote: true });
      const slug = "goals/learn-guitar";
      const content = "---\ntitle: Learn guitar\n---\n\nPractice regularly.";
      const first = (await putPage.handler(ctx, { slug, content })) as {
        revision: string;
      };
      const file = path.join(brainDir, `${slug}.md`);
      expect(
        (await engine.readPageSnapshot(slug, { sourceId: "default" }))?.page
          .type,
      ).toBe("goal");
      expect(fs.readFileSync(file, "utf8")).toContain("type: goal");

      const unchanged = await putPage.handler(ctx, {
        slug,
        content,
        expected_revision: first.revision,
      });
      expect(unchanged).toMatchObject({
        state: "committed",
        noop: true,
        revision: first.revision,
      });

      // A canonical file imported under the pack can omit type frontmatter.
      fs.writeFileSync(
        file,
        fs.readFileSync(file, "utf8").replace(/^type: goal\n/m, ""),
      );
      const edited = await putPage.handler(ctx, {
        slug,
        content: content.replace("regularly", "daily"),
        expected_revision: first.revision,
      });
      expect(edited).toMatchObject({ state: "committed" });
      expect(
        (await engine.readPageSnapshot(slug, { sourceId: "default" }))?.page
          .type,
      ).toBe("goal");
    });
  });

  test('remote writes infer path subtypes and preserve explicit or stored subtypes', async () => {
    const packDir = path.join(tmpRoot, 'home', '.gbrain', 'schema-packs', 'meeting-test');
    fs.mkdirSync(packDir, { recursive: true });
    fs.writeFileSync(path.join(packDir, 'pack.yaml'), `api_version: gbrain-schema-pack-v1
name: meeting-test
version: 1.0.0
extends: gbrain-base-v2
page_types:
  - name: meeting
    primitive: temporal
    path_prefixes: [therapy-meetings/, meetings/]
    aliases: []
    extractable: false
    expert_routing: false
    subtypes:
      - name: therapy
        when:
          path_pattern: '^therapy-meetings/'
      - name: relationship
        when:
          path_pattern: '^relationship-meetings/'
`);
    await withEnv({ GBRAIN_SCHEMA_PACK: 'meeting-test' }, async () => {
      const ctx = makeCtx({ remote: true });
      const slug = 'therapy-meetings/session';
      const content = '---\ntitle: Session\n---\n\nFirst discussion.';
      const first = await putPage.handler(ctx, { slug, content }) as { revision: string };
      const file = path.join(brainDir, `${slug}.md`);
      expect((await engine.readPageSnapshot(slug, { sourceId: 'default' }))?.page).toMatchObject({ type: 'meeting', frontmatter: { subtype: 'therapy' } });
      expect(fs.readFileSync(file, 'utf8')).toContain('subtype: therapy');

      const unchanged = await putPage.handler(ctx, { slug, content, expected_revision: first.revision });
      expect(unchanged).toMatchObject({ state: 'committed', noop: true, revision: first.revision });

      fs.writeFileSync(file, fs.readFileSync(file, 'utf8').replace(/^subtype: therapy\n/m, ''));
      const edited = await putPage.handler(ctx, { slug, content: content.replace('First', 'Second'), expected_revision: first.revision }) as { revision: string };
      expect(edited).toMatchObject({ state: 'committed' });
      expect((await engine.readPageSnapshot(slug, { sourceId: 'default' }))?.page.frontmatter.subtype).toBe('therapy');

      const explicit = await putPage.handler(ctx, { slug, content: '---\ntitle: Session\nsubtype: relationship\n---\n\nThird discussion.', expected_revision: edited.revision }) as { revision: string };
      expect((await engine.readPageSnapshot(slug, { sourceId: 'default' }))?.page.frontmatter.subtype).toBe('relationship');
      await putPage.handler(ctx, { slug, content: content.replace('First', 'Fourth'), expected_revision: explicit.revision });
      expect((await engine.readPageSnapshot(slug, { sourceId: 'default' }))?.page.frontmatter.subtype).toBe('relationship');

      const legacySlug = 'therapy-meetings/legacy';
      const legacy = await putPage.handler(ctx, { slug: legacySlug, content: '---\ntitle: Legacy\ntype: concept\n---\n\nExisting page.' }) as { revision: string };
      await putPage.handler(ctx, { slug: legacySlug, content: '---\ntitle: Legacy\n---\n\nUpdated page.', expected_revision: legacy.revision });
      expect((await engine.readPageSnapshot(legacySlug, { sourceId: 'default' }))?.page).toMatchObject({ type: 'concept' });
      expect((await engine.readPageSnapshot(legacySlug, { sourceId: 'default' }))?.page.frontmatter.subtype).toBeUndefined();
    });
  });

  test('a page stored before its pack subtype rule existed accepts edits and gains the subtype (#5928)', async () => {
    const writePack = (name: string, subtypes: string) => {
      const packDir = path.join(tmpRoot, 'home', '.gbrain', 'schema-packs', name);
      fs.mkdirSync(packDir, { recursive: true });
      fs.writeFileSync(path.join(packDir, 'pack.yaml'), `api_version: gbrain-schema-pack-v1
name: ${name}
version: 1.0.0
extends: gbrain-base-v2
page_types:
  - name: meeting
    primitive: temporal
    path_prefixes: [therapy-meetings/, meetings/]
    aliases: []
    extractable: false
    expert_routing: false
${subtypes}`);
    };
    writePack('before-rule', '');
    writePack('after-rule', `    subtypes:
      - name: therapy
        when:
          path_pattern: '^therapy-meetings/'
`);
    const ctx = makeCtx({ remote: true });
    const slug = 'therapy-meetings/session';
    const file = path.join(brainDir, `${slug}.md`);
    const content = '---\ntitle: Session\n---\n\nFirst discussion.';
    const first = await withEnv({ GBRAIN_SCHEMA_PACK: 'before-rule' }, () => putPage.handler(ctx, { slug, content })) as { revision: string };
    expect((await engine.readPageSnapshot(slug, { sourceId: 'default' }))?.page.frontmatter).not.toHaveProperty('subtype');
    expect(fs.readFileSync(file, 'utf8')).not.toContain('subtype:');

    // The canonical file is unchanged since that write; only the active pack gained a rule.
    const edited = await withEnv({ GBRAIN_SCHEMA_PACK: 'after-rule' }, () =>
      putPage.handler(ctx, { slug, content: content.replace('First', 'Second'), expected_revision: first.revision }));
    expect(edited).toMatchObject({ state: 'committed' });
    expect((await engine.readPageSnapshot(slug, { sourceId: 'default' }))?.page).toMatchObject({
      type: 'meeting', compiled_truth: 'Second discussion.', frontmatter: { subtype: 'therapy' } });
    expect(fs.readFileSync(file, 'utf8')).toContain('subtype: therapy');
  });

  test('a type-less file whose stored type is not its pack path type keeps the stored subtype in the file check (#5521)', async () => {
    const packDir = path.join(tmpRoot, 'home', '.gbrain', 'schema-packs', 'typed-meetings');
    fs.mkdirSync(packDir, { recursive: true });
    fs.writeFileSync(path.join(packDir, 'pack.yaml'), `api_version: gbrain-schema-pack-v1
name: typed-meetings
version: 1.0.0
extends: gbrain-base-v2
page_types:
  - name: meeting
    primitive: temporal
    path_prefixes: [therapy-meetings/]
    aliases: []
    extractable: false
    expert_routing: false
    subtypes:
      - name: therapy
        when:
          path_pattern: '^therapy-meetings/'
`);
    const ctx = makeCtx({ remote: true });
    const slug = 'therapy-meetings/review';
    const file = path.join(brainDir, `${slug}.md`);
    const write = (params: Record<string, unknown>) => withEnv({ GBRAIN_SCHEMA_PACK: 'typed-meetings' }, () => putPage.handler(ctx, { slug, ...params }));
    const first = await write({ content: '---\ntitle: Review\ntype: note\nsubtype: weekly\n---\n\nFirst discussion.' }) as { revision: string };
    expect((await engine.readPageSnapshot(slug, { sourceId: 'default' }))?.page).toMatchObject({ type: 'note', frontmatter: { subtype: 'weekly' } });

    // A mirror rewrites the file without its type and subtype lines; import reads it as the same page (#1035).
    fs.writeFileSync(file, fs.readFileSync(file, 'utf8').replace(/^(type|subtype): .*\n/gm, ''));
    const edited = await write({ content: '---\ntitle: Review\n---\n\nSecond discussion.', expected_revision: first.revision });
    expect(edited).toMatchObject({ state: 'committed' });
    expect((await engine.readPageSnapshot(slug, { sourceId: 'default' }))?.page).toMatchObject({
      type: 'note', compiled_truth: 'Second discussion.', frontmatter: { subtype: 'weekly' } });
  });

  test('a grandfather validate:false stamp held only by the database is not an uncoordinated file edit (#6429)', async () => {
    const ctx = makeCtx({ remote: true });
    const slug = 'companies/acme-example';
    const file = path.join(brainDir, `${slug}.md`);
    const content = '---\ntitle: Acme Example\ntype: company\n---\n\nFirst note.';
    const first = await putPage.handler(ctx, { slug, content }) as { revision: string };
    expect(fs.readFileSync(file, 'utf8')).not.toContain('validate:');
    // The unmanaged v0.13.1 grandfather path stamps the database row and never writes the file (v0_13_1.ts, raw UPDATE).
    await engine.executeRaw(`UPDATE pages SET frontmatter=jsonb_set(COALESCE(frontmatter,'{}'::jsonb),'{validate}','false'::jsonb) WHERE slug=$1 AND source_id='default'`, [slug]);
    const stamped = await engine.readPageSnapshot(slug, { sourceId: 'default' });
    expect(stamped?.page.frontmatter.validate).toBe(false);
    expect(stamped?.revision).not.toBe(first.revision);

    const edited = await putPage.handler(ctx, { slug, content: content.replace('First', 'Second'), expected_revision: stamped!.revision });
    expect(edited).toMatchObject({ state: 'committed' });
    expect((await engine.readPageSnapshot(slug, { sourceId: 'default' }))?.page.compiled_truth).toBe('Second note.');

    // A memory write renders the stored page, so it publishes the stamp to the file instead of refusing.
    await engine.executeRaw(`UPDATE pages SET frontmatter=jsonb_set(COALESCE(frontmatter,'{}'::jsonb),'{validate}','false'::jsonb) WHERE slug=$1 AND source_id='default'`, [slug]);
    const remember = operations.find((o) => o.name === 'remember')!;
    const saved = await withEnv({ GBRAIN_HOME: path.join(tmpRoot, 'home') }, () => remember.handler(ctx,
      { fact: 'Acme Example moved to Austin', provenance: 'user told me, 2026-10-10', entity: slug, visibility: 'world', request_id: randomUUID() })) as { state?: string; status?: string };
    expect(saved.state ?? saved.status).toMatch(/committed|inserted/);
    const onDisk = fs.readFileSync(file, 'utf8');
    expect(onDisk).toContain('validate: false');
    expect(onDisk).toContain('Acme Example moved to Austin');

    // A file that records its own decision still wins: that is a real edit, not the stamp.
    fs.writeFileSync(file, onDisk.replace('validate: false', 'validate: true'));
    const current = await engine.readPageSnapshot(slug, { sourceId: 'default' });
    await expect(putPage.handler(ctx, { slug, content: content.replace('First', 'Third'), expected_revision: current!.revision }))
      .rejects.toMatchObject({ code: 'source_changed' });
  });

  test('stamps provenance frontmatter (ingested_via=put_page for local CLI)', async () => {
    const ctx = makeCtx({ remote: false });
    const result = (await putPage.handler(ctx, {
      slug: 'inbox/provenance',
      content: '---\ntitle: P\n---\n\nbody',
    })) as { write_through?: { written: boolean; path?: string } };
    expect(result.write_through?.written).toBe(true);
    const onDisk = fs.readFileSync(path.join(brainDir, 'inbox/provenance.md'), 'utf8');
    expect(onDisk).toMatch(/ingested_via:\s*put_page/);
    expect(onDisk).toMatch(/ingested_at:/);
  });

  test('MCP/remote callers get ingested_via=mcp:put_page', async () => {
    const ctx = makeCtx({ remote: true });
    const result = (await putPage.handler(ctx, {
      slug: 'inbox/mcp-prov',
      content: '---\ntitle: Q\n---\n\nbody',
    })) as { write_through?: { written: boolean; path?: string } };
    expect(result.write_through?.written).toBe(true);
    expect(JSON.stringify(result)).not.toContain(brainDir);
    const onDisk = fs.readFileSync(path.join(brainDir, 'inbox/mcp-prov.md'), 'utf8');
    // YAML quotes strings containing `:` so the literal frontmatter line
    // is `ingested_via: 'mcp:put_page'`. Match the value substring.
    expect(onDisk).toMatch(/ingested_via:\s*['"]?mcp:put_page['"]?/);
  });

  test.each([false, true])('first-write provenance survives replay, identical no-op and later edits (remote=%s)', async (remote) => {
    const ctx = makeCtx({ remote });
    const slug = 'inbox/stable-provenance';
    const content = '---\ntitle: Stable provenance\ningested_at: forged timestamp\ningested_via: forged channel\nsource_kind: forged channel\n---\n\nOriginal body';
    const params = { slug, content, request_id: randomUUID() };
    const first = await putPage.handler(ctx, params) as { revision: string; created_at: string };
    const initial = (await engine.readPageSnapshot(slug, { sourceId: 'default' }))!;
    const file = path.join(brainDir, `${slug}.md`);
    const bytes = fs.readFileSync(file, 'utf8');
    expect(initial.page.frontmatter).toMatchObject({ source_kind: remote ? 'mcp:put_page' : 'put_page',
      ingested_via: remote ? 'mcp:put_page' : 'put_page', ingested_at: first.created_at });
    expect(initial.page.ingested_at?.toISOString()).toBe(first.created_at);
    expect(parseMarkdown(bytes, slug)).toMatchObject({ frontmatter: initial.page.frontmatter,
      compiled_truth: initial.page.compiled_truth, timeline: initial.page.timeline, tags: initial.tags });
    expect(bytes).not.toContain('forged');
    expect(await putPage.handler(ctx, params)).toEqual(first);

    const unchanged = await putPage.handler(ctx, { ...params, request_id: randomUUID(), expected_revision: first.revision });
    expect(unchanged).toMatchObject({ state: 'committed', noop: true, revision: first.revision });
    expect(fs.readFileSync(file, 'utf8')).toBe(bytes);
    expect(await engine.executeRaw('SELECT id FROM page_versions WHERE page_id=$1', [initial.page.id])).toEqual([]);

    const edited = await putPage.handler(ctx, { ...params, request_id: randomUUID(), expected_revision: first.revision,
      content: content.replace('Original body', 'Updated body') });
    const final = (await engine.readPageSnapshot(slug, { sourceId: 'default' }))!;
    expect(edited).toMatchObject({ state: 'committed', revision: final.revision });
    expect(final.revision).not.toBe(first.revision);
    expect(final.page.frontmatter).toEqual(initial.page.frontmatter);
    expect(final.page.ingested_at?.toISOString()).toBe(first.created_at);
    expect(parseMarkdown(fs.readFileSync(file, 'utf8'), slug)).toMatchObject({ frontmatter: final.page.frontmatter,
      compiled_truth: final.page.compiled_truth, timeline: final.page.timeline, tags: final.tags });
    expect(await putPage.handler(ctx, params)).toEqual(first);
  });

  test('an exact no-op on a historical unstamped page adds no provenance or revision', async () => {
    const slug = 'inbox/historical';
    await engine.putPage(slug, { type: 'note', title: 'Historical', compiled_truth: 'Existing body', timeline: '', frontmatter: {} });
    const before = (await engine.readPageSnapshot(slug, { sourceId: 'default' }))!;
    const bytes = serializePageToMarkdown(before.page, before.tags);
    fs.mkdirSync(path.join(brainDir, 'inbox'), { recursive: true });
    const file = path.join(brainDir, `${slug}.md`);
    fs.writeFileSync(file, bytes);
    expect(await putPage.handler(makeCtx(), { slug, content: bytes, expected_revision: before.revision }))
      .toMatchObject({ state: 'committed', noop: true, revision: before.revision });
    const after = (await engine.readPageSnapshot(slug, { sourceId: 'default' }))!;
    expect(after.page.frontmatter).toEqual({});
    expect(after.page.ingested_at).toBeNull();
    expect(fs.readFileSync(file, 'utf8')).toBe(bytes);
  });

  test('a filtered remote round-trip remains an unstamped no-op after hidden-fact restoration', async () => {
    const slug = 'inbox/historical-private';
    const body = upsertFactRow('Existing body', { claim: 'Private fixture claim', kind: 'fact', visibility: 'private',
      confidence: 1, notability: 'medium' }).body.trim();
    await engine.putPage(slug, { type: 'note', title: 'Historical private', compiled_truth: body, timeline: '', frontmatter: {} });
    const before = (await engine.readPageSnapshot(slug, { sourceId: 'default' }))!;
    const file = path.join(brainDir, `${slug}.md`);
    fs.mkdirSync(path.dirname(file), { recursive: true });
    const bytes = serializePageToMarkdown(before.page, before.tags);
    fs.writeFileSync(file, bytes);
    const remote = makeCtx({ remote: true });
    const visible = await operations.find(op => op.name === 'get_page')!.handler(remote, { slug, include_content: true }) as { content: string; revision: string };
    expect(visible.content).not.toContain('Private fixture claim');
    expect(await putPage.handler(remote, { slug, content: visible.content, expected_revision: visible.revision }))
      .toMatchObject({ state: 'committed', noop: true, revision: before.revision });
    expect((await engine.readPageSnapshot(slug, { sourceId: 'default' }))!.page.frontmatter).toEqual({});
    expect(fs.readFileSync(file, 'utf8')).toBe(bytes);
    expect(await engine.executeRaw('SELECT id FROM page_versions WHERE page_id=$1', [before.page.id])).toEqual([]);
  });

  test('editing legacy frontmatter cannot promote forged audit stamps into trusted columns', async () => {
    const slug = 'inbox/legacy-audit';
    await engine.putPage(slug, { type: 'note', title: 'Legacy audit', compiled_truth: 'Existing body', timeline: '',
      frontmatter: { source_kind: 'forged kind', ingested_via: 'forged channel', ingested_at: 'unknown' },
      source_kind: 'mcp:put_page', ingested_via: 'mcp:put_page' });
    const before = (await engine.readPageSnapshot(slug, { sourceId: 'default' }))!;
    const file = path.join(brainDir, `${slug}.md`);
    fs.mkdirSync(path.dirname(file), { recursive: true });
    const content = serializePageToMarkdown(before.page, before.tags);
    fs.writeFileSync(file, content);
    await putPage.handler(makeCtx({ remote: true }), { slug, content: content.replace('Existing body', 'Edited body'), force: true });
    const after = (await engine.readPageSnapshot(slug, { sourceId: 'default' }))!;
    // The edit is a remote agent write over an unclassified legacy row (stored tier unknown, no marker in the file):
    // the marker names the writer's tier, never a permanent `unknown` cap (#6550; #5575 CEO-21 keeps the marker).
    expect(after.page.frontmatter).toEqual({ source_kind: 'mcp:put_page', ingested_via: 'mcp:put_page',
      ingested_at: before.page.ingested_at!.toISOString(), trust_tier: 'agent_written' });
    expect(after.page.source_kind).toBe('mcp:put_page');
    expect(after.page.ingested_at).toEqual(before.page.ingested_at);
    expect(parseMarkdown(fs.readFileSync(file, 'utf8'), slug).frontmatter).toEqual(after.page.frontmatter);
  });

  test('a legacy unstamped external-ID duplicate creates neither a second page nor a file', async () => {
    const slug = 'inbox/legacy-id';
    await engine.putPage(slug, { type: 'note', title: 'Legacy ID', compiled_truth: 'Existing body', timeline: '',
      frontmatter: { id: 'legacy-external-id' } });
    const before = (await engine.readPageSnapshot(slug, { sourceId: 'default' }))!;
    const file = path.join(brainDir, `${slug}.md`);
    fs.mkdirSync(path.dirname(file), { recursive: true });
    const content = serializePageToMarkdown(before.page, before.tags);
    fs.writeFileSync(file, content);
    expect(await putPage.handler(makeCtx(), { slug: 'inbox/legacy-copy', content }))
      .toMatchObject({ state: 'committed', status: 'duplicate', slug });
    expect(await engine.executeRaw('SELECT id FROM pages')).toHaveLength(1);
    expect(fs.existsSync(path.join(brainDir, 'inbox/legacy-copy.md'))).toBe(false);
    expect(fs.readFileSync(file, 'utf8')).toBe(content);
    expect((await engine.readPageSnapshot(slug, { sourceId: 'default' }))!.revision).toBe(before.revision);
  });
});

describe('put_page write-through — trust gating', () => {
  test('subagent sandbox write (viaSubagent without allowedSlugPrefixes) stays DB-only', async () => {
    const ctx = makeCtx({
      remote: true,
      viaSubagent: true,
      subagentId: 42,
      // No allowedSlugPrefixes — sandbox writes only.
    });
    const result = (await putPage.handler(ctx, {
      slug: 'wiki/agents/42/scratch',
      content: '---\ntitle: S\n---\n\nbody',
    })) as { write_through?: { written: boolean; skipped?: string } };
    expect(result.write_through?.written).toBe(false);
    expect(result.write_through?.skipped).toBe('subagent_sandbox');
    expect(fs.existsSync(path.join(brainDir, 'wiki/agents/42/scratch.md'))).toBe(false);
  });

  test('trusted-workspace subagent (viaSubagent + allowedSlugPrefixes) writes through', async () => {
    const ctx = makeCtx({
      remote: true,
      viaSubagent: true,
      subagentId: 7,
      allowedSlugPrefixes: ['wiki/personal/reflections/*'],
    });
    const result = (await putPage.handler(ctx, {
      slug: 'wiki/personal/reflections/note',
      content: '---\ntitle: R\n---\n\nreflection',
    })) as { write_through?: { written: boolean; path?: string } };
    expect(result.write_through?.written).toBe(true);
    expect(fs.existsSync(path.join(brainDir, 'wiki/personal/reflections/note.md'))).toBe(true);
  });

  test('dry-run stays DB-only (early-return before importFromContent)', async () => {
    const ctx = makeCtx({ dryRun: true });
    const result = (await putPage.handler(ctx, {
      slug: 'inbox/dryrun',
      content: '---\ntitle: D\n---\n\nbody',
    })) as { dry_run?: boolean; write_through?: { skipped?: string } };
    // put_page's existing handler short-circuits on dry-run BEFORE
    // importFromContent, so write_through never fires. The legacy dry_run
    // contract is what callers see.
    expect(result.dry_run).toBe(true);
    expect(fs.existsSync(path.join(brainDir, 'inbox/dryrun.md'))).toBe(false);
  });
});

describe('put_page write-through — config edge cases', () => {
  test('repo not configured → skipped no_repo_configured', async () => {
    // No deleteConfig helper; remove via raw SQL.
    await engine.executeRaw("DELETE FROM config WHERE key = 'sync.repo_path'");
    const ctx = makeCtx();
    const result = (await putPage.handler(ctx, {
      slug: 'inbox/no-repo',
      content: '---\ntitle: N\n---\n\nbody',
    })) as { write_through?: { skipped?: string; warning?: string } };
    expect(result.write_through?.skipped).toBe('no_repo_configured');
    expect(result.write_through?.warning).toBeUndefined();
  });

  test('remote repo not configured → warns that the write is DB-only', async () => {
    await engine.executeRaw("DELETE FROM config WHERE key = 'sync.repo_path'");
    const ctx = makeCtx({ remote: true });
    const result = (await putPage.handler(ctx, {
      slug: 'inbox/no-repo-remote',
      content: '---\ntitle: Remote\n---\n\nbody',
    })) as { write_through?: { skipped?: string; warning?: string } };
    expect(result.write_through?.skipped).toBe('no_repo_configured');
    expect(result.write_through?.warning).toContain('wrote only to the database');
    expect(result.write_through?.warning).toContain("source 'default'");
    expect(result.write_through?.warning).toContain('no durable markdown file');
  });

  test('remote edit_page with no repo configured warns that the edit is DB-only too (#5616)', async () => {
    await engine.executeRaw("DELETE FROM config WHERE key = 'sync.repo_path'");
    const ctx = makeCtx({ remote: true });
    await putPage.handler(ctx, { slug: 'inbox/no-repo-edit', content: '---\ntitle: Edit\n---\n\nalpha line' });
    const { operations } = await import('../../src/core/operations.ts');
    const getPage = operations.find(op => op.name === 'get_page')!;
    const editPage = operations.find(op => op.name === 'edit_page')!;
    const read = await getPage.handler(ctx, { slug: 'inbox/no-repo-edit', include_content: true }) as { revision: string };
    const result = (await editPage.handler(ctx, {
      slug: 'inbox/no-repo-edit', expected_revision: read.revision, edits: [{ old_text: 'alpha line', new_text: 'beta line' }],
    })) as { write_through?: { skipped?: string; warning?: string } };
    expect(result.write_through?.skipped).toBe('no_repo_configured');
    expect(result.write_through?.warning).toContain('edit_page wrote only to the database');
  });

  test.each([false, true])('missing directory returns a private typed error before admission (remote=%s)', async (remote) => {
    await engine.setConfig('sync.repo_path', path.join(tmpRoot, 'does-not-exist'));
    const ctx = makeCtx({ remote });
    const requestId = randomUUID();
    const error = await putPage.handler(ctx, {
      slug: 'inbox/missing-repo', content: '---\ntitle: M\n---\n\nbody', request_id: requestId,
    }).then(() => null, (error: unknown) => error);
    expect(error).toBeInstanceOf(OperationError);
    expect((error as OperationError).toJSON()).toMatchObject({ error: 'storage_error' });
    expect((error as OperationError).writeRequest).toBeUndefined();
    expect(JSON.stringify(error)).not.toContain(tmpRoot);
    expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE request_id=$1::uuid', [requestId])).toEqual([]);
    expect(await engine.executeRaw('SELECT id FROM persistence_worktrees')).toEqual([]);
    expect(await engine.executeRaw('SELECT source_id FROM persistence_source_bindings')).toEqual([]);
    expect(await ctx.engine.getPage('inbox/missing-repo', { sourceId: 'default' })).toBeNull();
  });
});

describe('put_page write-through — multi-source filing', () => {
  test('non-default source writes inside its explicitly configured root', async () => {
    const sourceRoot = path.join(brainDir, '.sources/team-x');
    fs.mkdirSync(sourceRoot, { recursive: true });
    await engine.executeRaw(
      "INSERT INTO sources (id, name, local_path) VALUES ('team-x', 'team-x', $1)", [sourceRoot],
    );
    const ctx = makeCtx({ sourceId: 'team-x' });
    const result = (await putPage.handler(ctx, {
      slug: 'shared/page',
      content: '---\ntitle: X\n---\n\nbody',
    })) as { write_through?: { written: boolean; path?: string } };
    expect(result.write_through?.written).toBe(true);
    expect(fs.readFileSync(path.join(sourceRoot, 'shared/page.md'), 'utf8')).toContain('body');
    expect(fs.existsSync(path.join(brainDir, 'shared/page.md'))).toBe(false);
  });

  test('a source without a root stays database-only instead of using the default root', async () => {
    await engine.executeRaw("INSERT INTO sources (id,name) VALUES ('database-only','Database only')");
    const result = await putPage.handler(makeCtx({ sourceId: 'database-only' }), {
      slug: 'shared/database-page', content: '---\ntitle: Database only\n---\n\nbody',
    });
    expect(result).toMatchObject({ state: 'committed', write_through: { written: false, skipped: 'no_repo_configured' } });
    expect(await engine.getPage('shared/database-page', { sourceId: 'database-only' })).not.toBeNull();
    expect(fs.existsSync(path.join(brainDir, 'shared/database-page.md'))).toBe(false);
    expect(fs.existsSync(path.join(brainDir, '.sources/database-only/shared/database-page.md'))).toBe(false);
  });
});

describe('put_page write-through — failure isolation', () => {
  test('disk-write failure rejects the call and rolls back the new page (no index-only orphan)', async () => {
    // Point the config at a path that exists but isn't writable so the
    // write fails. Best portable trick: a regular file (writeFileSync to
    // a path inside a regular file fails with ENOTDIR).
    const blockFile = path.join(tmpRoot, 'block');
    fs.writeFileSync(blockFile, 'i am a file, not a dir');
    await engine.setConfig('sync.repo_path', blockFile);

    const ctx = makeCtx();
    await expect(
      putPage.handler(ctx, {
        slug: 'inbox/fail-isolated',
        content: '---\ntitle: F\n---\n\nbody',
      }),
    ).rejects.toBeInstanceOf(OperationError);

    // The markdown file is the system of record; a page that only exists
    // as a DB row is an orphan the caller can't see or fix. Since this was
    // a brand-new slug, the failed write is rolled back entirely.
    const page = await engine.getPage('inbox/fail-isolated');
    expect(page).toBeNull();
  });
});

// ── #4807 (E-D17): put_page refuses a new .md/.mdx-suffixed slug ─────────────

describe('put_page suffixed slugs (#4807)', () => {
  const content = '---\ntitle: Report\n---\n\nreport body';
  async function writeRequests(): Promise<number> {
    const [row] = await engine.executeRaw<{ n: number }>('SELECT COUNT(*)::int AS n FROM persistence_requests');
    return Number(row!.n);
  }
  async function refusalOf(promise: Promise<unknown>): Promise<OperationError> {
    try { await promise; } catch (error) { return error as OperationError; }
    throw new Error('expected a refusal');
  }

  test('a new suffixed slug is refused before admission: no row, no receipt, no file (x.md.md or x.md)', async () => {
    const before = await writeRequests();
    for (const slug of ['inbox/report.md', 'Inbox/Report.MD', 'inbox/report.md.mdx']) {
      const error = await refusalOf(putPage.handler(makeCtx(), { slug, content }));
      expect(error).toBeInstanceOf(OperationError);
      expect(error.code).toBe('invalid_params');
      expect(error.message).toBe('put_page slugs must not end in .md or .mdx.');
      expect(error.suggestion).toBe('Write the page as inbox/report: gbrain put inbox/report (the .md file name is added for you).');
    }
    expect(await writeRequests()).toBe(before);
    expect(await engine.getPage('inbox/report.md', { sourceId: 'default' })).toBeNull();
    expect(fs.existsSync(path.join(brainDir, 'inbox/report.md.md'))).toBe(false);
    expect(fs.existsSync(path.join(brainDir, 'inbox/report.md'))).toBe(false);
  });

  test('dry-run refuses the same way, and the corrected bare slug then writes inbox/report.md', async () => {
    const error = await refusalOf(putPage.handler(makeCtx({ dryRun: true }), { slug: 'inbox/report.md', content }));
    expect(error.code).toBe('invalid_params');
    const result = (await putPage.handler(makeCtx(), { slug: 'inbox/report', content })) as { slug_advisory?: string; write_through?: { written: boolean } };
    expect(result.write_through?.written).toBe(true);
    expect(result.slug_advisory).toBeUndefined();
    expect(fs.readFileSync(path.join(brainDir, 'inbox/report.md'), 'utf8')).toContain('report body');
  });

  test('rendered contract: CLI and MCP envelopes carry why, a read-only get_page fix and verify on the bare slug', async () => {
    const { toAgentError, cliRenderContext } = await import('../../src/core/agent-output.ts');
    const cli = toAgentError(await refusalOf(putPage.handler(makeCtx(), { slug: 'inbox/report.md', content })),
      { transport: 'cli', command: 'put', render: cliRenderContext() });
    expect(cli).toMatchObject({ code: 'invalid_params', class: 'caller', contract_version: 1 });
    expect(cli.why).toContain('<slug>.md.md');
    expect(cli.fix).toMatchObject({ argv: ['gbrain', 'get', 'inbox/report'], next: 'run', verify: { argv: ['gbrain', 'get', 'inbox/report'] } });
    const remote = await refusalOf(putPage.handler(makeCtx({ remote: true }), { slug: 'inbox/report.md', content }));
    expect(remote.suggestion).toBe('Call put_page again with slug "inbox/report" and the same content (the .md file name is added for you).');
    expect(remote.fix?.mcp).toEqual({ tool: 'get_page', arguments: { slug: 'inbox/report' } });
  });

  test('a live exact foo.md row (chunks, deep-research id) still updates, keeps its id and gets the move advisory; its bare twin is untouched', async () => {
    const { encodeDeepResearchId, decodeDeepResearchId } = await import('../../src/core/deep-research-id.ts');
    const legacy = 'notes/legacy.md';
    await engine.putPage(legacy, { type: 'note', title: 'Legacy', compiled_truth: 'old legacy body', timeline: '' }, { sourceId: 'default' });
    await engine.putPage('notes/legacy', { type: 'note', title: 'Twin', compiled_truth: 'bare twin body', timeline: '' }, { sourceId: 'default' });
    await engine.upsertChunks(legacy, [{ chunk_index: 0, chunk_text: 'old legacy body', chunk_source: 'compiled_truth' }], { sourceId: 'default' });
    const before = (await engine.getPage(legacy, { sourceId: 'default' }))!;
    const chunkText = async () => (await engine.executeRaw<{ t: string }>(
      "SELECT c.chunk_text AS t FROM content_chunks c JOIN pages p ON p.id = c.page_id WHERE p.slug = 'notes/legacy.md' AND p.source_id = 'default'")).map(r => r.t).join(' ');
    expect(await chunkText()).toContain('old legacy body');

    const snapshot = (await engine.readPageSnapshot(legacy, { sourceId: 'default' }))!;
    fs.mkdirSync(path.join(brainDir, 'notes'), { recursive: true });
    fs.writeFileSync(path.join(brainDir, `${legacy}.md`), serializePageToMarkdown(snapshot.page, snapshot.tags));
    const revision = snapshot.revision;
    const result = (await putPage.handler(makeCtx(), { slug: legacy, content: '---\ntitle: Legacy\n---\n\nnew legacy body', expected_revision: revision })) as { slug_advisory?: string };
    expect(result.slug_advisory).toBe('This page\'s slug ends in .md, which new pages cannot use. To move it, put_page its content under "notes/legacy", then delete_page "notes/legacy.md".');
    const after = (await engine.getPage(legacy, { sourceId: 'default' }))!;
    expect(after.id).toBe(before.id);
    expect(after.compiled_truth).toContain('new legacy body');
    expect(await chunkText()).toContain('new legacy body');
    const id = encodeDeepResearchId('default', legacy);
    expect(decodeDeepResearchId(id)).toEqual({ sourceId: 'default', slug: legacy });
    const fetchOp = operations.find(o => o.name === 'fetch')!;
    const fetched = (await fetchOp.handler(makeCtx(), { id })) as { id: string; text: string };
    expect(fetched.text).toContain('new legacy body');
    expect((await engine.getPage('notes/legacy', { sourceId: 'default' }))!.compiled_truth).toContain('bare twin body');
  });

  test('a soft-deleted foo.md row does not count as live: re-creating it is refused', async () => {
    await engine.putPage('notes/gone.md', { type: 'note', title: 'Gone', compiled_truth: 'gone', timeline: '' }, { sourceId: 'default' });
    await engine.executeRaw("UPDATE pages SET deleted_at = now() WHERE slug = 'notes/gone.md'");
    const error = await refusalOf(putPage.handler(makeCtx(), { slug: 'notes/gone.md', content }));
    expect(error.code).toBe('invalid_params');
  });
});

describe('file import with a .md-suffixed frontmatter slug (#4807)', () => {
  test('a frontmatter slug ending in .md that names no live page is held with the same rule; an existing exact row imports', async () => {
    const { importFile } = await import('../../src/core/import-file.ts');
    const file = path.join(brainDir, 'notes', 'held.md');
    fs.mkdirSync(path.dirname(file), { recursive: true });
    fs.writeFileSync(file, '---\ntitle: Held\nslug: notes/held.md\n---\n\nheld body');
    const held = await importFile(engine, file, 'notes/held.md', { noEmbed: true, sourceId: 'default' });
    expect(held).toMatchObject({ status: 'skipped', skip_reason: 'frontmatter_slug_conflict', refusal: { code: 'frontmatter_slug_conflict', key: 'slug' } });
    expect(held.error).toContain('must not end in .md or .mdx');
    expect(held.error).not.toContain('slug: notes/held.md');
    expect(await engine.getPage('notes/held.md', { sourceId: 'default' })).toBeNull();

    await engine.putPage('notes/held.md', { type: 'note', title: 'Held', compiled_truth: 'legacy', timeline: '' }, { sourceId: 'default' });
    const imported = await importFile(engine, file, 'notes/held.md', { noEmbed: true, sourceId: 'default' });
    expect(imported.status).toBe('imported');
    expect(imported.slug).toBe('notes/held.md');
  });
});