Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
31.1 KB
Raw Blame
/**
 * GBRA-217 `get_page {as_of}`: the edition of one page in force on a date (valid time), from the frontmatter
 * `valid_from` / `valid_until` of the current page and its retained versions.
 *
 * One statement picks over every row of the resolved page identity, before any visibility check: the greatest
 * `valid_from` on or before the date, the most recently recorded on a tie; with the counts, the gap facts and the
 * ambiguity window the verdict needs (src/core/valid-time.ts). A chosen edition the caller may not see answers as a
 * missing page, never with an older visible edition. Only `in_force` carries text at the top level; any other status
 * puts the edition under `last_in_force` or `earliest_known`. A large edition is read in windows whose cursor pins
 * that edition (`v:<version id>`, or the current page's revision, found again among the versions if the page moved
 * on); an edition that has gone answers `history: incomplete` with no text.
 */
import type { OperationContext, ParamDef } from './contract.ts';
import { opError } from './contract.ts';
import { hostFix, opTransport, readFix } from './op-fix.ts';
import { renderAction, type Action } from '../agent-output.ts';
import { assertExplicitSourceLive, federatedSearchScope, pageNotFoundError, parseSourceIdParam, validatePageSlug } from './context.ts';
import { inlineBodyBytes } from './get-page-body.ts';
import { pageTrustForRead, readQuarantined } from './get-page-projection.ts';
import { admitsTrust, type TrustTier } from '../trust/tier.ts';
import { isCalendarDate } from '../link-validity.ts';
import { replacedBecauseSql } from '../engine-sql/pages.ts';
import { callerReadersAllowedSql, privacyForCaller, privateLinkOriginFilterFragment, privatePagesFilterForCaller, privatePagesFilterFragment, privateSnapshotFilterFragment, remoteReadFloorSql, resolveExcludePrivatePages, worldOnlyFacts } from '../search/private-visibility.ts';
import { fenceTranscriptText, isQuotedPageType, neutralizeToolCalls, quotesStored } from '../search/transcript-quote.ts';
import { quotedPageMeta } from './get-page-projection.ts';
import { sanitizeRemoteBody } from '../remote-body.ts';
import { heldRowsForCaller } from '../eligibility/fence-overlay.ts';
import { serializePageToMarkdown } from '../markdown.ts';
import { pageDocument } from '../page-window/document.ts';
import { DEFAULT_WINDOW_BYTES, MAX_WINDOW_BYTES, decodeCursor, encodeCursor, totalLines, windowFrom, type WindowSlice } from '../page-window/window.ts';
import { openSegmentedBody } from '../page-body/read-range.ts';
import { isSegmentedPage } from '../page-body/page-shape.ts';
import { segmentedReadDocument } from '../page-window/segmented.ts';
import { PAGE_INLINE_MAX_BYTES } from '../page-size-policy.ts';
import { LARGE_PAGE_VERSIONS_KEPT } from '../page-body/limits.ts';
import { validDateSql, validTimeVerdict, type ValidTimeVerdict, type ValidTimeWhy } from '../valid-time.ts';
import type { BrainEngine } from '../engine.ts';
import type { Page } from '../types.ts';

export const AS_OF_PARAM: ParamDef = { type: 'string', description: 'YYYY-MM-DD: edition in force then. No valid_time in reply: current page.' };

/** get_page parameters an as_of read does not serve: an edit view, a fuzzy match, another clock or another body cut. */
const AS_OF_UNSUPPORTED = ['fuzzy', 'include_deleted', 'include_timeline_entries', 'grammar_diagnostics', 'include_quarantined',
  'lines', 'bytes', 'around_chunk_id', 'context_lines', 'view', 'outline_from', 'section', 'grep', 'context'] as const;
const INSTANT = /^[0-9]{4}-[0-9]{2}-[0-9]{2}[T ][0-9]{2}:[0-9]{2}/;
/** Sorts after every page_versions id (a SERIAL int): the current page's place in recorded order. */
const CURRENT_ORD = 2147483648;
const AMENDMENTS_CAP = 20;

