Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
29.1 KB
Raw Blame
import { describe, expect, test } from 'bun:test';
import { codeEndAt, indexOfOutsideCode, scanMarkdownCode, unclosedCodeFenceStart } from '../src/core/fence-scan.ts';
import {
  TAKES_FENCE_BEGIN, TAKES_FENCE_END, parseTakesFence, renderTakesFence, stripTakesFence, upsertTakeRow,
} from '../src/core/takes-fence.ts';
import {
  FACTS_FENCE_BEGIN, FACTS_FENCE_END, parseFactsFence, renderFactsTable, replaceOrInsertFactsFence, stripFactsFence, upsertFactRow,
} from '../src/core/facts-fence.ts';
import { escapeFenceCell, parseRowCells } from '../src/core/fence-shared.ts';
import { sanitizeRemoteBody } from '../src/core/remote-body.ts';
import { preserveProtectedTakes } from '../src/core/persistence/protected-takes.ts';
import { compileCanonicalProjections } from '../src/core/persistence/canonical-projections.ts';
import { withdrawalFenceBlocks } from '../src/core/facts/withdrawal-overlay.ts';
import { splitBody } from '../src/core/markdown.ts';
import type { ParsedPage } from '../src/core/import-file.ts';
import { cpuMs } from './helpers/cpu-time.ts';

const take = (claim: string) => ({ claim, kind: 'take' as const, holder: 'alice-example', weight: 0.5, active: true });
const realTakes = (claim: string) => upsertTakeRow('', take(claim)).body;

/** A doc page that documents the takes fence syntax inside a code block. */
const takesExample = [
  '```markdown',
  TAKES_FENCE_BEGIN,
  '| # | claim | kind | who | weight | since | source |',
  '|---|---|---|---|---|---|---|',
  '| 1 | EXAMPLE-CLAIM | take | alice-example | 0.5 | 2026-01 | docs |',
  TAKES_FENCE_END,
  '```',
].join('\n');

const factsExample = ['```markdown', FACTS_FENCE_BEGIN, '| 1 | EXAMPLE-FACT |', FACTS_FENCE_END, '```'].join('\n');

const worldAndPrivateFacts = renderFactsTable([
  { rowNum: 1, claim: 'WORLD-FACT', kind: 'fact', confidence: 1, visibility: 'world', notability: 'high', active: true },
  { rowNum: 2, claim: 'PRIVATE-FACT', kind: 'fact', confidence: 1, visibility: 'private', notability: 'high', active: true },
]);

/** Every code span, rebuilt by asking codeEndAt at each offset in order. */
function codeSlices(body: string): string[] {
  const map = scanMarkdownCode(body);
  const out: string[] = [];
  for (let i = 0; i < body.length;) {
    const end = codeEndAt(map, i);
    if (end === -1) { i++; continue; }
    out.push(body.slice(i, end));
    i = end;
  }
  return out;
}

const page = (compiled_truth: string): ParsedPage =>
  ({ type: 'concept', title: 't', compiled_truth, timeline: '', frontmatter: {}, tags: [] }) as ParsedPage;

