Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
80.7 KB
Raw Blame
/**
 * #4352 — page-level `visibility: private` enforcement for untrusted callers.
 *
 * Pages have carried `frontmatter.visibility` for a long time (the `remember`
 * verb documents "private: local CLI reads only"), but nothing on the READ
 * side ever enforced it for pages: a remote/MCP caller could retrieve a
 * `visibility: private` page through search, recall's query arm, entity
 * cards, context_pack — and the sibling read ops (get_page/fetch/list_pages,
 * get_chunks/get_versions/get_timeline/get_raw_data, resolve_slugs,
 * get_links/get_backlinks/traverse_graph). This module is the single
 * trust+config resolver:
 *
 *   ctx.remote === false          → see everything (trusted local CLI)
 *   GBRAIN_REMOTE_PRIVATE_PAGES=1 → operator escape hatch, see everything
 *   config search.remote_private_pages ∈ {visible,true,1}
 *                                 → operator opt-out, see everything
 *   otherwise                     → exclude private pages (FAIL-CLOSED default)
 *
 * The SQL predicate itself lives in buildVisibilityClause (sql-ranking.ts)
 * behind SearchOpts.excludePrivate; this resolver decides whether to set it.
 */

import { AsyncLocalStorage } from 'node:async_hooks';
import type { BrainEngine } from '../engine.ts';
import { embeddedKey, embeddedKeyInScope, engineScopeStore, unscopedWithOpenEmbeddedEngines } from '../engine-scope-store.ts';
import { schemaVersionSeen } from '../migrate-pending.ts';
import { requestConfigRows } from '../config-snapshot.ts';
import { isValidSourceId } from '../source-id.ts';
import { asciiLower, asciiLowerSql, edgeTrimSql } from '../edge-whitespace.ts';
import { ACCESS_ID_RE, hasReaders, MEMBER_PAGE_PREFIX, normalizePrincipal, readersAllow, validIdentity } from '../access/principals.ts';
import { ruleCoversSql, validPrefix, validQualifiedRuleId } from '../access/folder-rules.ts';
import { holdingSlugSql } from '../facts-fence.ts';
import { NAME_KEY_PAGE_DIRS } from '../entities/basename-dirs.ts';
import { atomMovedOriginPrivateSql, atomOriginSlugsSql } from '../persistence/atom-origin.ts';
import { ownerOnlyFactSql, ownerOnlyForm, ownerOnlyPageSql, ownerOnlySourcesPresent } from '../access/owner-only.ts';

export const REMOTE_PRIVATE_PAGES_KEY = 'search.remote_private_pages';

/**
 * GST-2059: the member who owns this brain (`gbrain access owner set <member>`). A remote credential or stdio server
 * bound to that live member reads as the owner: its privacy is relaxed in every source its grant reads (CallerAccess.owner).
 * Written only by the trusted local CLI, like mcp.stdio_member; unset, ill-formed or unreadable names no owner.
 */
export const OWNER_MEMBER_KEY = 'access.owner_member';

/**
 * GST-2490 (G6 of GST-2476): the owner opt-in. Set to '1' only by the trusted local operator (`gbrain access owner
 * reads-restricted on`); with it on, a read by a credential bound to the owner (CallerAccess.ownerReadsRestricted) reads
 * pages a readers list, folder rule or page rule would close to the owner, and their derived pages and facts, except
 * another member's own member page (memory/members/<id>) and anything derived from it. Off or unset changes nothing.
 */
export const OWNER_READS_RESTRICTED_KEY = 'access.owner_reads_restricted';

/**
 * GBRA-108 design 3: listed members read lineage. Set to '1' only by the trusted local operator (`gbrain access
 * members-read-lineage on`, access/lineage.ts); with it on, a read by a credential bound to one member speaking for itself (or for an audience of that
 * one member) passes a derived page or fact when that member reads every origin of it, as an owner read does
 * (CallerAccess.lineage). Never an audience of several, an unbound credential or an attested call. Off or unset
 * changes nothing.
 */
export const MEMBERS_READ_LINEAGE_KEY = 'access.members_read_lineage';

/**
 * #5525 — extracted atoms and synthesized concept pages are derived from
 * other pages or from private transcripts, so a missing `visibility` field on
 * them means "origin unknown", not "world". Pinned-question pages (`type:
 * question`) are owner-private. They fail closed; every other page keeps the
 * documented default (absent visibility is world).
 */
function derivedPageSql(pageAlias: string): string {
  return `(${pageAlias}.type IN ('atom', 'question') OR (${pageAlias}.type = 'concept' AND ${pageAlias}.frontmatter->>'synthesized_by' IS NOT NULL))`;
}

/**
 * Raw SQL predicate hiding `visibility: private` pages (absent visibility
 * defaults to 'world', except on derived atoms and concepts where it defaults
 * to 'private'). Single source of truth for the fragment — consumed by
 * buildVisibilityClause (search paths), both engines' listPages, the
 * relational-arm hydrate, and get_page's fuzzy-candidate filter. `pageAlias`
 * is a code-provided literal, never user input.
 */
export function privatePagesFilterFragment(pageAlias: string, derived = false): string {
  return `(${accessAllowedSql(pageAlias, [], [], derived)} AND ${privacyPartSql(pageAlias)})`;
}

/**
 * The privacy rules alone (visibility, aliases, pinned questions, lineage): what the escape hatches and granted_sources may relax.
 * `shadowedPages`: the statement shadows `pages` with a CTE (a postimage, repair/private-labels.ts), which a SQL
 * function body never reads, so the concept-input test runs inline over the shadow.
 */
export function privacyPartSql(pageAlias: string, shadowedPages = false): string {
  return `(${privateSnapshotFilterFragment(pageAlias)}
    AND NOT ${derivedOriginPrivateSql(pageAlias, shadowedPages)}
    AND NOT ${declaredLineagePrivateSql(pageAlias)})`;
}

/**
 * GBRA-218: the mandatory member-access predicate. A page that names readers
 * in frontmatter `readable_by` passes only for a caller whose identity
 * (`member:<id>` and its `group:<g>` entries) meets them, through the one SQL
 * normalization gbrain_access_readers() (malformed values read as nobody). A
 * page derived from a page that names readers is readable by no remote caller
 * (originAllowedSql). No escape hatch, operator opt-out or granted source
 * relaxes this part; with an empty identity it hides every restricted page.
 * `identity` must pass validIdentity (its alphabet has no quote), so it is
 * embedded as literals; anything else empties it (fail closed).
 */
export function accessAllowedSql(pageAlias: string, identity: readonly string[], satisfied: readonly string[] = satisfiedFor(identity), derived = false): string {
  return accessAllowedForAllSql(pageAlias, [identity], satisfied, derived);
}

/**
 * GBRA-231 (shared agents): accessAllowedSql for an audience. A page passes only when every identity in
 * `identities` meets its readers (one conjunct each; a guest's empty identity meets no readers), and its folder rules
 * are all in `satisfied` (for an audience, the intersection of every entry's satisfied set). `derived` tests a page as
 * the origin of what was derived from it (a fact's provenance page): raw-only rules (covers_derived false) do not count.
 */
export function accessAllowedForAllSql(pageAlias: string, identities: readonly (readonly string[])[], satisfied: readonly string[], derived = false): string {
  const ownerOnly = ownerOnlyAllowedSql(pageAlias, currentCallerAccess());
  if (!currentCallerAccess().restricted) return `(${pageAlias}.page_readers IS NULL AND ${pageAlias}.folder_rule_ids IS NULL${ownerOnly})`;
  const readers = (identities.length ? identities : [[]]).map(identity => readersAllowedSql(pageAlias, identity)).join(' AND ');
  return `(${readers} AND ${folderRulesAllowedSql(pageAlias, satisfied, derived)} AND ${originAllowedSql(pageAlias)}${ownerOnly})`;
}

/**
 * Owner-only sources (access/owner-only.ts): a page in one, or derived from one, passes only for an owner read
 * (CallerAccess.owner, never an audience of others or an attested call). Part of the member-access predicate, so no
 * grant, hatch, lineage setting or owner opt-in relaxes it; empty for the owner.
 */
function ownerOnlyAllowedSql(pageAlias: string, access: Pick<CallerAccess, 'owner'>): string {
  return access.owner ? '' : ` AND NOT ${ownerOnlyPageSql(pageAlias, ownerOnlyForm(readSchemaVersion()))}`;
}

/**
 * GBRA-218 (PR A2): the folder layer. `folder_rule_ids` holds the source-qualified ids
 * of every applied folder rule whose prefix the slug starts with (a trigger stamps it from the applied rulebook,
 * migration v283); a page passes only when the caller satisfies all of them (`<@`, set semantics), so nested member
 * and group rules both have to pass. `satisfied` is the caller's satisfied set (CallerAccess.satisfiedRuleIds); an
 * entry that is not a valid qualified id empties it (fail closed). Prefixes under a narrowing still being stamped,
 * or touched by a policy file that does not validate, read as nobody (CallerAccess.folderCoverage). Column tests
 * lead, so a page under no rule costs one NULL test. With `derived` (a fact judged by its provenance page), only the
 * rules that cover derived pages count (gbrain_access_lineage_rules, v305): a raw-only rule keeps its pages, not what
 * was derived from them.
 */
export function folderRulesAllowedSql(alias: string, satisfied: readonly string[], derived = false): string {
  const ids = satisfied.length && satisfied.every(validQualifiedRuleId) ? [...new Set(satisfied)].sort() : [];
  const array = ids.length ? `ARRAY[${ids.map(id => `'${id}'`).join(', ')}]::text[]` : 'ARRAY[]::text[]';
  const listed = ids.length ? ` OR ${alias}.folder_rule_ids <@ ${array}` : '';
  const lineage = derived ? ` OR COALESCE(gbrain_access_lineage_rules(${alias}.source_id, ${alias}.folder_rule_ids) <@ ${array}, true)` : '';
  return `(${alias}.folder_rule_ids IS NULL${listed}${lineage})${coverageSql(alias)}`;
}

/**
 * The pending or invalid prefixes of the current record as a conjunct (empty when none); an ill-formed entry hides
 * everything. Outside any caller record the prefixes are read live, so a page under a pending prefix stays hidden;
 * a database role that row-level security keeps from reading them reads every page as covered.
 */
