Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GST-359 C2 (GBRA-218): member facts. A fact a member saves remotely (an attested actor, or a credential bound to a
* member reading as itself) lives on that member's own page, `memory/members/<member>`, whose frontmatter names the
* member as its only reader. The fact row is `visibility: private`, so every fact read that admits only world facts
* hides it from everyone, and the page's readers (git-backed where a repo exists, the database row on a repo-less
* brain) decide the one caller allowed to read it back: `memberFactAdmitSql` admits a private fact only when it sits
* on the caller's own member page and that page's readers admit the caller. A fence rebuild re-derives the row from
* the page it lives on, so it keeps both.
*
* Caches and per-session state that a caller's identity changes are keyed by `callerIdentityKey()`, so two people
* behind one attest credential and one session id never share an entry.
*/
import { createHash } from 'node:crypto';
import type { OperationContext } from '../ops/contract.ts';
import { currentCallerAccess, folderRestrictedSql, isDerivationPrivate, privateFactSources, privatePagesFilterForCaller, withFolderRestricted } from '../search/private-visibility.ts';
import { factPagesOpenSql, unpagedFactSql } from '../facts/private-fact-pages.ts';
import { ownedMemorySubjectSql, unbackedEntitySql } from '../facts/withdrawal-schema.ts';
import type { BrainEngine } from '../engine.ts';
import { ACCESS_ID_RE, MEMBER_PAGE_PREFIX, normalizeReaders, SCOPE_PAGE_SLUG } from './principals.ts';
import { opError, type OperationError } from '../ops/contract.ts';
import { slugifyPath } from '../sync.ts';
export { MEMBER_PAGE_PREFIX, SCOPE_PAGE_SLUG };
/** GST-1113: the scope page or anything under its reserved prefix. */
export const isScopePageSlug = (slug: string): boolean => slug === SCOPE_PAGE_SLUG || slug.startsWith(`${SCOPE_PAGE_SLUG}/`);
export const memberPageSlug = (member: string): string => `${MEMBER_PAGE_PREFIX}${member}`;
/** The member the current caller reads as: the attested actor's, else a lone member identity (never an audience of several). */
export function callerMember(): string | null {
const access = currentCallerAccess();
if (access.actor) return access.actor.member;
if (access.audienceIdentities.length) return null;
const member = access.identity.find(p => p.startsWith('member:'))?.slice('member:'.length) ?? null;
return member && ACCESS_ID_RE.test(member) ? member : null;
}
/** GST-2897 B: the member a people page names: `people/<member>` or a page under it. */
export function peoplePageMember(slug: string | null | undefined): string | null {
const id = /^people\/([^/]+)/.exec(slug ?? '')?.[1];
return id && ACCESS_ID_RE.test(id) ? id : null;
}
/** GST-2897 B: the enabled member other than the caller whose people page `entitySlug` is, else null. */
export async function otherMemberSubject(engine: Pick<BrainEngine, 'executeRaw'>, entitySlug: string | null): Promise<string | null> {
const id = peoplePageMember(entitySlug);
if (!id || id === callerMember()) return null;
const rows = await engine.executeRaw('SELECT 1 FROM access_members WHERE id = $1 AND disabled_at IS NULL AND tombstoned_at IS NULL', [id]);
return rows.length ? id : null;
}
/**
* The member page a remote memory write goes to, or null when the caller writes as no single member (local or
* unbound). A member id whose page slug a repo brain would rename on sync (`a--b`, `zed-`) is refused: its facts
* would land on another path.
*/
export function memberFactPage(ctx: Pick<OperationContext, 'remote'>): string | null {
if (ctx.remote === false) return null;
const member = callerMember();
if (!member) return null;
const slug = memberPageSlug(member);
if (slugifyPath(slug) !== slug) {
throw opError('invalid_params', `Member id ${member} cannot hold member facts: its page ${slug} would be stored as ${slugifyPath(slug)}.`,
'Nothing was saved. The brain host gives this person a member id without repeated, leading or trailing separators (gbrain access member add) and links it instead.');
}
return slug;
}
/**
* GST-2346 D1: whether the caller is the brain owner's own credential speaking for itself: CallerAccess.owner with no
* attested actor and no asserted audience, outside a subagent and every slug-prefix fence. Its facts then save as a
* caller with no member page saves them, on the subject's page, and its forget reaches a fact off its member page the
* same way; a fact it asks to keep private, or one the page or the brain's default keeps private, stays on its member
* page. Every other member caller keeps its member page (GST-359 C2).
*/
export function ownerSpeaksForItself(ctx: Pick<OperationContext, 'remote' | 'viaSubagent' | 'allowedSlugPrefixes' | 'auth'>): boolean {
const access = currentCallerAccess();
return ctx.remote !== false && access.owner && !access.actor && access.audience === null && ctx.viaSubagent !== true
&& !ctx.allowedSlugPrefixes?.length && !ctx.auth?.boundSlugPrefixes && !ctx.auth?.fenceProjectionDegraded;
}
/**
* GST-2249 W1: a save made for an attested person (x-qm-actor) stays on that person's member page. Sharing it would be
* a write every reader of the source sees, made with no owner approval, so remember refuses share: true (and an explicit
* visibility "world") at the call, and a stored write that carries it is refused when it is prepared.
*/
export function attestedShareRefused(make: (code: 'invalid_params', message: string, suggestion: string) => OperationError): OperationError {
return Object.assign(make('invalid_params',
'remember: a fact saved for a person (x-qm-actor) stays on that person\'s own member page and is never shared with every reader of the source; nothing was saved.',
'Retry with no share and no visibility to keep the fact on the person\'s own member page. Knowledge for the whole team waits for the brain owner: propose it as a dated timeline entry or a link with memory_propose, which holds it until the owner approves.'),
{ reason: 'attested_share_refused' });
}
/** Whether a member page is that member's own: its readers are exactly the member (a squatted or widened page is not). */
export function memberPageIsOwn(slug: string, frontmatter: unknown): boolean {
const readers = normalizeReaders(frontmatter);
return readers?.length === 1 && readers[0] === `member:${slug.slice(MEMBER_PAGE_PREFIX.length)}`;
}
/** The refusal for a member fact whose member page names any readers but that member alone. */
export function memberPageNotOwned(slug: string): OperationError {
return opError('permission_denied', `${slug} does not name its member alone as its reader, so no member fact is saved there.`,
`Nothing was saved. The brain host restores readable_by: [member:${slug.slice(MEMBER_PAGE_PREFIX.length)}] on ${slug}, then the fact can be saved again.`);
}
/** A remote write under memory/members/ goes only to the caller's own member page; trusted local callers are unaffected. */
export function assertMemberPageWriter(ctx: Pick<OperationContext, 'remote'>, slug: string, opName: string): void {
if (ctx.remote === false || !slug.startsWith(MEMBER_PAGE_PREFIX)) return;
const member = callerMember();
if (member && slug === memberPageSlug(member)) return;
throw opError('permission_denied', `${opName}: ${slug} is written remotely only by its own member.`,
`Nothing was written. Pages under ${MEMBER_PAGE_PREFIX} hold one member's own facts; write elsewhere, or save a fact with remember as that member.`);
}
/**
* GST-1113: a remote write to the scope page (memory/scope, or under it) is only an attested memory_write that named its
* scope source (access/attest-sources.ts); trusted local callers are unaffected. A receipt read (write_request) is not a
* write: ownRequestAccessible has already kept it to the member who wrote it.
*/
export function assertScopePageWriter(ctx: Pick<OperationContext, 'remote' | 'attestedOp' | 'attestedSource'>, slug: string, opName: string): void {
if (ctx.remote === false || !isScopePageSlug(slug) || opName === 'write_request') return;
if (slug === SCOPE_PAGE_SLUG && ctx.attestedOp === 'memory_write' && ctx.attestedSource !== undefined && currentCallerAccess().actor) return;
throw opError('permission_denied', `${opName}: ${slug} is written remotely only by an attested memory_write to its scope source.`,
`Nothing was written. ${SCOPE_PAGE_SLUG} holds a shared scope's memory; write elsewhere.`);
}
/** Whether a scope page is shared with its whole source: no readers, no privacy and no folder rule narrow it (a squatted page is not). */
export async function scopePageIsShared(engine: Pick<BrainEngine, 'executeRaw'>, page: { source_id: string; slug: string; type?: string | null; frontmatter?: unknown }): Promise<boolean> {
return normalizeReaders(page.frontmatter) === null && !isDerivationPrivate(await withFolderRestricted(engine, page));
}
export function scopePageNotShared(sourceId: string): OperationError {
return opError('permission_denied', `${SCOPE_PAGE_SLUG} in source ${sourceId} names readers, is private or sits under a folder rule, so no scope fact is saved there.`,
`Nothing was saved. The brain host removes readable_by and visibility: private from ${SCOPE_PAGE_SLUG} in ${sourceId}, or the folder rule covering it (the scope source's read grant is its audience), then the fact can be saved again.`,
{ reason: 'scope_page_not_shared' });
}
/** The frontmatter of the scope page its first fact creates: no readers, so the source's read grant is its audience. */
export function scopePageFrontmatter(): string {
return ['---', 'type: note', 'title: Scope memory', '---', ''].join('\n');
}
/** The frontmatter of a member page its first fact creates: the member is its only reader. */
export function memberPageFrontmatter(member: string): string {
return ['---', 'type: note', `title: Memory of ${member}`, 'readable_by:', ` - member:${member}`, '---', ''].join('\n');
}
/**
* The private facts the current caller may read: those on its own member page, while the caller may read that live
* page itself (its readers, folder rules and privacy, as get_page judges it). FALSE outside a member caller record. `alias` is a code-provided facts alias; the
* member id passed ACCESS_ID_RE, whose alphabet has no quote.
*/
export function memberFactAdmitSql(alias: string): string {
const member = callerMember();
if (!member) return 'FALSE';
return `(${alias}.visibility = 'private' AND ${alias}.source_markdown_slug = '${memberPageSlug(member)}' AND EXISTS (
SELECT 1 FROM pages member_page WHERE member_page.source_id = ${alias}.source_id AND member_page.slug = ${alias}.source_markdown_slug
AND member_page.deleted_at IS NULL AND member_page.page_readers && ARRAY['member:${member}']::text[]
AND ${privatePagesFilterForCaller('member_page')}))`;
}
/**
* GST-2407: the facts among `ids` in `sourceId` that sit on the current caller's own member page, by memberFactAdmitSql.
* forget_fact withdraws a remote member's fact only when it is in this set, and memory_recall reports the same set as
* own_page, so the two never disagree. Empty outside a member caller record.
*/
export async function ownMemberFactIds(engine: Pick<BrainEngine, 'executeRaw'>, sourceId: string, ids: readonly number[]): Promise<Set<number>> {
if (!ids.length || !callerMember()) return new Set();
const rows = await engine.executeRaw<{ id: number | string }>(`SELECT id FROM facts WHERE id = ANY($1::bigint[]) AND source_id = $2 AND ${memberFactAdmitSql('facts')}`, [[...ids], sourceId]);
return new Set(rows.map(r => Number(r.id)));
}
/**
* GBRA-575: the private facts the current caller's private-facts grant admits: a fact stamped private in a source the
* grant lists by id (privateFactSources) whose holding, provenance and entity pages are none of member,
* derivation-private (private, privacy alias, readable_by, folder rule), missing or quarantined (factPagesOpenSql, the
* same pages `gbrain repair open-facts` refuses to open), and that has a page to check: never an unpaged or
* transcript-lane fact (unpagedFactSql), conversation archive included. FALSE outside such a grant. Source ids passed
* isValidSourceId, so they embed as literals.
*/
export function grantedPrivateFactSql(alias: string): string {
const sources = privateFactSources();
if (!sources.length) return 'FALSE';
return `(${alias}.visibility = 'private' AND ${alias}.source_id IN (${sources.map(s => `'${s}'`).join(', ')}) AND NOT COALESCE(${unpagedFactSql(alias)}, false) AND ${factPagesOpenSql(alias)})`;
}
/** A remote fact read's visibility list as SQL: the listed values, widened only by memberFactAdmitSql and grantedPrivateFactSql. */
export function factVisibilitySql(alias: string, visibility: readonly string[]): string {
const known = (['world', 'private'] as const).filter(v => visibility.includes(v));
const listed = known.length ? `${alias}.visibility IN (${known.map(v => `'${v}'`).join(', ')})` : 'FALSE';
if (known.includes('private')) return listed;
const widened = [memberFactAdmitSql(alias), grantedPrivateFactSql(alias)].filter(sql => sql !== 'FALSE');
return widened.length ? `(${[listed, ...widened].join(' OR ')})` : listed;
}
/**
* Facts on any owned memory page (a member page or a scope page), as SQL: writers that dedup, supersede or contest never
* cross from one such page to another or to an ordinary page.
*/
export function onOwnedMemoryPageSql(alias: string): string {
return `(starts_with(COALESCE(${alias}.source_markdown_slug, ''), '${MEMBER_PAGE_PREFIX}') OR COALESCE(${alias}.source_markdown_slug, '') = '${SCOPE_PAGE_SLUG}')`;
}
/**
* GST-359 D: the withdrawal-ledger subject of a fact, as SQL. A fact on an owned memory page (a member page, GST-1113 a
* scope page) is withdrawn for that page alone (its slug), so forgetting it never reaches another copy of the same claim;
* any other fact keeps its entity ('*' without one, and GBRA-574 '*' for an unbacked entity).
*/
export function factWithdrawalSubjectSql(alias: string): string {
return `CASE WHEN ${onOwnedMemoryPageSql(alias)} THEN ${alias}.source_markdown_slug WHEN ${unbackedEntitySql(alias)} THEN '*'
ELSE COALESCE(${alias}.entity_slug, '*') END`;
}
/**
* Whether withdrawal row `w` covers fact `f`, as SQL: every subject ('*'), the fact's entity, or the owned memory page it
* sits on. GST-2346: a fact on a member page is covered by that page's own withdrawals alone, as the insert guards
* judge it (facts/withdrawal-schema.ts): a withdrawal of another subject expired it when it was made, or the row is one
* its member saved since, checked against the claims that member reads.
*/
export function withdrawalCoversFactSql(w: string, f: string): string {
return `(CASE WHEN starts_with(COALESCE(${f}.source_markdown_slug, ''), '${MEMBER_PAGE_PREFIX}') THEN ${w}.subject = ${f}.source_markdown_slug
ELSE ${withdrawalReachedFactSql(w, f)} END)`;
}
/** Whether withdrawal row `w` expired fact `f` when it was made (recordFactWithdrawal's reach), as SQL: every subject ('*'), the fact's entity, any subject but an owned memory page for an unbacked entity, or the owned memory page it sits on. */
export function withdrawalReachedFactSql(w: string, f: string): string {
return `(${w}.subject = '*' OR ${w}.subject = COALESCE(${f}.entity_slug, '*') OR (${unbackedEntitySql(f)} AND NOT ${ownedMemorySubjectSql(`${w}.subject`)}) OR (${onOwnedMemoryPageSql(f)} AND ${w}.subject = ${f}.source_markdown_slug))`;
}
/** The owned memory page a claim is checked on for withdrawals, or null: `slug` when it is one, so a page-scoped withdrawal applies there alone. */
export function ownedPageWithdrawalSubject(slug: string | null | undefined): string | null {
return slug && (slug.startsWith(MEMBER_PAGE_PREFIX) || slug === SCOPE_PAGE_SLUG) ? slug : null;
}
/**
* Facts whose source page names readers or sits under a folder rule, as SQL. Derivations that write their output onto
* another page (consolidation into takes, relinking onto an entity page) skip them: the output would lose the readers.
*/
export function readersSourcedFactSql(alias: string): string {
return `EXISTS (SELECT 1 FROM pages readers_page WHERE readers_page.source_id = ${alias}.source_id AND readers_page.slug = ${alias}.source_markdown_slug
AND (readers_page.page_readers IS NOT NULL OR readers_page.frontmatter ? 'readable_by' OR ${folderRestrictedSql('readers_page')}))`;
}
/**
* A short hash of everything about the current caller that changes what a read returns (the attested actor, the
* member identity, an audience), or '' outside a member or audience record. Cache and session-state keys append it.
*/
export function callerIdentityKey(): string {
const access = currentCallerAccess();
if (!access.actor && !access.identity.length && !access.audienceIdentities.length && !access.audience) return '';
const parts = { actor: access.actor ? [access.actor.system, access.actor.member] : null, identity: access.identity, audience: access.audienceIdentities, entries: access.audience,
...(access.lineage ? { owner_reads: access.owner ? (access.ownerReadsRestricted ? 'restricted' : 'lineage') : 'member_lineage' } : {}),
...(access.audienceKindMembers.length ? { audience_kind: access.audienceKindMembers } : {}),
...(access.labelledOnly ? { labelled_only: true } : {}) };
return createHash('sha256').update(JSON.stringify(parts)).digest('hex').slice(0, 16);
}
/**
* A per-session state key (the delta cursor) for the current caller: `base` for a credential reading as itself, so a
* change to its member's groups or the upgrade keeps its cursor; otherwise `base` plus the person the call serves (the
* attested member, or the asserted audience entries), never the group-derived identity.
*/
export function callerSessionKey(base: string | null): string | null {
const access = currentCallerAccess();
const person = access.actor ? { actor: [access.actor.system, access.actor.member] } : access.audience ? { audience: [...access.audience].sort() } : null;
return person ? `${base ?? 'remote'}#id:${createHash('sha256').update(JSON.stringify(person)).digest('hex').slice(0, 16)}` : base;
}
/**
* Whether a stored write's actingFor is the current caller's, compared the way submissionAuthority stores it: the same
* attested system and member, else the same audience (distinct entries, any order), else neither.
*/
export function sameAttestedActor(stored: unknown): boolean {
const { actor, audience } = currentCallerAccess();
if (actor) {
const row = stored && typeof stored === 'object' && !Array.isArray(stored) ? stored as { system?: unknown; member?: unknown } : null;
return !!row && row.system === actor.system && row.member === actor.member;
}
if (!audience?.length) return stored === undefined || stored === null;
const key = (list: readonly unknown[]) => [...new Set(list)].map(String).sort().join(',');
return Array.isArray(stored) && key(stored) === key(audience);
}