describe('markdown code map', () => {
  test('closed fences and same-line inline spans are code', () => {
    expect(codeSlices('a `x` b\n```\ncode\n```\ntail')).toEqual(['`x`', '```\ncode\n```\n']);
  });

  test('an unclosed fence anywhere means fence pairing cannot be trusted', () => {
    // The stray ~~~ proves some fence line is mispaired, so no block is code.
    expect(codeSlices('a `x` b\n```\ncode\n```\n~~~\nopen to EOF')).toEqual(['`x`']);
  });

  test('a longer outer fence nests an example; a same-length inner opener is a mispairing', () => {
    const nested = '````markdown\n```ts\nx\n```\n````\n';
    expect(codeSlices(`${nested}tail`)).toEqual([nested]);
    // ``` then ```ts: the inner opener cannot close the block, so the first
    // ``` must be a stray that paired with the wrong line.
    expect(codeSlices('```\nstray\n```ts\nx\n```\ntail')).toEqual([]);
  });

  test('double-backtick spans, escaped backticks and CRLF line endings', () => {
    const body = 'p ``a ` b`` q \\`not code` r\r\n```\r\nz\r\n```';
    expect(codeSlices(body)).toEqual(['``a ` b``', '```\r\nz\r\n```']);
  });

  test('bare CR line endings are line breaks too', () => {
    const body = 'a `x`\r```\rz\r```\rtail';
    expect(codeSlices(body)).toEqual(['`x`', '```\rz\r```\r']);
  });

  test('stays linear on long pages with no backticks or line breaks to find', () => {
    // A per-line search that runs to EOF on every line lacking a backtick is
    // quadratic: ~200 ms per MB of plain prose. Linear is ~1 ms.
    const prose = 'Plain prose with no code at all, just words.\n'.repeat(45_000);
    const ms = cpuMs(() => expect(scanMarkdownCode(prose).fenced).toEqual([]));
    expect(ms).toBeLessThan(150);
  });

  test('stays linear with thousands of quoted markers on one long line', () => {
    // Inline spans are computed per marker line on demand; a line's spans must
    // be computed once, not once per marker on it.
    const line = `\`${TAKES_FENCE_BEGIN}\` `.repeat(20_000);
    const ms = cpuMs(() => expect(indexOfOutsideCode(line, TAKES_FENCE_BEGIN)).toBe(-1));
    expect(ms).toBeLessThan(150);
  });

  test('stays linear across many marker lines on a page with no backticks', () => {
    // A facts/takes-heavy page without inline code: judging each marker line
    // must not search the rest of the body for a backtick.
    const body = `${FACTS_FENCE_BEGIN}\n${'x'.repeat(80)}\n`.repeat(20_000);
    const ms = cpuMs(() => {
      const code = scanMarkdownCode(body);
      let n = 0;
      for (let at = indexOfOutsideCode(body, FACTS_FENCE_BEGIN); at !== -1; at = indexOfOutsideCode(body, FACTS_FENCE_BEGIN, at + 1, code)) n++;
      expect(n).toBe(20_000);
    });
    expect(ms).toBeLessThan(150);
  });

  test('stays linear when a lone CR sits far before many marker lines', () => {
    // Finding a marker's line must never search toward the start of the body.
    const body = 'head\r' + `plain line of prose here\n\`${TAKES_FENCE_BEGIN}\`\n`.repeat(20_000);
    const ms = cpuMs(() => expect(indexOfOutsideCode(body, TAKES_FENCE_BEGIN)).toBe(-1));
    expect(ms).toBeLessThan(150);
  });

  test('indexOfOutsideCode skips quoted occurrences and finds the live one', () => {
    const body = `\`${TAKES_FENCE_BEGIN}\`\n${TAKES_FENCE_BEGIN}`;
    expect(indexOfOutsideCode(body, TAKES_FENCE_BEGIN)).toBe(body.lastIndexOf(TAKES_FENCE_BEGIN));
    expect(indexOfOutsideCode('`only quoted`', 'quoted')).toBe(-1);
  });

  test('unclosedCodeFenceStart ignores closed fences', () => {
    expect(unclosedCodeFenceStart('a\n```\nb\n```\nc')).toBe(-1);
    expect(unclosedCodeFenceStart('a\n```\nb\n```\n~~~\nc')).toBe('a\n```\nb\n```\n'.length);
  });
});

describe('takes fence markers quoted in code are documentation', () => {
  test('parse ignores a fenced example and still reads the real fence after it', () => {
    expect(parseTakesFence(`doc\n\n${takesExample}\n`)).toEqual({ takes: [], warnings: [], reservedRowNums: [] });
    const body = `doc\n\n${takesExample}\n\n${realTakes('REAL-CLAIM')}`;
    expect(parseTakesFence(body).takes.map(t => t.claim)).toEqual(['REAL-CLAIM']);
  });

  test('an inline-code mention of the marker is neither unbalanced nor a near miss', () => {
    const body = `The marker is \`${TAKES_FENCE_BEGIN}\` on its own line.\n\nTAIL`;
    expect(parseTakesFence(body).warnings).toEqual([]);
    expect(parseTakesFence(`mention \`<!-- gbrain:takes:begin -->\``).warnings).toEqual([]);
  });

  test('upsert leaves the example untouched and adds a real fence', () => {
    const body = `doc\n\n${takesExample}\n`;
    const out = upsertTakeRow(body, take('REAL-CLAIM')).body;
    expect(out.startsWith(body)).toBe(true);
    expect(parseTakesFence(out).takes.map(t => t.claim)).toEqual(['REAL-CLAIM']);
  });

  test('strip hides the example too: the privacy boundary never trusts code blocks', () => {
    const body = `doc\n\n${takesExample}\n\n${realTakes('REAL-CLAIM')}`;
    const out = stripTakesFence(body);
    expect(out).not.toContain('EXAMPLE-CLAIM');
    expect(out).not.toContain('REAL-CLAIM');
  });
});