function coverageSql(alias: string): string {
  if (!callerAccessStore.getStore()) return ` AND NOT EXISTS (SELECT 1 FROM access_pending_coverage pc WHERE pc.source_id = ${alias}.source_id AND ${ruleCoversSql(`${alias}.slug`, 'pc.prefix')}) AND NOT (SELECT gbrain_access_state_unreadable())`;
  const coverage = currentCallerAccess().folderCoverage;
  if (!coverage.length) return '';
  return coverage.map(c => !isValidSourceId(c.source_id) || (c.prefix !== '' && !validPrefix(c.prefix)) ? ' AND FALSE'
    : c.prefix === '' ? ` AND ${alias}.source_id <> '${c.source_id}'`
    : ` AND NOT (${alias}.source_id = '${c.source_id}' AND ${ruleCoversSql(`${alias}.slug`, `'${c.prefix}'`)})`).join('');
}

/** The satisfied rule ids for `identity`: the current record's set when it is the record's identity, else none. */
function satisfiedFor(identity: readonly string[]): readonly string[] {
  const access = currentCallerAccess();
  if (!identity.length || identity.length !== access.identity.length) return [];
  const sorted = [...identity].sort();
  return sorted.every((p, i) => p === access.identity[i]) ? access.satisfiedRuleIds : [];
}

/**
 * The readers test alone, without lineage. On a pages row it reads the
 * derived `page_readers` column (a trigger keeps it equal to
 * gbrain_access_readers(frontmatter)); a row that names readers but has no
 * derived value yet (written before the migration, not yet repaired by
 * `gbrain repair access`) reads as nobody. `row: 'snapshot'` evaluates a
 * version snapshot's own frontmatter directly (bounded to one page's versions).
 */
export function readersAllowedSql(alias: string, identity: readonly string[], row: 'page' | 'snapshot' = 'page'): string {
  const ids = identity.length && validIdentity(identity) ? identity : [];
  const readers = row === 'page' ? `${alias}.page_readers` : `gbrain_access_readers(${alias}.frontmatter)`;
  const listed = ids.length ? ` OR ${readers} && ARRAY[${ids.map(id => `'${id}'`).join(', ')}]::text[]` : '';
  const none = row === 'page' ? `(${alias}.page_readers IS NULL AND NOT (${alias}.frontmatter ? 'readable_by'))` : `NOT (${alias}.frontmatter ? 'readable_by')`;
  return `(${none}${listed})`;
}

/** A page names readers (valid or not); SQL twin of hasReaders. */
function namesReadersSql(alias: string): string {
  return `(${alias}.frontmatter ? 'readable_by')`;
}

/**
 * GBRA-218 (plan D4): a derived page whose origin names readers is readable
 * by no remote caller, members included, whatever its own fields say: an atom
 * of such a page, a synthesized concept with such an input (or an input
 * atom's origin), a Life Chronicle event extracted from one, or a page whose
 * declared `derived_from` names one. Read-time, so derivatives written before
 * the origin gained readers are covered; new derivations are stamped private
 * by isDerivationPrivate. The lineage test lives in the SQL function
 * gbrain_access_origin_restricted (migration v282) behind a cheap type and
 * key guard, so a read plans one function call instead of four subplans. Both
 * parts lead with column tests (page_readers IS NULL, type) so the planner's
 * row estimate follows column statistics instead of a default guess.
 */
function originAllowedSql(p: string): string {
  return `((${p}.type NOT IN ('atom', 'question', 'concept', 'event') AND NOT (${p}.frontmatter ? 'derived_from'))
    OR NOT gbrain_access_origin_restricted(${p}.id, ${p}.source_id, ${p}.type, ${p}.frontmatter))`;
}

/**
 * GST-2490 / GBRA-108 design 3: the reader's own member page for a lineage read (CallerAccess.lineage: an owner read,
 * or a listed member's read under access.members_read_lineage), else null.
 */
function lineageReadPage(access: CallerAccess): string | null {
  if (!access.lineage) return null;
  const member = access.identity.find(p => p.startsWith('member:'))?.slice('member:'.length);
  return member && ACCESS_ID_RE.test(member) ? `${MEMBER_PAGE_PREFIX}${member}` : null;
}

/** GST-2490: the owner's own member page for an owner read under the opt-in (access.owner_reads_restricted), else null. */
function ownerOptInPage(access: CallerAccess): string | null {
  return access.ownerReadsRestricted ? lineageReadPage(access) : null;
}

/** GBRA-108 design 2: the member pages of the audience members an owner read treats as naming the owner; none for any other read. */
function audiencePages(access: CallerAccess): string[] {
  return access.owner && access.lineage ? access.audienceKindMembers.filter(id => ACCESS_ID_RE.test(id)).map(id => `${MEMBER_PAGE_PREFIX}${id}`) : [];
}

/** GBRA-108 design 2: `alias` is an audience member's own member page (FALSE when there is none). */
function audiencePageSql(alias: string, pages: readonly string[]): string {
  return pages.length ? `${alias}.slug IN (${pages.map(p => `'${p}'`).join(', ')})` : 'FALSE';
}

/** GST-2490: `alias` is not another member's own member page (the reader's own one, and GBRA-108 an audience member's for the owner, pass). */
function notOtherMemberPageSql(alias: string, ownPage: string, audience: readonly string[] = []): string {
  return `(NOT starts_with(${alias}.slug, '${MEMBER_PAGE_PREFIX}') OR ${alias}.slug = '${ownPage}'${audience.length ? ` OR ${audiencePageSql(alias, audience)}` : ''})`;
}

const textArraySql = (values: readonly string[]): string => values.length ? `ARRAY[${values.map(v => `'${v}'`).join(', ')}]::text[]` : 'ARRAY[]::text[]';

/**
 * GST-2490: originAllowedSql for a lineage read. A derived page passes when the reader reads every origin of it
 * (gbrain_access_origin_hidden_for with the reader's identity and satisfied rules, v304/v305), so a page whose readers or
 * rule name the reader keeps its derivatives for it; under the owner opt-in every origin passes except another member's
 * own member page and pending coverage. GBRA-108: an owner read passes audience members' pages as origins naming the
 * owner. The identity, rule ids and member ids are validated on the record, so they embed as literals.
 */
function lineageOriginAllowedSql(p: string, access: CallerAccess, ownPage: string): string {
  const identity = validIdentity(access.identity) ? access.identity : [];
  const satisfied = access.satisfiedRuleIds.every(validQualifiedRuleId) ? access.satisfiedRuleIds : [];
  return `((${p}.type NOT IN ('atom', 'question', 'concept', 'event') AND NOT (${p}.frontmatter ? 'derived_from'))
    OR NOT gbrain_access_origin_hidden_for(${p}.id, ${p}.source_id, ${p}.type, ${p}.frontmatter, ${textArraySql(identity)}, ${textArraySql(satisfied)}, ${access.ownerReadsRestricted}, '${ownPage}', ${textArraySql(audiencePages(access))}))`;
}

/**
 * GST-2490: the member-access part for a lineage read: the reader's readers and folder rules as for any member, with
 * its lineage (lineageOriginAllowedSql) instead of the every-caller one. Under the owner opt-in, a page that is not
 * another member's own member page passes too, outside a prefix that reads as nobody. GBRA-108 design 2: for an owner
 * read an audience member's own member page reads as if its readers named the owner. `derived` judges the page as an
 * origin (a fact's provenance page; raw-only rules do not count).
 */
function lineageAccessSql(pageAlias: string, access: CallerAccess, ownPage: string, derived = false): string {
  const audience = audiencePages(access);
  const notOther = notOtherMemberPageSql(pageAlias, ownPage, audience);
  const ownerOnly = ownerOnlyAllowedSql(pageAlias, access);
  if (!access.restricted) {
    const unrestricted = `(${pageAlias}.page_readers IS NULL AND ${pageAlias}.folder_rule_ids IS NULL)`;
    return `(${access.ownerReadsRestricted ? `(${unrestricted} OR ${notOther})` : unrestricted}${ownerOnly})`;
  }
  const readers = audience.length ? `(${readersAllowedSql(pageAlias, access.identity)} OR ${audiencePageSql(pageAlias, audience)})` : readersAllowedSql(pageAlias, access.identity);
  const listed = `(${readers} AND ${folderRulesAllowedSql(pageAlias, access.satisfiedRuleIds, derived)})`;
  const page = access.ownerReadsRestricted ? `(${listed} OR (${notOther}${coverageSql(pageAlias)}))` : listed;
  return `(${page} AND ${lineageOriginAllowedSql(pageAlias, access, ownPage)}${ownerOnly})`;
}

/**
 * GST-2346: GST-2490's owner read rule (lineageAccessSql, the opt-in off) and the privacy part, for the owner's explicit
 * identity and satisfied folder rules outside its read record, so a stored write can judge what its owner writer reads.
 * access.owner_reads_restricted and audience members never apply here: a page kept to other members stays closed.
 */
export function ownerReadPolicyFragment(pageAlias: string, identity: readonly string[], satisfied: readonly string[]): string {
  const access: CallerAccess = { ...currentCallerAccess(), identity, satisfiedRuleIds: satisfied, owner: true, lineage: true, ownerReadsRestricted: false, audienceKindMembers: [], restricted: true };
  const ownPage = lineageReadPage(access);
  return ownPage ? `(${lineageAccessSql(pageAlias, access, ownPage)} AND ${privacyPartSql(pageAlias)})` : 'FALSE';
}

/**
 * `privatePagesFilterFragment` with a cheap first test: a page with no
 * `visibility` or `derived_from` key (nor, unless the operator turned
 * `visibility.honor_aliases` off, a privacy-alias key, nor `readable_by` or `pinned_question`) whose type is not atom, concept,
 * event or question is visible by every rule
 * above, so only the remaining pages run the full check. For scans over thousands of
 * candidate pages (an entity's referrers).
 */
export function privatePagesFilterFragmentFast(pageAlias: string): string {
  return `(${folderRulesAllowedSql(pageAlias, [])} AND ((${pageAlias}.frontmatter->'visibility' IS NULL AND ${pageAlias}.frontmatter->'derived_from' IS NULL${honorAliases()
      ? `\n      AND ${pageAlias}.frontmatter->'access' IS NULL AND ${pageAlias}.frontmatter->'confidentiality' IS NULL` : ''}
      AND ${pageAlias}.frontmatter->'readable_by' IS NULL AND ${pageAlias}.frontmatter->'pinned_question' IS NULL
      AND ${pageAlias}.type NOT IN ('atom', 'concept', 'event', 'question'))
    OR ${privatePagesFilterFragment(pageAlias)}))`;
}