interface Identity { id: number; source_id: string; slug: string; source_path: string | null; local_path: string | null; world: boolean }
interface PickRow {
  version_id: number | null; ord: number; replaced_at: string | null; valid_from: string; valid_until: string | null; visible: boolean;
  reason: string | null; successor_pruned: boolean; segmented: boolean; recorded_since: string | null; introduced_because: string | null; chosen: boolean;
  /** GBRA-286 (GST-687): the stored trust tier of this edition and of the write that replaced it (the next row), for the quote fence. */
  tier: string | null; successor_tier: string | null;
}
interface PickResult { row: PickRow | null; competing: number[]; undated: number; largeVersions: number; segmentedVersions: number; anyFiled: boolean; gapAt: string | null; createdAt: string | null }

const iso = (v: unknown): string | null => v == null ? null : new Date(v as string).toISOString();

/** The as_of date: a calendar date; an instant is the other clock (`known_as_of`), refused `clock_mismatch`. */
function parseAsOf(ctx: OperationContext, value: unknown): string {
  if (isCalendarDate(value)) return value;
  if (typeof value === 'string' && INSTANT.test(value.trim())) {
    throw opError('clock_mismatch', `as_of takes a calendar date (YYYY-MM-DD), not the instant ${value.trim().slice(0, 40)}.`,
      'as_of is valid time: the date an edition was in force. For what the brain had recorded at an instant, pass known_as_of instead; for valid time, pass the date alone (2026-07-01).',
      { reason: 'instant_for_date' });
  }
  throw opError('invalid_params', 'get_page: as_of must be a calendar date YYYY-MM-DD.', 'Pass a date such as 2026-07-01.',
    { fix: readFix('Reads the edition in force on that date.', { mcp: { tool: 'get_page', arguments: { slug: 'policies/policy-4a-example', as_of: '2026-07-01' } } }) });
}

function refuseCombinations(ctx: OperationContext, p: Record<string, unknown>): void {
  const slug = String(p.slug);
  if (p.known_as_of !== undefined) {
    throw opError('invalid_params', 'get_page: as_of (valid time) and known_as_of (recorded time) answer different questions; pass one.',
      'Use as_of for the edition in force on a date, or known_as_of for the page as the brain had recorded it at an instant.',
      { fix: readFix('Reads the edition in force on that date.', { mcp: { tool: 'get_page', arguments: { slug, as_of: p.as_of } } }) });
  }
  if (p.include_content === true || p.content_only === true) {
    throw opError('invalid_params', 'get_page: as_of does not combine with include_content or content_only.',
      'An as_of read returns an older edition; writing it back with put_page would silently revert the page. To edit, read the current page with include_content, then edit it; to quote the old edition, read it with as_of alone.',
      { fix: readFix('Reads the current page with its revision, ready to edit.', { mcp: { tool: 'get_page', arguments: { slug, include_content: true } } }) });
  }
  const extra = AS_OF_UNSUPPORTED.filter(k => p[k] !== undefined && p[k] !== false);
  if (extra.length || (p.body !== undefined && p.body !== 'auto' && p.body !== 'full')) {
    throw opError('invalid_params', `get_page: as_of does not combine with ${extra.length ? extra.join(', ') : `body: ${String(p.body)}`}.`,
      'Read the edition with as_of alone (plus source_id, min_trust, or the cursor and max_bytes of its next call).');
  }
}

/** The one page the read is about: a slug in more than one granted source refuses and asks for source_id. */
async function resolveIdentity(tx: BrainEngine, ctx: OperationContext, slug: string, scope: { sourceId?: string; sourceIds?: string[] }, excludePrivate: boolean, asOf: string): Promise<Identity> {
  const rows = await tx.executeRaw<Identity>(`SELECT p.id, p.source_id, p.slug, p.source_path, s.local_path, ${privatePagesFilterFragment('p')} AS world
      FROM pages p JOIN sources s ON s.id = p.source_id
     WHERE p.slug = $1 AND p.deleted_at IS NULL AND ($2::text IS NULL OR p.source_id = $2) AND ($3::text[] IS NULL OR p.source_id = ANY($3::text[]))
       ${excludePrivate ? `AND ${privatePagesFilterForCaller('p')}` : ''}
     ORDER BY p.source_id LIMIT 6`, [slug, scope.sourceId ?? null, scope.sourceIds ?? null]);
  if (rows.length > 1) {
    const sources = rows.map(r => r.source_id);
    throw opError('invalid_params', `get_page: ${slug} exists in several sources (${sources.join(', ')}); an as_of read follows one page's history.`,
      'Pass source_id to name the page.', { fix: readFix(`Reads the page in source ${sources[0]}.`, { mcp: { tool: 'get_page', arguments: { slug, source_id: sources[0], as_of: asOf } } }) });
  }
  if (!rows[0]) throw pageNotFoundError(ctx, slug, { includeDeleted: false, sourceIdParam: scope.sourceId });
  return { ...rows[0], id: Number(rows[0].id), world: rows[0].world === true };
}