describe('remote privacy boundary', () => {
  test('the boundary never hides less than the lexical scan: an inline-code marker still protects its tail', () => {
    // Readers no longer treat the mention as a fence, but the privacy boundary
    // only ever changes toward hiding more, so the tail stays protected.
    const body = `intro\n\nThe marker is \`${TAKES_FENCE_BEGIN}\` on its own line.\n\nPRIVATE TAIL`;
    expect(parseTakesFence(body)).toEqual({ takes: [], warnings: [], reservedRowNums: [] });
    expect(sanitizeRemoteBody(body)).not.toContain('PRIVATE TAIL');
    expect(stripTakesFence(body)).not.toContain('PRIVATE TAIL');
  });

  test('a real fence after a documented example is still stripped', () => {
    const body = `doc\n\n${takesExample}\n\n${realTakes('SECRET-CLAIM')}\n\nafter`;
    const out = sanitizeRemoteBody(body);
    expect(out).not.toContain('EXAMPLE-CLAIM');
    expect(out).not.toContain('SECRET-CLAIM');
    expect(out).toContain('after');
  });

  test('fails closed: a fence after an unclosed code block is still stripped', () => {
    const body = `doc\n\n\`\`\`text\nnever closed\n\n${realTakes('SECRET-CLAIM')}\n`;
    expect(sanitizeRemoteBody(body)).not.toContain('SECRET-CLAIM');
    expect(stripTakesFence(body)).not.toContain('SECRET-CLAIM');
  });

  test('every take the parser sees is hidden from remote readers', () => {
    const bodies = [
      realTakes('P1'),
      `${takesExample}\n\n${realTakes('P2')}`,
      `\`${TAKES_FENCE_BEGIN}\`\n\n${realTakes('P3')}`,
      `\`\`\`\nunclosed\n${realTakes('P4')}`,
    ];
    for (const body of bodies) {
      const claims = parseTakesFence(body).takes.map(t => t.claim);
      expect(claims.length).toBe(1);
      for (const claim of claims) expect(sanitizeRemoteBody(body)).not.toContain(claim);
    }
  });

  test('private facts stay hidden when a facts example precedes the fence', () => {
    const body = `doc\n\n${factsExample}\n\n${worldAndPrivateFacts}\n`;
    const out = sanitizeRemoteBody(body);
    expect(out).not.toContain('EXAMPLE-FACT');
    expect(out).toContain('WORLD-FACT');
    expect(out).not.toContain('PRIVATE-FACT');
  });
});

describe('remote page replacement', () => {
  test('a remote replacement of a page with an unpaired inline-code marker stays refused (unchanged boundary)', () => {
    const stored = `The marker is \`${TAKES_FENCE_BEGIN}\`.\n`;
    expect(() => preserveProtectedTakes(`${stored}edit\n`, stored)).toThrow('must be repaired');
  });

  test('two live fences in one section are still rejected', () => {
    const twice = `${realTakes('A')}\n\n${realTakes('B')}\n`;
    expect(() => compileCanonicalProjections(page(twice), 'docs/fences', 'default')).toThrow('at most one');
    const strayEnd = `${realTakes('A')}\n${TAKES_FENCE_END}\n`;
    expect(() => compileCanonicalProjections(page(strayEnd), 'docs/fences', 'default')).toThrow('at most one');
    const bothFacts = `${worldAndPrivateFacts}\n\n${worldAndPrivateFacts}\n`;
    expect(() => compileCanonicalProjections(page(bothFacts), 'docs/fences', 'default')).toThrow('at most one');
  });

  test('a documented example plus a real fence passes the canonical projection checks', () => {
    const body = `doc\n\n${takesExample}\n\n${realTakes('REAL-CLAIM')}\n\n${factsExample}\n`;
    const compiled = compileCanonicalProjections(page(body), 'docs/fences', 'default');
    expect(compiled.takes.map(t => t.claim)).toEqual(['REAL-CLAIM']);
    expect(compiled.quoted?.takes.has('1:EXAMPLE-CLAIM')).toBe(true);
  });
});