/**
 * The current caller's access record. MCP dispatch sets it around every remote
 * operation (src/mcp/dispatch.ts), and a local `--as <member>` read sets it
 * with applyRemoteReadPolicy. Fields:
 *  - identity: GBRA-218, the caller's member and group principals (empty when
 *    the credential is bound to no member);
 *  - privateReadableSources: GBRA-156, the sources whose private pages the read
 *    may see, from its grant's `private_pages: granted_sources` axis (never the
 *    no-grant floor, federation, an OAuth client's bound source or a request's
 *    `source_ids`); empty for writes;
 *  - privateFactSources: GBRA-575, the sources whose private facts the read may
 *    see, from its grant's `private_facts: granted_sources` axis, on the same
 *    terms as privateReadableSources; empty for writes, audiences, attested
 *    actors and scope reads (privateFactSources());
 *  - hidePrivate: false only when an operator relaxed privacy for remote reads
 *    (GBRAIN_REMOTE_PRIVATE_PAGES=1 or search.remote_private_pages=visible),
 *    or the caller is the brain owner (owner);
 *  - owner: GST-2059, the caller's credential (or stdio server) is bound to the
 *    live member config access.owner_member names, and it asserts no audience
 *    other than that member; never an attested actor. The owner sees
 *    visibility: private pages, privacy aliases, derived and pinned-question
 *    pages and private facts in every source its grant reads; member access
 *    (readable_by, folder rules) stays mandatory;
 *  - restricted: false only inside a remote request on a brain whose config
 *    access.restrictions_present was unset when the request began. Then no
 *    page named readers at that moment and none predates the migration (v282
 *    sets the flag when one does), so every readers value is in the derived
 *    column: accessAllowedSql tests only page_readers IS NULL and
 *    folder_rule_ids IS NULL (live, so a page gaining readers or a folder rule
 *    mid-request is still hidden, since the triggers fill both columns in that
 *    write) and skips lineage, member matching and the frontmatter test, whose
 *    per-row JSONB read cost keyword search about 3%. The flag is sticky and set
 *    in the same transaction as the first page that names readers, the first
 *    member and the first folder rule or pending folder prefix (v283).
 * Outside any record (local CLI, jobs, cycles) the identity is empty, no
 * source is private-readable and hidePrivate follows the process's hatch
 * state, so caller-aware fragments still fail closed on restricted pages.
 */
export interface CallerAccess {
  identity: readonly string[];
  /**
   * GBRA-231 (shared agents): the normalized audience a request asserted (member:<id>, group:<g>, guest), or null.
   * Reported in _meta.access and whoami, carried by queued writes and agent jobs. With one entry, `identity` is that
   * entry's identity; with more, `identity` is empty (a site that reads it alone over-hides) and
   * `audienceIdentities` holds one identity per entry, every one of which must meet a page's readers.
   */
  audience: readonly string[] | null;
  audienceIdentities: readonly (readonly string[])[];
  /**
   * GST-359 C1: the attested actor (a trusted system named the person; access/actor.ts), or null. Its audience is that
   * one member and its privacy is never relaxed. Queued writes and agent jobs carry it and re-resolve it live.
   */
  actor?: Readonly<{ system: string; external_id: string; member: string }> | null;
  /** GBRA-218 (A2): the source-qualified folder-rule ids (`<source>:<rule>`) the identity satisfies, from the applied rulebook. */
  satisfiedRuleIds: readonly string[];
  /** GBRA-218 (A2): prefixes that read as nobody (a narrowing being stamped, an invalid policy file); prefix '' is the whole source. */
  folderCoverage: readonly FolderCoverage[];
  privateReadableSources: readonly string[];
  privateFactSources: readonly string[];
  hidePrivate: boolean;
  owner: boolean;
  /**
   * GST-2490 / GBRA-108 design 3: a lineage read, one member speaking for itself in a non-mutating operation: the owner
   * always, any other member only under access.members_read_lineage. Derived pages and facts pass when that member reads
   * every origin (lineageOriginAllowedSql) instead of being hidden from every remote caller. Never an audience of
   * several, an unbound credential or an attested call.
   */
  lineage: boolean;
  /**
   * GST-2490: an owner read (owner and lineage) on a brain whose operator turned on access.owner_reads_restricted:
   * readers lists, folder rules and page rules stop closing pages, their derivatives and their facts to the owner,
   * except another member's own member page and what derives from it (lineageAccessSql).
   */
  ownerReadsRestricted: boolean;
  /**
   * GBRA-108 design 2: the enabled members of kind audience (a group chat, a shared assistant), kept only on an owner
   * read (owner and lineage): the owner reads each one's own member page, its older versions, its derived pages and its
   * facts as if its readers named the owner. Ids pass ACCESS_ID_RE, so they embed as literals; empty otherwise.
   */
  audienceKindMembers: readonly string[];
  /**
   * GBRA-108 design 1 (labelled-only grant): the caller's member carries access_members.labelled_only (the labelled-only migration), so every
   * credential bound to it reads only pages that name it: its member id or one of its groups in readable_by, or a folder
   * or page rule that lists it (labelledOnlySql). An unlabelled page its source grant would otherwise open is hidden; a
   * derived page or fact with no readers and no rule of its own is hidden too, except under access.members_read_lineage
   * where every origin is labelled for the caller (gbrain_access_origin_labelled_for). Never on the owner.
   */
  labelledOnly: boolean;
  applyRemoteReadPolicy: boolean;
  restricted: boolean;
  /** The fresh remote policy (readRemotePolicyNow) a remote request read when it started; null outside one. */
  remotePolicy: RemotePolicy | null;
}
export interface FolderCoverage { source_id: string; prefix: string }
const callerAccessStore = new AsyncLocalStorage<CallerAccess>();

/** The current read's caller-access record (see CallerAccess). */
export function currentCallerAccess(): CallerAccess {
  return callerAccessStore.getStore() ?? { identity: [], audience: null, audienceIdentities: [], actor: null, satisfiedRuleIds: [], folderCoverage: [], privateReadableSources: [], privateFactSources: [], hidePrivate: !processPrivacyRelaxed(), owner: false, lineage: false, ownerReadsRestricted: false, audienceKindMembers: [], labelledOnly: false, applyRemoteReadPolicy: false, restricted: true, remotePolicy: null };
}

/** Runs `fn` under `access` merged over the current record; an invalid identity or source id empties that set (fail closed). */
export function withCallerAccess<T>(access: Partial<CallerAccess>, fn: () => T): T {
  const base = currentCallerAccess();
  const identity = access.identity ?? base.identity;
  const sources = access.privateReadableSources ?? base.privateReadableSources;
  const validIds = identity.length > 0 && validIdentity(identity);
  const fresh = access.identity !== undefined || access.audienceIdentities !== undefined;
  const factSources = access.privateFactSources ?? (fresh ? [] : base.privateFactSources);
  const audienceIdentities = (access.audienceIdentities ?? (fresh ? [] : base.audienceIdentities))
    .map(id => id.length && validIdentity(id) ? Object.freeze([...new Set(id)].sort()) : Object.freeze([] as string[]));
  const audience = access.audience !== undefined ? access.audience : fresh ? null : base.audience;
  const actor = access.actor !== undefined ? access.actor : fresh ? null : base.actor ?? null;
  const satisfiedOk = validIds || audienceIdentities.some(id => id.length > 0);
  const satisfied = satisfiedOk ? access.satisfiedRuleIds ?? (fresh ? [] : base.satisfiedRuleIds) : [];
  return callerAccessStore.run(Object.freeze({
    identity: validIds && audienceIdentities.length <= 1 ? Object.freeze([...new Set(identity)].sort()) : Object.freeze([]),
    audience: audience && audience.every(validAudienceEntry) ? Object.freeze([...audience]) : audience ? Object.freeze([GUEST_ENTRY]) : null,
    audienceIdentities: Object.freeze(audienceIdentities.length > 1 ? audienceIdentities : []),
    actor: actor ? Object.freeze({ system: actor.system, external_id: actor.external_id, member: actor.member }) : null,
    satisfiedRuleIds: satisfied.length && satisfied.every(validQualifiedRuleId) ? Object.freeze([...new Set(satisfied)].sort()) : Object.freeze([]),
    folderCoverage: Object.freeze([...(access.folderCoverage ?? base.folderCoverage)].map(c => Object.freeze({ source_id: c.source_id, prefix: c.prefix }))),
    privateReadableSources: sources.length && sources.every(isValidSourceId) ? Object.freeze([...new Set(sources)]) : Object.freeze([]),
    privateFactSources: factSources.length && factSources.every(isValidSourceId) ? Object.freeze([...new Set(factSources)]) : Object.freeze([]),
    hidePrivate: access.hidePrivate ?? (fresh ? true : base.hidePrivate),
    owner: access.owner ?? (fresh ? false : base.owner),
    ...lineageReads(access.owner ?? (fresh ? false : base.owner), audienceIdentities.length <= 1,
      access.lineage ?? (fresh ? false : base.lineage), access.ownerReadsRestricted ?? (fresh ? false : base.ownerReadsRestricted),
      access.audienceKindMembers ?? (fresh ? [] : base.audienceKindMembers)),
    labelledOnly: access.labelledOnly ?? (fresh ? false : base.labelledOnly),
    applyRemoteReadPolicy: access.applyRemoteReadPolicy ?? base.applyRemoteReadPolicy,
    restricted: access.restricted ?? base.restricted,
    remotePolicy: access.remotePolicy ?? base.remotePolicy,
  }), fn);
}

/**
 * GST-2490 / GBRA-108: the lineage flags of a record. Lineage needs one identity (never an audience of several); the owner
 * opt-in and the audience members need an owner read.
 */
function lineageReads(owner: boolean, single: boolean, lineage: boolean, readsRestricted: boolean, audienceKind: readonly string[]): Pick<CallerAccess, 'lineage' | 'ownerReadsRestricted' | 'audienceKindMembers'> {
  const read = single && lineage;
  const ownerRead = owner && read;
  return { lineage: read, ownerReadsRestricted: ownerRead && readsRestricted,
    audienceKindMembers: Object.freeze(ownerRead && audienceKind.every(id => ACCESS_ID_RE.test(id)) ? [...new Set(audienceKind)].sort() : []) };
}

/** Runs `fn` outside any caller's record, for work a request spawns that must not inherit its view. */
export function withoutCallerAccess<T>(fn: () => T): T {
  return callerAccessStore.exit(fn);
}

/** Runs `fn` with `sourceIds` as the private-readable set; an invalid id empties the whole set (fail closed). */
export function withPrivateReadableSources<T>(sourceIds: readonly string[] | undefined, fn: () => T): T {
  return withCallerAccess({ privateReadableSources: sourceIds ?? [] }, fn);
}

/** The private-readable set of the current read; empty outside a granted remote read. */
export function privateReadableSources(): readonly string[] {
  return currentCallerAccess().privateReadableSources;
}