const bodyKey = (a: string) => `CASE WHEN ${a}.body_storage = 'segmented' THEN 's:' || COALESCE(${a}.content_hash, '')
  ELSE md5(COALESCE(${a}.compiled_truth, '') || chr(1) || COALESCE(${a}.timeline, '')) END`;

/**
 * The pick: one statement over the current page and its retained versions. With `pinOrd` it measures that row instead
 * (a cursor's edition). The ambiguity window is the rows recorded after the pick with an earlier valid_from, and the
 * pick's recorded neighbours that keep its body under another valid_from.
 */
async function pick(tx: BrainEngine, pageId: number, asOf: string, excludePrivate: boolean, pinOrd: number | null): Promise<PickResult> {
  const vd = (a: string, key: string) => validDateSql(`${a}.frontmatter->>'${key}'`);
  const [r] = await tx.executeRaw<Record<string, unknown>>(`WITH rows AS (
      SELECT pv.id AS version_id, pv.id::bigint AS ord, pv.snapshot_at AS replaced_at, ${vd('pv', 'valid_from')} AS valid_from, ${vd('pv', 'valid_until')} AS valid_until,
             ${bodyKey('pv')} AS body_key, (${callerReadersAllowedSql('pv', 'snapshot')} AND ${privacyForCaller('p', privateSnapshotFilterFragment('pv'))}) AS visible,
             ${replacedBecauseSql('pv', excludePrivate)} AS reason, pv.trust_tier AS tier,
             COALESCE(pv.successor_pruned, false) AS successor_pruned, COALESCE(pv.body_storage = 'segmented', false) AS segmented,
             (pv.body_storage IS DISTINCT FROM 'segmented' AND octet_length(COALESCE(pv.compiled_truth, '')) + octet_length(COALESCE(pv.timeline, '')) > $3) AS large,
             pv.source_path IS NOT NULL AS filed
        FROM page_versions pv JOIN pages p ON p.id = pv.page_id WHERE pv.page_id = $1
      UNION ALL
      SELECT NULL, ${CURRENT_ORD}::bigint, NULL, ${vd('p', 'valid_from')}, ${vd('p', 'valid_until')}, ${bodyKey('p')}, ${privatePagesFilterForCaller('p')}, NULL, p.trust_tier,
             false, COALESCE(p.body_storage = 'segmented', false), false, p.source_path IS NOT NULL
        FROM pages p WHERE p.id = $1),
    seq AS (
      SELECT r.*, lag(r.replaced_at) OVER w AS recorded_since, lag(CASE WHEN NOT r.successor_pruned${excludePrivate ? ' AND r.visible' : ''} THEN r.reason END) OVER w AS introduced_because, lead(r.tier) OVER w AS successor_tier,
             lag(r.ord) OVER w AS prev_ord, lead(r.ord) OVER w AS next_ord
        FROM rows r WINDOW w AS (ORDER BY r.ord)),
    pick AS (
      SELECT s.*, (s.valid_from <= $2::text) AS chosen FROM seq s
       WHERE s.valid_from IS NOT NULL AND ($4::bigint IS NULL OR s.ord = $4::bigint)
       ORDER BY (s.valid_from <= $2::text) DESC, CASE WHEN s.valid_from <= $2::text THEN s.valid_from END DESC,
                CASE WHEN s.valid_from > $2::text THEN s.valid_from END ASC, s.ord DESC
       LIMIT 1)
    SELECT k.version_id, k.ord, k.replaced_at, k.valid_from, k.valid_until, k.visible, k.reason, k.successor_pruned, k.segmented,
           k.recorded_since, k.introduced_because, k.chosen, k.tier, k.successor_tier,
           (SELECT array_agg(c.ord ORDER BY c.ord) FROM (SELECT s.ord FROM seq s
              WHERE s.valid_from IS NOT NULL AND s.ord <> k.ord AND (
                (s.ord > k.ord AND s.valid_from < k.valid_from)
                OR (s.ord IN (k.prev_ord, k.next_ord) AND s.body_key = (SELECT b.body_key FROM seq b WHERE b.ord = k.ord) AND s.valid_from <> k.valid_from))
              ORDER BY s.ord LIMIT 5) c) AS competing,
           (SELECT count(*) FROM seq WHERE valid_from IS NULL) AS undated,
           (SELECT count(*) FROM seq WHERE version_id IS NOT NULL AND large) AS large_versions,
           (SELECT count(*) FROM seq WHERE version_id IS NOT NULL AND segmented) AS segmented_versions,
           (SELECT bool_or(filed) FROM seq) AS any_filed,
           p.version_history_gap_at AS gap_at, p.created_at
      FROM pages p LEFT JOIN pick k ON true WHERE p.id = $1`, [pageId, asOf, PAGE_INLINE_MAX_BYTES, pinOrd]);
  const row: PickRow | null = r && r.ord != null ? {
    version_id: r.version_id == null ? null : Number(r.version_id), ord: Number(r.ord), replaced_at: iso(r.replaced_at), valid_from: String(r.valid_from),
    valid_until: r.valid_until == null ? null : String(r.valid_until), visible: r.visible === true, reason: (r.reason as string | null) ?? null,
    successor_pruned: r.successor_pruned === true, segmented: r.segmented === true, recorded_since: iso(r.recorded_since),
    introduced_because: (r.introduced_because as string | null) ?? null, chosen: r.chosen === true,
    tier: (r.tier as string | null) ?? null, successor_tier: (r.successor_tier as string | null) ?? null,
  } : null;
  return { row, competing: ((r?.competing as unknown[] | null) ?? []).map(Number), undated: Number(r?.undated ?? 0),
    largeVersions: Number(r?.large_versions ?? 0), segmentedVersions: Number(r?.segmented_versions ?? 0), anyFiled: r?.any_filed === true,
    gapAt: iso(r?.gap_at), createdAt: iso(r?.created_at) };
}