describe('facts fence', () => {
  test('parse ignores a fenced example; strip and withdrawal enumeration still cover it', () => {
    const body = `doc\n\n${factsExample}\n\n${worldAndPrivateFacts}\n`;
    expect(parseFactsFence(body).facts.map(f => f.claim)).toEqual(['WORLD-FACT', 'PRIVATE-FACT']);
    expect(stripFactsFence(body)).not.toContain('EXAMPLE-FACT');
    // Withdrawal keeps enumerating every lexical fence (privacy direction), the real one included.
    expect(withdrawalFenceBlocks(body).at(-1)!.parsed.facts.map(f => f.claim)).toEqual(['WORLD-FACT', 'PRIVATE-FACT']);
  });
});

describe('fence placement above an unclosed code block', () => {
  test('a new takes fence is not written inside an unclosed code block', () => {
    const body = 'doc\n\n```text\nnever closed\n';
    const out = upsertTakeRow(body, take('REAL-CLAIM')).body;
    const fenceAt = out.indexOf(TAKES_FENCE_BEGIN);
    expect(fenceAt).toBeGreaterThan(-1);
    expect(fenceAt).toBeLessThan(out.indexOf('```text'));
    expect(out.endsWith('```text\nnever closed\n')).toBe(true);
    expect(parseTakesFence(out).takes.map(t => t.claim)).toEqual(['REAL-CLAIM']);
  });

  test('a new facts fence is not written inside an unclosed code block', () => {
    const body = 'doc\n\n```text\nnever closed\n';
    const out = replaceOrInsertFactsFence(body, worldAndPrivateFacts);
    expect(out.indexOf(FACTS_FENCE_BEGIN)).toBeLessThan(out.indexOf('```text'));
    expect(out.endsWith('```text\nnever closed\n')).toBe(true);
  });

  test('without an unclosed code block the placement is unchanged', () => {
    expect(upsertTakeRow('doc\n', take('X')).body.startsWith('doc\n\n## Takes\n\n')).toBe(true);
    expect(replaceOrInsertFactsFence('doc\n', worldAndPrivateFacts)).toBe(`doc\n\n## Facts\n\n${worldAndPrivateFacts}\n`);
  });
});

/**
 * A stray ``` pairs with a later block's opener, so a real fence between them
 * reads as the inside of a closed code block. The shapes below are the ways
 * that happens; none may expose a protected row.
 */
const stray = 'doc\n\n```\nnever closed\n\n';
const mispaired = {
  // The later block's closer is left unpaired: an unclosed fence remains.
  shifted: (fence: string) => `${stray}${fence}\n\n\`\`\`\ncode\n\`\`\`\n`,
  // An info string cannot close a block, so everything pairs up and no
  // unclosed fence is left to reveal the mispairing.
  infoString: (fence: string) => `${stray}${fence}\n\n\`\`\`ts\ncode\n\`\`\`\n`,
  // Deliberately wrapped in a balanced code block.
  wrapped: (fence: string) => `doc\n\n\`\`\`\n${fence}\n\`\`\`\n`,
};