/** GST-2059: is the current caller the brain owner (CallerAccess.owner)? False outside a remote record or a local --as of the owner. */
export function callerIsOwner(): boolean {
  return currentCallerAccess().owner;
}

/**
 * GST-2089: whether a fact read stays world-only (visibility = 'world'). Only the trusted local CLI (remote strictly
 * false) and the brain owner (CallerAccess.owner, the page rule) read private facts; provenance, source grants and
 * member access still apply to both. Fact arms decide their visibility list here and nowhere else.
 * GBRA-575: a world-only read is not always world-only row by row. Its caller's private-facts grant
 * (privateFactSources) still admits private facts in the sources that grant names: the visibility list stays
 * ['world'] and factVisibilitySql widens it per row, because a whole-read boolean cannot see which source a row is in.
 */
export function worldOnlyFacts(remote: boolean | undefined): boolean {
  return remote !== false && !callerIsOwner();
}

/**
 * GBRA-575: the sources whose private facts a world-only read (worldOnlyFacts true) still admits: the grant's
 * `private_facts: granted_sources` sources, which dispatch sets only on a credential's own non-mutating read. Empty
 * for an audience, an attested actor and a labelled-only caller, and outside a remote record.
 */
export function privateFactSources(): readonly string[] {
  const access = currentCallerAccess();
  return access.audience || access.actor || access.labelledOnly ? [] : access.privateFactSources;
}

/** The current caller's member identity; empty outside a bound remote read or a local --as, and for an audience of several entries (see callerIdentities). */
export function callerIdentity(): readonly string[] {
  return currentCallerAccess().identity;
}

/** GBRA-231: every identity a page's readers must meet for the current caller: one per audience entry, else the caller's own. */
export function callerIdentities(): readonly (readonly string[])[] {
  const access = currentCallerAccess();
  return access.audienceIdentities.length ? access.audienceIdentities : [access.identity];
}

/** GBRA-231: readersAllow for the current caller (every audience entry must be a reader). */
export function callerReadersAllow(frontmatter: unknown, slug?: string): boolean {
  const access = currentCallerAccess();
  const ownPage = ownerOptInPage(access);
  if (typeof slug === 'string' && audiencePages(access).includes(slug)) return true;
  if (ownPage && typeof slug === 'string' && (!slug.startsWith(MEMBER_PAGE_PREFIX) || slug === ownPage)) return true;
  return callerIdentities().every(identity => readersAllow(frontmatter, identity));
}

/** GBRA-231: readersAllowedSql for the current caller, one conjunct per audience entry. */
export function callerReadersAllowedSql(alias: string, row: 'page' | 'snapshot' = 'page'): string {
  const access = currentCallerAccess();
  const ownPage = ownerOptInPage(access);
  const audience = audiencePages(access);
  const onPage = (test: (pageAlias: string) => string) => row === 'snapshot' ? `EXISTS (SELECT 1 FROM pages sp WHERE sp.id = ${alias}.page_id AND ${test('sp')})` : test(alias);
  const readers = ownPage ? `(${readersAllowedSql(alias, access.identity, row)} OR ${onPage(a => notOtherMemberPageSql(a, ownPage, audience))})`
    : audience.length ? `(${readersAllowedSql(alias, access.identity, row)} OR ${onPage(a => audiencePageSql(a, audience))})`
    : callerIdentities().map(identity => readersAllowedSql(alias, identity, row)).join(' AND ');
  if (!access.labelledOnly) return readers;
  if (row === 'page') return `(${readers} AND ${labelledOnlySql(alias, access)})`;
  return `(${readers} AND (COALESCE(gbrain_access_readers(${alias}.frontmatter) && ${textArraySql(labelledIdentity(access))}, false)
    OR EXISTS (SELECT 1 FROM pages sp WHERE sp.id = ${alias}.page_id AND ${labelledOnlySql('sp', access, false)})))`;
}

type LabelledRecord = Pick<CallerAccess, 'identity' | 'audienceIdentities' | 'satisfiedRuleIds' | 'lineage' | 'owner'>;

/** GBRA-108 design 1: every principal a labelled-only read may be named by (the identity, or each audience entry's). */
function labelledIdentity(access: LabelledRecord): string[] {
  const identity = [...new Set([...access.identity, ...access.audienceIdentities.flat()])].sort();
  return identity.length && validIdentity(identity) ? identity : [];
}

/**
 * GBRA-108 design 1: `alias` names a labelled-only caller (CallerAccess.labelledOnly): its readable_by holds the caller's
 * member or one of its groups, or one of its folder or page rules lists them (a rule the caller satisfies). Under
 * access.members_read_lineage (a member read with lineage) a derived page with no label of its own passes only when it
 * has an origin and every origin names the caller (gbrain_access_origin_labelled_for, the labelled-only migration); with it off a derived page
 * that names nobody is hidden, whatever its origins say. ANDed with the caller's ordinary access, so it only narrows.
 * `readers` false tests only the rules (a version snapshot carries its own readers). Ids embed as validated literals.
 */
function labelledOnlySql(alias: string, access: LabelledRecord, readers = true): string {
  const identity = textArraySql(labelledIdentity(access));
  const satisfied = textArraySql(access.satisfiedRuleIds.every(validQualifiedRuleId) ? access.satisfiedRuleIds : []);
  const named = `(${readers ? `COALESCE(${alias}.page_readers && ${identity}, false) OR ` : ''}COALESCE(${alias}.folder_rule_ids && ${satisfied}, false))`;
  if (!access.lineage || access.owner) return named;
  return `(${named} OR ((${alias}.type IN ('atom', 'question', 'concept', 'event') OR ${alias}.frontmatter ? 'derived_from')
    AND gbrain_access_origin_labelled_for(${alias}.id, ${alias}.source_id, ${alias}.type, ${alias}.frontmatter, ${identity}, ${satisfied})))`;
}

/**
 * GBRA-108 design 1: the fact conjunct of a labelled-only read. A fact has no readers or rule of its own, so it is hidden,
 * except on the caller's own member page while that page names the member (the member's own memory), and under
 * access.members_read_lineage when its provenance page exists and names the caller (labelledOnlySql). Empty for every
 * other caller.
 */
function labelledOnlyFactSql(factAlias: string): string {
  const access = currentCallerAccess();
  if (!access.labelledOnly) return '';
  const lone = access.audienceIdentities.length ? null : access.identity.find(p => p.startsWith('member:'))?.slice('member:'.length) ?? null;
  const member = access.actor?.member ?? lone;
  const own = member && ACCESS_ID_RE.test(member) ? `EXISTS (SELECT 1 FROM pages lp WHERE lp.source_id = ${factAlias}.source_id AND lp.slug = ${factAlias}.source_markdown_slug
    AND lp.slug = '${MEMBER_PAGE_PREFIX}${member}' AND COALESCE(lp.page_readers && ARRAY['member:${member}']::text[], false))` : 'FALSE';
  if (!access.lineage || access.owner) return ` AND ${own}`;
  return ` AND (${own} OR EXISTS (SELECT 1 FROM pages lp WHERE lp.source_id = ${factAlias}.source_id AND lp.slug = ${factAlias}.source_markdown_slug AND ${labelledOnlySql('lp', access)}))`;
}

/**
 * GBRA-108 design 1: the floor of a remote read gate that is not caller-aware. For any caller that is not labelled-only
 * it is exactly privatePagesFilterFragment; a labelled-only caller also gets its labelled-only conjunct, so a page that
 * does not name it never answers. Write-side, maintenance and derived-visibility decisions keep the plain fragment; test/remote-read-floor.test.ts pins which call sites do.
 */
export function remoteReadFloorSql(pageAlias: string, derived = false): string {
  const plain = privatePagesFilterFragment(pageAlias, derived);
  const access = currentCallerAccess();
  return access.labelledOnly ? `(${plain} AND ${labelledOnlySql(pageAlias, access)})` : plain;
}

/** remoteReadFloorSql for a fact lookup: privateProvenanceFilterFragment, plus the labelled-only fact conjunct for a labelled-only caller. */
export function remoteProvenanceFloorSql(factAlias: string): string {
  const plain = privateProvenanceFilterFragment(factAlias);
  const labelled = labelledOnlyFactSql(factAlias);
  return labelled ? `(${plain}${labelled})` : plain;
}

const GUEST_ENTRY = 'guest';
function validAudienceEntry(entry: string): boolean {
  return entry === GUEST_ENTRY || normalizePrincipal(entry) === entry;
}

function callerAccessSql(pageAlias: string): string {
  const access = currentCallerAccess();
  const ownPage = lineageReadPage(access);
  const allowed = ownPage ? lineageAccessSql(pageAlias, access, ownPage)
    : access.audienceIdentities.length ? accessAllowedForAllSql(pageAlias, access.audienceIdentities, access.satisfiedRuleIds)
    : accessAllowedSql(pageAlias, access.identity);
  return access.labelledOnly ? `(${allowed} AND ${labelledOnlySql(pageAlias, access)})` : allowed;
}

/**
 * GBRA-108 design 1: the labelled-only conjunct for a page row checked outside the caller's read (a stored write's writer,
 * the enforced member CLI): the page names one of `identities` or sits under a rule in `satisfied` (`readers` false: the
 * rule alone, for a slug with no row yet). No lineage: a write never reads through it.
 */
export function labelledOnlyForSql(pageAlias: string, identities: readonly (readonly string[])[], satisfied: readonly string[], readers = true): string {
  return labelledOnlySql(pageAlias, { identity: [], audienceIdentities: identities, satisfiedRuleIds: satisfied, lineage: false, owner: false }, readers);
}

/**
 * `visiblePredicate` (a privacy-only predicate), widened to pages
 * (`pageAlias`, a code-provided alias) whose source is in the current
 * private-readable set. A page carrying the `pinned_question` marker never
 * widens: pinned questions stay owner-private (src/core/questions/pages.ts).
 * Never pass a predicate that contains accessAllowedSql: the widening would
 * reach it. The ids are embedded as literals: each passed
 * isValidSourceId, whose alphabet has no quote or backslash.
 */
export function orPrivateReadableSource(pageAlias: string, visiblePredicate: string): string {
  const ids = privateReadableSources();
  if (ids.length === 0) return visiblePredicate;
  return `((${pageAlias}.source_id IN (${ids.map(id => `'${id}'`).join(', ')}) AND NOT COALESCE(${pageAlias}.frontmatter ? 'pinned_question', false)) OR ${visiblePredicate})`;
}

/**
 * A privacy-only predicate for the current caller: TRUE when an operator
 * relaxed privacy, else widened only to private-readable sources. Never pass
 * a predicate that contains accessAllowedSql or readersAllowedSql.
 */