function verdictOf(asOf: string, picked: PickResult): ValidTimeVerdict {
  const row = picked.row;
  return validTimeVerdict({
    asOf, undatedVersions: picked.undated, gapAt: picked.gapAt, gbrainWritten: !picked.anyFiled,
    couldHaveBeenPruned: picked.largeVersions >= LARGE_PAGE_VERSIONS_KEPT || picked.segmentedVersions > 0,
    ambiguous: picked.competing.length > 0,
    edition: row ? { chosen: row.chosen, isCurrent: row.version_id === null, validFrom: row.valid_from, validUntil: row.valid_until,
      successorPruned: row.successor_pruned, recordedSince: row.recorded_since, replacedAt: row.replaced_at } : null,
  });
}

/** Amendment records (`amends` links to the page) dated after the edition took effect and on or before the date: as_of does not fold them in. */
async function amendmentsNotApplied(tx: BrainEngine, pageId: number, editionFrom: string, asOf: string, excludePrivate: boolean, scope: { sourceId?: string; sourceIds?: string[] }) {
  const sources = scope.sourceIds ?? (scope.sourceId ? [scope.sourceId] : null);
  const rows = await tx.executeRaw<{ slug: string; source_id: string; since: string | null }>(`SELECT f.slug, f.source_id, min(to_char(r.first_start, 'YYYY-MM-DD')) AS since
      FROM links l JOIN pages f ON f.id = l.from_page_id AND f.deleted_at IS NULL${excludePrivate ? ` AND ${remoteReadFloorSql('f')}` : ''}
      LEFT JOIN link_relationships r ON r.from_page_id = l.from_page_id AND r.to_page_id = l.to_page_id AND r.link_type = l.link_type AND r.scope = $4
     WHERE l.to_page_id = $1 AND l.link_type = 'amends'${excludePrivate ? ` AND ${privateLinkOriginFilterFragment('l')}` : ''}
       AND ($5::text[] IS NULL OR f.source_id = ANY($5::text[]))
       AND (r.first_start IS NULL OR (r.first_start > $2::date AND r.first_start <= $3::date))
     GROUP BY f.slug, f.source_id ORDER BY f.slug LIMIT ${AMENDMENTS_CAP}`, [pageId, editionFrom, asOf, excludePrivate ? 'world' : 'all', sources]).catch(() => []);
  return rows.map(r => ({ slug: r.slug, source_id: r.source_id, since: r.since ?? null }));
}