describe('mispaired code fences at the privacy boundary', () => {
  for (const [name, shape] of Object.entries(mispaired)) {
    test(`${name}: takes stay hidden from every boundary consumer`, () => {
      const body = shape(realTakes('SECRET-CLAIM'));
      expect(sanitizeRemoteBody(body)).not.toContain('SECRET-CLAIM');
      expect(stripTakesFence(body)).not.toContain('SECRET-CLAIM');
    });

    test(`${name}: private facts stay hidden from every boundary consumer`, () => {
      const body = shape(worldAndPrivateFacts);
      expect(sanitizeRemoteBody(body)).not.toContain('PRIVATE-FACT');
      expect(stripFactsFence(body)).not.toContain('PRIVATE-FACT');
      expect(stripFactsFence(body, { keepVisibility: ['world'] })).not.toContain('PRIVATE-FACT');
    });
  }

  test('readers see a mispaired real fence again', () => {
    for (const shape of [mispaired.shifted, mispaired.infoString]) {
      expect(parseTakesFence(shape(realTakes('REAL-CLAIM'))).takes.map(t => t.claim)).toEqual(['REAL-CLAIM']);
    }
  });

  test('readers treat a deliberately wrapped fence as code', () => {
    expect(parseTakesFence(mispaired.wrapped(realTakes('REAL-CLAIM'))).takes).toEqual([]);
  });

  test('a fence readers see stays hidden up to the end marker readers pair with it', () => {
    // An end marker quoted in a code block inside the fence does not end it
    // for readers, so it must not end the hidden region either.
    const quotedEnd = ['```', TAKES_FENCE_END, '```'].join('\n');
    const body = [
      TAKES_FENCE_BEGIN,
      '| # | claim | kind | who | weight | since | source |',
      '|---|---|---|---|---|---|---|',
      '| 1 | FIRST-SECRET | take | alice-example | 0.5 | 2026-01 | x |',
      quotedEnd,
      '| 2 | SECOND-SECRET | take | alice-example | 0.5 | 2026-01 | x |',
      TAKES_FENCE_END,
      'after',
    ].join('\n');
    const claims = parseTakesFence(body).takes.map(t => t.claim);
    expect(claims).toContain('SECOND-SECRET');
    for (const out of [sanitizeRemoteBody(body), stripTakesFence(body)]) {
      for (const claim of claims) expect(out).not.toContain(claim);
      expect(out).toContain('after');
    }
  });

  test('a remote replacement keeps a mispaired real fence', () => {
    const stored = mispaired.shifted(realTakes('REAL-CLAIM'));
    const incoming = `${sanitizeRemoteBody(stored).trimEnd()}\nedit\n`;
    expect(preserveProtectedTakes(incoming, stored)).toContain('REAL-CLAIM');
  });

  test('a remote replacement of a page whose only fence is a code example is refused', () => {
    // Re-appending the hidden example at EOF would make it a live fence.
    const stored = `doc\n\n${takesExample}\n`;
    const incoming = `${sanitizeRemoteBody(stored).trimEnd()}\nedit\n`;
    expect(() => preserveProtectedTakes(incoming, stored)).toThrow('inside markdown code');
  });
});

describe('timeline sentinel quoted in code', () => {
  const SENTINEL = '<!-- timeline -->';
  const entry = '- **2026-01-01** | manual — entry';

  test('a sentinel inside a code block example does not split the page', () => {
    const body = `Intro\n\n\`\`\`markdown\n${SENTINEL}\n\`\`\`\n\nMore prose.\n\n${SENTINEL}\n\n${entry}`;
    expect(splitBody(body)).toEqual({
      compiled_truth: `Intro\n\n\`\`\`markdown\n${SENTINEL}\n\`\`\`\n\nMore prose.\n`,
      timeline: `\n${entry}`,
    });
  });

  test('a legacy --- plus ## Timeline pair inside a code block does not split the page', () => {
    const body = 'Intro\n\n```\n---\n## Timeline\n```\n\nAfter.';
    expect(splitBody(body)).toEqual({ compiled_truth: body, timeline: '' });
  });

  test('the serializer\'s sentinel still splits when a stray fence mispairs the blocks', () => {
    for (const opener of ['```', '```ts']) {
      const body = `Intro\n\n\`\`\`\nstray\n\n${SENTINEL}\n\n${entry}\n\n${opener}\ncode\n\`\`\``;
      expect(splitBody(body).timeline).toContain(entry);
    }
  });

  test('a new facts fence lands above the real sentinel, not above a quoted one', () => {
    const body = `doc\n\n\`\`\`markdown\n${SENTINEL}\n\`\`\`\n\nprose\n\n${SENTINEL}\n\n${entry}\n`;
    const out = replaceOrInsertFactsFence(body, worldAndPrivateFacts);
    expect(out.indexOf(FACTS_FENCE_BEGIN)).toBeGreaterThan(out.indexOf('prose'));
    expect(out.indexOf(FACTS_FENCE_BEGIN)).toBeLessThan(out.lastIndexOf(SENTINEL));
  });
});

/**
 * Adversarial matrix for the remote privacy boundary (fix wave 10, #5397).
 * Every stored body below holds a real takes fence with SECRET and real facts
 * with PRIVATE-FACT next to a trap: unbalanced fences, CRLF / CR, nested
 * backtick and tilde fences, indented code, inline-code markers, and a marker
 * inside a quoted code block. For each one the secret must stay hidden from
 * remote reads and chunk strips, and a remote write may neither drop the
 * stored fence nor replace it with an attacker's fence.
 */