export function privacyForCaller(pageAlias: string, privacyPredicate: string): string {
  return currentCallerAccess().hidePrivate ? orPrivateReadableSource(pageAlias, privacyPredicate) : 'TRUE';
}

function callerPrivacySql(pageAlias: string, privacyPredicate: string): string {
  return privacyForCaller(pageAlias, privacyPredicate);
}

/** privatePagesFilterFragment for a remote read: the caller's member access, then the privacy part with its grant and hatch. Read sites only; derived-visibility decisions keep the plain fragment. */
export function privatePagesFilterForCaller(pageAlias: string): string {
  return `(${callerAccessSql(pageAlias)} AND ${callerPrivacySql(pageAlias, privacyPartSql(pageAlias))})`;
}

/** The mandatory member-access part alone (readers and lineage) for the current caller; privacy is not tested. */
export function callerAccessAllowedSql(pageAlias: string): string {
  return callerAccessSql(pageAlias);
}

/**
 * The read policy for an explicit identity, outside any caller record (a
 * write's publication re-resolves its writer's identity): the member-access
 * part, then the privacy part unless `hidePrivate` is false. With an empty
 * identity and `hidePrivate` it equals privatePagesFilterFragment.
 */
export function readPolicyFragment(pageAlias: string, identity: readonly string[] | { all: readonly (readonly string[])[] }, hidePrivate: boolean, satisfied?: readonly string[], derived = false): string {
  const access = 'all' in identity ? accessAllowedForAllSql(pageAlias, identity.all, satisfied ?? [], derived) : accessAllowedSql(pageAlias, identity, satisfied ?? satisfiedFor(identity), derived);
  return `(${access} AND ${hidePrivate ? privacyPartSql(pageAlias) : 'TRUE'})`;
}

/** privatePagesFilterFragmentFast for a remote read. */
export function privatePagesFilterFastForCaller(pageAlias: string): string {
  return `(${callerAccessSql(pageAlias)} AND ${callerPrivacySql(pageAlias, privacyPartFastSql(pageAlias))})`;
}

/** The fast form of privacyPartSql (see privatePagesFilterFragmentFast). */
function privacyPartFastSql(pageAlias: string): string {
  return `((${pageAlias}.frontmatter->'visibility' IS NULL AND ${pageAlias}.frontmatter->'derived_from' IS NULL${honorAliases()
      ? `\n      AND ${pageAlias}.frontmatter->'access' IS NULL AND ${pageAlias}.frontmatter->'confidentiality' IS NULL` : ''}
      AND ${pageAlias}.frontmatter->'pinned_question' IS NULL
      AND ${pageAlias}.type NOT IN ('atom', 'concept', 'event', 'question'))
    OR ${privacyPartSql(pageAlias)})`;
}

/**
 * isPrivatePage for a remote read: true when the page names readers the
 * caller does not meet; otherwise the privacy rule, false for a page whose
 * `source_id` is private-readable or when an operator relaxed privacy. A row
 * without `source_id` keeps the plain privacy rule.
 */
export function isPrivatePageForCaller(page: { type?: string | null; frontmatter?: unknown; source_id?: string | null; slug?: string | null }): boolean {
  const access = currentCallerAccess();
  if (!callerReadersAllow(page.frontmatter, page.slug ?? undefined)) return true;
  if (!access.hidePrivate || !isPrivacyPrivatePage(page)) return false;
  if (typeof page.frontmatter === 'object' && page.frontmatter !== null && (page.frontmatter as Record<string, unknown>).pinned_question != null) return true;
  return !(typeof page.source_id === 'string' && access.privateReadableSources.includes(page.source_id));
}

/**
 * Declared lineage: a page whose frontmatter `derived_from` names a page (one
 * slug or a list, `.md` optional) that is explicitly `visibility: private` in
 * the same source is private too, whatever its own field says. Summaries,
 * digests and reports written from finance-only or other private material
 * therefore stay behind the same boundary as their inputs. Only an explicitly
 * private input propagates; a missing input does not hide the page.
 */
function declaredLineagePrivateSql(p: string): string {
  return `(CASE WHEN jsonb_typeof(${p}.frontmatter->'derived_from') IN ('array', 'string') THEN EXISTS (
    SELECT 1 FROM pages declared_origin
    WHERE declared_origin.source_id = ${p}.source_id
      AND declared_origin.frontmatter->>'visibility' = 'private'
      AND declared_origin.slug = ANY(ARRAY(
        SELECT regexp_replace(declared.slug, '\\.md$', '') FROM jsonb_array_elements_text(
          CASE WHEN jsonb_typeof(${p}.frontmatter->'derived_from') = 'array' THEN ${p}.frontmatter->'derived_from'
            ELSE jsonb_build_array(${p}.frontmatter->'derived_from') END) AS declared(slug)))) ELSE false END)`;
}

/**
 * The same rule on a row's own `type`/`frontmatter` only, for snapshots such
 * as `page_versions` that have no page identity to follow to an origin. Callers
 * pair it with privatePagesFilterFragment on the live page. A page carrying the
 * `pinned_question` marker is private whatever its `visibility` says (pinned
 * questions are owner-private, src/core/questions/pages.ts). A page with no
 * `visibility` but a privacy alias is private too, unless the operator turned
 * `visibility.honor_aliases` off; the row-side isPrivatePage applies the same rule.
 */
export function privateSnapshotFilterFragment(alias: string): string {
  return `(COALESCE(${alias}.frontmatter->>'visibility', CASE WHEN ${derivedPageSql(alias)} THEN 'private' ELSE 'world' END) <> 'private'
    AND NOT COALESCE(${alias}.frontmatter ? 'pinned_question', false)${honorAliases()
      ? `\n    AND NOT (${alias}.frontmatter->>'visibility' IS NULL AND ${privacyAliasSql(alias)})` : ''})`;
}

/**
 * #5525 — a later private flip of an origin page reaches its derived pages
 * before any repair runs: an atom whose origin page is explicitly private, and
 * a synthesized concept with a private input atom (or an input atom whose
 * origin is private), are private whatever their own field says.
 * `gbrain repair visibility` then stamps the stricter value on the rows.
 * An atom whose origin a sync rename moved (#7462) is private when the page at
 * its `source_slug` or the page the rename moved it to is private, including a
 * move whose alias a later rename onto the old slug dropped (#8920). A concept's
 * inputs are judged the same way, moved origins included (GST-2687), by the SQL
 * function gbrain_concept_inputs_private (migration v311), one planned call per
 * page instead of the subplans, when the read's schema version is at or above v311: the one its remote, scope or
 * attested caller record carries, or, with no remote policy, the one the engine in scope recorded at connect or
 * migration (schemaVersionSeen). Over a shadowed `pages` (privacyPartSql), outside an engine scope, and on a brain
 * whose schema predates v311 or whose version was not read, the same test runs inline, as gbrain_access_origin_restricted is
 * skipped inside a request on a brain that never set access.restrictions_present.
 */
/** The schema version (migration v311) that creates gbrain_concept_inputs_private; a literal so the CLI dispatcher never loads a migration module. */
export const CONCEPT_INPUTS_PRIVATE_SINCE = 311;

/** The read's schema version: the one its remote, scope or attested caller record carries, else the one the engine in scope recorded (schemaVersionSeen); undefined when neither. */
function readSchemaVersion(): number | undefined {
  const { remotePolicy } = currentCallerAccess();
  const scoped = engineScopeStore.getStore();
  return remotePolicy ? remotePolicy.schemaVersion : scoped ? schemaVersionSeen(scoped) : undefined;
}

function derivedOriginPrivateSql(p: string, shadowedPages: boolean): string {
  const privateOrigin = (atom: string, alias: string) => `EXISTS (SELECT 1 FROM pages ${alias} WHERE ${alias}.source_id = ${atom}.source_id
      AND ${alias}.slug = ANY(${atomOriginSlugsSql(atom)}) AND ${alias}.frontmatter->>'visibility' = 'private')`;
  const schema = readSchemaVersion();
  const conceptInputsPrivate = !shadowedPages && schema !== undefined && schema >= CONCEPT_INPUTS_PRIVATE_SINCE ? `gbrain_concept_inputs_private((${p}.id)::integer)`
    : `EXISTS (SELECT 1 FROM links derived_input_link
      JOIN pages derived_input ON derived_input.id = derived_input_link.to_page_id
      WHERE derived_input_link.from_page_id = ${p}.id AND derived_input_link.link_source = 'concept-provenance'
        AND derived_input_link.link_type = 'synthesized_from'
        AND (COALESCE(derived_input.frontmatter->>'visibility', CASE WHEN derived_input.type = 'atom' THEN 'private' ELSE 'world' END) = 'private'
          OR ${privateOrigin('derived_input', 'derived_input_origin')} OR ${atomMovedOriginPrivateSql('derived_input')}))`;
  return `(CASE WHEN ${p}.type = 'atom' THEN (${privateOrigin(p, 'derived_origin')} OR ${atomMovedOriginPrivateSql(p)})
    WHEN ${derivedPageSql(p)} THEN ${conceptInputsPrivate}
    WHEN ${p}.type = 'event' AND ${p}.frontmatter->>'captured_via' LIKE 'life-chronicle:%' THEN ${chronicleOriginNotVisibleSql(p)}
    ELSE false END)`;
}

/**
 * #5876 (C4a/E7) — a Life Chronicle event is private whenever the meeting,
 * conversation or calendar page it was extracted from (`event.depth`, same
 * source) is private by its own field or its declared lineage, and fails
 * closed when that origin is missing (renamed or purged). Covers events
 * written before the rule existed, at read time.
 */
function chronicleOriginNotVisibleSql(p: string): string {
  return `NOT EXISTS (SELECT 1 FROM pages chronicle_origin WHERE chronicle_origin.source_id = ${p}.source_id
      AND chronicle_origin.slug = ${p}.frontmatter->'event'->>'depth'
      AND ${privateSnapshotFilterFragment('chronicle_origin')}
      AND NOT ${declaredLineagePrivateSql('chronicle_origin')})`;
}

export type Visibility = 'private' | 'world';

/**
 * Privacy aliases: keys a page may carry instead of `visibility` (the
 * bulk-ingestion template's `access`, a `confidentiality` field), with the
 * values that mean private. Matching is ASCII case-insensitive on the value trimmed of
 * edge whitespace, the same on the TypeScript and SQL sides.
 * Everything derived from an aliased page (facts, chronicle events, timeline
 * rows, remember saves into it) is private. Remote page reads honor the aliases
 * too unless the operator sets `visibility.honor_aliases false`.
 */