/** The serialized frontmatter edit that sets valid_from to the `<DATE>` placeholder: the existing line, or a new first key. */
function validFromEdit(page: Page, tags: string[]): { old_text: string; new_text: string } | null {
  const head = serializePageToMarkdown({ slug: page.slug, type: page.type, title: page.title, frontmatter: page.frontmatter, compiled_truth: '', timeline: '' } as Page, tags);
  const close = head.indexOf('\n---', 4);
  const fm = head.slice(0, close < 0 ? head.length : close + 1);
  const line = fm.split('\n').find(l => l.startsWith('valid_from:'));
  if (line) return { old_text: `${line}\n`, new_text: "valid_from: '<DATE>'\n" };
  const first = fm.split('\n')[1];
  return head.startsWith('---\n') && first ? { old_text: `---\n${first}\n`, new_text: `---\nvalid_from: '<DATE>'\n${first}\n` } : null;
}

/** ask_user for the date an edition took effect, then the templated edit_page that records it as valid_from. */
function askDateFix(identity: Identity, page: Page, tags: string[], revision: string, question: string, why: string): Action {
  const edit = validFromEdit(page, tags);
  return {
    ask_user: true, consent: [], actor: 'user', why, user_message: question, requires_exclusive: false,
    ...(edit ? { then: { mcp: { tool: 'edit_page', arguments: { slug: identity.slug, source_id: identity.source_id, expected_revision: revision, edits: [edit],
      reason: 'Record the date this edition took effect.' } },
      inputs: [{ name: 'DATE', how: 'The date the user named, as YYYY-MM-DD (kept quoted in the frontmatter).' }],
      consent: [], actor: 'agent', why: 'Sets valid_from on the current page, so as_of reads pick it on that date.', requires_exclusive: false } } : {}),
  };
}

/**
 * Where the missing editions can be found: a world-visible file in a source with a Git checkout has them in the file's
 * history (run locally; over MCP the user or host operator runs it); otherwise only a retained copy the user holds.
 */
function recoveryFix(ctx: OperationContext, identity: Identity, asOf: string, why: ValidTimeWhy): Action {
  const gitWhy = `gbrain does not hold every edition of ${identity.slug} around ${asOf} (${why}); the file's Git history does. Read the editions there and their valid_from lines.`;
  if (identity.source_path && identity.world && identity.local_path) {
    if (ctx.remote === false && identity.local_path) {
      return { argv: ['git', '-C', identity.local_path, 'log', '--follow', '-p', '--', identity.source_path], consent: [], actor: 'agent', why: gitWhy, requires_exclusive: false };
    }
    return { ...hostFix(ctx, ['git', 'log', '--follow', '-p', '--', identity.source_path], gitWhy,
      { user_message: `gbrain no longer holds every edition of ${identity.slug} around ${asOf}. In the Git checkout of source ${identity.source_id}, run the command shown and share the editions it prints.` }),
      ...(ctx.remote === false ? {} : { actor: 'user' as const }) };
  }
  return { ask_user: true, consent: [], actor: 'user', requires_exclusive: false,
    why: `gbrain does not hold every edition of ${identity.slug} around ${asOf} (${why}), and the page has no file whose history could fill the gap. Do not retry this read unchanged: the answer will not change.`,
    user_message: `gbrain does not hold every edition of ${identity.slug} around ${asOf}. Do you have a retained copy or a backup of the page from then?` };
}

interface Edition { versionId: number | null; title: string; type: string; tags: string[]; frontmatter: Record<string, unknown>; compiled_truth: string; timeline: string; revision: string; segmented: boolean; generation?: number }