describe('adversarial fence matrix (remote privacy)', () => {
  const SECRET = 'SECRET-TAKE-CLAIM';
  const realFence = realTakes(SECRET);
  const facts = worldAndPrivateFacts;
  const fenceBody = `${realFence}\n\n${facts}`;
  const indent = (text: string) => text.split('\n').map(l => `    ${l}`).join('\n');
  const quote = (text: string) => text.split('\n').map(l => `> ${l}`).join('\n');
  const traps: Record<string, string> = {
    'unclosed fence before': `doc\n\n\`\`\`text\nnever closed\n\n${fenceBody}\n`,
    'unclosed fence after': `doc\n\n${fenceBody}\n\n\`\`\`\nopen to EOF\n`,
    'stray closer before': `doc\n\n\`\`\`\n\n${fenceBody}\n\`\`\`\ntail\n`,
    'code end marker inside the real fence': `doc\n\n${realFence.replace('\n|', `\n\`${TAKES_FENCE_END}\`\n|`)}\n\n${facts}\n`,
    'fenced end marker inside the real fence': `doc\n\n${realFence.replace(TAKES_FENCE_END, `\`\`\`\n${TAKES_FENCE_END}\n\`\`\`\n${TAKES_FENCE_END}`)}\n\n${facts}\n`,
    'nested backtick in tilde wrap': `doc\n\n~~~~\n\`\`\`\n${fenceBody}\n\`\`\`\n~~~~\ntail\n`,
    'nested tilde in backtick wrap': `doc\n\n\`\`\`\`markdown\n~~~\n${fenceBody}\n~~~\n\`\`\`\`\ntail\n`,
    'mismatched fence chars': `doc\n\n\`\`\`\n${fenceBody}\n~~~\ntail\n`,
    'indented code block': `doc\n\n${indent(fenceBody)}\n\ntail\n`,
    'inline begin before the real fence': `doc \`${TAKES_FENCE_BEGIN}\` and \`${FACTS_FENCE_BEGIN}\`\n\n${fenceBody}\n`,
    'inline end before the real fence': `doc \`${TAKES_FENCE_END}\` and \`${FACTS_FENCE_END}\`\n\n${fenceBody}\n`,
    'marker in a quoted code block': `doc\n\n${quote(`\`\`\`markdown\n${fenceBody}\n\`\`\``)}\n\ntail\n`,
    'quoted code block then real fence': `doc\n\n${quote(`\`\`\`markdown\n${TAKES_FENCE_BEGIN}\n\`\`\``)}\n\n${fenceBody}\n`,
  };
  const variants: Array<[string, string]> = Object.entries(traps).flatMap(([name, body]) => [
    [name, body], [`${name} (CRLF)`, body.replace(/\n/g, '\r\n')], [`${name} (CR)`, body.replace(/\n/g, '\r')],
  ]);

  for (const [name, body] of variants) {
    test(`${name}: hidden from remote reads and chunk strips`, () => {
      for (const out of [sanitizeRemoteBody(body), stripFactsFence(stripTakesFence(body)), stripFactsFence(stripTakesFence(body), { keepVisibility: ['world'] })]) {
        expect(out).not.toContain(SECRET);
        expect(out).not.toContain('PRIVATE-FACT');
      }
    });

    test(`${name}: a remote round trip never drops the stored fence`, () => {
      const incoming = `${sanitizeRemoteBody(body).trimEnd()}\nedit\n`;
      let out: string | undefined;
      try { out = preserveProtectedTakes(incoming, body); } catch (e) { expect((e as Error).name).toBe('OperationError'); return; }
      expect(out).toContain(SECRET);
    });

    for (const [how, fake] of [
      ['plain', realTakes('ATTACKER-CLAIM')],
      ['in a code block', `\`\`\`\n${realTakes('ATTACKER-CLAIM')}\n\`\`\``],
      ['in inline code', `\`${TAKES_FENCE_BEGIN}\` ATTACKER-CLAIM \`${TAKES_FENCE_END}\``],
      ['as a bare begin', `${TAKES_FENCE_BEGIN}\n| 1 | ATTACKER-CLAIM |`],
    ] as const) {
      test(`${name}: a remote fake fence (${how}) cannot overwrite the stored take`, () => {
        const incoming = `${sanitizeRemoteBody(body).trimEnd()}\n\n${fake}\n`;
        let out: string | undefined;
        try { out = preserveProtectedTakes(incoming, body); } catch (e) { expect((e as Error).name).toBe('OperationError'); return; }
        // Accepted only when the fake was no fence at all: the stored fence is
        // kept verbatim and no attacker row reaches the readers.
        expect(out).toContain(SECRET);
        expect(parseTakesFence(out).takes.map(t => t.claim)).not.toContain('ATTACKER-CLAIM');
      });
    }
  }

  test('every boundary refusal renders the agent contract without echoing page text', async () => {
    const { renderCliError } = await import('../src/core/agent-output.ts');
    const errors: unknown[] = [];
    for (const [stored, incoming] of [
      [`doc\n\n${TAKES_FENCE_BEGIN}\n| 1 | ${SECRET} |\n`, 'x\n'],
      [`doc\n\n${takesExample}\n`, 'doc\nedit\n'],
      [`doc\n\n${realFence}\n`, `doc\n\n${realTakes('ATTACKER-CLAIM')}\n`],
    ] as const) {
      try { preserveProtectedTakes(incoming, stored); } catch (e) { errors.push(e); }
    }
    expect(errors).toHaveLength(3);
    for (const e of errors) {
      const env = JSON.parse(renderCliError(e, { json: true, command: 'put', tty: false }).stdout!);
      expect(['invalid_params', 'permission_denied']).toContain(env.code);
      expect(env.message).toBeTruthy();
      expect(env.suggestion).toBeTruthy();
      expect(JSON.stringify(env)).not.toContain(SECRET);
      expect(JSON.stringify(env)).not.toContain('ATTACKER-CLAIM');
    }
  });
});