export const PRIVACY_ALIASES: Readonly<Record<string, readonly string[]>> = {
  access: ['private', 'restricted', 'confidential'],
  confidentiality: ['confidential', 'secret', 'private', 'restricted'],
};
export const HONOR_ALIASES_KEY = 'visibility.honor_aliases';

function hasPrivacyAlias(frontmatter: Record<string, unknown>): boolean {
  return Object.entries(PRIVACY_ALIASES).some(([key, values]) => {
    const value = frontmatter[key];
    return typeof value === 'string' && values.includes(asciiLower(value.trim()));
  });
}

/** SQL twin of hasPrivacyAlias on a page alias (a code-provided literal). */
export function privacyAliasSql(alias: string): string {
  return `(${Object.entries(PRIVACY_ALIASES).map(([key, values]) =>
    `COALESCE(${asciiLowerSql(edgeTrimSql(`${alias}.frontmatter->>'${key}'`))} IN (${values.map(v => `'${v}'`).join(',')}), false)`).join(' OR ')})`;
}

/**
 * `visibility.honor_aliases` per brain in this process, as last read by
 * resolveExcludePrivatePages (the resolver every remote read runs before it builds
 * SQL). The fragments are synchronous, so the setting is process-wide and leans
 * private: the aliases are honored unless a brain turned them off and no brain in
 * the process keeps them on. Unset means on.
 */
const honorAliasEngines = new Set<BrainEngine>();
const aliasOptOutEngines = new Set<BrainEngine>();
/**
 * An engine opened from settings keeps its own policy here instead (keyed by engineKey, so it goes with the engine and a
 * per-call engine is never retained): inside its scope its own setting decides, and it never sways the process sets.
 */
let embeddedPolicy = new WeakMap<object, { honorAliases?: boolean; expose?: boolean }>();
const embeddedPolicyOf = (key: object) => {
  let policy = embeddedPolicy.get(key);
  if (!policy) embeddedPolicy.set(key, policy = {});
  return policy;
};
const ALIAS_OPT_OUT_VALUES = ['false', '0', 'off', 'no'];
function honorAliases(): boolean {
  const scoped = embeddedKeyInScope();
  if (scoped) return embeddedPolicy.get(scoped)?.honorAliases ?? true;
  if (unscopedWithOpenEmbeddedEngines()) return true;
  return honorAliasEngines.size > 0 || aliasOptOutEngines.size === 0;
}

/** Reads this brain's `visibility.honor_aliases` into the process setting (an embedded engine's: its own); true unless it is false/0/off/no. Unreadable keeps the last value. */
export async function readHonorAliases(engine: BrainEngine): Promise<boolean> {
  try {
    const optOut = ALIAS_OPT_OUT_VALUES.includes((await engine.getConfig(HONOR_ALIASES_KEY))?.trim().toLowerCase() ?? '');
    const embedded = embeddedKey(engine);
    if (embedded) {
      embeddedPolicyOf(embedded).honorAliases = !optOut;
      return !optOut;
    }
    (optOut ? aliasOptOutEngines : honorAliasEngines).add(engine);
    (optOut ? honorAliasEngines : aliasOptOutEngines).delete(engine);
    return !optOut;
  } catch {
    const embedded = embeddedKey(engine);
    return embedded ? embeddedPolicy.get(embedded)?.honorAliases ?? true : !aliasOptOutEngines.has(engine);
  }
}

/**
 * A page whatever is derived from it must not outrank: private to remote readers, carrying a privacy alias, or under a
 * folder rule or a pending folder prefix (`folder_restricted`, selected with folderRestrictedSql or looked up with folderRestricted).
 */
export function isDerivationPrivate(page: { type?: string | null; frontmatter?: unknown; folder_restricted?: boolean | null }): boolean {
  return page.folder_restricted === true || hasReaders(page.frontmatter) || isPrivacyDerivationPrivate(page);
}

/** isDerivationPrivate by privacy alone (visibility, aliases, pinned questions): what decides where a page lives in Git. */
export function isPrivacyDerivationPrivate(page: { type?: string | null; frontmatter?: unknown }): boolean {
  if (isPrivacyPrivatePage(page)) return true;
  return typeof page.frontmatter === 'object' && page.frontmatter !== null && hasPrivacyAlias(page.frontmatter as Record<string, unknown>);
}

/** SQL twin of isDerivationPrivate. */
export function derivationPrivateSql(alias: string): string {
  return `(NOT ${privateSnapshotFilterFragment(alias)} OR ${privacyAliasSql(alias)} OR ${namesReadersSql(alias)} OR ${folderRestrictedSql(alias)})`;
}

/**
 * GBRA-218 (A2): the page row sits under an applied folder rule (its stamp) or a pending or invalid folder prefix, or
 * this database role cannot read the folder access tables.
 */
export function folderRestrictedSql(alias: string): string {
  return `(${alias}.folder_rule_ids IS NOT NULL OR gbrain_access_pending_covers(${alias}.source_id, ${alias}.slug) OR (SELECT gbrain_access_state_unreadable()))`;
}

/**
 * folderRestrictedSql for a page known by its slug (a parsed page, a row read without the column, a page about to be
 * written): judged against the applied folder rules, not the stamp. A failed read counts as restricted.
 */
export async function folderRestricted(engine: Pick<BrainEngine, 'executeRaw'>, sourceId: string, slug: string): Promise<boolean> {
  try {
    const [row] = await engine.executeRaw<{ restricted: boolean }>(
      'SELECT (gbrain_access_folder_rules($1, $2) IS NOT NULL OR gbrain_access_pending_covers($1, $2) OR gbrain_access_state_unreadable()) AS restricted', [sourceId, slug]);
    return row?.restricted === true;
  } catch {
    return true;
  }
}

/** `page` with folder_restricted looked up (folderRestricted), for a page read without it, such as a page snapshot. */
export async function withFolderRestricted(engine: Pick<BrainEngine, 'executeRaw'>, page: { source_id: string; slug: string; type?: string | null; frontmatter?: unknown }): Promise<{ type?: string | null; frontmatter?: unknown; folder_restricted: boolean }> {
  return { type: page.type, frontmatter: page.frontmatter, folder_restricted: await folderRestricted(engine, page.source_id, page.slug) };
}

/**
 * #5525 — the visibility a derived page takes from its origin: transcripts and
 * missing origins are private, and a page origin is private when remote
 * readers cannot see it or it carries a privacy alias.
 */
export function effectiveVisibility(origin: { kind: 'transcript' } | { kind: 'page'; page: { type?: string | null; frontmatter?: unknown; folder_restricted?: boolean | null } | null }): Visibility {
  if (origin.kind === 'transcript' || !origin.page) return 'private';
  return isDerivationPrivate(origin.page) ? 'private' : 'world';
}

/** Derived outputs take the strictest visibility of their inputs. */
export function strictestVisibility(values: Iterable<Visibility>): Visibility {
  for (const value of values) if (value === 'private') return 'private';
  return 'world';
}

/** Check the actual origin, independently of joins that redact its source. */
export function privateLinkOriginFilterFragment(linkAlias: string): string {
  return `(${linkAlias}.origin_page_id IS NULL OR EXISTS (
    SELECT 1 FROM pages origin_private
    WHERE origin_private.id = ${linkAlias}.origin_page_id
      AND ${privatePagesFilterFragment('origin_private')}
  ))`;
}

/** A projection's private event must stay hidden even when its join is source-redacted. */
export function privateTimelineEventFilterFragment(timelineAlias: string): string {
  return `(${timelineAlias}.event_page_id IS NULL OR EXISTS (
    SELECT 1 FROM pages event_private
    WHERE event_private.id = ${timelineAlias}.event_page_id
      AND ${privatePagesFilterFragment('event_private')}
  ))`;
}

/** privateLinkOriginFilterFragment for a remote read: an origin page in a private-readable source passes. */
export function privateLinkOriginFilterForCaller(linkAlias: string): string {
  return `(${linkAlias}.origin_page_id IS NULL OR EXISTS (
    SELECT 1 FROM pages origin_private
    WHERE origin_private.id = ${linkAlias}.origin_page_id
      AND ${privatePagesFilterForCaller('origin_private')}
  ))`;
}

/** privateTimelineEventFilterFragment for a remote read. */
export function privateTimelineEventFilterForCaller(timelineAlias: string): string {
  return `(${timelineAlias}.event_page_id IS NULL OR EXISTS (
    SELECT 1 FROM pages event_private
    WHERE event_private.id = ${timelineAlias}.event_page_id
      AND ${privatePagesFilterForCaller('event_private')}
  ))`;
}

/**
 * Fact-row twin for ontology provenance: hide an observation whose provenance
 * page (`source_markdown_slug`, looked up in the fact's own source) is
 * private. Non-page provenance (e.g. `manual`) has no page row and passes;
 * deleted page rows still count (fail-closed). Keys on (facts.source_id, slug),
 * so a provenance page living in a DIFFERENT source than the fact is not
 * consulted — fail-open for cross-source provenance, acceptable under source
 * isolation because ontology_propose stamps the fact with ctx.sourceId.
 */
/**
 * GBRA-218: privateProvenanceFilterFragment for the fact reads a caller gates on `excludePrivate`. The readers part
 * always applies (a world fact held in or extracted from a page that names readers stays hidden from every remote
 * caller, as with the plain fragment); the privacy part is dropped when an operator relaxed privacy for this remote
 * read, which is what the hatches did to these reads before member access (`excludePrivate` was false then).
 * Outside a remote record nothing relaxes it. GST-359 C2: a fact on the caller's own member page
 * (`memory/members/<member>`, one attested or bound member) alone is judged as the caller, so its member reads it back;
 * every other page, other members' pages included, keeps the empty identity. GST-2490 / GBRA-108: a lineage read judges
 * every other page that is not a member page as the reader, and an owner read an audience member's page too. The
 * provenance page is judged as an origin: a raw-only rule (covers_derived false) does not hide the facts from its pages.
 */