async function loadEdition(tx: BrainEngine, identity: Identity, row: PickRow): Promise<{ edition: Edition; current: { page: Page; tags: string[]; revision: string } } | null> {
  const snap = await tx.readPageSnapshot(identity.slug, { sourceId: identity.source_id });
  if (!snap) return null;
  const current = { page: snap.page, tags: snap.tags, revision: snap.revision };
  if (row.version_id === null) {
    const p = snap.page, segmented = isSegmentedPage(p);
    return { current, edition: { versionId: null, title: p.title, type: p.type, tags: snap.tags, frontmatter: (p.frontmatter ?? {}) as Record<string, unknown>,
      compiled_truth: segmented ? '' : p.compiled_truth ?? '', timeline: segmented ? '' : p.timeline ?? '', revision: snap.revision, segmented, generation: snap.bodyGeneration } };
  }
  const [v] = await tx.executeRaw<Record<string, unknown>>(`SELECT id, title, type, tags, frontmatter, compiled_truth, timeline, knowledge_revision::text AS revision,
      body_storage, body_generation FROM page_versions WHERE id = $1 AND page_id = $2`, [row.version_id, identity.id]);
  if (!v) return null;
  const tags = Array.isArray(v.tags) ? v.tags.map(String) : typeof v.tags === 'string' ? JSON.parse(v.tags) as string[] : [];
  const fm = (typeof v.frontmatter === 'string' ? JSON.parse(v.frontmatter) : v.frontmatter ?? {}) as Record<string, unknown>;
  return { current, edition: { versionId: Number(v.id), title: String(v.title ?? identity.slug), type: String(v.type ?? ''), tags, frontmatter: fm,
    compiled_truth: String(v.compiled_truth ?? ''), timeline: String(v.timeline ?? ''), revision: String(v.revision ?? ''),
    segmented: v.body_storage === 'segmented', ...(v.body_generation != null ? { generation: Number(v.body_generation) } : {}) } };
}

/**
 * The edition as the caller may read it: whole, or one window (with the next call pinned to it) when it is large or segmented.
 * GBRA-286 (#8042, GST-687): with `quote` (a remote reader, and an edition below the owner's tier or of a third-party
 * type) its text and metadata are fenced as quoted source material, a third-party edition's tool-call blocks summarized,
 * as get_page quotes the current page.
 */
async function editionView(ctx: OperationContext, identity: Identity, e: Edition, asOf: string, offset: number | null, maxBytes: number, quote: boolean): Promise<Record<string, unknown> | 'gone'> {
  const neutralize = quote && ctx.thinClient !== true && isQuotedPageType(e.type);
  const omitRows = e.segmented ? undefined : await heldRowsForCaller(ctx.engine, ctx.remote, { sourceId: identity.source_id, slug: identity.slug, compiled_truth: e.compiled_truth, timeline: e.timeline });
  const clean = (s: string) => {
    if (ctx.remote === false) return s;
    const safe = sanitizeRemoteBody(s, { includeWithdrawn: true, keepMaterializedMarkers: true, omitRows });
    return neutralize ? neutralizeToolCalls(safe) : safe;
  };
  const fence = (s: string) => quote && s ? fenceTranscriptText(s, identity.slug) : s;
  const { title, frontmatter, tags } = quotedPageMeta({ slug: identity.slug, title: e.title, frontmatter: e.frontmatter }, quote, e.tags);
  const meta = { ...(e.versionId === null ? { revision: e.revision } : { version_id: e.versionId }), title, type: e.type, tags, frontmatter, ...(quote ? { quoted: 'transcript' } : {}) };
  const truth = e.segmented ? '' : clean(e.compiled_truth), timeline = e.segmented ? '' : clean(e.timeline);
  const bytes = Buffer.byteLength(truth, 'utf8') + Buffer.byteLength(timeline, 'utf8');
  if (!e.segmented && offset === null && (ctx.remote === false || bytes <= await inlineBodyBytes(ctx))) return { ...meta, compiled_truth: fence(truth), timeline: fence(timeline) };
  let total: number, slice: WindowSlice, lines: number | undefined;
  if (e.segmented) {
    try {
      const body = await openSegmentedBody(ctx.engine, { pageId: identity.id, ...(e.generation !== undefined ? { generation: e.generation } : {}), hideHeld: worldOnlyFacts(ctx.remote) });
      const seg = await segmentedReadDocument(ctx.engine, body);
      total = seg.total;
      slice = await seg.from(offset ?? 0, maxBytes);
    } catch { return 'gone'; }
  } else {
    const doc = pageDocument({ compiled_truth: truth, timeline });
    total = doc.bytes.length; lines = totalLines(doc.bytes);
    slice = windowFrom(doc.bytes, offset ?? 0, maxBytes);
  }
  const text = fence(e.segmented && neutralize ? neutralizeToolCalls(slice.text) : slice.text);
  const out: Record<string, unknown> = { ...meta, body: 'window', size: { total_bytes: total, ...(lines !== undefined ? { total_lines: lines } : {}) },
    window: text === slice.text ? slice : { ...slice, text }, truncated: slice.byte_start > 0 || slice.byte_end < total };
  if (slice.byte_end < total) {
    const cursor = encodeCursor({ page_id: identity.id, revision: e.versionId === null ? e.revision : `v:${e.versionId}`, view: 'read', offset: slice.byte_end, max_bytes: maxBytes });
    out.next_cursor = cursor;
    out.next = { tool: 'get_page', arguments: { slug: identity.slug, source_id: identity.source_id, as_of: asOf, cursor } };
  }
  return out;
}