describe('fence markers inside a cell are encoded, never live (#5395)', () => {
  const rawBegin = '<!--- gbrain:facts:begin -->';
  const rawEnd = '<!--- gbrain:facts:end -->';
  const fact = (claim: string, extra: Partial<Parameters<typeof upsertFactRow>[1]> = {}) =>
    ({ claim, kind: 'fact' as const, confidence: 1, visibility: 'world' as const, notability: 'high' as const, ...extra });

  test('upsertFactRow with a raw marker in row 2 keeps every row and the remote body intact', () => {
    const claim2 = `the row said ${rawBegin} then ${rawEnd} in plain text`;
    let body = upsertFactRow('# Page\n\nIntro.\n', fact('row one')).body;
    body = upsertFactRow(body, fact(claim2)).body;
    body = upsertFactRow(body, fact('row three', { visibility: 'private' })).body;
    const parsed = parseFactsFence(body);
    expect(parsed.warnings).toEqual([]);
    expect(parsed.facts.map(f => f.claim)).toEqual(['row one', claim2, 'row three']);
    // Exactly one live begin and one live end marker on the page.
    expect(body.split(FACTS_FENCE_BEGIN).length - 1).toBe(1);
    expect(body.split(FACTS_FENCE_END).length - 1).toBe(1);
    // The remote boundary still pairs the real markers: the private row is
    // hidden, the world rows and the prose after the fence survive.
    const remote = sanitizeRemoteBody(`${body}\n\nTail prose.\n`);
    expect(remote).toContain('Intro.');
    expect(remote).toContain('Tail prose.');
    expect(remote).toContain('row one');
    expect(remote).not.toContain('row three');
  });

  test('every cell position of the facts fence round-trips a raw marker', () => {
    const m = 'gbrain:facts:end';
    const row = fact(`claim ${m}`, { validFrom: `from ${m}`, validUntil: `until ${m}`, source: `src ${m}`, context: `ctx ${m}`, claimMetric: `metric ${m}`, claimValue: 1, claimUnit: `unit ${m}`, claimPeriod: `period ${m}` });
    const body = upsertFactRow('', row).body;
    const [f] = parseFactsFence(body).facts;
    expect(f!.claim).toBe(`claim ${m}`);
    expect(f!.validFrom).toBe(`from ${m}`);
    expect(f!.validUntil).toBe(`until ${m}`);
    expect(f!.source).toBe(`src ${m}`);
    expect(f!.context).toBe(`ctx ${m}`);
    expect(f!.claimMetric).toBe(`metric ${m}`);
    expect(f!.claimUnit).toBe(`unit ${m}`);
    expect(f!.claimPeriod).toBe(`period ${m}`);
    // The only bare occurrence left on the page is the live end marker.
    expect(body.split(m).length - 1).toBe(1);
  });

  test('the takes fence round-trips raw markers in the claim, source and evidence cells', () => {
    const m = `${TAKES_FENCE_BEGIN} and ${TAKES_FENCE_END}`;
    const upserted = upsertTakeRow('', { ...take(`take says ${m}`), source: `src ${m}` }).body;
    expect(parseTakesFence(upserted).takes.map(t => [t.claim, t.source])).toEqual([[`take says ${m}`, `src ${m}`]]);
    const body = renderTakesFence([{ ...take(`take says ${m}`), rowNum: 1, source: `src ${m}`, resolvedAt: '2026-01-01', resolvedQuality: 'correct' as const, resolvedOutcome: true, resolvedEvidence: `ev ${m}`, resolvedBy: `by ${m}` }]);
    const parsed = parseTakesFence(body);
    expect(parsed.warnings).toEqual([]);
    expect(parsed.takes).toHaveLength(1);
    expect(parsed.takes[0]!.claim).toBe(`take says ${m}`);
    expect(parsed.takes[0]!.source).toBe(`src ${m}`);
    expect(parsed.takes[0]!.resolvedEvidence).toBe(`ev ${m}`);
    expect(parsed.takes[0]!.resolvedBy).toBe(`by ${m}`);
    expect(body.split(TAKES_FENCE_BEGIN).length - 1).toBe(1);
    expect(body.split(TAKES_FENCE_END).length - 1).toBe(1);
  });

  test('the codec is injective: a literal entity form and a nested form both survive', () => {
    const literals = ['gbrain&#58;facts:begin', 'gbrain&amp;#58;takes:end', 'gbrain&amp;amp;#58;facts:end', 'gbrain:takes:begin'];
    for (const literal of literals) {
      const claim = `literal ${literal} here`;
      const body = upsertFactRow('', fact(claim)).body;
      expect(parseFactsFence(body).facts[0]!.claim).toBe(claim);
      expect(body).not.toContain('gbrain:takes:begin');
    }
    // All four distinct inputs render as four distinct cells.
    const rendered = literals.map(l => renderFactsTable([{ ...fact(l), rowNum: 1, active: true }]));
    expect(new Set(rendered).size).toBe(literals.length);
    // A `&#58;` not followed by the marker suffix is untouched.
    const plain = 'colon &#58; entity and gbrain&#58;other:begin stay';
    expect(parseFactsFence(upsertFactRow('', fact(plain)).body).facts[0]!.claim).toBe(plain);
    expect(upsertFactRow('', fact(plain)).body).toContain(plain);
  });

  test('encode and decode are inverse over random ampersand runs', () => {
    const kinds = ['facts', 'takes'];
    const edges = ['begin', 'end'];
    let seed = 5395;
    const rnd = (n: number) => { seed = (seed * 1103515245 + 12345) & 0x7fffffff; return seed % n; };
    for (let i = 0; i < 200; i++) {
      const parts: string[] = [];
      const n = 1 + rnd(4);
      for (let j = 0; j < n; j++) {
        const level = rnd(4);
        const mid = level === 0 ? ':' : `&${'amp;'.repeat(level - 1)}#58;`;
        parts.push(`x${rnd(10)} gbrain${mid}${kinds[rnd(2)]}:${edges[rnd(2)]}`);
      }
      const text = parts.join(rnd(2) ? ' ' : '');
      const encoded = escapeFenceCell(text);
      expect(encoded).not.toMatch(/gbrain:(facts|takes):(begin|end)/);
      expect(parseRowCells(`| ${encoded} |`)).toEqual([text]);
      // decode∘encode = id on the encoded image: a second parse of the already-decoded text is a no-op only when it holds no bare form,
      // and encode∘decode = id on any encoded cell.
      expect(escapeFenceCell(parseRowCells(`| ${encoded} |`)![0]!)).toBe(encoded);
    }
  });

  test('repeated upsert is byte-idempotent and the transcript-escaped form still parses', () => {
    const claim = `quoted ${rawBegin}`;
    const once = upsertFactRow('', fact(claim)).body;
    const twice = upsertFactRow(once, fact('another')).body;
    expect(parseFactsFence(twice).facts.map(f => f.claim)).toEqual([claim, 'another']);
    const reRendered = replaceOrInsertFactsFence(twice, renderFactsTable(parseFactsFence(twice).facts));
    expect(reRendered).toBe(twice);
    const escaped = 'see gbrain\\:facts:begin in a transcript';
    const body = upsertFactRow('', fact(escaped)).body;
    expect(parseFactsFence(body).facts[0]!.claim).toBe(escaped);
  });
});