export function privateProvenanceFilterUnderPolicy(factAlias: string, perCandidate = false): string {
  const access = currentCallerAccess();
  const hide = !callerRelaxesPrivacy();
  const member = access.actor?.member ?? (access.audienceIdentities.length ? null : access.identity.find(p => p.startsWith('member:'))?.slice('member:'.length));
  const ownPage = lineageReadPage(access);
  const audience = audiencePages(access);
  const memberPage = audience.length ? `(starts_with(pp.slug, '${MEMBER_PAGE_PREFIX}') AND NOT ${audiencePageSql('pp', audience)})` : `starts_with(pp.slug, '${MEMBER_PAGE_PREFIX}')`;
  const otherwise = ownPage
    ? `CASE WHEN ${memberPage} THEN ${readPolicyFragment('pp', [], hide, [], true)} ELSE (${lineageAccessSql('pp', access, ownPage, true)} AND ${hide ? privacyPartSql('pp') : 'TRUE'}) END`
    : readPolicyFragment('pp', [], hide, [], true);
  const policy = member && ACCESS_ID_RE.test(member)
    ? `CASE WHEN pp.slug = '${MEMBER_PAGE_PREFIX}${member}' THEN ${readPolicyFragment('pp', access.identity, hide, access.satisfiedRuleIds, true)} ELSE ${otherwise} END`
    : otherwise;
  return `(NOT EXISTS (SELECT 1 FROM pages pp WHERE pp.source_id = ${factAlias}.source_id AND pp.slug = ${factAlias}.source_markdown_slug AND NOT (${policy})) AND ${privateEntityFilterForCaller(factAlias, perCandidate)}${labelledOnlyFactSql(factAlias)}${ownerOnlyFactAllowedSql(factAlias)})`;
}

/**
 * A fact is never wider than the page it is about: hide a fact whose entity page (`entity_slug`, looked up in the fact's
 * own source) the current caller cannot read under the read policy its page reads use, so a member the page's readers
 * name keeps the fact and every other remote caller loses it. A fact held on a holding page (GST-2492) is also judged by
 * that page as a page, not as lineage, so a folder's holding page hides its facts exactly as it hides itself. A fact with
 * no entity page passes. Read sites only; it only ever narrows. GBRA-108 design 1: the entity page and the holding page
 * are judged by the caller's ordinary access, not its labelled-only grant: a labelled-only caller's fact is already kept
 * to provenance that names it (labelledOnlyFactSql), and that conjunct is what narrows it.
 */
export function privateEntityFilterForCaller(factAlias: string, perCandidate = false): string {
  const entityPolicy = currentCallerAccess().labelledOnly ? withCallerAccess({ labelledOnly: false }, () => privatePagesFilterForCaller('entity_pp')) : privatePagesFilterForCaller('entity_pp');
  const held = `CASE WHEN ${factAlias}.entity_slug IS NOT NULL AND ${holdingSlugSql(`${factAlias}.source_markdown_slug`)} THEN ${factAlias}.source_markdown_slug END`;
  // GBRA-574: a bare name key reads as the page later written at <dir>/<key>, so that page's privacy covers it.
  const keyedSlugs = `ARRAY[${NAME_KEY_PAGE_DIRS.map(dir => `'${dir}/' || ${factAlias}.entity_slug`).join(', ')}]`;
  const keyed = `CASE WHEN strpos(${factAlias}.entity_slug, '/') = 0 THEN NOT EXISTS (SELECT 1 FROM pages entity_pp WHERE entity_pp.source_id = ${factAlias}.source_id AND entity_pp.slug = ANY(${keyedSlugs}) AND NOT ${entityPolicy}${perCandidate ? ' OFFSET 0' : ''}) ELSE TRUE END`;
  return `(NOT EXISTS (SELECT 1 FROM pages entity_pp WHERE entity_pp.source_id = ${factAlias}.source_id AND entity_pp.slug IN (${factAlias}.entity_slug, ${held}) AND NOT ${entityPolicy}${perCandidate ? ' OFFSET 0' : ''}) AND ${keyed}${sharedHeldRuledSql(factAlias)})`;
}

/**
 * GST-2492: a fact still held on a holding page for an entity a rule now narrows below that page (a folder rule over the
 * shared page, an exact page rule over a folder's holding page; applied by sync, or a remember planned before the rule,
 * until the held-fact move takes it away) reads as that entity's page would: only for a caller who satisfies every
 * covering rule, and for nobody while a pending narrowing covers it. The owner under the opt-in reads it, as it reads every restricted page.
 */
function sharedHeldRuledSql(factAlias: string): string {
  const access = currentCallerAccess();
  if (access.ownerReadsRestricted) return '';
  const satisfied = access.restricted ? access.satisfiedRuleIds : [];
  const ids = satisfied.length && satisfied.every(validQualifiedRuleId) ? [...new Set(satisfied)].sort() : [];
  const array = ids.length ? `ARRAY[${ids.map(id => `'${id}'`).join(', ')}]::text[]` : 'ARRAY[]::text[]';
  return ` AND NOT (${factAlias}.entity_slug IS NOT NULL AND ${holdingSlugSql(`${factAlias}.source_markdown_slug`)}`
    + ` AND (NOT COALESCE(gbrain_access_folder_rules(${factAlias}.source_id, ${factAlias}.entity_slug) <@ ${array}, true)`
    + ` OR gbrain_access_pending_covers(${factAlias}.source_id, ${factAlias}.entity_slug)))`;
}

/**
 * privateProvenanceFilterFragment for a remote fact read: the provenance page gate plus the caller's entity-page gate.
 * perCandidate keeps the entity gate a lookup per candidate row (OFFSET 0 stops the planner turning it into a join), so
 * a scan an index serves, such as the saved-fact keyword match, keeps that index.
 */
export function privateFactFilterForCaller(factAlias: string, perCandidate = false): string {
  return `(${privateProvenanceFilterFragment(factAlias)} AND ${privateEntityFilterForCaller(factAlias, perCandidate)}${labelledOnlyFactSql(factAlias)})`;
}

/**
 * GST-2951: the page gate for a fact read whose visibility follows worldOnlyFacts. The brain owner's read is judged by
 * the policy recall and find_trajectory use (privateProvenanceFilterUnderPolicy), so the owner keeps facts taken from a
 * private page it reads, while member access still applies; every other caller keeps privateFactFilterForCaller.
 */
export function privateFactFilterForReader(factAlias: string, perCandidate = false): string {
  return callerIsOwner() ? privateProvenanceFilterUnderPolicy(factAlias, perCandidate) : privateFactFilterForCaller(factAlias, perCandidate);
}

/** True only inside a remote caller record whose read an operator relaxed (the env hatch or the config opt-out). */
export function callerRelaxesPrivacy(): boolean {
  return callerAccessStore.getStore()?.hidePrivate === false;
}

export function privateProvenanceFilterFragment(factAlias: string): string {
  return `(NOT EXISTS (SELECT 1 FROM pages pp WHERE pp.source_id = ${factAlias}.source_id ` +
    `AND pp.slug = ${factAlias}.source_markdown_slug AND NOT (${privatePagesFilterFragment('pp', true)}))${ownerOnlyFactAllowedSql(factAlias)})`;
}

/** A fact held in or derived from an owner-only source (access/owner-only.ts) passes only for an owner read; empty for the owner. */
function ownerOnlyFactAllowedSql(factAlias: string): string {
  return currentCallerAccess().owner ? '' : ` AND NOT ${ownerOnlyFactSql(factAlias, ownerOnlyForm(readSchemaVersion()))}`;
}

/**
 * Row-side twin of privatePagesFilterFragment for pages already fetched
 * (get_page / fetch read one row by slug; re-querying just to filter would
 * be a second round-trip). Same semantics: an explicit 'private' hides a
 * page, and an absent value hides only derived atoms and concepts.
 */
export function isPrivatePage(page: { type?: string | null; frontmatter?: unknown }): boolean {
  return hasReaders(page.frontmatter) || isPrivacyPrivatePage(page);
}

/** isPrivatePage without the member-access rule: visibility, aliases and pinned questions only. */
export function isPrivacyPrivatePage(page: { type?: string | null; frontmatter?: unknown }): boolean {
  const frontmatter = typeof page.frontmatter === 'object' && page.frontmatter !== null
    ? page.frontmatter as Record<string, unknown> : {};
  if (frontmatter.pinned_question != null) return true;
  if (frontmatter.visibility == null && honorAliases() && hasPrivacyAlias(frontmatter)) return true;
  const derived = page.type === 'atom' || page.type === 'question' || (page.type === 'concept' && frontmatter.synthesized_by != null);
  return (frontmatter.visibility ?? (derived ? 'private' : 'world')) === 'private';
}

/**
 * Slugs an untrusted caller must not see enumerated: every in-scope page row
 * for the slug is `visibility: private`. A slug with at least one non-private
 * in-scope page stays visible (multi-source: private in one source, world in
 * another). Slugs with no page row at all (dangling link endpoints) are not
 * returned — they reveal nothing private. Used only for get_page's fuzzy
 * candidate enumeration; data-bearing reads authorize concrete rows in the
 * engine instead of treating a visible namesake as authorization. `scope` follows the
 * canonical precedence (federated array > scalar > nothing); with
 * `includeDeleted` unset, only live rows are considered.
 */
export async function findPrivateOnlySlugs(
  engine: BrainEngine,
  slugs: string[],
  scope: { sourceId?: string; sourceIds?: string[] } = {},
  opts: { includeDeleted?: boolean } = {},
): Promise<Set<string>> {
  if (slugs.length === 0) return new Set();
  const params: unknown[] = [slugs];
  let scopeClause = '';
  if (scope.sourceIds && scope.sourceIds.length > 0) {
    params.push(scope.sourceIds);
    scopeClause = `AND p.source_id = ANY($${params.length}::text[])`;
  } else if (scope.sourceId) {
    params.push(scope.sourceId);
    scopeClause = `AND p.source_id = $${params.length}`;
  }
  const rows = await engine.executeRaw<{ slug: string }>(
    `SELECT p.slug FROM pages p
      WHERE p.slug = ANY($1::text[])
        ${opts.includeDeleted ? '' : 'AND p.deleted_at IS NULL'}
        ${scopeClause}
      GROUP BY p.slug
      HAVING bool_and(NOT (${privatePagesFilterForCaller('p')}))`,
    params,
  );
  return new Set(rows.map(r => r.slug));
}

const CACHE_TTL_MS = 30_000;
let cache = new WeakMap<BrainEngine, { at: number; expose: boolean }>();
const exposeEngines = new Set<BrainEngine>();
const strictEngines = new Set<BrainEngine>();

/** GBRA-218: set once a page names readers or a member exists (sticky; a trigger and `gbrain access` write it). */
export const ACCESS_RESTRICTIONS_KEY = 'access.restrictions_present';

/**
 * GST-363: whom the brain serves. SERVES_KEY is the explicit `one` or `several` (`gbrain setup --serves several`
 * writes it, and it wins); SERVES_DERIVED_KEY is `several` while two or more members are enabled, `one` otherwise;
 * SERVES_SINCE_KEY is when the brain first served several people, set once and never cleared. A trigger on
 * access_members and on config access.serves keeps the last two (migration v309), so a request reads them from its
 * config snapshot with no query. REQUESTER_SCOPE_ENFORCE_KEY `false` turns the unscoped-read refusal into a notice
 * (hosted, until its control plane binds each connection to a member).
 */