/** A cursor's pinned edition as a recorded-order position: its version, or the current page while it is still at the cursor's revision. */
async function pinnedOrd(tx: BrainEngine, ctx: OperationContext, identity: Identity, raw: unknown): Promise<{ ord: number | null; offset: number; maxBytes: number }> {
  const c = typeof raw === 'string' ? decodeCursor(raw) : null;
  if (!c || c.page_id !== identity.id || c.view !== 'read') {
    throw opError('invalid_params', `get_page: cursor is not an as_of window cursor for page ${identity.slug}.`, 'Pass the next_cursor of the previous as_of read, with the same slug, source_id and as_of.');
  }
  if (c.revision.startsWith('v:')) return { ord: Number(c.revision.slice(2)), offset: c.offset, maxBytes: c.max_bytes };
  const [row] = await tx.executeRaw<{ current: boolean; version_id: number | null }>(`SELECT (p.knowledge_revision::text = $2) AS current,
      (SELECT max(v.id) FROM page_versions v WHERE v.page_id = p.id AND v.knowledge_revision::text = $2) AS version_id FROM pages p WHERE p.id = $1`, [identity.id, c.revision]);
  const ord = row?.current === true ? CURRENT_ORD : row?.version_id != null ? Number(row.version_id) : -1;
  return { ord, offset: c.offset, maxBytes: c.max_bytes };
}

