Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { randomUUID } from 'node:crypto';
import { pageQuarantinedNotice } from '../quarantine.ts';
import { indexRestoredNotice } from './git-door.ts';
import { fenceNormalizedNotice, type FencesNormalized } from '../fence-repair/report.ts';
import { parseFenceRepairReceipt } from '../fence-repair/receipt.ts';
import { realpathSync } from 'node:fs';
import { isAbsolute, join, relative, resolve, sep } from 'node:path';
import { isHostAbsolutePath } from '../path-confine.ts';
import type { OperationContext } from '../ops/contract.ts';
import { OperationError } from '../ops/contract.ts';
import { admitChangeReason, CHANGE_REASON_OPERATIONS } from './change-reason.ts';
import { grantedWriteSource, writeGrantRefusal } from './write-grant.ts';
import { VERSION } from '../../version.ts';
import { ownerBuildMismatch } from './publication-failure.ts';
import { enforceClientSlugFence, enforceSubagentSlugFence, isLegacyStoredPageSlug, normalizeSlugPrefix, parseSourceIdParam, requireWritablePage, validatePageSlug } from '../ops/context.ts';
import { suffixedSlugAdmission } from './suffixed-slug.ts';
import { defaultSlug, detectBinaryNullByte, explicitCaptureType, mergeCaptureFrontmatter, normalizeForHash } from '../capture-content.ts';
import { computeContentHash } from '../ingestion/types.ts';
import { resolveSlugForPath } from '../sync.ts';
import { scannerSlugRootMode, scannerSourcePath } from '../write-through.ts';
import { sha256 } from './digest.ts';
import { receiptReservation } from './receipt-bytes.ts';
import { assertPersistenceAccepting, estimatedRetryAfterMs, waiterOnlyOwner, onPersistenceLane, waitForWrite, writeResponse } from './service.ts';
import { parseWireWriteWaitMs } from './write-wait.ts';
import { withRefreshFenceBudget } from './admission-retry.ts';
import { assertTimelineNotOmitted, isTimelineSection, timelineSectionOf, type TimelineSection } from './timeline-omission.ts';
import { contentOriginTier } from '../trust/tier.ts';
import { PAGE_MAX_BYTES } from '../page-size-policy.ts';
import { contentSizeHold, frontmatterBodyOffset, parseMarkdownHead } from '../markdown.ts';
import { dataFrontmatter, dumpFrontmatterYaml } from '../data-frontmatter.ts';
import { throwIfHeld } from '../trust/gate-outcomes.ts';
import { admitWrite, assertPageRequestIdentity, assertReplayIntent, getWriteRequest, intentDigest, type WriteAdmission } from './journal.ts';
import { submissionAuthority, authorizeStoredRequest } from './authority.ts';
import { currentVerifiedLocalWriter, hostIdFor, readLocalWriter, registerLocalWriter, withVerifiedLocalRegistration } from './identity.ts';
import type { BrainEngine } from '../engine.ts';
import { claimWorktree, getWorktreeBinding } from './ownership.ts';
import { clientRequestIdOf, parseMutationPrecondition } from './preconditions.ts';
import { assertPurgeParams } from './purge-params.ts';
import type { Principal, WriteRequest } from './model.ts';
import { normalizeSubagentPageInput, undeclaredPageTypeWarning, type PageTypeWarning } from './page-input.ts';
import { assertKnowledgePublicationAllowed } from '../shared-skills/knowledge-guard.ts';
import { decideUnboundWrite, isUnboundSourcePage } from './unbound-source.ts';
import { assertRestoreOrigin } from './detached-pages.ts';
import { isSourceDbOnlySlug } from './source-storage.ts';
import { colonSlugWindowsRefusal, isWindowsColonTarget } from './native-file-target.ts';
import { CALLER_CONTENT_OPERATIONS, publishesDatabaseOnly } from './page-prepare.ts';
import { isSegmentedPage } from '../page-body/page-shape.ts';
import { liveSearchable } from './searchable.ts';
import { ADMISSION_SOURCE_SQL, cachedPreadmitBrain, dropPreadmitCache, preadmitReads, preadmitRecheckFailed } from './preadmit-cache.ts';
import { pipelined } from '../page-state/transactions.ts';
import { holdsSummarizedToolCalls, isQuotedPageType, quotesTier, unquoteTranscriptText } from '../search/transcript-quote.ts';
import { readStoredBody } from '../facts/file-body-guard.ts';
import { isMirrorOnlyPage, sourceMirrorReadOnly } from './mirror-read-only.ts';
import { perCallWriteSource } from '../access/attest-sources.ts';
import type { GuestSource } from '../guests/sources.ts';
import { admitGuestOperation, assertGuestFrontmatter, assertGuestReaders, GUEST_NOTE_INTENT_KEY, guestPageImmutable, guestSourcesUnreadable, refuseRemoteGuestDelete, schemaBehindGuests } from '../guests/admission.ts';
import { currentCallerAccess } from '../search/private-visibility.ts';
import { assertStorageSourceWriter } from '../storage-manifest/door.ts';
export async function requestPrincipalForContext(ctx: OperationContext): Promise<Principal> {
// #5994: a failed-writes replay is admitted under the original writer.
if (ctx.replayAuthority) return { ...ctx.replayAuthority.principal };
if (ctx.auth?.principal) return { ...ctx.auth.principal };
const verified = currentVerifiedLocalWriter();
if (verified) return verified.principal;
const lane = ctx.remote === false ? 'cli' : 'stdio';
const local = await readLocalWriter(ctx.engine, lane);
return { kind: lane === 'cli' ? 'local_cli' : 'local_stdio', id: local.id };
}
/** A local installation registers once; revoked records are never silently replaced. */
export async function initializeLocalPersistence(ctx: OperationContext): Promise<void> {
if (!ctx.auth && !currentVerifiedLocalWriter()) await registerLocalWriter(ctx.engine, ctx.remote === false ? 'cli' : 'stdio');
}
const flatSql = (sql: string) => sql.replace(/\s+/g, ' ').trim();
/**
* Pre-admission reads every page of one batch makes with the same arguments:
* the source row, the worktree binding, the writer registration, the shared
* skillpack roots, the persistence identity and config values, and a managed
* import's source-root and company-profile checks. All of them are rechecked
* under lock by the admission transaction or by publication.
*/
type AdmissionSource = { incarnation: string; archived: boolean; local_path: string | null; kind: string | null; role: string | null; guest_writers: string[] | null; guest_trust_ceiling: string | null; guest_sources_hidden: boolean };
const BATCH_SHARED_READS = new Set([
ADMISSION_SOURCE_SQL,
'SELECT s.source_id,s.source_incarnation,s.worktree_id,s.relative_path, s.topology_generation::text AS topology_generation,w.owner_host_id,w.owner_epoch::text AS owner_epoch,w.state, h.local_path,h.coordination_path FROM persistence_source_bindings s JOIN persistence_worktrees w ON w.id=s.worktree_id LEFT JOIN persistence_host_bindings h ON h.worktree_id=w.id AND h.host_id=$2::uuid WHERE s.source_id=$1',
'SELECT lane,revoked_at,grant_ceiling FROM persistence_local_writers WHERE id=$1::uuid',
'SELECT local_path FROM sources WHERE id=$1 AND incarnation=$2::uuid',
'SELECT brain_id FROM persistence_brain WHERE singleton=1',
'SELECT value FROM config WHERE key=$1',
"SELECT config,incarnation FROM sources WHERE id=$1",
"SELECT r.id FROM source_ingestion_receipts r JOIN sources s ON s.id=r.source_id AND s.incarnation=r.source_incarnation WHERE r.source_id=$1 AND r.profile='company-brain' LIMIT 1",
'SELECT s.id,s.local_path,h.local_path AS worktree_path,b.relative_path FROM sources s LEFT JOIN persistence_source_bindings b ON b.source_id=s.id AND b.source_incarnation=s.incarnation LEFT JOIN persistence_host_bindings h ON h.worktree_id=b.worktree_id AND h.host_id=$1::uuid WHERE NOT s.archived',
]);
/**
* A managed import's no-op screen (import-mutations.ts) only decides that a
* file is skipped; a file it does not skip is admitted and rechecked under
* lock. It also answers the local writer's credential check and the shared
* skill pack roots once per batch.
*/
export const SCREENING_SHARED_READS: ReadonlySet<string> = new Set([
'SELECT lane,credential_hash,grant_ceiling,revoked_at FROM persistence_local_writers WHERE id=$1::uuid',
'SELECT p.source_id,p.source_incarnation,s.local_path AS source_root, h.local_path AS worktree_root,b.relative_path FROM shared_skill_packs p JOIN sources s ON s.id=p.source_id AND s.incarnation=p.source_incarnation LEFT JOIN persistence_source_bindings b ON b.source_id=p.source_id AND b.source_incarnation=p.source_incarnation LEFT JOIN persistence_host_bindings h ON h.worktree_id=b.worktree_id AND h.host_id=$1::uuid',
]);
export function batchSharedReads(engine: BrainEngine, extra?: ReadonlySet<string>): BrainEngine {
const reads = new Map<string, Promise<unknown>>();
const once = <T>(id: string, read: () => Promise<T>): Promise<T> => {
let value = reads.get(id) as Promise<T> | undefined;
if (!value) { value = read(); reads.set(id, value); value.catch(() => reads.delete(id)); }
return value;
};
return new Proxy(engine, { get(target, key) {
if (key === 'executeRaw') return (sql: string, params?: unknown[], opts?: { signal?: AbortSignal }) =>
BATCH_SHARED_READS.has(flatSql(sql)) || extra?.has(flatSql(sql)) ? once(JSON.stringify([flatSql(sql), params ?? null]), () => target.executeRaw(sql, params, opts)) : target.executeRaw(sql, params, opts);
if (key === 'getConfig') return (name: string) => once(`config:${name}`, () => target.getConfig(name));
if (key === 'getAllConfig' && extra) return () => once('config:*', () => target.getAllConfig()).then(all => ({ ...all }));
const value = Reflect.get(target, key, target);
return typeof value === 'function' ? value.bind(target) : value;
} });
}
/**
* #6007: prepares one batch's page admissions under one writer verification
* and one read snapshot. `run` gets the caller's context (for a page that may
* claim the source's worktree) and a context whose engine answers the batch's
* shared pre-admission reads once; the local writer is verified once for the
* whole call instead of once per page.
*/
export async function withBatchAdmission<T>(ctx: OperationContext, run: (own: OperationContext, shared: OperationContext) => Promise<T>): Promise<T> {
const shared: OperationContext = { ...ctx, engine: batchSharedReads(ctx.engine) };
if (ctx.auth || currentVerifiedLocalWriter()) return run(ctx, shared);
await initializeLocalPersistence(ctx);
const registration = await readLocalWriter(ctx.engine, ctx.remote === false ? 'cli' : 'stdio');
return withVerifiedLocalRegistration(ctx.engine, registration, () => run(ctx, shared));
}
/** Validate explicit routing before any admission, including dry-run adapters. */
/**
* validatePageSlug, except that delete and restore may name a slug an older
* gbrain stored and today's grammar refuses, when an existing row in
* `sourceId` holds exactly that slug (#6212). Such a row publishes
* database-only (page-prepare.ts prepareFileTarget).
*/
export async function validateMutationSlug(ctx: OperationContext, operation: string, slug: string, sourceId: string): Promise<void> {
if ((operation === 'delete_page' || operation === 'restore_page') && isLegacyStoredPageSlug(slug)
&& await ctx.engine.readPageSnapshot(slug, { sourceId, includeDeleted: true })) return;
validatePageSlug(slug);
}
export function pageMutationSource(ctx: OperationContext, params: Record<string, unknown>, operation: string): string {
const sourceId = parseSourceIdParam(params.source_id, operation) ?? ctx.sourceId ?? 'default';
if (sourceId === '__all__') {
throw new OperationError('invalid_params', 'A mutation must target exactly one source.',
`Pass source_id as one source (for example ${ctx.sourceId && ctx.sourceId !== '__all__' ? ctx.sourceId : 'default'}); writes never fan out across sources.`);
}
const granted = grantedWriteSource(ctx);
if (ctx.remote !== false && sourceId !== granted && !perCallWriteSource(ctx, sourceId)) {
throw writeGrantRefusal(ctx,
`This connection writes only to source ${granted}. Pass source_id ${granted} (or omit it), or ask the brain host's operator to grant write access to ${sourceId}.`);
}
return sourceId;
}
/**
* #5622: a trusted `capture --file` path becomes a source-relative physical path
* or 'cli-file'; the host path is never stored. Returns the slug sync would give
* that file, so only a capture under that slug binds the file as its origin.
*/
async function resolveCaptureFile(ctx: OperationContext, sourceId: string, p: Record<string, unknown>): Promise<string | null> {
if (Object.hasOwn(p, 'capture_path')) {
throw new OperationError('invalid_params', 'capture_path is reserved for the capture owner.', 'Drop capture_path and pass the text as content; gbrain sets the capture path itself.');
}
if (p.local_file === undefined) return null;
if (ctx.remote !== false || typeof p.local_file !== 'string' || !isAbsolute(p.local_file)) {
throw new OperationError('invalid_params', 'Capture file paths are accepted only from the trusted local CLI.',
'Read the file yourself and pass its content; file capture runs through the gbrain capture command on the brain host.');
}
const file = p.local_file;
delete p.local_file;
const [source] = await ctx.engine.executeRaw<{ local_path: string | null }>('SELECT local_path FROM sources WHERE id=$1', [sourceId]);
const binding = await getWorktreeBinding(ctx.engine, sourceId);
let root = binding ? binding.owner_host_id === hostIdFor(ctx.engine) && binding.local_path ? join(binding.local_path, binding.relative_path) : null
: source?.local_path || (sourceId === 'default' ? await ctx.engine.getConfig('sync.repo_path') : null);
if (root && !isHostAbsolutePath(root)) root = null;
let origin: string | null = null;
try { if (root) origin = relative(realpathSync(root), realpathSync(file)); } catch { /* unreadable or absent root */ }
if (!root || !origin || isAbsolute(origin) || origin === '..' || origin.startsWith(`..${sep}`) || !/\.mdx?$/i.test(origin)) {
p.source_uri = 'cli-file';
return null;
}
const capturePath = origin.split(sep).join('/');
p.capture_path = capturePath;
const canonicalRoot = realpathSync(root);
return resolveSlugForPath(scannerSourcePath(canonicalRoot, join(canonicalRoot, capturePath), await scannerSlugRootMode(ctx.engine, sourceId, canonicalRoot)));
}
export function pendingAwareResponse(ctx: OperationContext, row: WriteRequest): Record<string, unknown> {
try { return writeResponse(row, { retryAfterMs: estimatedRetryAfterMs(ctx.engine, 1), waiterOnlyOwner: waiterOnlyOwner(ctx.engine) }); } catch (error) {
// #5929: a trusted local caller is told when an owner on another build ran the failed attempt.
const mismatch = ctx.remote === false ? ownerBuildMismatch(row.error_detail, VERSION) : null;
if (mismatch && error instanceof OperationError) { error.why = mismatch.why; error.fix = mismatch.fix; }
throw error;
}
}
/**
* A committed reply whose outcome left the projection pending says whether search sees the page now (searchable.ts), in
* the reply and its `write_request`; `projection: 'pending'` stays only while it still is.
*/
export async function withLiveSearchable(ctx: OperationContext, response: Record<string, unknown>): Promise<Record<string, unknown>> {
if (response.searchable !== 'pending') return response;
const live = await liveSearchable(ctx, response as Parameters<typeof liveSearchable>[1]);
const settle = (fields: Record<string, unknown>) => {
const { projection, ...rest } = fields;
return { ...(live.searchable === 'pending' ? { projection } : {}), ...rest, ...live };
};
const receipt = response.write_request as Record<string, unknown> | undefined;
return { ...settle(response), ...(receipt ? { write_request: settle(receipt) } : {}) };
}
/** #6188 (D21): a write whose fence Tier 1 rewrote carries one `fence_normalized` coaching notice; a strict write whose door restored a stale index entry carries `git_index_restored`. */
export function emitFenceNotice(ctx: Pick<OperationContext, 'emitNotice'>, response: Record<string, unknown>, slug?: string): void {
const report = response.fences_normalized as FencesNormalized | undefined;
if (report) ctx.emitNotice?.(fenceNormalizedNotice(report, slug));
// #6259: a write the content-quality gate quarantined says so (`quarantined` plus one safety notice).
const quarantined = response.quarantined as { reason: string; detail: string } | undefined;
if (quarantined && slug) ctx.emitNotice?.(pageQuarantinedNotice(slug, quarantined, 'write'));
const restored = (response.persistence as { git_index_restored?: string[] } | undefined)?.git_index_restored;
if (restored?.length) ctx.emitNotice?.(indexRestoredNotice(restored));
}
/** Owner-internal `put_page` kinds the trusted local file writers (import, frontmatter repair, quarantine clear) submit; every other caller is refused them. */
const OWNER_FILE_INTENTS: ReadonlySet<string> = new Set(['managed_file_import', 'managed_file_repair', 'managed_quarantine_clear']);
/** #6007: a `put_pages` child: its batch, its position and the batch size are part of its identity. */
export interface PageBatchMember { id: string; index: number; size: number; requestId: string; repeats?: number[] }
export async function submitPageMutation(ctx: OperationContext,
input: { operation: string; params: Record<string, unknown>; waitMs?: number; managedFileImport?: true; timelineSection?: TimelineSection; databaseOnly?: 'overwrite_restore' | 'detached';
/** commit_page_upload: `params.body_ref` names the caller's sealed upload session (persistence/page-upload.ts). */
stagedBody?: true }): Promise<Record<string, unknown>> {
assertPersistenceAccepting(ctx.engine);
// #6007: wait_ms is a reply deadline from arrival, never part of the write's identity.
const arrived = performance.now();
const { wait_ms: wireWait, ...params } = input.params;
const wireWaitMs = parseWireWriteWaitMs(wireWait);
const waitMs = () => wireWaitMs !== undefined ? Math.max(0, wireWaitMs - (performance.now() - arrived)) : input.waitMs ?? ctx.writeWaitMs;
// Phase 4.2: pre-admission reads that admission rechecks come from this process's cache; a refusal the
// cache could explain drops it and prepares the write once more, uncached, so it ends as it would without it.
const cached = await preadmitReads(ctx.engine);
let prepared = await preparePageAdmission(cached ? { ...ctx, engine: cached } : ctx, { ...input, params });
if (prepared.prior) return withLiveSearchable(ctx, throwIfHeld(pendingAwareResponse(ctx, await waitForWrite(ctx.engine, prepared.prior, ctx.config, waitMs())), false));
const brainId = cached ? cachedPreadmitBrain(ctx.engine) : undefined;
// Phase 4.4: the admission transaction runs on the warm single-write lane when it is free.
// GST-1387: an explicit wait_ms also bounds the refresh-fence wait, so wait_ms 0 is refused at once, never held.
const admit = (admission: WriteAdmission) => withRefreshFenceBudget(() => onPersistenceLane(ctx.engine, transaction => admitWrite(ctx.engine, admission, undefined, transaction),
() => admitWrite(ctx.engine, admission)), wireWaitMs !== undefined ? waitMs() : undefined);
let row: WriteRequest;
try { row = await admit(brainId ? { ...prepared.admission, brainId } : prepared.admission); }
catch (error) {
if (!cached || !preadmitRecheckFailed(error)) throw error;
dropPreadmitCache(ctx.engine);
prepared = await preparePageAdmission(ctx, { ...input, params: { ...params, request_id: prepared.admission.requestId } });
if (prepared.prior) return withLiveSearchable(ctx, throwIfHeld(pendingAwareResponse(ctx, await waitForWrite(ctx.engine, prepared.prior, ctx.config, waitMs())), false));
row = await admit(prepared.admission);
}
const response = await withLiveSearchable(ctx, throwIfHeld(pendingAwareResponse(ctx, await waitForWrite(ctx.engine, row, ctx.config, waitMs())), false));
emitFenceNotice(ctx, response, row.slug);
return { ...response, ...(prepared.typeWarning ? { type_warning: prepared.typeWarning } : {}), ...(prepared.slugAdvisory ? { slug_advisory: prepared.slugAdvisory } : {}) };
}
/**
* #8042: a remote put_page (put_pages too) of a quoted page's get_page content writes the page body, not the fences
* get_page added (search/transcript-quote.ts). A fence naming the page is removed when its stored type or the type the
* new content declares is one get_page quotes (either, so a retype keeps the body), or (GST-687) when the stored page is
* below the owner's tier, which get_page quotes too; an owner-tier note keeps a fence naming it only when its stored body
* already holds one, so a fence read before a claim raised the page's tier is never stored.
* GST-687: content carrying a tool-call summary that only the neutralized read of the stored chat page holds (get_page's
* reading shape, fetch) is refused, so a read-then-write never replaces a stored tool call with its summary.
*/
/** Every string in `value` with the fences naming `slug` removed (get_page's quotedPageMeta, reversed). */
function unquotedStrings(value: unknown, slug: string): unknown {
return typeof value === 'string' ? unquoteTranscriptText(value, slug)
: Array.isArray(value) ? value.map(v => unquotedStrings(v, slug))
: value && typeof value === 'object' && !(value instanceof Date) ? Object.fromEntries(Object.entries(value).map(([k, v]) => [k, unquotedStrings(v, slug)])) : value;
}
/**
* #8377: a quoted read's reading shape fences the title and each frontmatter string as `slug`'s (a whole-markdown read is
* fenced once instead, and its metadata is the page's own). YAML indents those fences, so the body's unquote misses them.
* #8384: only the top-level keys that held a fence are rewritten; every other line keeps the bytes the caller sent, so a
* naive datetime keeps its brain-timezone reading. A fenced key not found on its own line, or a line rewrite that does not
* parse back to the unquoted values (a flow mapping continued on an unindented line, an anchor another key aliases),
* rewrites the whole block.
*/
function unquotedFrontmatter(sent: string, content: string, slug: string): string {
const offset = frontmatterBodyOffset(content);
if (!offset || !frontmatterBodyOffset(sent) || !content.slice(0, offset).includes('```text')) return content;
const { frontmatter } = parseMarkdownHead(content);
const data = unquotedStrings(frontmatter, slug) as Record<string, unknown>;
const fenced = new Set(Object.keys(data).filter(k => JSON.stringify(data[k]) !== JSON.stringify(frontmatter[k])));
if (!fenced.size) return content;
const lines = content.slice(0, offset).split('\n');
const open = lines.findIndex(l => l.trim() === '---');
const close = lines.findIndex((l, i) => i > open && l.trim() === '---');
const out = lines.slice(0, open + 1);
for (let i = open + 1; i < close;) {
let end = i + 1;
while (end < close && /^(?:[ \t]|-(?:[ \t]|\r?$)|\r?$)/.test(lines[end]!)) end++;
const m = /^(?:"([^"]*)"|'([^']*)'|([^\s#'"-][^:]*?))[ \t]*:(?:[ \t]|\r?$)/.exec(lines[i]!);
const key = m?.[1] ?? m?.[2] ?? m?.[3];
if (key !== undefined && fenced.delete(key)) {
const eol = lines[i]!.endsWith('\r') ? '\r' : '';
out.push(...dumpFrontmatterYaml({ [key]: data[key] }).trimEnd().split('\n').map(l => l + eol));
} else out.push(...lines.slice(i, end));
i = end;
}
const whole = dataFrontmatter.stringify('', data) + content.slice(offset);
if (fenced.size) return whole;
const partial = [...out, ...lines.slice(close)].join('\n') + content.slice(offset);
try {
return JSON.stringify(parseMarkdownHead(partial).frontmatter) === JSON.stringify(data) ? partial : whole;
} catch {
return whole;
}
}
async function unquotedPutContent(engine: BrainEngine, sourceId: string, slug: string, content: string): Promise<string> {
const bodyUnquoted = unquoteTranscriptText(content, slug, true);
const unquoted = unquotedFrontmatter(content, bodyUnquoted, slug);
const summarized = /, arguments omitted\]/.test(unquoted);
const quotedType = isQuotedPageType(String(parseMarkdownHead(unquoted).frontmatter.type ?? ''));
if (!summarized && (unquoted === content || quotedType)) return unquoted;
const [stored] = await engine.executeRaw<{ type: string | null; trust_tier: string | null; title: string | null; frontmatter: unknown }>(
'SELECT type, trust_tier, title, frontmatter FROM pages WHERE source_id = $1 AND slug = $2', [sourceId, slug]);
// Compared with the stored body's tool calls; a segmented page reads NULL inline columns, so its summarized round trip is refused.
const losesCalls = async () => {
const body = await readStoredBody(engine, sourceId, slug);
return body?.compiled_truth == null || holdsSummarizedToolCalls(`${body.compiled_truth}\n${body.timeline ?? ''}`, unquoted);
};
if (summarized && stored && isQuotedPageType(stored.type) && await losesCalls()) {
throw new OperationError('invalid_params', `put_page: this content has tool calls that a read of ${slug} summarized; writing it would replace the stored calls with their summaries.`,
'Nothing was written. Change the page with edit_page, or read it with get_page include_content: true (its content keeps the stored text) and write that back.');
}
if (unquoted === content || quotedType) return unquoted;
if (!stored) return content;
if (isQuotedPageType(stored.type) || quotesTier(stored.trust_tier)) return unquoted;
// An owner-tier page keeps a fence naming it only when its stored body already holds one: a fence read while the page sat
// below the owner's tier (before a claim or backfill raised it, or from a quoted version) is a read's, not the page's.
// Its title and frontmatter are judged the same way, by the stored title and frontmatter.
const body = await readStoredBody(engine, sourceId, slug);
const storedText = `${body?.compiled_truth ?? ''}\n${body?.timeline ?? ''}`;
const kept = body?.compiled_truth != null && unquoteTranscriptText(storedText, slug) === storedText ? bodyUnquoted : content;
const storedMeta = [stored.title, typeof stored.frontmatter === 'string' ? JSON.parse(stored.frontmatter) : stored.frontmatter];
return JSON.stringify(unquotedStrings(storedMeta, slug)) === JSON.stringify(storedMeta) ? unquotedFrontmatter(content, kept, slug) : kept;
}
/**
* Every check a page mutation passes before it is journaled, without admitting
* it: either the authorized prior request with this request_id (a replay), or
* the admission to submit. `put_pages` admits several of these together.
*/
export async function preparePageAdmission(ctx: OperationContext,
input: { operation: string; params: Record<string, unknown>; managedFileImport?: true; batch?: PageBatchMember; timelineSection?: TimelineSection;
/** #6712 `repair overwritten-edits`: publish to the database only, so the restore never rewrites the committed file. */
databaseOnly?: 'overwrite_restore' | 'detached'; stagedBody?: true }
): Promise<{ prior: WriteRequest; admission?: undefined; typeWarning?: undefined; slugAdvisory?: undefined } | { prior?: undefined; admission: WriteAdmission; typeWarning: PageTypeWarning | null; slugAdvisory: string | null }> {
if (input.operation === 'put_page' && ['kind', 'preview', 'backup_reference'].some(key => Object.hasOwn(input.params, key))) {
if (ctx.remote !== false || input.managedFileImport !== true || !OWNER_FILE_INTENTS.has(String(input.params.kind)) ||
['preview', 'backup_reference'].some(key => Object.hasOwn(input.params, key))) {
throw new OperationError('invalid_params', 'Reserved persistence fields cannot be submitted through put_page. Use trusted local reconciliation administration.',
'Drop kind, preview and backup_reference from put_page; reconciling a canonical file runs through gbrain sources reconcile on the brain host.');
}
}
// #8765 review: a managed_sync_ kind marks managed sync's own rows, so no page write may carry one (a capture's event kind).
if (typeof input.params.kind === 'string' && input.params.kind.startsWith('managed_sync_')) {
throw new OperationError('invalid_params', `kind ${input.params.kind} is reserved for managed sync, so nothing was written.`,
'Use another kind, or drop kind.');
}
const bodyRefKind = (input.params.body_ref as { kind?: unknown } | null | undefined)?.kind;
const staged = input.stagedBody === true && ['put_page', 'append_page'].includes(input.operation) && bodyRefKind === 'staging';
const imported = input.managedFileImport === true && input.operation === 'put_page' && bodyRefKind === 'input_file';
if (Object.hasOwn(input.params, 'body_ref') && ((!staged && !imported) || Object.hasOwn(input.params, 'content') || Object.hasOwn(input.params, 'text'))) {
throw new OperationError('invalid_params', 'body_ref is reserved for commit_page_upload.',
'Drop body_ref and send the page as content; a page larger than one request goes through begin_page_upload, upload_page_part and commit_page_upload.');
}
// #6188: a fence repair's receipt is recorded only by the trusted local fence repair, never by a caller.
if (Object.hasOwn(input.params, 'fence_repair') && (input.operation !== 'put_page' || ctx.remote !== false || !parseFenceRepairReceipt(input.params.fence_repair))) {
throw new OperationError('invalid_params', 'fence_repair is reserved for the trusted fence repair.',
'Drop fence_repair and submit the page without it; gbrain repair fences records its own receipt on the brain host. To fix a malformed facts or takes fence, correct it in content (or write facts with remember and takes with takes_add); a held file is repaired by the brain host operator with gbrain repair fences, so ask the user to run it.');
}
// G6: the hidden-row merge of an untrusted capture's body (page-prepare.ts) is opted into only by the trusted local ingest_capture
// handler, whose caller never saw the page's non-world rows; a remote put_page has it already, through its authority.
// GST-2891: and by an enforced member's put_page or edit_page (cli/enforced-member.ts), whose reads left out held rows.
if (Object.hasOwn(input.params, 'keep_hidden_rows') && (!['put_page', 'edit_page'].includes(input.operation) || ctx.remote !== false || input.params.keep_hidden_rows !== true)) {
throw new OperationError('invalid_params', 'keep_hidden_rows is reserved for trusted local ingestion.',
'Drop keep_hidden_rows and submit the page without it; a remote put_page already keeps the rows its caller could not read.');
}
// A body over the page ceiling can never be admitted: refuse it as a caller error before the journal
// reserves intent bytes, so an oversized write never reads as retryable queue_capacity.
const body = input.params.content;
const bodyBytes = (input.operation === 'put_page' || input.operation === 'capture') && typeof body === 'string' && body.length > PAGE_MAX_BYTES / 3
? Buffer.byteLength(body, 'utf-8') : 0;
if (bodyBytes > PAGE_MAX_BYTES) {
throw new OperationError('request_too_large', contentSizeHold(bodyBytes, PAGE_MAX_BYTES)!.message,
`Nothing was admitted or written, and the same content is refused on every retry. Pages up to ${PAGE_MAX_BYTES} bytes are stored and searchable; send a smaller page.`);
}
const { page_batch: _forged, timeline_section: _section, [GUEST_NOTE_INTENT_KEY]: _guestNote, ...params } = input.params;
const p: Record<string, unknown> = { ...params, ...parseMutationPrecondition(params) };
if (p.content_origin !== undefined) contentOriginTier(p.content_origin);
if (input.batch) p.page_batch = { id: input.batch.id, index: input.batch.index, size: input.batch.size, ...(input.batch.repeats?.length ? { repeats: input.batch.repeats } : {}) };
const requestId = input.batch ? input.batch.requestId : typeof p.request_id === 'string' ? p.request_id : randomUUID();
const sourceId = pageMutationSource(ctx, p, input.operation);
await initializeLocalPersistence(ctx);
const captureSlug = input.operation === 'capture' ? await resolveCaptureFile(ctx, sourceId, p) : null;
const principal = await requestPrincipalForContext(ctx);
// Independent reads go out together on Postgres; the first refusal in this order is the one reported.
const [, prior, [source]] = await pipelined(ctx.engine, [
() => assertPageRequestIdentity(ctx.engine, principal, requestId),
() => getWriteRequest(ctx.engine, principal, requestId),
() => ctx.engine.executeRaw<AdmissionSource>(ADMISSION_SOURCE_SQL, [sourceId]).catch(e => schemaBehindGuests(ctx.engine, e)),
]) as [unknown, WriteRequest | null, AdmissionSource[]];
if (source?.guest_sources_hidden) throw guestSourcesUnreadable(sourceId);
const guest: GuestSource | null = source?.guest_writers ? { source_id: sourceId, writers: source.guest_writers, trust_ceiling: source.guest_trust_ceiling! } : null;
// GBRA-504: a guest source admits only its listed writers' plain put_page, carrying the guest attribution, which joins
// the intent (and so the replay identity) here; every other write to it is refused before anything is journaled.
const guestNote = guest ? admitGuestOperation(guest, { principal, operation: input.operation, remote: ctx.remote !== false,
plainPut: !input.batch && !staged && !imported && input.managedFileImport !== true, params: p, channels: ctx.guestChannels }) : null;
if (guestNote) p[GUEST_NOTE_INTENT_KEY] = guestNote;
// GBRA-217: a reason is refused before anything is journaled; its canonical form joins the replay identity. An
// operation that records no reason never journals one a caller passed anyway.
if (CHANGE_REASON_OPERATIONS.includes(input.operation) && Object.hasOwn(p, 'reason')) {
const reason = admitChangeReason(p.reason);
if (reason === null) delete p.reason; else p.reason = reason;
} else delete p.reason;
const callerIntent = { ...p };
delete callerIntent.request_id;
if (prior) {
await submissionAuthority(ctx, prior.operation, prior.source_id, prior.source_incarnation, prior.slug);
await authorizeStoredRequest(ctx.engine, prior);
assertReplayIntent(prior, intentDigest({ operation: input.operation, sourceId, slug: prior.slug, callerIntent }));
return { prior };
}
if (input.operation === 'delete_page') assertPurgeParams(p, ctx.remote);
if (guest && input.operation === 'delete_page' && ctx.remote !== false && typeof p.slug === 'string') await refuseRemoteGuestDelete(ctx.engine, sourceId, p.slug.toLowerCase(), principal);
if (!source || source.archived) {
throw new OperationError('source_changed', 'The write source is not active.',
`Source ${sourceId} is archived or not registered, so nothing was written. Write to an active source (sources_list shows them).`);
}
// GST-1943: the storage manifest takes page writes only from the storage verbs (and the owner's import of its own commits).
assertStorageSourceWriter(ctx, sourceId, source.role, { managedFileImport: input.managedFileImport });
// After the replay check: the request digest covers what the caller sent, so a retry matches whatever the page's type is by then.
if (input.operation === 'put_page' && ctx.remote !== false && typeof p.content === 'string' && typeof p.slug === 'string') {
p.content = await unquotedPutContent(ctx.engine, sourceId, p.slug.toLowerCase(), p.content);
}
let slug = typeof p.slug === 'string' ? p.slug.toLowerCase() : '';
const intent = ['takes_add','takes_update','takes_supersede','takes_resolve','takes_remove'].includes(input.operation)
? await (await import('./takes-prepare.ts')).normalizeTakesIntent(ctx,p) : { ...p };
delete intent.request_id;
// #5969 (D3): read before normalization; a replay carries the section its first admission read.
if (input.operation === 'put_page' && input.managedFileImport !== true && p.kind === undefined && typeof p.content === 'string') {
intent.timeline_section = isTimelineSection(input.timelineSection) ? input.timelineSection : timelineSectionOf(p.content, slug);
}
if (input.operation === 'put_page') await normalizeSubagentPageInput(ctx, intent);
const typeWarning = input.operation === 'put_page' && input.managedFileImport !== true
? await undeclaredPageTypeWarning(ctx, { ...intent, slug }, sourceId) : null;
if (input.operation === 'capture') {
if (typeof p.content !== 'string' || !normalizeForHash(p.content) || detectBinaryNullByte(Buffer.from(p.content)) !== -1) {
throw new OperationError('invalid_params', 'Capture requires nonempty text without binary NUL bytes.',
'Pass content as non-empty text; binary files are not captured (store them with file_upload instead).');
}
const explicitType = explicitCaptureType(p.content, typeof p.type === 'string' ? p.type : undefined);
if (explicitType) {
const { loadActivePackForWriteVocabulary, packDeclaresPageType, undeclaredPageTypeMessage, undeclaredPageTypeSuggestion } = await import('../schema-pack/write-vocabulary.ts');
const pack = await loadActivePackForWriteVocabulary(ctx);
if (pack && !packDeclaresPageType(pack, explicitType)) throw new OperationError('invalid_params', undeclaredPageTypeMessage(explicitType, pack, 'capture'), undeclaredPageTypeSuggestion(pack));
}
const type = explicitType ?? 'note';
if (!slug) {
slug = defaultSlug(normalizeForHash(p.content), new Date(), type);
if (ctx.auth?.boundSlugPrefixes?.length) slug = `${normalizeSlugPrefix(ctx.auth.boundSlugPrefixes[0]).replace(/\/$/, '')}/${slug}`;
}
intent.content = mergeCaptureFrontmatter(p.content, { type, capturedVia: ctx.remote === false ? 'capture-cli' : 'capture-mcp',
...Object.fromEntries(['who','what','where','kind','depth'].filter(key => typeof p[key] === 'string').map(key => [key, p[key]])) });
intent.capture_hash = computeContentHash(normalizeForHash(p.content));
// Only a file whose own path names this slug can be the page's origin; sync keys origins by path.
if (typeof intent.capture_path === 'string' && captureSlug !== slug) {
delete intent.capture_path;
intent.source_uri = 'cli-file';
}
if (typeof intent.capture_path === 'string') intent.capture_file_hash = sha256(p.content);
}
await validateMutationSlug(ctx, input.operation, slug, sourceId);
enforceClientSlugFence(ctx, slug, input.operation);
enforceSubagentSlugFence(ctx, slug, input.operation);
// Preserve same-source diagnostics for new timeline writes without making
// terminal replay depend on a page that may have since been purged.
if (input.operation === 'add_timeline_entry') await requireWritablePage({ ...ctx, sourceId }, slug, input.operation, 'page');
intent.slug = slug;
// #8667: only a remote write that supplies page text is an ingestion; any other keeps the page's provenance.
if (ctx.remote !== false) {
const via = CALLER_CONTENT_OPERATIONS.includes(input.operation) ? `mcp:${input.operation}` : null;
Object.assign(intent, { source_kind: via, source_uri: null, ingested_via: via });
}
const [authority, , snapshot, boundAtStart, writeThroughSetting, repoPath] = await pipelined(ctx.engine, [
() => submissionAuthority(ctx, input.operation, sourceId, source.incarnation, slug),
() => assertKnowledgePublicationAllowed(ctx.engine, { source_id: sourceId, source_incarnation: source.incarnation, slug, operation: input.operation,
intent: { purge: intent.purge, retention: intent.retention } }),
() => ctx.engine.readPageSnapshot(slug, { sourceId, includeDeleted: true }),
() => getWorktreeBinding(ctx.engine, sourceId),
() => ctx.engine.getConfig('sync.write_through'),
async () => !source.local_path && sourceId === 'default' ? ctx.engine.getConfig('sync.repo_path') : null,
]) as [Awaited<ReturnType<typeof submissionAuthority>>, unknown, Awaited<ReturnType<BrainEngine['readPageSnapshot']>>, Awaited<ReturnType<typeof getWorktreeBinding>>, string | null, string | null];
if (typeof intent.content === 'string' && (typeof p.expected_revision !== 'string' || p.expected_revision === snapshot?.revision)) {
await assertTimelineNotOmitted(ctx.engine, { intent, remote: ctx.remote !== false, writer: typeof p.expected_revision === 'string' ? 'editing' : 'preserving',
slug, sourceId, content: intent.content, prior: snapshot });
}
if (guestNote) {
if (snapshot?.page.deleted_at) throw guestPageImmutable(`put_page over the deleted guest page ${slug}`);
await assertGuestReaders(ctx.engine, assertGuestFrontmatter(p.content, guestNote), currentCallerAccess().audience);
}
const slugAdvisory = (input.operation === 'put_page' || input.operation === 'capture') && input.managedFileImport !== true
? suffixedSlugAdmission(ctx, slug, !!snapshot && !snapshot.page.deleted_at, input.operation) : null;
// #5616: typed edit refusals before admission; publication repeats them on the locked snapshot.
if (input.operation === 'edit_page') {
const { applyPageEdits, assertEditRevision, assertSegmentedEditFences, parseEditWithin, parsePageEdits } = await import('./page-edit.ts');
if (!snapshot || snapshot.page.deleted_at) throw new OperationError('page_not_found', `Page not found: ${slug}`, 'edit_page changes an existing page; create it with put_page.');
assertEditRevision(snapshot.revision, p.expected_revision);
const within = parseEditWithin(p.within);
// A segmented page is matched by its preparation, which streams the segments (spec 6.3): never read whole here.
if (!isSegmentedPage(snapshot.page)) applyPageEdits(snapshot.page, snapshot.tags, ctx.remote !== false, parsePageEdits(p.edits), within);
else { parsePageEdits(p.edits); await assertSegmentedEditFences(ctx.engine, snapshot.page, within, ctx.remote !== false); }
}
// Wave B: an append names an existing page; its preconditions are checked when it is prepared, on the page it extends.
if (input.operation === 'append_page' && (!snapshot || snapshot.page.deleted_at)) {
throw new OperationError('page_not_found', `Page not found: ${slug}`, 'append_page adds to an existing page; create it with put_page.');
}
let binding = boundAtStart;
const sandbox = ctx.viaSubagent === true && !(ctx.allowedSlugPrefixes?.length);
const configuredWriteThrough = !/^(false|0|off|no)$/i.test(writeThroughSetting ?? 'true');
const configuredRoot = source.local_path || repoPath;
const root = configuredRoot && isHostAbsolutePath(configuredRoot) ? configuredRoot : null;
// Checkout paths belong to a host binding; sources.local_path may name
// another host's original checkout after a verified ownership transfer.
const localRoot = binding ? binding.owner_host_id === hostIdFor(ctx.engine) && binding.local_path
? join(binding.local_path, binding.relative_path) : null : root;
// #7324: a declared db_only page is canonical in the database, so its detach restore publishes database-only even
// where write-through would re-create its file (a managed checkout); assertRestoreOrigin still requires the file gone.
const databaseOnly = input.databaseOnly ?? (input.operation === 'restore_page' && p.detach === true && localRoot
&& isSourceDbOnlySlug(localRoot, slug, 'not_db_only') ? 'detached' : undefined);
const writeThrough = configuredWriteThrough && !sandbox && !databaseOnly;
if (sandbox) authority.databaseOnlyReason = 'subagent_sandbox';
else if (databaseOnly) authority.databaseOnlyReason = databaseOnly;
else if (!configuredWriteThrough) authority.databaseOnlyReason = 'disabled_by_config';
else if (!root && !binding) authority.databaseOnlyReason = configuredRoot ? 'relative_root' : 'no_repo_configured';
if (p.local_dir !== undefined) {
let matches = false;
if (ctx.remote === false && typeof p.local_dir === 'string' && localRoot) {
try { matches = realpathSync(resolve(p.local_dir)) === realpathSync(resolve(localRoot)); } catch { /* missing local binding */ }
}
if (!matches) throw new OperationError('invalid_params', 'The CLI directory must match the selected source canonical root.',
'Register the source canonical path, then omit --dir or use that same path.');
}
if (writeThrough && root && !binding) {
// #5393: a revert is also judged on the version it writes.
const fileBacked = Boolean(snapshot?.page.source_path) || Boolean(input.operation === 'revert_version' && snapshot
&& (await ctx.engine.executeRaw<{ source_path: string | null }>('SELECT source_path FROM page_versions WHERE id=$1 AND page_id=$2',
[p.version_id, snapshot.page.id]))[0]?.source_path);
const decision = await decideUnboundWrite(ctx.engine, { sourceId, sourceKind: source.kind, fileBacked, path: ctx.remote === false ? root : null });
if (decision.kind === 'claim') binding = await claimWorktree(ctx.engine, sourceId, root, undefined, undefined, { automatic: true });
else authority.databaseOnlyReason = decision.reason;
}
// #6609 (D5): a restore that writes no file refuses a page whose recorded file is gone, unless detach.
if (input.operation === 'restore_page') await assertRestoreOrigin(ctx.engine, { sourceId, slug, snapshot,
publishesFile: writeThrough && binding !== null, detach: p.detach === true, remote: ctx.remote !== false });
// #5032: this host publishes the canonical file, and on Windows a ':' in its
// name cannot be stored; refuse before admission. Database-only writes pass,
// including read-only mirror sources and pages created while one (#5409).
if (writeThrough && binding?.owner_host_id === hostIdFor(ctx.engine) && binding.local_path && isWindowsColonTarget(snapshot?.page.source_path ?? `${slug}.md`)
&& !(snapshot && !snapshot.page.source_path && await isUnboundSourcePage(ctx.engine, sourceId, slug))
&& !await sourceMirrorReadOnly(ctx.engine, sourceId)
&& !(snapshot && !snapshot.page.source_path && await isMirrorOnlyPage(ctx.engine, sourceId, slug))
&& !publishesDatabaseOnly(join(binding.local_path, binding.relative_path), slug, snapshot)) {
throw colonSlugWindowsRefusal(slug, sourceId);
}
return { typeWarning, slugAdvisory, admission: { origin: ctx.admissionOrigin, principal, operation: input.operation, sourceId, sourceIncarnation: source.incarnation,
slug, pageId: snapshot?.page.id ?? null, requestId, clientRequestId: input.batch ? undefined : clientRequestIdOf(params.request_id), callerIntent, intent, authority,
...(input.operation === 'edit_page' ? { terminalReservation: receiptReservation({ intent, authority }, (await import('./page-edit.ts')).EDIT_PAGE_RECEIPT_RESERVE) } : {}),
worktreeId: writeThrough ? binding?.worktree_id : null, topologyGeneration: writeThrough ? binding?.topology_generation : null, deferrable: true } };
}