export const SERVES_KEY = 'access.serves';
export const SERVES_DERIVED_KEY = 'access.serves_derived';
export const SERVES_SINCE_KEY = 'access.serves_since';
export const REQUESTER_SCOPE_ENFORCE_KEY = 'access.requester_scope_enforce';
/** The schema version migrate.ts records in config. */
const SCHEMA_VERSION_KEY = 'version';

/** @internal exported for tests: engines the process-wide policy sets hold. */
export function __aliasPolicyEngineCountForTests(): number {
  return honorAliasEngines.size + aliasOptOutEngines.size + exposeEngines.size + strictEngines.size;
}

/** Test helper: drop the per-engine config cache. */
export function __resetPrivateVisibilityCacheForTests(): void {
  cache = new WeakMap();
  embeddedPolicy = new WeakMap();
  honorAliasEngines.clear();
  aliasOptOutEngines.clear();
  exposeEngines.clear();
  strictEngines.clear();
}

/**
 * The process-wide privacy relaxation used when no caller record exists:
 * the env hatch, or a brain that opted out while none in this process stayed
 * strict (the same lean-private rule as visibility.honor_aliases).
 */
function processPrivacyRelaxed(): boolean {
  if (process.env.GBRAIN_REMOTE_PRIVATE_PAGES === '1') return true;
  const scoped = embeddedKeyInScope();
  if (scoped) return embeddedPolicy.get(scoped)?.expose === true;
  if (unscopedWithOpenEmbeddedEngines()) return false;
  return exposeEngines.size > 0 && strictEngines.size === 0;
}

/**
 * Has an operator relaxed privacy for remote reads on this brain
 * (GBRAIN_REMOTE_PRIVATE_PAGES=1 or search.remote_private_pages=visible)?
 * The only reader of either switch: every privacy decision comes through here
 * or through resolveExcludePrivatePages. Config lookups are cached 30s per
 * engine; a failed lookup counts as "not relaxed" (fail-closed).
 */
export async function remotePrivacyRelaxed(engine: BrainEngine): Promise<boolean> {
  if (process.env.GBRAIN_REMOTE_PRIVATE_PAGES === '1') return true; // incident escape hatch
  const hit = cache.get(engine);
  if (hit && Date.now() - hit.at < CACHE_TTL_MS) return hit.expose;
  let expose: boolean;
  try {
    const v = await engine.getConfig(REMOTE_PRIVATE_PAGES_KEY);
    expose = v === 'visible' || v === 'true' || v === '1';
  } catch {
    expose = false; // config unreadable → enforce (fail-closed)
  }
  await readHonorAliases(engine);
  cache.set(engine, { at: Date.now(), expose });
  const embedded = embeddedKey(engine);
  if (embedded) {
    embeddedPolicyOf(embedded).expose = expose;
    return expose;
  }
  (expose ? exposeEngines : strictEngines).add(engine);
  (expose ? strictEngines : exposeEngines).delete(engine);
  return expose;
}

/** GST-363: whom the brain serves, as a remote request reads it from config (no query). `since` is epoch seconds. */
export interface ServesPolicy { several: boolean; from: 'config' | 'members'; since: number | null; enforce: boolean }

/** `servesUnknown`: the config read failed, so whom the brain serves is not known (never read as one person, GST-363). */
/** `schemaVersion`: config `version` as the request read it; below v311, or absent, the concept-input test runs inline (derivedOriginPrivateSql). A local read has no policy and uses its engine's recorded version instead. */
export interface RemotePolicy { privacyRelaxed: boolean; restricted: boolean; ownerMember?: string | null; ownerReadsRestricted?: boolean; membersReadLineage?: boolean; serves?: ServesPolicy; servesUnknown?: boolean; schemaVersion?: number }

/** GST-363: an explicit access.serves wins over the trigger-kept member count; enforcement is on unless set to false. */
export function servesPolicyFrom(config: Record<string, string | undefined>): ServesPolicy {
  const explicit = config[SERVES_KEY]?.trim().toLowerCase();
  const fromConfig = explicit === 'one' || explicit === 'several';
  const since = Date.parse(config[SERVES_SINCE_KEY]?.trim() ?? '');
  return {
    several: (fromConfig ? explicit : config[SERVES_DERIVED_KEY]?.trim()) === 'several',
    from: fromConfig ? 'config' : 'members',
    since: Number.isFinite(since) ? Math.floor(since / 1000) : null,
    enforce: !['false', '0', 'off', 'no'].includes(config[REQUESTER_SCOPE_ENFORCE_KEY]?.trim().toLowerCase() ?? ''),
  };
}

/**
 * The remote read policy read fresh, for publication: whether an operator
 * relaxed privacy (the env hatch or the config opt-out, uncached) and whether
 * the brain holds member-access restrictions. Takes any executeRaw engine (a
 * transaction included). An unreadable config counts as not opted out and
 * restricted (fail closed); the env hatch needs no read. Whom the brain serves
 * is then unknown (servesUnknown, GST-363): the requester-scope gate reads the
 * serves keys once more (readServesPolicy) and refuses an unbound read when that
 * fails too, because a timeout or a dropped pooled connection can fail this one
 * statement while the next read succeeds.
 */
export async function readRemotePolicyNow(engine: Pick<BrainEngine, 'executeRaw'>): Promise<RemotePolicy> {
  try {
    const rows = await engine.executeRaw<{ key: string; value: string }>('SELECT key, value FROM config WHERE key = ANY($1::text[])', [[REMOTE_PRIVATE_PAGES_KEY, ACCESS_RESTRICTIONS_KEY, OWNER_MEMBER_KEY, OWNER_READS_RESTRICTED_KEY, MEMBERS_READ_LINEAGE_KEY,
      SERVES_KEY, SERVES_DERIVED_KEY, SERVES_SINCE_KEY, REQUESTER_SCOPE_ENFORCE_KEY, SCHEMA_VERSION_KEY]]);
    return remotePolicyFrom(Object.fromEntries(rows.map(r => [r.key, r.value])));
  } catch {
    return { privacyRelaxed: process.env.GBRAIN_REMOTE_PRIVATE_PAGES === '1', restricted: true, ownerMember: null, ownerReadsRestricted: false, membersReadLineage: false, servesUnknown: true };
  }
}

/** GST-2687: the schema version a scope or attested caller record carries, read now; absent when unreadable, so the read rule stays inline. */
export async function schemaVersionNow(engine: Pick<BrainEngine, 'executeRaw'>): Promise<Pick<RemotePolicy, 'schemaVersion'>> {
  const { schemaVersion } = await readRemotePolicyNow(engine);
  return schemaVersion === undefined ? {} : { schemaVersion };
}

/** GST-363: whom the brain serves, read on its own (the requester-scope gate's re-read after an unreadable policy read). Throws when unreadable. */
export async function readServesPolicy(engine: Pick<BrainEngine, 'executeRaw'>): Promise<ServesPolicy> {
  const rows = await engine.executeRaw<{ key: string; value: string }>('SELECT key, value FROM config WHERE key = ANY($1::text[])', [[SERVES_KEY, SERVES_DERIVED_KEY, SERVES_SINCE_KEY, REQUESTER_SCOPE_ENFORCE_KEY]]);
  return servesPolicyFrom(Object.fromEntries(rows.map(r => [r.key, r.value])));
}

/**
 * The remote read policy a request starts under: answered from the read request's config snapshot when one is open
 * (taken when the request started, so no staler than readRemotePolicyNow there, and no extra round trip, #6721);
 * otherwise (a write reads config live, or the snapshot's bulk read failed) readRemotePolicyNow's one statement.
 */
export async function requestRemotePolicy(engine: BrainEngine): Promise<RemotePolicy> {
  const rows = await requestConfigRows(engine).catch(() => undefined);
  return rows ? remotePolicyFrom(rows) : readRemotePolicyNow(engine);
}

function remotePolicyFrom(config: Record<string, string>): RemotePolicy {
  const hatch = process.env.GBRAIN_REMOTE_PRIVATE_PAGES === '1';
  const owner = config[OWNER_MEMBER_KEY]?.trim();
  const schemaVersion = Number.parseInt(config[SCHEMA_VERSION_KEY] ?? '', 10);
  return { privacyRelaxed: hatch || ['visible', 'true', '1'].includes(config[REMOTE_PRIVATE_PAGES_KEY] ?? ''), restricted: config[ACCESS_RESTRICTIONS_KEY] === '1',
    ownerMember: owner && ACCESS_ID_RE.test(owner) ? owner : null, ownerReadsRestricted: config[OWNER_READS_RESTRICTED_KEY]?.trim() === '1',
    membersReadLineage: config[MEMBERS_READ_LINEAGE_KEY]?.trim() === '1', serves: servesPolicyFrom(config),
    ...(Number.isFinite(schemaVersion) ? { schemaVersion } : {}) };
}

/** GBRA-218: does this brain hold member-access restrictions? Read live (the request snapshot answers it inside a read); unreadable counts as yes. */
export async function accessRestrictionsPresent(engine: BrainEngine): Promise<boolean> {
  try {
    return (await engine.getConfig(ACCESS_RESTRICTIONS_KEY)) === '1';
  } catch {
    return true;
  }
}

/**
 * Should this caller's page reads apply the read-policy fragment
 * (`excludePrivate`)? `remote` follows the repo trust convention: anything
 * that is not strictly `false` is untrusted. A trusted local caller applies
 * it only under a local `--as <member>` record. A remote caller always
 * applies it, except when an operator relaxed privacy and the brain holds no
 * member-access restriction, where the hatches keep their pre-GBRA-218
 * meaning. With restrictions present the fragment still applies under a
 * hatch: caller-aware fragments relax only their privacy part, and the
 * member-access part (accessAllowedSql) stays mandatory. A shared-agent audience the hatch does not relax (a
 * channel: several entries, a group or a guest) always applies it, restrictions or not.
 */
export async function resolveExcludePrivatePages(
  engine: BrainEngine,
  remote: boolean | undefined,
): Promise<boolean> {
  if (remote === false) return currentCallerAccess().applyRemoteReadPolicy;
  if (!await remotePrivacyRelaxed(engine)) return true;
  const access = currentCallerAccess();
  if (access.audience?.length && access.hidePrivate) return true;
  return await accessRestrictionsPresent(engine) || (!access.owner && await ownerOnlySourcesPresent(engine));
}