/** `get_page {as_of}`: the edition in force on the date, with the valid_time block that says how sure the answer is. */
export async function getPageAsOf(ctx: OperationContext, p: Record<string, unknown>): Promise<Record<string, unknown>> {
  refuseCombinations(ctx, p);
  const asOf = parseAsOf(ctx, p.as_of);
  const slug = String(p.slug);
  validatePageSlug(slug);
  const sourceIdParam = parseSourceIdParam(p.source_id, 'get_page', { allowAll: true });
  const scope = federatedSearchScope(ctx, sourceIdParam);
  await assertExplicitSourceLive(ctx, sourceIdParam);
  const excludePrivate = await resolveExcludePrivatePages(ctx.engine, ctx.remote);
  const read = await ctx.engine.transaction(async tx => {
    await tx.executeRaw('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ');
    const identity = await resolveIdentity(tx, ctx, slug, scope, excludePrivate, asOf);
    const pin = p.cursor !== undefined ? await pinnedOrd(tx, ctx, identity, p.cursor) : null;
    let picked = await pick(tx, identity.id, asOf, excludePrivate, pin?.ord ?? null);
    const pinGone = pin !== null && !picked.row;
    if (pinGone) picked = await pick(tx, identity.id, asOf, excludePrivate, null);
    const loaded = picked.row ? await loadEdition(tx, identity, picked.row) : null;
    const amendments = picked.row?.chosen ? await amendmentsNotApplied(tx, identity.id, picked.row.valid_from, asOf, excludePrivate, scope) : [];
    return { identity, pin, picked, pinGone, loaded, amendments };
  });
  const { identity, pin, picked, loaded, amendments } = read;
  const row = picked.row;
  const missing = () => pageNotFoundError(ctx, slug, { includeDeleted: false, sourceIdParam });
  const admitted = await pageTrustForRead(ctx, { id: identity.id }, p.min_trust);
  if (!admitted) throw missing();
  const floor = admitted.eligibility.floor;
  if (floor && row && !admitsTrust((row.tier ?? 'unknown') as TrustTier, floor)) throw missing();
  if (!row) {
    const snap = await ctx.engine.readPageSnapshot(identity.slug, { sourceId: identity.source_id });
    if (!snap) throw missing();
    throw opError('valid_time_undeclared', `${identity.slug} declares no valid_from in any retained version, so no edition can be placed on ${asOf}.`,
      'Ask the user when this text took effect and record it as valid_from; never invent a date. For what the brain had recorded at a time, read with known_as_of instead.',
      { fix: askDateFix(identity, snap.page, snap.tags, snap.revision, `When did the current text of ${identity.slug} take effect? (a date, YYYY-MM-DD)`,
        'An as_of read needs a valid_from date on the page; only the user knows when this text took effect.') });
  }
  if (excludePrivate && !row.visible) throw missing();
  if (!loaded) throw missing();
  // #6259: a quarantined page (now, or in the chosen edition) keeps its body from a remote reader, as the plain read does.
  const quarantined = readQuarantined(ctx, loaded.current.page, false)
    ?? readQuarantined(ctx, { slug: identity.slug, source_id: identity.source_id, frontmatter: loaded.edition.frontmatter }, false);
  const verdict = verdictOf(asOf, picked);
  let { history, uncertain, why } = verdict;
  let view: Record<string, unknown> | 'gone' | null = null;
  const requested = typeof p.max_bytes === 'number' && Number.isSafeInteger(p.max_bytes) && p.max_bytes > 0 ? p.max_bytes : pin?.maxBytes ?? DEFAULT_WINDOW_BYTES;
  const quotes = (tier: string | null) => ctx.remote !== false && quotesStored(loaded.edition.type, tier);
  if (!read.pinGone && quarantined?.body_omitted !== true) view = await editionView(ctx, identity, loaded.edition, asOf, pin ? pin.offset : null, ctx.remote === false ? requested : Math.min(requested, MAX_WINDOW_BYTES), quotes(row.tier));
  if (read.pinGone || view === 'gone') { history = 'incomplete'; uncertain = true; why = 'edition_pruned'; view = null; }
  const reason = (s: string | null, tier: string | null) => {
    if (s === null || ctx.remote === false) return s;
    const clean = sanitizeRemoteBody(s);
    return quotes(tier) && clean ? fenceTranscriptText(clean, identity.slug) : clean;
  };
  const chosen = row.chosen;
  const validTime = {
    as_of: asOf, status: verdict.status,
    chosen_version_id: chosen ? row.version_id : null, chosen_is_current: chosen && row.version_id === null,
    valid_from: chosen ? row.valid_from : null, valid_until: chosen ? row.valid_until : null,
    introduced_because: chosen ? reason(row.introduced_because, row.tier) : null, replaced_because: chosen ? reason(row.reason, row.successor_tier) : null,
    history, uncertain, why, undated_versions: picked.undated, amendments_not_applied: amendments,
    recorded_since: chosen ? row.recorded_since ?? (picked.gapAt === null ? picked.createdAt : null) : null,
    ...(why === 'ambiguous_edition_dates' ? { competing_version_ids: picked.competing.map(o => o === CURRENT_ORD ? null : o) } : {}),
    ...(!chosen ? { earliest_known_valid_from: row.valid_from } : {}),
  };
  let fix: Action | undefined;
  if (why === 'ambiguous_edition_dates') {
    fix = askDateFix(identity, loaded.current.page, loaded.current.tags, loaded.current.revision,
      `Which date did this edition of ${identity.slug} take effect? Its recorded dates disagree (versions ${validTime.competing_version_ids?.map(v => v ?? 'current').join(', ')}).`,
      'A date correction, a renewal, a backfill and a withdrawn scheduled edition look alike in the page history; only the user can say which happened.');
  } else if (why !== null && why !== 'undated_editions') fix = recoveryFix(ctx, identity, asOf, why);
  const render = { transport: opTransport(ctx), isCallable: () => ctx.remote !== false, preapproved: () => false };
  const base = { slug: identity.slug, source_id: identity.source_id, valid_time: validTime, ...(quarantined ? { quarantined } : {}), ...(fix ? { fix: renderAction(fix, render) } : {}) };
  if (!view) return base;
  if (verdict.status === 'in_force') return { ...view, ...base };
  return { ...base, [chosen ? 'last_in_force' : 'earliest_known']: { ...view, valid_from: row.valid_from, valid_until: row.valid_until } };
}