Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { isEmbedSkipped } from '../embed-skip.ts';
import { appendPurgeCommitted } from '../belief/purge-mirror.ts';
import { sizeStateField } from '../page-embedding-budget.ts';
import { enterClaimStep, waitingOnWhile, type ClaimPhaseClock } from './claim-phase.ts';
import { boundedReads } from './bounded-reads.ts';
import { isQuarantined, quarantineOutcome } from '../quarantine.ts';
import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
import { join, relative, sep } from 'node:path';
import { isSyncMetafile, matchesAnyGlob } from '../sync.ts';
import { syncExcludePatterns } from './sync-discovery.ts';
import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import type { Page, PageVersion } from '../types.ts';
import { importFromContent, verifyPageReadable, type ParsedPage } from '../import-file.ts';
import { classifyImportHold, comparableFrontmatter, frontmatterHoldMessageWithoutKeys, parseMarkdown, resolveParsedSubtype, serializePageToMarkdown, resolveSourceLocalFilePath, type ParsedMarkdown, type ParseOpts } from '../markdown.ts';
import { alignWithStored } from './align-stored.ts';
import { assertLargePageReplacement } from './large-page-guard.ts';
import { applyInference } from '../frontmatter-inference.ts';
import { OperationError, opError } from '../ops/contract.ts';
import { CANONICAL_FILE_MISSING } from './publication-failure.ts';
import { committedBlob, committedPendingImport, headBlob, pendingImportRefusal, SYNC_HELD } from './pending-import.ts';
import { sourceCanonicalGit } from './git-door.ts';
import { assertLfsTarget, ignoredTarget, isNeverFiledDerivedPage, isPrivacyClass, renderedPageForClass, strictPageClass } from './git-declared.ts';
import { readFix } from '../ops/op-fix.ts';
import { isOpPageSlug } from '../ops/context.ts';
import { shellQuote, type Action } from '../agent-output.ts';
import type { RegistryCode } from '../error-registry.ts';
import { pageIdentityError } from './page-identity.ts';
import { contentRefusalError, PAGE_OVER_LIMIT_SUGGESTION, TAG_TOO_LONG_SUGGESTION, type ContentRefusal } from '../import-screen.ts';
import { tagLengthHold } from '../tag-limit.ts';
import { ContentSanityBlockError } from '../content-sanity.ts';
import { assertPageRevision, type PageSnapshot } from '../page-state/types.ts';
import { GIT_HOLD_OP, gitHoldFingerprint, gitHoldFix, readGitHold } from './sync-holds.ts';
import { hostOperatorFix, recordRoute } from './held-reads.ts';
import { heldFileMessage, PAGE_CHANGED_DURING_PREPARATION_MESSAGE, sourceCheckoutMissingRefusal } from './verb-errors.ts';
import { isWriteTargetContained } from '../path-confine.ts';
import { recordedPathFromFileUri, scannerSlugRootMode, scannerSourcePath } from '../write-through.ts';
import { engineMutationPrecondition, parseMutationPrecondition } from './preconditions.ts';
import { assertPurgeParams } from './purge-params.ts';
import { authorizeWrite, slugDisclosable } from './authority.ts';
import { remoteLabelsChecked, defaultSourceMemberWriter, defaultSourceWriterIsOwner, defaultSourceWriterReaders, ownerRewriteOf, storedWriterReadsHeld } from './page-visibility.ts';
import { loadFenceChunkOverlay } from '../eligibility/fence-overlay.ts';
import { findLiveFileClaimants, type FileClaimant, type FileClaimTarget } from './file-claims.ts';
import { digest, sha256 } from './digest.ts';
import { replaceableFile } from '../facts/file-body-guard.ts';
import { getWorktreeBinding } from './ownership.ts';
import type { PreparedContentImport } from './prepared-import.ts';
import type { PreparedMutation } from './coordinator.ts';
import { requestPrincipal, type SqlEngine, type WriteRequest } from './model.ts';
import { isUnboundSourcePage } from './unbound-source.ts';
import { slugPathFile } from './unbound-pages.ts';
import { isOriginTwinPage } from './origin-twins.ts';
import { sealImportedPage, sealPageTextProjection } from '../page-state/projections.ts';
import { materializedSnapshot, sealSegmentedPage } from './segmented-apply.ts';
import { isStagingBodyRef, prepareStagedUpload } from './page-upload.ts';
import { pipelined } from '../page-state/transactions.ts';
import { overlayCanonicalBodies } from '../page-state/snapshot.ts';
import { segmentedRevertRefusal } from '../page-state/versions.ts';
import { bodyUnread, fenceBody, isSegmentedPage, pageBodySegmentedError, withoutBody } from '../page-body/page-shape.ts';
import { fileBodyDigests, overlaidFileBodyDigests, storedBodyDigests, type ByteSource, type FileReading, type RegionDigests } from '../page-body/body-digests.ts';
import { ledgerApplies, type BodyLedger } from '../page-body/segment-ledger.ts';
import { inferredHeadPrefix } from '../page-body/streamed-import.ts';
import { fenceTooLargeError } from '../page-body/read-range.ts';
import { FRONTMATTER_HEAD_MAX_BYTES } from '../page-body/limits.ts';
import { occurrencesWithoutChunks, readSegmentedBody } from '../page-body/ingest.ts';
import { ContentHashStream } from '../page-body/content-hash-stream.ts';
import { buildSegmentedProjection, hasStaleChunks } from '../page-body/projection.ts';
import { segmentedExportMarkdown } from '../export-snapshot.ts';
import { loadImportSanityConfig } from '../import-screen.ts';
import { DEFAULT_WRITE_GATE_CONFIG, writeGateApplies } from '../write-gate.ts';
import { materializeTimeline, prepareCanonicalProjections, type TimelineRowsRemoved } from './canonical-projections.ts';
import { assertTimelineNotOmitted, timelineWritePolicy } from './timeline-omission.ts';
import { preserveProtectedTakes } from './protected-takes.ts';
import { assertPrivateRequestKept, privateRequestGuarded, readPrivateRequest } from './visibility-request.ts';
import { isAutoLinkEnabled } from '../link-extraction.ts';
import { prepareAutomaticLinks } from './links-preparation.ts';
import { loadActivePackForEngine } from '../schema-pack/engine-resolution.ts';
import { preparePageAdvisories, remoteLinkHint, pageNoopAdvisories, timelineRowsRemovedAdvisory } from './page-advisories.ts';
import { assertKnowledgePublicationAllowed } from '../shared-skills/knowledge-guard.ts';
import { colonSlugWindowsRefusal, isWindowsColonTarget, nativeFileTarget } from './native-file-target.ts';
import { isSourceDbOnlySlug } from './source-storage.ts';
import { gitIgnoresUntracked } from './sync-origin-evidence.ts';
import { gitDurabilityPolicy } from './git-durability-policy.ts';
import { isMirrorOnlyPage, sourceMirrorReadOnly } from './mirror-read-only.ts';
import { SOURCE_CONFIG_OBJECT_SQL } from '../source-config-sql.ts';
import { readSlugRootMode } from '../sync-anchor.ts';
import { applyPageEdits, editDiff, parseEditWithin, parsePageEdits, prepareSegmentedEditMutation } from './page-edit.ts';
import { carryCoreMarking, prepareCoreGuard } from './core-guard.ts';
import { assertRetirementStampUnchanged } from './derived-retirement-hold.ts';
import { fenceWhere } from '../fence-repair/refusal.ts';
import { pageFencesNormalized } from '../fence-repair/report.ts';
import { parseFenceRepairReceipt } from '../fence-repair/receipt.ts';
import { fenceRepairCommit } from './effect-model.ts';
import { withoutSafetyAssessments } from './reconcile-safety.ts';
import { POLICY_KEYS } from './reconcile-additive.ts';
import { readLabelEdit, spliceLabelLines, type LabelEdit } from './label-edit.ts';
import { protectedReconcileKey } from './reconcile-merge.ts';
import { PROTECTED_FRONTMATTER_KEYS } from '../frontmatter-recovery.ts';
import { preparePagePurge, purgePageInTransaction, type PreparedPagePurge } from './page-purge.ts';
import { originCommitted } from './sync-markers.ts';
import { syncDeleteOrigin } from './sync-delete-tombstones.ts';
import { withTrustKeep } from './context.ts';
import { holdPrivacyLabels, isFenceEditWrite, labelGuardApplies, labelGuardOwner, labelGuardTier, pageGateTrust, privacyLabelGuard, pageWriteTrust, recordAgentPageLowering, stampPageTrustMarker, storedPageTier,
type HeldPrivacyLabels, type LabelGuard } from '../trust/page-write.ts';
import { compareTrust, maxTrust, type TrustTier, type WriteTrust } from '../trust/tier.ts';
import { suppliedTrustMarkerView } from '../trust/channel.ts';
import { gateField, gateInput } from '../trust/gate-outcomes.ts';
import { PUSH_SCAN_MAX_FILE_BYTES } from '../page-size-policy.ts';
import { fileContentHash, FileBytes, isStreamedContent, LARGE_FILE_MIN_BYTES, StreamedFileContent } from './large-file.ts';
import { bindOrigin } from './origin-guard.ts';
import { assertGuestWriterAtPublication, insertGuestMark, refuseRemoteGuestDelete } from '../guests/admission.ts';
import { skipsGuestNote } from '../guests/derived.ts';
import { NOT_A_GUEST_WRITE, prepareGuestWrite, type GuestWrite } from '../guests/publication.ts';
import { clearOwedPurges } from './derived-origin-hold.ts';
const ownerStatusFix = (sourceId: string): Action => readFix(`Shows source ${sourceId}'s canonical owner with its pending, failed and recovering requests, read-only.`,
{ argv: ['gbrain', 'sources', 'writer', 'status', '--source', sourceId, '--json'] });
export const pageFix = (sourceId: string, slug: string): Action => readFix(`Shows page ${slug} in source ${sourceId} as it is now, with its revision.`,
{ argv: ['gbrain', 'get', '--source', sourceId, '--', slug], mcp: { tool: 'get_page', arguments: { slug, source_id: sourceId } } });
/**
* A refused page request. The journal keeps only code and message, so the
* suggestion stands alone: the cause and next step, then the request to
* inspect before anything is resubmitted.
*/
export function pageRefusal(code: RegistryCode, message: string, row: WriteRequest, cause: string, fix?: Action): OperationError {
return opError(code, message,
`${cause} Request ${row.request_id} in source ${row.source_id} was refused; inspect it before resubmitting, and use a new request_id for any corrected write.`,
{ fix: fix ?? (row.principal_kind === 'local_cli'
? readFix(`Reads request ${row.request_id}'s durable receipt: its state and recorded error, read-only.`, { argv: ['gbrain', 'write-request', '--', row.request_id] })
: ownerStatusFix(row.source_id)) });
}
/**
* GST-2521: under the publication's page lock, a write whose label guard (its tier, or the owner it keeps as a reader)
* moved since preparation refuses `revision_conflict`: a guard raised over labels that already match, or an owner set,
* enabled or opted out after preparation, moves no page revision. The write publishes nothing; submitted again, it is
* prepared against the current guard and held.
*/
async function assertLabelGuardUnchanged(tx: BrainEngine, row: WriteRequest, trust: WriteTrust | undefined, page: PageSnapshot['page'] | null,
stored: TrustTier | null, incoming: Record<string, unknown> | null, prepared: LabelGuard | null): Promise<void> {
if (!labelGuardApplies(row, trust, page, stored)) return;
const [tier, owner] = await Promise.all([labelGuardTier(tx, trust!, page, stored!), labelGuardOwner(tx, page.frontmatter ?? {}, incoming)]);
if (tier === (prepared?.tier ?? null) && JSON.stringify(owner) === JSON.stringify(prepared?.owner ?? null)) return;
throw pageRefusal('revision_conflict', 'The page\'s label guard changed while this write was being prepared.', row,
`The label guard of page ${row.slug} (the labels and the owner reader it keeps) changed after this write was prepared, so it published nothing; the page itself is unchanged. Submit the same write again: it is prepared against the current guard.`);
}
/**
* The parser trims titles, so a stored title differing only in surrounding whitespace is not drift (#5635), and it
* never carries `type`/`title`/`tags`/`slug` into the frontmatter object, so a stored copy of one (#6454: older
* imports kept them) is compared through `comparableFrontmatter` on both sides, never as drift.
*/
function canonical(page: Pick<Page, 'type' | 'title' | 'compiled_truth' | 'timeline' | 'frontmatter'>, tags: string[]) {
return { type: page.type, title: page.title.trim(), compiled_truth: page.compiled_truth, timeline: page.timeline ?? '',
frontmatter: comparableFrontmatter(page.frontmatter), tags: [...new Set(tags)].sort() };
}
/** GST-2603: what two canonical readings differ in, by frontmatter key, then title, type, tags, body and timeline; empty when they are equal. */
function canonicalDifference(a: ReturnType<typeof canonical>, b: ReturnType<typeof canonical>): string[] {
if (digest(a) === digest(b)) return [];
const has = (frontmatter: Record<string, unknown>, key: string) => Object.hasOwn(frontmatter, key) && frontmatter[key] !== undefined;
const keys = [...new Set([...Object.keys(a.frontmatter), ...Object.keys(b.frontmatter)])].filter(key => has(a.frontmatter, key) !== has(b.frontmatter, key)
|| has(a.frontmatter, key) && digest(a.frontmatter[key]) !== digest(b.frontmatter[key])).sort();
const fields = (['title', 'type', 'tags', 'compiled_truth', 'timeline'] as const).filter(field => digest(a[field]) !== digest(b[field]));
return [...keys, ...fields.map(field => field === 'compiled_truth' ? 'body' : field)];
}
interface CanonicalProvenance { source_kind: string; ingested_via: string; ingested_at: string; }
/**
* Writes whose caller supplies the page text, and so could supply provenance stamps in its frontmatter. Unlike
* trust/page-write.ts CONTENT_OPERATIONS, revert_version and restore_page are absent: they replay a stored version.
*/
export const CALLER_CONTENT_OPERATIONS = ['put_page', 'edit_page', 'append_page', 'capture'];
/**
* Canonical stamps belong to the first write, never to a later preparation attempt. #7873: they are server-owned on
* every caller-content write a remote caller makes, with or without a repository: the caller's values are dropped and
* the stored page's kept. A managed put_page (local too) also stamps the first write's provenance.
*/
function putProvenance(row: WriteRequest, snapshot: PageSnapshot | null, parsed: ParsedPage): CanonicalProvenance | undefined {
if (!serverOwnsProvenance(row)) return undefined;
const managedPut = row.operation === 'put_page' && !!row.worktree_id;
keepStoredProvenance(parsed.frontmatter, snapshot?.page.frontmatter);
if (!managedPut) return undefined;
const tags = [...new Set([...(snapshot?.tags ?? []), ...parsed.tags])].sort();
if (snapshot && !snapshot.page.deleted_at && digest(canonical(snapshot.page, snapshot.tags)) === digest(canonical(parsed, tags))) {
return undefined;
}
const string = (value: unknown) => typeof value === 'string' && value ? value : undefined;
const first = snapshot?.page;
const via = row.authority.remote ? 'mcp:put_page' : 'put_page';
// Historical frontmatter was caller-controlled. Only trusted provenance
// columns may supply a prior channel or timestamp for the first-write record.
const stamp: CanonicalProvenance = {
source_kind: string(first?.source_kind) ?? string(row.intent?.source_kind) ?? via,
ingested_via: string(first?.ingested_via) ?? string(row.intent?.ingested_via) ?? via,
ingested_at: new Date(first?.ingested_at ?? row.created_at).toISOString(),
};
Object.assign(parsed.frontmatter, stamp);
return stamp;
}
function serverOwnsProvenance(row: WriteRequest): boolean {
return (row.operation === 'put_page' && !!row.worktree_id) || (row.authority.remote === true && CALLER_CONTENT_OPERATIONS.includes(row.operation));
}
/**
* #7873: the tier of a write whose provenance stamps are server-owned is the lower of its own frontmatter's and the
* frontmatter it publishes (the stored stamps kept), so dropping a stored lowering stamp escapes neither the write gate
* nor the page row's tier.
*/
export function provenanceWriteTrust(row: WriteRequest, frontmatter: Record<string, unknown> | null, stored: Record<string, unknown> | null | undefined): WriteTrust | undefined {
const trust = pageWriteTrust(row, frontmatter);
if (!trust || !frontmatter || !serverOwnsProvenance(row)) return trust;
const published = { ...frontmatter };
keepStoredProvenance(published, stored);
const kept = pageWriteTrust(row, published);
return kept && compareTrust(kept.tier, trust.tier) < 0 ? kept : trust;
}
/** The provenance stamps of `stored` replace whatever `frontmatter` carries for them (removed when the stored page has none). */
export function keepStoredProvenance(frontmatter: Record<string, unknown>, stored: Record<string, unknown> | null | undefined): void {
for (const key of ['source_kind', 'ingested_via', 'ingested_at'] as const) {
delete frontmatter[key];
if (stored?.[key] !== undefined) frontmatter[key] = stored[key];
}
}
export { isNeverFiledDerivedPage };
/**
* A live page whose canonical file is absent publishes to the database only
* when its slug is a declared db_only path or a never-filed derive-phase page.
*/
export function publishesDatabaseOnly(root: string, slug: string, snapshot: { page: Pick<PageSnapshot['page'], 'deleted_at' | 'source_path' | 'source_uri'> } | null): boolean {
if (!snapshot || snapshot.page.deleted_at) return false;
return isSourceDbOnlySlug(root, slug, 'refuse') || isNeverFiledDerivedPage(slug, snapshot.page);
}
/**
* #6605: a canonical file read the way the importer reads it. A file with no frontmatter under a
* directory-inference rule is imported with the frontmatter and tags inferred from its path
* (`applyInference` after stripping a BOM: import-prepare.ts, import-file.ts), so comparing its raw bytes
* with the stored row reads every untouched file as drift. `sourcePath` is the path the importer infers
* from (`scannerSourcePath`). Inference is deterministic, so this reproduces what the import stored;
* `inferred` is false when no rule applies (the bytes are read as they are).
*/
export function readCanonicalAsImported(bytes: string, sourcePath: string): { content: string; inferred: boolean } {
const inference = applyInference(sourcePath, bytes.replace(/^\uFEFF/, ''));
return inference.inferred.skipped === true ? { content: bytes, inferred: false } : { content: inference.content, inferred: true };
}
/**
* Whether file bytes hold the snapshot's page: the canonical (format-insensitive)
* comparison prepareFileTarget applies before replacing a canonical file. Lint
* uses it to bind a repair to the revision it read before reading the file.
* `sourcePath` (the importer's path for the file, or a resolver for it) lets a
* frontmatter-less file match the row an inferring import stored (#6605); the
* raw reading still matches a row imported without inference (`gbrain reindex`
* on an unmanaged brain passes `inferFrontmatter: false`).
*/
export async function fileMatchesSnapshot(engine: BrainEngine, slug: string, bytes: string, snapshot: PageSnapshot,
sourcePath: string | (() => Promise<string>), activePack?: ParseOpts['activePack']): Promise<boolean> {
return (await fileSnapshotDifference(engine, slug, bytes, snapshot, sourcePath, activePack)).length === 0;
}
/**
* GST-2603: what file bytes differ from the snapshot's page in, compared as fileMatchesSnapshot compares them (the stamps
* only the database holds are kept on the file side, align-stored.ts), so a stamp is never named: frontmatter keys, then
* title, type, tags, body and timeline. Empty when the file holds the page; otherwise the reading closer to the page.
*/
export async function fileSnapshotDifference(engine: BrainEngine, slug: string, bytes: string, snapshot: PageSnapshot,
sourcePath: string | (() => Promise<string>), activePack?: ParseOpts['activePack']): Promise<string[]> {
snapshot = (await materializedSnapshot(engine, snapshot))!;
const expected = canonical({ ...snapshot.page, frontmatter: withoutSafetyAssessments(snapshot.page.frontmatter ?? {}) }, snapshot.tags);
const difference = async (content: string, inferred: boolean) => {
const parsed = parseMarkdown(content, slug, { activePack });
const type = importedFileType(parsed, snapshot.page, inferred);
// Withdrawal overlays intentionally precede physical mirroring. The ledger
// is applied by the import preparation and cannot be undone by this check.
const actual = canonical({ ...parsed, frontmatter: withoutSafetyAssessments(parsed.frontmatter), type, ...await overlayCanonicalBodies(engine.executeRaw.bind(engine),
parsed.compiled_truth, parsed.timeline ?? '', snapshot.withdrawals, { sourceId: snapshot.page.source_id, marker: snapshot.globalPurges }) }, parsed.tags);
return canonicalDifference(actual, expected);
};
const raw = await difference(bytes, false);
if (!raw.length) return raw;
const reading = readCanonicalAsImported(bytes, typeof sourcePath === 'string' ? sourcePath : await sourcePath());
if (!reading.inferred) return raw;
const inferred = await difference(reading.content, true);
return inferred.length < raw.length ? inferred : raw;
}
/**
* #8109: the file a write publishes over a canonical file that differs from the database only in frontmatter, or null
* when the write must refuse as drift. The file and the database must agree on everything but frontmatter (body,
* timeline, title, type and tags, as fileMatchesSnapshot compares them), no drifted key may be a policy, protected,
* access, lineage or trust-lowering key, and the write must leave the stored frontmatter unchanged. The file then keeps its own frontmatter block and
* takes the write's body, so neither side's frontmatter is lost; the drift stays for reconcile.
*/
const SPLICE_REFUSED_KEYS = new Set([...PROTECTED_FRONTMATTER_KEYS, 'trust_tier', 'transcript_import', 'source_url', 'clipped_at', 'clipper', 'dream_generated']);
async function frontmatterDriftWrite(engine: BrainEngine, slug: string, fileText: string, snapshot: PageSnapshot, content: string,
activePack?: ParseOpts['activePack']): Promise<string | null> {
snapshot = (await materializedSnapshot(engine, snapshot))!;
const file = parseMarkdown(fileText, slug, { activePack });
const type = importedFileType(file, snapshot.page, false);
const bodies = await overlayCanonicalBodies(engine.executeRaw.bind(engine), file.compiled_truth, file.timeline ?? '', snapshot.withdrawals,
{ sourceId: snapshot.page.source_id, marker: snapshot.globalPurges });
const bare = (page: Parameters<typeof canonical>[0], tags: string[]) => digest(canonical({ ...page, frontmatter: {} }, tags));
if (bare({ ...file, type, ...bodies }, file.tags) !== bare(snapshot.page, snapshot.tags)) return null;
const fileFrontmatter = comparableFrontmatter(withoutSafetyAssessments(file.frontmatter));
const stored = comparableFrontmatter(withoutSafetyAssessments(snapshot.page.frontmatter ?? {}));
const drifted = [...new Set([...Object.keys(fileFrontmatter), ...Object.keys(stored)])].filter(key => digest(fileFrontmatter[key] ?? null) !== digest(stored[key] ?? null));
if (!drifted.length || drifted.some(key => POLICY_KEYS.has(key) || protectedReconcileKey(key) || SPLICE_REFUSED_KEYS.has(key))) return null;
const incoming = parseMarkdown(content, slug, { activePack });
if (digest(comparableFrontmatter(withoutSafetyAssessments(incoming.frontmatter))) !== digest(stored)
|| bare({ ...incoming, compiled_truth: '', timeline: '' }, incoming.tags) !== bare({ ...snapshot.page, compiled_truth: '', timeline: '' }, snapshot.tags)) return null;
const head = /^\uFEFF?---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n/;
const fileHead = head.exec(fileText), contentHead = head.exec(content);
if (!fileHead || !contentHead) return null;
const spliced = fileHead[0] + content.slice(contentHead[0].length);
const check = parseMarkdown(spliced, slug, { activePack });
return digest(check.frontmatter) === digest(file.frontmatter) && check.title === file.title && check.type === incoming.type && digest(check.tags) === digest(file.tags)
&& check.compiled_truth === incoming.compiled_truth && (check.timeline ?? '') === (incoming.timeline ?? '') ? spliced : null;
}
/**
* GST-2468: the file a label-only maintenance write publishes over a canonical file that holds the page (fileMatchesSnapshot):
* the file's own bytes with only its label lines edited (label-edit.ts spliceLabelLines), keeping its body when it reads as
* the write's body, else its head over the write's body (a fact row's visibility cell in the fence). Either must read back
* as `content`, the file the write would otherwise render; a label line that cannot be edited as a line refuses, so the
* file is never re-rendered under a label edit.
*/
export function labelEditFile(slug: string, before: Buffer | FileBytes, content: string, edit: LabelEdit, snapshot: PageSnapshot, activePack?: ParseOpts['activePack']): string {
const fit = labelEditFit(slug, before, content, edit, snapshot, activePack);
if (typeof fit === 'string') return fit;
throw labelEditRefused(snapshot.page, fit.keys, edit);
}
/**
* GST-2603: a label write's refusal when the page's file holds the page but cannot take `edit` line by line (`keys`: what
* still differs, empty when the label line itself cannot be edited). Repairs count `label_edit_refused` as the page declining
* the write, never toward the run's systemic-failure stop (repair/core.ts), whether the preview's check, the apply's check or
* the managed publish (labelEditFile) refuses.
*/
export function labelEditRefused(page: { source_id: string; slug: string }, keys: string[], edit: LabelEdit): OperationError {
const ref = `${page.source_id}:${page.slug}`;
const labels = [...Object.keys(edit.set), ...edit.remove].join(', ') || 'the label';
return keys.length
? opError('label_edit_refused', `${ref} was not written: with only its label lines edited, its file still differs from the page in ${keys.join(', ')}.`,
`In the page's file, make ${keys.join(', ')} match the page (gbrain get --source ${page.source_id} -- ${page.slug} prints it), commit it, run gbrain sync --source ${page.source_id}, then preview the repair again.`,
{ reason: 'file_differs', detail: keys.join(',') })
: opError('label_edit_refused', `${ref} was not written: its file's ${labels} line cannot be edited as one line.`,
`In the page's file, write ${labels} as one plain line in the frontmatter block (no block or multi-line value, no duplicate key; add a frontmatter block if the file has none), commit it, run gbrain sync --source ${page.source_id}, then preview the repair again.`,
{ reason: 'label_line', detail: labels });
}
/**
* labelEditFile without the refusal: the file to publish, or the fields that keep the edited file from reading as `content`
* (a frontmatter key, title, type, tags, body or timeline; never a stamp only the database holds, align-stored.ts), empty
* when its label lines cannot be edited as lines at all.
*/
export function labelEditFit(slug: string, before: Buffer | FileBytes, content: string, edit: LabelEdit, snapshot: PageSnapshot, activePack?: ParseOpts['activePack']): string | { keys: string[] } {
const read = (text: string, file: boolean) => {
const parsed = parseMarkdown(text, slug, { activePack });
// The type first: aligning a file's parse with the stored page also adds the stamps only the database holds to its frontmatter.
const type = file ? importedFileType(parsed, snapshot.page, false) : parsed.type;
return canonical({ ...parsed, frontmatter: withoutSafetyAssessments(parsed.frontmatter), type }, parsed.tags);
};
const spliced = before instanceof Buffer ? spliceLabelLines(before.toString('utf8'), edit) : null;
const contentHead = /^\uFEFF?---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n/.exec(content);
const expected = read(content, false);
const candidates = spliced ? [spliced.text, ...(contentHead ? [spliced.head + content.slice(contentHead[0].length)] : [])] : [];
const readings = candidates.map(text => ({ text, keys: canonicalDifference(read(text, true), expected) }));
const fits = readings.find(reading => !reading.keys.length);
if (fits) return fits.text;
return { keys: readings.reduce<string[] | null>((best, reading) => best && best.length <= reading.keys.length ? best : reading.keys, null) ?? [] };
}
/**
* GST-1601: whether a local edit changes what an adoption must never take without a person: the title, the type, or a
* policy, protected, access, lineage or trust-lowering frontmatter key (the keys frontmatterDriftWrite never splices).
*/
export async function protectedLocalEdit(engine: BrainEngine, slug: string, fileText: string, snapshot: PageSnapshot, activePack?: ParseOpts['activePack']): Promise<boolean> {
snapshot = (await materializedSnapshot(engine, snapshot))!;
const file = parseMarkdown(fileText, slug, { activePack });
if (file.title !== snapshot.page.title || importedFileType(file, snapshot.page, false) !== snapshot.page.type) return true;
const fileFrontmatter = comparableFrontmatter(withoutSafetyAssessments(file.frontmatter));
const stored = comparableFrontmatter(withoutSafetyAssessments(snapshot.page.frontmatter ?? {}));
return [...new Set([...Object.keys(fileFrontmatter), ...Object.keys(stored)])].some(key => digest(fileFrontmatter[key] ?? null) !== digest(stored[key] ?? null)
&& (POLICY_KEYS.has(key) || protectedReconcileKey(key) || SPLICE_REFUSED_KEYS.has(key) || key === 'slug'));
}
/** The type a file's parse compares with (`fileMatchesSnapshot`), after aligning the parse with what its import over `page` stores. */
function importedFileType(parsed: ParsedMarkdown, page: Pick<Page, 'type' | 'frontmatter'>, inferred: boolean): Page['type'] {
// #5521 parity for subtype (#5928): a pack rule is not part of the file's bytes, so a file
// without an explicit `subtype:` keeps the stored subtype (or none); the import still stamps it.
delete parsed.inferredSubtype;
alignWithStored(parsed, page, inferred);
return parsed.type;
}
/** The withdrawal ledger readPageSnapshot overlaid the snapshot's body with, for a segmented body read under it. */
export function snapshotLedger(snapshot: PageSnapshot): BodyLedger {
return { withdrawals: snapshot.withdrawals, ...(snapshot.globalPurges ? { globalPurges: snapshot.globalPurges } : {}) };
}
/**
* Wave B: `fileMatchesSnapshot` for a segmented page whose body was not read back (over the single-string ceiling).
* The same comparison (the gate's safety markers stripped on both sides) with each body region replaced by its SHA-256 on both sides: the file's regions as the streamed
* importer's scan splits them, the stored ones from the trusted stored body (body-digests.ts), one segment at a time.
* The withdrawal overlay leaves a body without a facts fence unchanged; a file whose body has one under a ledger
* that applies cannot be overlaid streamed, so it refuses (`page_body_segmented`) instead of reading as drift.
*/
async function segmentedFileMatches(engine: BrainEngine, slug: string, bytes: ByteSource, snapshot: PageSnapshot,
sourcePath: () => Promise<string>, activePack?: ParseOpts['activePack'], between?: () => Promise<void>): Promise<boolean> {
const ledger = snapshotLedger(snapshot);
let stored: RegionDigests | undefined;
const matches = async (reading: FileReading, inferred: boolean) => {
const file = fileBodyDigests(bytes, reading, slug, { activePack });
await between?.();
if (file.kind !== 'ok') return file.reason;
// A facts fence under a ledger that applies is compared overlaid, one complete fence block at a time; a fence longer
// than FENCE_MAX_BYTES refuses, as the stored side's trusted read does.
const fileDigests = file.factsFence && ledgerApplies(ledger)
? await overlaidFileBodyDigests(bytes, reading, file.regions, async text => (await overlayCanonicalBodies(engine.executeRaw.bind(engine), text, '',
ledger.withdrawals, { sourceId: snapshot.page.source_id, marker: ledger.globalPurges })).compiled_truth,
fence => fenceTooLargeError(slug, snapshot.page.source_id, fence), between)
: file.digests;
const parsed = { ...file.parsed, compiled_truth: fileDigests.truth, timeline: fileDigests.timeline };
const type = importedFileType(parsed, snapshot.page, inferred);
stored ??= await storedBodyDigests(engine, Number(snapshot.page.id), ledger, between);
return digest(canonical({ ...parsed, frontmatter: withoutSafetyAssessments(parsed.frontmatter), type }, parsed.tags))
=== digest(canonical({ ...withoutBody(snapshot.page), frontmatter: withoutSafetyAssessments(snapshot.page.frontmatter ?? {}), compiled_truth: stored.truth, timeline: stored.timeline }, snapshot.tags));
};
const raw = await matches({ prefix: new Uint8Array(0), skip: 0 }, false);
if (raw === true) return true;
if (raw === 'invalid_utf8') return false;
const bom = bytes.subarray(0, 3);
const skip = bom[0] === 0xef && bom[1] === 0xbb && bom[2] === 0xbf ? 3 : 0;
const prefix = await inferredHeadPrefix(bytes.subarray(skip, skip + FRONTMATTER_HEAD_MAX_BYTES), await sourcePath());
return !!prefix?.length && await matches({ prefix, skip }, true) === true;
}
export async function prepareFileTarget(engine: BrainEngine, row: Pick<WriteRequest, 'source_id' | 'worktree_id' | 'slug'> & Partial<Pick<WriteRequest, 'sequence'>> & { operation?: string }, snapshot: PageSnapshot | null,
content: string | Uint8Array | StreamedFileContent | null, hostId?: string, options: { allowMissing?: boolean; deleting?: boolean; capture?: { path: string; hash: string }; activePack?: ParseOpts['activePack']; remote?: boolean;
/** #6368: a tombstone purge whose file matches these sync.exclude globs (relative to the source root) owns no file. */
excludeTombstone?: { patterns: string[]; onExcluded: (path: string) => void };
/** #7130: a new page's put_page/capture whose file target .gitignore excludes publishes database-only instead. */
newPageIgnoredDatabaseOnly?: boolean;
/** #6517: a delete whose file another live page of the source records owns no file; the census target and claimants are reported. */
sharedOrigin?: { onShared: (shared: SharedOrigin) => void };
/** Runs between the pieces of a segmented page's file comparison (an effect's claim renewal). */
between?: () => Promise<void>;
/** #7436: the preparation's clock, so its stamp says `waiting_on=git` while a Git check runs. */
clock?: ClaimPhaseClock;
/** GST-2468: a label-only maintenance write edits only the label lines of the file it matches (labelEditFile). */
labelEdit?: LabelEdit } = {}): Promise<PreparedMutation['file']> {
if (!row.worktree_id) return undefined;
// An in-memory canonical file over the 25 MiB push-scan cap is refused (only a page over the 24 MiB single-string
// ceiling renders one). That page's file is streamed instead (restore_page of a page whose body was not read back,
// large-file.ts), and the push gate scans a staged file over the cap in bounded windows (workspace-push.ts).
if (content !== null && !isStreamedContent(content) && Buffer.byteLength(content, 'utf-8') > PUSH_SCAN_MAX_FILE_BYTES) throw opError('request_too_large', 'The canonical file would exceed the pre-push secret-scan cap.',
`Nothing was written. The rendered file of ${row.slug} is over ${PUSH_SCAN_MAX_FILE_BYTES} bytes, which the pre-push secret scan cannot scan, so it would block every push of source ${row.source_id}. Keep the page under the 24 MiB page ceiling (docs/guides/memory-boundaries.md#large-pages).`);
// #6212: a legacy slug (admitted only to delete or restore its existing row) never owns a file: its recorded
// source_uri or source_path may name the file of another page, such as the one sync now slugs it to.
if (!isOpPageSlug(row.slug)) return undefined;
// #5409: a read-only mirror's checkout belongs to its Git remote; nothing is written or removed there.
if (await sourceMirrorReadOnly(engine, row.source_id)) return undefined;
if (snapshot && !snapshot.page.source_path && await isMirrorOnlyPage(engine, row.source_id, row.slug)) return undefined;
// #5254: a page written while its source was unbound stays database-only in
// every state (live, tombstone, restore, revert, delete, purge); any file at
// its derived path is not its canonical file and is neither written nor removed.
if (snapshot && !snapshot.page.source_path && await isUnboundSourcePage(engine, row.source_id, row.slug)) return undefined;
// #6948: a page that gave its file up to a duplicate it was merged into never writes or removes a file again (restore,
// edit, purge); any file at its slug path is another page's.
if (snapshot && !snapshot.page.source_path && await isOriginTwinPage(engine, row.source_id, row.slug)) return undefined;
const binding = await getWorktreeBinding(engine, row.source_id, hostId);
if (!binding?.local_path) throw opError('owner_unavailable', 'The canonical worktree is unavailable on this host.',
`This host does not hold source ${row.source_id}'s canonical worktree (or it has no local path), so the file of ${row.slug} was not written. Inspect the owner before resubmitting; the write publishes on the host that owns the source.`,
{ fix: ownerStatusFix(row.source_id) });
if (!existsSync(binding.local_path)) throw sourceCheckoutMissingRefusal(row.source_id, row.slug);
const root = join(binding.local_path, binding.relative_path);
// #5622: a new page captured from a file inside the source is published to that file.
const capturedPath = !snapshot && options.capture ? options.capture.path : recordedPathFromFileUri(snapshot?.page.source_uri, root);
// G7a: a strict page that turned private keeps the path of the file its removal took (withheld_source_path) and writes it there again.
const recordedPath = snapshot?.page.source_path || snapshot?.page.withheld_source_path || null;
const mode = recordedPath ? await scannerSlugRootMode(engine, row.source_id, root) : undefined;
const candidate = resolveSourceLocalFilePath(root, recordedPath, row.slug, mode)
?? (capturedPath ? join(root, capturedPath) : snapshot ? slugPathFile(root, row.slug, await scannerSlugRootMode(engine, row.source_id, root)) : join(root, `${row.slug}.md`));
if (isWindowsColonTarget(relative(root, candidate))) {
if (!options.allowMissing && publishesDatabaseOnly(root, row.slug, snapshot)) return undefined;
throw colonSlugWindowsRefusal(row.slug, row.source_id);
}
const path = nativeFileTarget(binding.local_path, candidate);
if (!isWriteTargetContained(path, root)) throw opError('source_changed', 'The canonical file target is outside its registered source.',
`The file of ${row.slug} resolves outside source ${row.source_id}'s registered root (a symlinked directory or a moved checkout), so nothing was written. Inspect the owner before resubmitting; how to repair the checkout is the user's decision.`,
{ fix: ownerStatusFix(row.source_id) });
// #7130: a canonical file under a path the checkout's .gitignore excludes would never be committed, so the page would be
// file-backed by a file no history holds (and a later sync could read its absence as a deletion). The write publishes
// to the database only and binds no file; a declared db_only page keeps its cache file as before. Only a new page whose
// target file does not exist yet: an existing page keeps its file (and its drift checks and storage refusals), and only a
// person's detach turns it database-only. A Git-durable source keeps writing the file: its Git effect cannot commit an
// ignored target and parks it (`git_target_unsafe`), which already shows the page needs a decision.
// G7a (git-declared.ts): on a strict source a declared database-only page gets no file to commit (no door commit, no Git
// effect), a page turning private gets the removal of the file it still has, and a path under an LFS rule commits only
// when the operator opted in and the checkout configures LFS. Removals are never refused: they move the database toward Git.
if (binding.canonical_git === true && content !== null) {
const declared = await strictPageClass(engine, row.source_id, root, renderedPageForClass(row.slug, content, snapshot), snapshot?.page ?? null)
?? (await waitingOnWhile(options.clock, 'git', () => ignoredTarget(root, path)) ? 'git_ignored' : null);
if (declared) {
if (!isPrivacyClass(declared) || !snapshot || snapshot.page.deleted_at) return undefined;
if (!existsSync(path) && await headBlob(root, path) === null) return undefined;
content = null;
options = { ...options, deleting: true };
} else await assertLfsTarget(engine, row, root, path, options.remote === true);
}
// GST-2519: the live file check (liveFileDrift: no content) of a strict page declared git_ignored, whose path Git still
// ignores, finds no file target, as its publication does; a page whose ignore rule is gone is still checked for its file.
if (binding.canonical_git === true && content === null && options.deleting !== true && snapshot && !snapshot.page.deleted_at && !snapshot.page.source_path && !existsSync(path)
&& (await engine.executeRaw<{ reason: string | null }>('SELECT database_only_reason AS reason FROM pages WHERE id=$1', [snapshot.page.id]))[0]?.reason === 'git_ignored'
&& await waitingOnWhile(options.clock, 'git', () => ignoredTarget(root, path))) return undefined;
if (options.newPageIgnoredDatabaseOnly && !snapshot && content !== null && !existsSync(path) && !isSourceDbOnlySlug(root, row.slug, 'not_db_only') && await waitingOnWhile(options.clock, 'git', () => gitIgnoresUntracked(root, relative(root, path).split(sep).join('/')))
&& !(await gitDurabilityPolicy(binding, root)).durable) return undefined;
if (options.excludeTombstone && snapshot) {
const rel = relative(root, path).split(sep).join('/');
if (unimportedBySync(rel, options.excludeTombstone.patterns)) { options.excludeTombstone.onExcluded(rel); return undefined; }
}
// A prior file over the single-string ceiling is read on demand in pieces (large-file.ts), never whole; so is the file
// of a page stored in segments, or of a streamed target, at any size (its comparison reads it piecewise anyway).
const piecewise = (snapshot && bodyUnread(snapshot.page)) || (content !== null && isStreamedContent(content));
const before: Buffer | FileBytes | null = !existsSync(path) ? null
: piecewise || statSync(path).size > LARGE_FILE_MIN_BYTES ? FileBytes.open(path) : readFileSync(path);
try {
return await compareFileTarget(engine, row, snapshot, content, options, { root, path, mode, capturedPath, before });
} finally { if (before instanceof FileBytes) before.close(); }
}
/** prepareFileTarget's comparison of the file at `path` (`before`, its bytes or a piecewise reading) with the snapshot. */
async function compareFileTarget(engine: BrainEngine, row: Parameters<typeof prepareFileTarget>[1], snapshot: PageSnapshot | null,
content: string | Uint8Array | StreamedFileContent | null, options: Parameters<typeof prepareFileTarget>[5] & object,
target: { root: string; path: string; mode: Awaited<ReturnType<typeof scannerSlugRootMode>> | undefined; capturedPath: string | null | undefined; before: Buffer | FileBytes | null }): Promise<PreparedMutation['file']> {
const { root, path, mode, capturedPath, before } = target;
// GST-1582: an earlier write to this page held for an import that has not landed goes first, so this one is held behind the
// same import (holdForImport) and both are released, in admission order, at its checkpoint; it never commits before the held one.
// GST-1623: only a journaled request (one with a sequence) waits, and only on a write admitted before it; an effect or a
// maintenance read of the file (Git and withdrawal-mirror effects, lint, drift checks) is never refused by another request's hold.
const [heldFirst] = row.sequence == null ? [] : await engine.executeRaw<{ deferred_import_from: string }>(`SELECT r.deferred_import_from FROM persistence_requests r
JOIN sources s ON s.id=r.source_id WHERE r.source_id=$1 AND r.slug=$2 AND r.sequence<$3 AND r.state='deferred' AND r.deferred_import_from IS NOT NULL
AND COALESCE(s.last_commit,'')=r.deferred_import_from ORDER BY r.sequence LIMIT 1`, [row.source_id, row.slug, String(row.sequence)]);
if (heldFirst) throw pendingImportRefusal(row, options.remote === true, heldFirst.deferred_import_from, { root, path });
const beforeHash = () => before instanceof FileBytes ? before.hash() : sha256(before!);
if (options.deleting === true && options.sharedOrigin && snapshot && before) {
const target: FileClaimTarget = { sourceId: row.source_id, slug: row.slug, pageId: snapshot.page.id, root, path, canonicalPath: realpathSync(path),
mode: mode ?? await scannerSlugRootMode(engine, row.source_id, root), recordedUri: capturedPath ? snapshot.page.source_uri ?? null : null };
const claimants = await findLiveFileClaimants(engine, target);
if (claimants.length) { options.sharedOrigin.onShared({ target, claimants }); return undefined; }
}
// G7a: a page whose file its private transition removed (withheld_source_path) writes it again; the file is absent by design.
// So does a strict page that was private from its first write (database_only_reason private, no file ever recorded): it
// writes its file for the first time when it turns world.
const withheld = !snapshot?.page.source_path && (Boolean(snapshot?.page.withheld_source_path) || (!before && !!snapshot && !snapshot.page.source_uri
&& isPrivacyClass((await engine.executeRaw<{ reason: string | null }>('SELECT database_only_reason AS reason FROM pages WHERE id=$1', [snapshot.page.id]))[0]?.reason)));
if (!before && snapshot && !snapshot.page.deleted_at && !options.allowMissing && !withheld) {
// A declared db_only page has no canonical file by design and publishes to
// the database only. gbrain.yml is consulted only here, where the write
// would otherwise refuse, so an invalid config can only change the refusal.
// Derive-phase output (atoms/, concepts/, ...) is database-only by design and
// deliberately never declared in gbrain.yml. A page there that never recorded a
// canonical file publishes to the database only; a recorded file that went
// missing still refuses below.
if (publishesDatabaseOnly(root, row.slug, snapshot)) return undefined;
if (options.deleting === true && content === null && !snapshot.page.source_path && !capturedPath) return undefined;
// G2: on a strict source a removal Git already holds (a replay after the door commit landed) completes in the database;
// G7a: one whose file HEAD still holds (only the worktree copy is gone) is committed through the door.
if (options.deleting === true && content === null && await sourceCanonicalGit(engine, row.source_id)) {
return await headBlob(root, path) === null ? undefined : { path, root, content: null, expectedBeforeHash: null };
}
// #6696 (A12): tagged, so a producer can refuse this before admission and the receipt says which refusal it was.
throw opError('source_changed', 'The canonical file was removed outside coordinated publication.',
`Import the local deletion or recover the canonical file before editing this page. To narrow who reads it without restoring its file, add a page rule: gbrain access rule add --slug ${row.slug} --readers <member> --source ${row.source_id} (it previews; --yes applies).`, { detail: CANONICAL_FILE_MISSING });
}
// A normal edit may replace only the bytes represented by its read snapshot.
// Unknown local edits require explicit import/recovery, even for force writes.
if (before && snapshot) {
const importPath = async () => scannerSourcePath(root, path, mode ?? await scannerSlugRootMode(engine, row.source_id, root));
// An inline page's file over the push-scan cap cannot hold its body (at most 24 MiB): drift, never read whole.
const matches = bodyUnread(snapshot.page) ? await segmentedFileMatches(engine, row.slug, before, snapshot, importPath, options.activePack, options.between)
: before.length <= PUSH_SCAN_MAX_FILE_BYTES && await fileMatchesSnapshot(engine, row.slug, (before instanceof FileBytes ? Buffer.from(before.subarray()) : before).toString('utf8'), snapshot, importPath, options.activePack);
// #6986: a declared db_only page or a never-filed derive-phase page (atoms/, ...) is canonical in the database, so the
// file at its path is a cache. A cache that holds a state the database already had (the live page or a recent
// version), left behind by a writer that skipped it, is refreshed by this write under the bytes compared; a cache
// holding content the database never had is an uncoordinated edit and still refuses below.
const staleCache = !matches && before instanceof Buffer && publishesDatabaseOnly(root, row.slug, snapshot)
&& await replaceableFile(engine, row.source_id, row.slug, path).then(check => check.ok && check.expectedFileBytes === before.toString('utf8'));
// G2: a strict publication replayed after its door commit landed finds exactly its own bytes, committed, and completes against them.
const landed = !matches && !staleCache && content !== null && beforeHash() === fileContentHash(content)
&& await sourceCanonicalGit(engine, row.source_id) && await committedBlob(root, path) !== null;
if (landed) return { path, root, content, expectedBeforeHash: beforeHash() };
if (!matches && !staleCache) {
const held = await heldFileRefusal(engine, row, root, path, 'drift', options.remote === true);
if (held) throw held;
// #6394: a page that never recorded its file reconciles against the file at its slug path only when adopted explicitly.
const adopt = !snapshot.page.source_path && !snapshot.page.source_uri ? ['--adopt-slug-path'] : [];
// #6693: a committed Git change sync has not imported yet (another agent's commit), on a page that records its file.
if (!adopt.length) {
// GST-1582: read before the check, so a write held for the import never waits on a commit the check already saw imported.
const [source] = await engine.executeRaw<{ last_commit: string | null }>('SELECT last_commit FROM sources WHERE id=$1', [row.source_id]);
if (await waitingOnWhile(options.clock, 'git', () => committedPendingImport(engine, row.source_id, root, path, options.clock?.signal))) throw pendingImportRefusal(row, options.remote === true, source?.last_commit ?? '', { root, path });
}
// #8109: drift confined to ordinary frontmatter keys never blocks a write that leaves the frontmatter alone.
const spliced = !adopt.length && options.deleting !== true && typeof content === 'string' && before instanceof Buffer && !bodyUnread(snapshot.page) && before.length <= PUSH_SCAN_MAX_FILE_BYTES
? await frontmatterDriftWrite(engine, row.slug, before.toString('utf8'), snapshot, content, options.activePack) : null;
if (spliced !== null) return { path, root, content: spliced, expectedBeforeHash: beforeHash() };
// GST-1601: the drifted file rides the refusal, so the owner can adopt a one-sided local edit (local-edit-adoption.ts).
throw Object.assign(opError('source_changed', 'The canonical file contains an uncoordinated local edit.',
`On the brain host, run gbrain sources reconcile ${row.source_id} ${row.slug} --brain <brain id, host by default> --preview${adopt.length ? ' --adopt-slug-path (the page records no file of its own, so the preview adopts the file at its slug path)' : ''}, review and apply the resolved preview, then retry this write with a new request_id. Neither copy was overwritten.`,
{ detail: 'file_database_drift', fix: readFix(`Previews how page ${row.slug}'s canonical file and database copy reconcile; a preview never changes canonical content.`,
{ argv: ['gbrain', 'sources', 'reconcile', row.source_id, row.slug, '--brain', 'host', '--preview', ...adopt] }) }),
adopt.length || options.deleting === true ? {} : { localEdit: { root, path } });
}
if (matches && options.labelEdit && typeof content === 'string') {
return { path, root, content: labelEditFile(row.slug, before, content, options.labelEdit, snapshot, options.activePack), expectedBeforeHash: beforeHash() };
}
} else if (before && !snapshot && content !== null && beforeHash() !== fileContentHash(content)
&& !(options.capture && beforeHash() === options.capture.hash)) {
throw await heldFileRefusal(engine, row, root, path, 'occupied', options.remote === true)
?? new OperationError('source_changed', 'An unindexed file already occupies the canonical page path.', 'Import the file before replacing it.');
}
return { path, root, content, expectedBeforeHash: before ? beforeHash() : null };
}
/**
* #5988: a drift or occupied-path refusal whose file sync holds names the hold
* instead of reconciliation: the page stays read-only for put_page until the
* file is repaired. Two point reads, only when the refusal already fires.
*/
async function heldFileRefusal(engine: BrainEngine, row: Pick<WriteRequest, 'source_id' | 'slug'>, root: string, path: string,
kind: 'drift' | 'occupied', remote: boolean): Promise<OperationError | null> {
const [source] = await engine.executeRaw<{ incarnation: string }>('SELECT incarnation::text AS incarnation FROM sources WHERE id=$1', [row.source_id]);
const hold = source ? await readGitHold(engine, row.source_id, source.incarnation, relative(root, path).split(sep).join('/')) : null;
if (!hold) return null;
const effect = kind === 'drift' ? `page ${row.slug} keeps its last good revision and` : `page ${row.slug} does not exist yet and its path`;
if (remote) {
// Remote callers get the code and the host operator's command, never the held path or key.
const error = opError('source_changed', heldFileMessage(kind, hold.code, { sourceId: row.source_id, incarnation: source!.incarnation }),
`Sync holds this page's canonical file in source ${row.source_id} (${hold.code}${hold.meta.reason ? `, ${hold.meta.reason}` : ''}) because gbrain cannot import it, `
+ `so ${effect} is read-only for put_page until the brain host operator repairs the file; retrying this write refuses the same way. Relay the fix to the user, then submit the intended write with a new request_id. Neither copy was overwritten.`,
{ fix: hostOperatorFix([{ source_id: row.source_id, route: recordRoute(hold) }], `The canonical file of page ${row.slug} is held (${hold.code}): only the brain host operator can inspect and repair it.`) });
if (kind === 'drift') error.detail = 'file_database_drift';
error.reason = SYNC_HELD;
return error;
}
const fix = gitHoldFix(hold);
const where = [hold.meta.line !== undefined ? `line ${hold.meta.line}` : '', hold.meta.key ? `key "${hold.meta.key}"` : ''].filter(Boolean).join(', ');
const error = opError('source_changed', heldFileMessage(kind, hold.code, { sourceId: row.source_id, incarnation: source!.incarnation }),
`Sync holds ${hold.path} in source ${row.source_id} (${hold.code}${hold.meta.reason ? `, ${hold.meta.reason}` : ''}${where ? ` at ${where}` : ''}) because gbrain cannot import it, `
+ `so ${effect} is read-only for put_page until the file is repaired; retrying this write refuses the same way. `
+ `Repair the file first (${shellQuote(fix.argv ?? [])}: ${fix.why}), then submit the intended write with a new request_id. Neither copy was overwritten. `
+ `Hold row read: op ${GIT_HOLD_OP}, fingerprint ${gitHoldFingerprint(row.source_id, source!.incarnation, hold.path)}, held since ${hold.held_at}.`, { fix });
if (kind === 'drift') error.detail = 'file_database_drift';
error.reason = SYNC_HELD;
return error;
}
/**
* Receipt reason for a page write that publishes no file. Invariant: for a
* bound row, prepareFileTarget returns no target only for a live declared
* db_only page whose file is absent, a page of a read-only mirror source
* (#5409), a page written while its source was unbound (#5254) in any state, or a page merged into its duplicate (#6948);
* every other case returns a target or throws.
*/
export function databaseOnlyPublication(row: Pick<WriteRequest, 'worktree_id'>, file: PreparedMutation['file']): Pick<PreparedMutation, 'databaseOnlyReason'> {
return row.worktree_id && !file ? { databaseOnlyReason: 'db_only' } : {};
}
/**
* G7a: the file target of a strict page turning private (git-declared.ts): the removal of the file it still has in the
* worktree or at HEAD, which the door commits. The publication then stamps `database_only_reason` and clears
* `source_path`/`source_uri` in the same transaction (`declareStrictPublication`). Undefined when there is no file to
* remove, the write is unbound, or the source is not strict (such a page publishes as before).
*/
export async function preparePrivateTransition(engine: BrainEngine, row: Pick<WriteRequest, 'source_id' | 'worktree_id' | 'slug'>, snapshot: PageSnapshot,
options: { remote?: boolean; clock?: ClaimPhaseClock } = {}): Promise<PreparedMutation['file']> {
if (!row.worktree_id || !await sourceCanonicalGit(engine, row.source_id)) return undefined;
return prepareFileTarget(engine, row, snapshot, null, undefined, { ...options, deleting: true });
}
export async function pageDatabaseOnlyPublication(engine: SqlEngine, row: WriteRequest, file: PreparedMutation['file']): Promise<Pick<PreparedMutation, 'databaseOnlyReason'>> {
const reason = databaseOnlyPublication(row, file);
if (reason.databaseOnlyReason && (await sourceMirrorReadOnly(engine, row.source_id) || await isMirrorOnlyPage(engine, row.source_id, row.slug))) {
return { databaseOnlyReason: 'mirror_read_only' };
}
if (reason.databaseOnlyReason && await isOriginTwinPage(engine, row.source_id, row.slug)) return { databaseOnlyReason: 'origin_twin' };
return reason.databaseOnlyReason && await isUnboundSourcePage(engine, row.source_id, row.slug) ? { databaseOnlyReason: 'unbound_source' } : reason;
}
/**
* #6368: a tombstone whose file is under sync.exclude does not own that file (sync never reads it again), so its purge is
* database-only: the file is neither compared nor removed. `excludedPath` names that file; the apply re-checks it.
* #7613: the same holds for a file at a root sync metafile path (`unimportedBySync`), so every tombstone purge runs the check.
* #8920: a root metafile is never a page's file whatever the delete (a soft delete, remote included, or an owner purge of a
* live page), so every delete runs the metafile check and publishes database-only; sync.exclude still applies to tombstone purges only.
*/
async function prepareDeleteFileTarget(engine: BrainEngine, row: WriteRequest, snapshot: PageSnapshot, purge: boolean,
options: Parameters<typeof prepareFileTarget>[5]): Promise<{ file: PreparedMutation['file']; excludedPath: string | null; shared: SharedOrigin | null }> {
let excludedPath: string | null = null, shared: SharedOrigin | null = null;
const patterns = purge && snapshot.page.deleted_at != null ? await syncExcludePatterns(engine) : [];
const file = await prepareFileTarget(engine, row, snapshot, null, undefined, { ...options, excludeTombstone: { patterns, onExcluded: (path: string) => { excludedPath = path; } },
sharedOrigin: { onShared: value => { shared = value; } } });
return { file, excludedPath, shared };
}
/** #6517: the recorded-origin census of a delete's file (file-claims.ts) and the other live pages that record it. */
export interface SharedOrigin { target: FileClaimTarget; claimants: FileClaimant[] }
export const sharedOriginReceipt = (sourceId: string, survivor: string | null) => 'The selected database page is hidden; the file and the surviving page remain. This does not erase that file\'s contents. '
+ `Sync does not overwrite the surviving page with the file (#6712: a file whose page differs from it is held file_drift); import the file's current content into it with gbrain repair file-drift --source ${sourceId} --slug ${survivor ?? '<surviving-slug>'} --prefer file `
+ '(it previews and writes nothing; run the apply command it prints), then gbrain sync --source ' + sourceId + ' --no-pull. Edit the file first if it holds the deleted page\'s text.';
/**
* #6517 [R8]: the survivor is revalidated under publication: the kept file must still resolve to the same real file and the
* same live pages must still record it; otherwise the delete refuses and the file is never removed as a fallback.
* [R9]: the receipt names a surviving slug only to the trusted local owner, or to a remote writer whose grant and visibility cover it.
*/
async function validateSharedOrigin(tx: BrainEngine, row: WriteRequest, shared: SharedOrigin, retentionPurge: boolean): Promise<string> {
const changed = retentionPurge ? sharedTombstoneChanged : sharedOriginChanged;
let canonicalPath: string;
try { canonicalPath = realpathSync(shared.target.path); }
catch { throw changed(row, 'the shared file was moved or removed'); }
const claimants = await findLiveFileClaimants(tx, { ...shared.target, canonicalPath });
if (claimants.map(page => page.id).join(',') !== shared.claimants.map(page => page.id).join(',')) throw changed(row, 'the pages recording the shared file changed');
const named: string[] = [];
for (const page of claimants) if (await slugDisclosable(tx, row.authority, page.slug)) named.push(page.slug);
const who = named.length ? `Another page of this source records the same file: ${named.join(', ')}.` : 'Another page of this source records the same file.';
if (retentionPurge) return `${who} The expired tombstone was removed database-only: the file and the surviving page are untouched, and no content tombstone was written.`;
return `${who} ${sharedOriginReceipt(row.source_id, named.length === 1 ? named[0]! : null)}`;
}
function sharedOriginChanged(row: WriteRequest, what: string): OperationError {
const error = pageRefusal('source_changed', `The shared canonical file changed while the delete was prepared: ${what} before it published, so nothing was written and the file was not removed. Submit the delete again with a new request_id; it re-reads the file's claimants.`, row,
`Page ${row.slug}'s file in source ${row.source_id} was recorded by another live page when this delete was prepared.`, pageFix(row.source_id, row.slug));
error.detail = 'shared_origin';
return error;
}
/**
* #7311: the retention purge of a shared-origin tombstone whose census moved defers (a revision race to the purge, which
* retries it next run): the next preparation reads the claimants again, so a tombstone that now owns the file alone
* takes the normal purge path and its file is compared and removed, never left behind.
*/
function sharedTombstoneChanged(row: WriteRequest, what: string): OperationError {
return pageRefusal('revision_conflict', `The shared canonical file changed while the purge was prepared: ${what} before it published, so nothing was purged and the file was not removed. The next purge run reads the file's claimants again.`, row,
`Page ${row.slug}'s file in source ${row.source_id} was recorded by another live page when this retention purge was prepared.`, pageFix(row.source_id, row.slug));
}
/**
* #7613: whether sync never imports the file at `rel` (source-relative, `/`-separated): it is under sync.exclude, or it is a
* sync metafile at the source root, which is scaffolding in every `sync.metafile_pages` mode. A nested metafile can be a page.
*/
function unimportedBySync(rel: string, exclude: string[]): boolean {
return (!rel.includes('/') && isSyncMetafile(rel)) || matchesAnyGlob(rel, exclude);
}
async function assertStillSyncExcluded(tx: BrainEngine, row: WriteRequest, excludedPath: string): Promise<void> {
if (unimportedBySync(excludedPath, await syncExcludePatterns(tx))) return;
throw pageRefusal('source_changed', 'sync.exclude changed while the purge was prepared.', row,
`${excludedPath} was excluded from sync when the purge of ${row.slug} was prepared and is not any more, so nothing was purged. Run the purge again; it re-reads the exclusion.`, pageFix(row.source_id, row.slug));
}
/** The `delete_page` preparation: soft delete, or purge with its journal sweep (#6511) run under the preparation budget. */
async function prepareDeletePageMutation(engine: BrainEngine, row: WriteRequest, snapshot: PageSnapshot | null,
options: { activePack?: ParseOpts['activePack']; clock?: ClaimPhaseClock; allowMissingFile?: boolean }): Promise<PreparedMutation> {
const p = row.intent!, source = { sourceId: row.source_id }, clock = options.clock;
assertPurgeParams(p, row.authority.remote);
if (!snapshot) throw pageRefusal('page_not_found', 'Page not found.', row,
`Page ${row.slug} does not exist in source ${row.source_id}, so nothing was deleted. Check the slug and the source.`, pageFix(row.source_id, row.slug));
const observedRevision = snapshot.revision;
const purge = p.purge === true;
const noop = !purge && snapshot.page.deleted_at != null;
// Always-loaded core pages: a remote caller cannot delete one (owner-only).
if (!noop) { enterClaimStep(clock, 'core_guard', undefined, 'db'); await prepareCoreGuard(engine, { row, snapshot, incoming: null }); }
enterClaimStep(clock, 'file_target', undefined, 'fs');
// Tombstones still own their recorded artifact. Purge always attempts its
// removal before the guarded hard-delete and receipt commit; failure rolls
// back to the prior row, and replay survives the eventual absence of that row.
const { file, excludedPath, shared } = await prepareDeleteFileTarget(engine, row, snapshot, purge, { allowMissing: purge || options.allowMissingFile, deleting: true, activePack: options.activePack, remote: row.authority.remote });
// #6517: an owner purge tombstones content hashes source-wide, so a page whose file another live page records is only
// soft-deleted. #7311: the retention purge of such a tombstone tombstones nothing, so it removes the row database-only.
const sharedRetention = shared !== null && purge && p.retention === true && snapshot.page.deleted_at != null;
if (shared && purge && !sharedRetention) {
const next = snapshot.page.deleted_at != null
? 'The page is already soft-deleted (hidden; the file and the surviving page remain): the retention purge removes it database-only once it is older than the recovery window, with no content tombstone (gbrain pages purge-deleted --older-than 72h --yes, or the autopilot purge phase).'
: `Soft-delete it instead (gbrain delete ${row.slug} --source-id ${row.source_id} --expected-revision <rev>): the page is hidden, the file and the surviving page remain, and nothing is erased.`;
const error = pageRefusal('source_changed', `The page's canonical file is shared with another live page, so a purge (which tombstones its content source-wide) was refused and nothing was removed, tombstoned or redacted. ${next}`, row,
`Another live page of source ${row.source_id} records the file of ${row.slug}.`, pageFix(row.source_id, row.slug));
error.detail = 'shared_origin';
throw error;
}
// GST-2201: a retention purge never removes a file committed at the source's last commit or at HEAD. A tombstone sync made
// from the file's absence waits for the sync that restores it; a person's tombstone is removed database-only and the file stays.
// A person's delete that made this tombstone and never removed its file (`write_through.written: false`: another live page
// shared it, the source was unbound, ...) still has the purge finish that removal. Publication re-checks, so a commit made after preparation is kept too.
const retentionFile = purge && p.retention === true && snapshot.page.deleted_at != null && !!file && !shared && excludedPath === null;
const committedNow = async (exec: BrainEngine) => await originCommitted(exec, row.source_id, snapshot.page.source_path)
&& (await exec.executeRaw(`SELECT 1 FROM persistence_requests r JOIN pages p ON p.id=$3 WHERE r.source_id=$1 AND r.slug=$2 AND (r.page_id IS NULL OR r.page_id=$3)
AND r.operation='delete_page' AND r.state='committed' AND r.outcome->'write_through'->>'written'='false' AND NOT ${syncDeleteOrigin('p')}
AND NOT EXISTS (SELECT 1 FROM persistence_requests l WHERE l.source_id=r.source_id AND l.slug=r.slug AND l.state='committed' AND l.sequence > r.sequence
AND l.operation IN ('restore_page', 'delete_page')) LIMIT 1`, [row.source_id, row.slug, snapshot.page.id])).length === 0;
const committedFile = retentionFile && await committedNow(engine);
let keepOrigin = false;
if (committedFile) {
const [made] = await engine.executeRaw<{ sync: boolean }>(`SELECT ${syncDeleteOrigin('p')} AS sync FROM pages p WHERE p.id=$1`, [snapshot.page.id]);
// Only a file on disk can come back through sync: one off disk in working-tree mode is purged database-only instead.
if (made?.sync && existsSync(file!.path)) throw pageRefusal('revision_conflict', 'The file of this sync-deleted page is committed again, so the retention purge left the page and the file alone; the next sync restores the page.', row,
`Page ${row.slug}'s file is committed in source ${row.source_id}'s checkout.`, pageFix(row.source_id, row.slug));
keepOrigin = made?.sync === true;
}
// #6511: the purge's journal sweep runs here, under the preparation budget, never inside the 5 s publication transaction.
const preparedPurge: PreparedPagePurge | null = purge ? { ...await preparePagePurge(engine, row, snapshot, clock), ...(keepOrigin ? { keepOrigin } : {}) } : null;
// #6948: a page merged into its duplicate holds that page's body, so an owner purge would tombstone the survivor's content.
if (preparedPurge && !preparedPurge.retention && await isOriginTwinPage(engine, row.source_id, row.slug)) {
const error = pageRefusal('source_changed', 'The page was merged into a duplicate that holds the same content, so a purge (which tombstones its content source-wide) was refused and nothing was removed, tombstoned or redacted. '
+ 'The 72 h retention purge removes it database-only; to erase the content itself, purge the page it was merged into.', row,
`${row.slug} of source ${row.source_id} was merged into a duplicate page (gbrain repair origin-twins).`, pageFix(row.source_id, row.slug));
error.detail = 'origin_twin';
throw error;
}
const prepared: PreparedMutation = { observedRevision, noop, file: committedFile ? undefined : file, ...await pageDatabaseOnlyPublication(engine, row, committedFile ? undefined : file),
// W1: a purge bumps sources.purge_epoch, so it holds the source row exclusively from the start (retention bumps nothing, #26);
// the derived rows' and cascaded links' streams are locked with the page.
...(purge && !preparedPurge?.retention ? { sourceExclusive: true } : {}),
// The purge mirror's `committed` line comes from the coordinator after the commit, whoever waits for the reply (#23).
...(preparedPurge && !preparedPurge.retention ? { afterCommit: async () => { appendPurgeCommitted(row.id); } } : {}),
...(preparedPurge?.derivedSlugs.length ? { additionalPageKeys: preparedPurge.derivedSlugs.map(slug => ({ sourceId: row.source_id, slug })) } : {}),
...(excludedPath !== null ? { databaseOnlyReason: 'sync_excluded' as const } : {}), ...(shared ? { databaseOnlyReason: 'shared_origin' as const } : {}),
...(committedFile ? { databaseOnlyReason: 'committed_file' as const } : {}),
...(shared ? { validate: async (tx: BrainEngine) => { prepared.databaseOnlyWarning = await validateSharedOrigin(tx, row, shared, sharedRetention); } } : {}),
...(retentionFile && !committedFile ? { validate: async (tx: BrainEngine) => {
if (await committedNow(tx)) throw pageRefusal('revision_conflict', 'The page\'s file was committed while the retention purge was prepared, so the purge left the page and the file alone; the next run re-reads it.', row,
`Page ${row.slug}'s file is committed in source ${row.source_id}'s checkout.`, pageFix(row.source_id, row.slug));
} } : {}),
apply: async tx => {
if (row.authority.remote) await refuseRemoteGuestDelete(tx, row.source_id, row.slug, requestPrincipal(row));
if (purge && excludedPath !== null) await assertStillSyncExcluded(tx, row, excludedPath);
// #7311: the tombstone forgets the survivor's file, as an origin_twin page has, so its purge writes no deletion marker for it.
if (preparedPurge && sharedRetention) return purgePageInTransaction(tx, row, { ...snapshot, page: { ...(bodyUnread(snapshot.page) ? withoutBody(snapshot.page) : snapshot.page), source_path: null, source_uri: null } as Page }, preparedPurge);
if (preparedPurge) return purgePageInTransaction(tx, row, snapshot, preparedPurge);
// GST-2518: a soft delete authors no content, so the tombstone keeps its tier (and a write over it the page's label guard).
if (!noop) { await tx.createVersion(row.slug, source); await withTrustKeep(tx, ['pages'], () => tx.softDeletePage(row.slug, source)); }
return { status: 'soft_deleted', slug: row.slug, source_id: row.source_id, noop,
recoverable_until: 'now + 72h via restore_page (remove immediately instead: gbrain delete <slug> --purge, local CLI only)' };
} };
return prepared;
}
/**
* Wave B: `restore_page` of a segmented page whose body was not read back (over the single-string ceiling). Soft
* delete only set `deleted_at` (its body, chunks, links and projections stay), so the restore clears it without
* re-serializing or re-importing the body: version, clear, reseal (or queue the projection when chunks are missing or a
* deferred retirement left rows of retired occurrences).
* Whether it reseals is decided here, before publication: both probes read one index entry per live occurrence, so on
* a loaded host they can outlast the publication transaction's 5 s statement_timeout, and a cancelled publication is
* prepared and its whole file streamed again. Deciding here is exact: the transaction publishes only at the observed
* revision, so the page is still soft-deleted at the same body generation, and a deleted page gains no chunk rows
* (its projection skips it) and loses only rows its live generation does not hold.
* The canonical file is serializePageToMarkdown's bytes streamed from the segments by export's serializer into one
* buffer, never one string. The restore adds no text, so an agent-tier writer's advisory gate scan (flag only) is not
* re-run over the stored body; a step that needs the whole body refuses (`page_body_segmented`): a core page's budget
* render, and an external_untrusted writer, whose gate may quarantine or reject.
*/
async function prepareUnreadRestore(engine: BrainEngine, row: WriteRequest, snapshot: PageSnapshot,
options: { activePack?: ParseOpts['activePack']; clock?: ClaimPhaseClock; allowMissingFile?: boolean }): Promise<PreparedMutation> {
const source = { sourceId: row.source_id };
const noop = snapshot.page.deleted_at == null;
const storedTier = await storedPageTier(engine, row.source_id, row.slug);
const trust = pageWriteTrust(row, snapshot.page.frontmatter);
const gateTrust = pageGateTrust(row, trust, storedTier);
if (!noop && gateTrust?.tier === 'external_untrusted' && writeGateApplies(gateTrust.tier, (await loadImportSanityConfig(engine)).writeGate ?? DEFAULT_WRITE_GATE_CONFIG)) {
throw pageBodySegmentedError(snapshot.page, 'restore_page (the write gate scans the whole body of an external_untrusted write)');
}
enterClaimStep(options.clock, 'core_guard', undefined, 'db');
const core = noop ? null : await prepareCoreGuard(engine, { row, snapshot, incoming: snapshot.page });
enterClaimStep(options.clock, 'file_target', undefined, 'fs');
const file = await prepareFileTarget(engine, row, snapshot, await unreadPageFile(engine, snapshot), undefined,
{ allowMissing: options.allowMissingFile, activePack: options.activePack, remote: row.authority.remote, clock: options.clock });
const pageId = Number(snapshot.page.id);
enterClaimStep(options.clock, 'seal_probe', undefined, 'db');
const generation = Number(snapshot.bodyGeneration), live = noop ? [] : await engine.readManifest(pageId, { generation });
const complete = noop || !(await occurrencesWithoutChunks(engine, pageId, generation, live)).length
&& !await hasStaleChunks(engine, pageId, generation, live.map(row => Number(row.occurrenceId)));
const prepared: PreparedMutation = { observedRevision: snapshot.revision, noop, file, ...await pageDatabaseOnlyPublication(engine, row, file),
...(core ? { exclusiveSources: core.exclusiveSources } : {}), ...(trust ? { trust } : {}),
validate: async tx => { await core?.validate(tx); },
apply: async tx => {
if (noop) return { ...pageNoopAdvisories(row), status: 'skipped', slug: row.slug, source_id: row.source_id, noop: true, chunks: 0, chunk_skip_reason: 'write_skipped' };
await tx.createVersion(row.slug, source);
await tx.restorePage(row.slug, source);
const lowered = storedTier ? await recordAgentPageLowering(tx, row, { tier: storedTier, revision: snapshot.revision }) : null;
if (complete) await sealSegmentedPage(tx, pageId);
if (core) await core.record(tx, (await tx.readPageSnapshot(row.slug, source))?.revision ?? null);
return { ...pageNoopAdvisories(row), status: 'restored', slug: row.slug, source_id: row.source_id, chunks: 0, noop: false,
...(complete ? {} : { projection: 'pending' }), ...await sizeStateField(tx, row.source_id, row.slug, snapshot.page),
...(lowered ? { trust_lowered: lowered } : {}) };
},
afterCommit: async target => { if (!complete) await buildSegmentedProjection(target, { sourceId: row.source_id, slug: row.slug }).catch(() => undefined); } };
return prepared;
}
/**
* GBRA-504: `restore_page` of a guest page (only the local owner may submit one). Soft delete only set `deleted_at`, so
* the restore clears it without re-importing the body: a re-import would rewrite the page's content columns, which the
* guest-source guard refuses from anyone but a listed writer, and would project rows a guest page never has. A guest
* source is database-only, so there is no file to write.
*/
async function prepareGuestRestore(engine: BrainEngine, row: WriteRequest, snapshot: PageSnapshot): Promise<PreparedMutation> {
const source = { sourceId: row.source_id };
const noop = snapshot.page.deleted_at == null;
return { observedRevision: snapshot.revision, noop, ...await pageDatabaseOnlyPublication(engine, row, undefined),
validate: async () => {},
apply: async tx => {
if (noop) return { ...pageNoopAdvisories(row), status: 'skipped', slug: row.slug, source_id: row.source_id, noop: true, chunks: 0, chunk_skip_reason: 'write_skipped' };
await tx.createVersion(row.slug, source);
await tx.restorePage(row.slug, source);
await sealPageTextProjection(tx, row.slug, row.source_id);
return { ...pageNoopAdvisories(row), status: 'restored', slug: row.slug, source_id: row.source_id, chunks: 0, noop: false };
} };
}
/**
* serializePageToMarkdown's bytes for a page whose body was not read back, streamed from its segments by export's
* serializer: measured here, produced again into the publication's staging file (large-file.ts), never concatenated.
* A withdrawal mirror of a segmented page (effects.ts, effect-recovery.ts) renders its file the same way, with
* `between` (its claim renewal) run after each piece each time the file is produced. The body is read at the snapshot's
* revision; a page that moved since refuses `revision_conflict`, as a changed staging hash does, so the request prepares again.
*/
export async function unreadPageFile(engine: BrainEngine, snapshot: PageSnapshot, between?: () => Promise<void>, ledger: BodyLedger = snapshotLedger(snapshot)): Promise<StreamedFileContent> {
const head = serializePageToMarkdown({ ...withoutBody(snapshot.page), compiled_truth: '', timeline: '' }, snapshot.tags).slice(0, -1);
const produce = async function* (exec: BrainEngine) {
try { yield* segmentedExportMarkdown(exec, snapshot.page, ledger, head, snapshot.revision); } catch (error) {
if (!(error instanceof OperationError) || error.canonical !== 'revision_changed') throw error;
throw new OperationError('revision_conflict', PAGE_CHANGED_DURING_PREPARATION_MESSAGE, 'Read its current revision and submit the updated intent with a new request_id.');
}
};
return StreamedFileContent.measure(engine, !between ? produce : async function* (exec) { for await (const piece of produce(exec)) { yield piece; await between(); } });
}
/** Work counters of segmented tag flips: `flips` applied, `hashStreams` content hashes recomputed over the segments. */
export const segmentedTagWork = { flips: 0, hashStreams: 0 };
/**
* Wave B (spec 6.4): add_tag / remove_tag on a segmented page, at any size, as a metadata flip that reuses the live
* manifest: the body generation, segment texts and chunks stay as they are. As the inline tag write does, it versions
* the page (a segmented version references the live generation, O(1)), changes the tag rows, stores the new
* content_hash and reseals a sealed page at its new revision; the canonical file is serializePageToMarkdown's bytes
* with the new tags, streamed from the segments (unreadPageFile). The hash resumes from the last live row's midstate
* (content-hash-stream.ts); a midstate that does not reproduce the stored hash is replaced by one pass over the segments.
* Null when the write gate would scan the whole body (an external_untrusted writer): that write takes the put path.
*/
export async function prepareSegmentedTagMutation(engine: BrainEngine, row: WriteRequest, snapshot: PageSnapshot, tags: string[]): Promise<PreparedMutation | null> {
const tagHold = tagLengthHold(tags);
if (tagHold) throw contentRefusalError(tagHold, TAG_TOO_LONG_SUGGESTION, { legacy_error: 'invalid_params' });
const source = { sourceId: row.source_id };
const [, pack, storedTier] = await Promise.all([assertKnowledgePublicationAllowed(engine, row),
loadActivePackForEngine(engine, { remote: row.authority.remote, sourceId: row.source_id }).catch(() => null), storedPageTier(engine, row.source_id, row.slug)]);
const noop = tags.length === snapshot.tags.length && tags.every(tag => snapshot.tags.includes(tag));
const trust = pageWriteTrust(row, snapshot.page.frontmatter);
const gateTrust = pageGateTrust(row, trust, storedTier);
if (!noop && gateTrust && writeGateApplies(gateTrust.tier, (await loadImportSanityConfig(engine)).writeGate ?? DEFAULT_WRITE_GATE_CONFIG)
&& gateTrust.tier === 'external_untrusted') return null;
const pageId = Number(snapshot.page.id);
const hash = noop ? snapshot.page.content_hash : await segmentedContentHash(engine, snapshot, tags);
const file = row.worktree_id ? await prepareFileTarget(engine, row, snapshot, await unreadPageFile(engine, { ...snapshot, tags }), undefined,
{ activePack: pack?.manifest, remote: row.authority.remote }) : undefined;
const sealed = snapshot.page.text_projection_revision === snapshot.revision;
return { observedRevision: snapshot.revision, noop, file, ...await pageDatabaseOnlyPublication(engine, row, file), ...(trust ? { trust } : {}),
apply: async tx => {
if (noop) return { ...pageNoopAdvisories(row), status: 'skipped', slug: row.slug, source_id: row.source_id, noop: true, chunks: 0, chunk_skip_reason: 'write_skipped' };
await tx.createVersion(row.slug, source);
for (const tag of snapshot.tags) if (!tags.includes(tag)) await tx.removeTag(row.slug, tag, source);
for (const tag of tags) if (!snapshot.tags.includes(tag)) await tx.addTag(row.slug, tag, source);
await tx.executeRaw('UPDATE pages SET content_hash=$2, updated_at=now() WHERE id=$1', [pageId, hash]);
if (sealed) await sealSegmentedPage(tx, pageId);
segmentedTagWork.flips++;
return { ...remoteLinkHint(row), status: 'created_or_updated', slug: row.slug, source_id: row.source_id, chunks: 0, noop: false,
searchable: isQuarantined(snapshot.page.frontmatter) ? false : sealed ? true : 'pending', ...await sizeStateField(tx, row.source_id, row.slug, snapshot.page) };
} };
}
/** The content_hash of a segmented page with `tags`: its stored body and frontmatter, resumed from the last live manifest row's midstate. */
async function segmentedContentHash(engine: BrainEngine, snapshot: PageSnapshot, tags: string[]): Promise<string> {
const pageId = Number(snapshot.page.id);
const meta = { frontmatter: snapshot.page.frontmatter, tags };
const last = (await engine.readManifest(pageId)).at(-1);
const resumed = last ? (() => { try { return ContentHashStream.fromState(last.hashState); } catch { return null; } })() : null;
if (resumed && resumed.finish({ frontmatter: snapshot.page.frontmatter, tags: snapshot.tags }) === snapshot.page.content_hash) return resumed.finish(meta);
segmentedTagWork.hashStreams++;
const stream = ContentHashStream.begin(snapshot.page);
const decoder = new TextDecoder();
for await (const part of readSegmentedBody(engine, pageId, snapshot.page.source_id)) {
if (part.region === 'truth') stream.pushTruth(decoder.decode(part.bytes)); else stream.pushTimeline(decoder.decode(part.bytes));
}
return stream.finish(meta);
}
/**
* Providers and parsing run before the OS lock and before any publication transaction.
* `coordinated`: the caller publishes this mutation itself through the coordinator, whose
* page guard and revision check on `row.slug` cover this import (the put_page apply diet).
*/
/**
* `options.clock` (#6278): the claim's phase clock; each await boundary names its step through `enterClaimStep`, and the
* preparation's raw reads run bounded by its remaining budget (`boundedReads`; a statement carrying the foreground `signal` keeps it).
* `unprojected` (GBRA-190 G4): the caller writes the rows this page write would project (a fence fact append,
* facts/fence-fact-append.ts), so the page publishes without canonical projection, as remember and takes writes do.
*/
export async function preparePageMutation(unbounded: BrainEngine, row: WriteRequest, _config: GBrainConfig,
preparedIntent?: { content: string; expectedRevision: string; tags?: string[] }, signal?: AbortSignal,
options: { allowMissingFile?: boolean; coordinated?: boolean; clock?: ClaimPhaseClock; boundedChunkWrites?: true; unprojected?: true } = {}): Promise<PreparedMutation> {
// Wave B (spec 6.2): a committed upload session prepares the put_page its staged parts hold.
if (row.operation === 'put_page' && isStagingBodyRef(row.intent?.body_ref)) {
signal?.throwIfAborted();
return prepareStagedUpload(unbounded, row, staged => preparePageMutation(unbounded, staged, _config, preparedIntent, signal, options));
}
return prepareInlineOrSegmentedMutation(unbounded, row, _config, preparedIntent, signal, options,
row.operation === 'delete_page' ? NOT_A_GUEST_WRITE : await prepareGuestWrite(unbounded, row, preparedIntent?.content ?? row.intent?.content));
}
/** A remote caller's refusal names the line, never a key: keys can be private, and the receipt keeps the message. */
const remoteSafeRefusal = (row: WriteRequest, refusal: ContentRefusal): ContentRefusal =>
row.authority.remote && refusal.code === 'invalid_frontmatter' ? { ...refusal, key: undefined, message: frontmatterHoldMessageWithoutKeys(refusal.message) } : refusal;
const frontmatterRefusalError = (refusal: ContentRefusal) => contentRefusalError(refusal,
`Correct ${refusal.line !== undefined ? `frontmatter line ${refusal.line}${refusal.key ? ` (key "${refusal.key}")` : ''}` : 'the frontmatter'}: one line per key with its whole value quoted, then submit the corrected content with a new request_id.`,
{ legacy_error: 'invalid_params' });
/** A private request the importer would hold keeps the importer's typed refusal; any other must be kept as written. */
function assertPrivateRequestAllowed(row: WriteRequest, content: string, frontmatter: Record<string, unknown> | null | undefined): void {
const hold = classifyImportHold(parseMarkdown(content, row.slug, { validate: true }));
if (hold) throw frontmatterRefusalError(remoteSafeRefusal(row, hold));
assertPrivateRequestKept(row, frontmatter);
}
/**
* Core marking is owner-only: a remote write that omits always_load or
* core_priority keeps the stored values instead of silently un-coring the page.
*/
function remoteCoreMarkingKept(row: WriteRequest, snapshot: PageSnapshot | null, content: string, activePack: ParseOpts['activePack']): string {
if (!row.authority.remote || !snapshot || snapshot.page.deleted_at || typeof content !== 'string'
|| (snapshot.page.frontmatter?.always_load === undefined && snapshot.page.frontmatter?.core_priority === undefined)) return content;
const parsed = parseMarkdown(content, row.slug, { activePack });
const carried = carryCoreMarking(snapshot.page.frontmatter, parsed.frontmatter ?? {});
if (carried.always_load === parsed.frontmatter?.always_load && carried.core_priority === parsed.frontmatter?.core_priority) return content;
return serializePageToMarkdown({ ...snapshot.page, ...parsed, frontmatter: carried }, parsed.tags);
}
async function prepareInlineOrSegmentedMutation(unbounded: BrainEngine, row: WriteRequest, _config: Parameters<typeof preparePageMutation>[2],
preparedIntent: Parameters<typeof preparePageMutation>[3], signal: AbortSignal | undefined,
options: NonNullable<Parameters<typeof preparePageMutation>[5]>, guest: GuestWrite): Promise<PreparedMutation> {
signal?.throwIfAborted();
const clock = options.clock;
const engine = boundedReads(unbounded, clock);
enterClaimStep(clock, 'page_snapshot', undefined, 'db');
if (!row.intent) throw pageRefusal('storage_error', 'A pending write lost its normalized intent.', row,
`The request has no stored intent for ${row.slug} (its payload was compacted or never recorded), so it cannot be published and wrote nothing.`);
const p = row.intent;
const source = { sourceId: row.source_id };
// A coordinated (single-write) preparation sends its independent reads together; the first refusal in this order is reported.
const together = options.coordinated ? engine : { kind: 'sequential' };
const [, stored, pack] = await pipelined(together, [
() => assertKnowledgePublicationAllowed(engine, row),
() => engine.readPageSnapshot(row.slug, { ...source, includeDeleted: true }),
() => loadActivePackForEngine(engine, { remote: row.authority.remote, sourceId: row.source_id }).catch(() => null),
]) as [unknown, PageSnapshot | null, Awaited<ReturnType<typeof loadActivePackForEngine>> | null];
// Wave B (spec 6.3): edit_page on a segmented page splices the touched segments; a declined edit takes the string path.
const segmented = row.operation === 'edit_page' && stored && !stored.page.deleted_at && isSegmentedPage(stored.page) && stored.page.id === row.page_id
? await prepareSegmentedEditMutation(engine, row, stored) : null;
if (segmented) return segmented;
// Wave B: a segmented page within the single-string ceiling is compared and merged as strings.
const snapshot = await materializedSnapshot(unbounded, stored);
signal?.throwIfAborted();
enterClaimStep(clock, 'revision_check');
assertPageRevision(snapshot, preparedIntent ? { expectedRevision: preparedIntent.expectedRevision } : engineMutationPrecondition(parseMutationPrecondition(p)));
if ((snapshot?.page.id ?? null) !== row.page_id) throw pageIdentityError(snapshot != null || row.page_id === null, 'The accepted page identity changed.');
const observedRevision = snapshot?.revision ?? null;
const activePack = pack?.manifest;
const replacesTombstone = snapshot?.page.deleted_at != null && (row.operation === 'put_page' || row.operation === 'capture');
if (row.operation === 'put_page' && snapshot && !snapshot.page.deleted_at && typeof p.content === 'string'
&& `${snapshot.page.compiled_truth}\n${snapshot.page.timeline ?? ''}`.trim()) {
const incoming = parseMarkdown(p.content, row.slug, { activePack });
if (!preparedIntent && row.authority.remote) assertLargePageReplacement(row.slug, row.source_id, p, snapshot, incoming);
if (p.allow_empty !== true && !`${incoming.compiled_truth}\n${incoming.timeline ?? ''}`.trim()) {
throw new OperationError('invalid_params', `Refusing to overwrite existing non-empty page '${row.slug}' with empty content. Use capture --file PATH --slug SLUG for file input; set allow_empty:true to intentionally clear it.`,
'Use capture --file PATH --slug SLUG for file input, or pass allow_empty:true with the expected revision to intentionally clear it.');
}
}
if (row.operation === 'delete_page') return prepareDeletePageMutation(engine, row, snapshot, { activePack, clock, allowMissingFile: options.allowMissingFile });
// #6188: a trusted local fence repair's receipt (admission refuses it from every other caller) rides the outcome and the file's commit.
const fenceRepair = row.operation === 'put_page' && !row.authority.remote ? parseFenceRepairReceipt(p.fence_repair) : null;
const fenceRepairOutcome = fenceRepair ? { fence_repair: fenceRepair } : {};
// #5616: edits apply to the caller's view of the locked snapshot (revision checked above).
const edited = row.operation === 'edit_page' ? await editLockedPage(engine, row, snapshot) : undefined;
let content = edited?.content ?? preparedIntent?.content ?? p.content as string;
const privateRequest = privateRequestGuarded(row.operation, p.kind) && typeof content === 'string' ? readPrivateRequest(content, () => parseMarkdown(content as string, row.slug, { activePack }).frontmatter) : null;
if (privateRequest) assertPrivateRequestAllowed(row, content as string, privateRequest.frontmatter);
let versionTags: string[] | undefined = replacesTombstone && typeof content === 'string' ? parseMarkdown(content, row.slug, { activePack }).tags : preparedIntent?.tags;
// A replacement/restore publishes a live page. Only a recorded version may
// explicitly restore a tombstone; legacy versions leave this state unchanged.
let targetDeleted = false;
if (row.operation === 'restore_page' || row.operation === 'revert_version') {
if (!snapshot) throw pageRefusal('page_not_found', 'Page not found.', row,
`Page ${row.slug} does not exist in source ${row.source_id} (it was purged or never written), so nothing was ${row.operation === 'restore_page' ? 'restored' : 'reverted'}. Check the slug and the source.`,
pageFix(row.source_id, row.slug));
if (row.operation === 'restore_page' && (guest.write || bodyUnread(snapshot.page))) return guest.write ? prepareGuestRestore(engine, row, snapshot) : prepareUnreadRestore(engine, row, snapshot, { activePack, clock, allowMissingFile: options.allowMissingFile });
let page = snapshot.page;
let tags = snapshot.tags;
if (row.operation === 'revert_version') {
const [version] = await engine.executeRaw<PageVersion>(
'SELECT * FROM page_versions WHERE id=$1 AND page_id=$2', [p.version_id, page.id]);
if (!version) throw pageRefusal('not_found', 'Version not found for this page.', row,
`Version ${String(p.version_id)} is not in the history of page ${row.slug}, so nothing was reverted. List the page's versions (get_versions; CLI: gbrain history) and revert to one of them.`);
if (version.body_storage === 'segmented' || isSegmentedPage(page)) throw segmentedRevertRefusal(row.slug, p.version_id);
targetDeleted = version.is_deleted ?? (snapshot.page.deleted_at != null);
page = { ...page, compiled_truth: version.compiled_truth, frontmatter: version.frontmatter,
...(version.timeline !== null && version.timeline !== undefined ? { timeline: version.timeline } : {}),
...(version.title !== null && version.title !== undefined ? { title: version.title } : {}),
...(version.type !== null && version.type !== undefined ? { type: version.type } : {}) };
if (version.tags !== null && version.tags !== undefined) tags = version.tags;
versionTags = tags;
}
content = serializePageToMarkdown(page, tags);
}
if (row.authority.remote && row.operation !== 'remember' && !row.operation.startsWith('takes_') && typeof content==='string') {
const parsed=parseMarkdown(content,row.slug,{ activePack });
assertRetirementStampUnchanged(row.slug, parsed.frontmatter, snapshot?.page.frontmatter);
const compiled_truth=preserveProtectedTakes(parsed.compiled_truth,snapshot?.page.compiled_truth??''), timeline=preserveProtectedTakes(parsed.timeline??'',snapshot?.page.timeline??'');
if (compiled_truth!==parsed.compiled_truth || timeline!==(parsed.timeline??'')) content=serializePageToMarkdown({
...(snapshot?.page??{id:0,source_id:row.source_id,created_at:new Date(),updated_at:new Date()}),...parsed,compiled_truth,timeline},parsed.tags);
}
content = remoteCoreMarkingKept(row, snapshot, content, activePack);
const projected = !skipsGuestNote('publication_projections', guest.write) && !(options.unprojected || row.operation === 'remember' || row.operation.startsWith('takes_') || (row.operation === 'extract_facts' && p.kind === 'managed_facts_entity'));
const writer = replacesTombstone || ((row.operation === 'put_page' || row.operation === 'edit_page') && p.kind !== 'managed_maintenance_page'
&& (preparedIntent !== undefined || typeof p.expected_revision === 'string')) ? 'editing' : 'preserving';
// #5969 (D3): only an ordinary put_page intent carries a timeline section; every other writer keeps the shared policy.
const timelinePolicy = row.operation === 'put_page' ? timelineWritePolicy(p, row.authority.remote, writer) : undefined;
enterClaimStep(clock, 'timeline_policy', undefined, 'db');
if (timelinePolicy && typeof content === 'string') await assertTimelineNotOmitted(engine, { intent: p, remote: row.authority.remote, writer,
slug: row.slug, sourceId: row.source_id, content, prior: snapshot });
// #5567: database-only timeline rows are written back into the page before
// the no-op check, digest, rendering and chunking see the body.
if (projected && snapshot && !replacesTombstone && typeof content === 'string') {
const parsed = parseMarkdown(content,row.slug);
enterClaimStep(clock, 'materialize_timeline', undefined, 'db');
const { timeline, materialized } = await materializeTimeline(engine,parsed,row.slug,snapshot,writer,timelinePolicy);
if (materialized) content = serializePageToMarkdown({...snapshot.page,...parsed,timeline,type:parsed.typeExplicit ? parsed.type : snapshot.page.type},parsed.tags);
}
const storedTier = snapshot ? await storedPageTier(engine, row.source_id, row.slug) : null;
// Detect an exact canonical no-op before ingestion can invoke any provider.
// Revision/identity checks above still apply to stale identical replacements.
if (snapshot && (snapshot.page.deleted_at != null) === targetDeleted && typeof content === 'string') {
const incoming = parseMarkdown(content,row.slug,{ activePack });
resolveParsedSubtype(incoming, snapshot.page);
const tags = versionTags ?? [...new Set([...snapshot.tags,...incoming.tags])].sort();
if (digest(canonical(snapshot.page,snapshot.tags)) === digest(canonical(incoming,tags))) {
const file=await prepareFileTarget(engine,row,snapshot,targetDeleted ? null : serializePageToMarkdown(snapshot.page,snapshot.tags),undefined,{ activePack, remote: row.authority.remote, clock });
return {observedRevision,noop:true,file,...await pageDatabaseOnlyPublication(engine,row,file),
apply:async()=>({...pageNoopAdvisories(row),status:'skipped',slug:row.slug,source_id:row.source_id,noop:true,chunks:0,chunk_skip_reason:'write_skipped',
...(row.operation==='capture'?{channel:'capture',content_hash:p.capture_hash}:{}),...fenceRepairOutcome})};
}
}
let prepared: PreparedContentImport | undefined;
let provenance: CanonicalProvenance | undefined;
let suppliedTrustMarker: unknown;
// #5575: the page's tier, computed once before import so the write gate sees exactly it (ENG-18).
const incoming = typeof content === 'string' && !isFenceEditWrite(row) ? parseMarkdown(content, row.slug, { activePack }).frontmatter : null;
const trust = provenanceWriteTrust(row, incoming, snapshot?.page.frontmatter);
const gateTrust = pageGateTrust(row, trust, storedTier);
// GST-2518: a lower-tier local write keeps the page's privacy labels it would widen (GST-2521: and the owner as a reader); its proposal carries the request.
const labelGuard = await privacyLabelGuard(engine, row, trust, snapshot?.page ?? null, storedTier, incoming);
let heldLabels: HeldPrivacyLabels | null = null;
const defaultSourceWriter = row.operation === 'restore_page' || row.operation === 'revert_version' ? null : await defaultSourceMemberWriter(engine, row.authority), defaultSourceOwner = await defaultSourceWriterIsOwner(engine, defaultSourceWriter), ownerRewrite = ['put_page', 'edit_page', 'append_page'].includes(row.operation) ? await ownerRewriteOf(engine, row.authority, row.source_id, row.slug, row.operation === 'put_page') : null;
// The apply diet: the publisher's locked read of row.slug is the import base, and one read after the
// last page write serves the read-back check, the seal, the core notice and the receipt (as sync does).
const lean = options.coordinated === true && !targetDeleted && row.operation !== 'restore_page' && !versionTags;
enterClaimStep(clock, 'import_content', undefined, 'db');
const result = await importFromContent(engine, row.slug, content, {
...source, noEmbed: true, remote: row.authority.remote || p.keep_hidden_rows === true, restoreHeldRows: p.keep_hidden_rows === true || !await storedWriterReadsHeld(engine, row.authority), activePack, fences: projected ? 'coordinated' : 'lenient', coordinated: lean, boundedChunkWrites: options.boundedChunkWrites,
segmentedOwner: { kind: row.operation === 'edit_page' ? 'edit' : 'put', principalKind: row.principal_kind, principalId: row.principal_id, baseRevision: observedRevision },
...(lean ? { existingSnapshot: snapshot } : {}),
// #6259: only owner-tier intents keep gate-owned markers; an ordinary put_page, local or remote, has them stripped.
preserveGateMarkers: !row.authority.remote && (p.kind === 'managed_maintenance_page' || p.kind === 'managed_quarantine_clear'),
forceRechunk: row.operation === 'restore_page' || row.operation === 'revert_version',
allowEmptyOverwrite: p.allow_empty === true || row.operation === 'restore_page' || row.operation === 'revert_version',
source_kind: typeof p.source_kind === 'string' ? p.source_kind : null,
source_uri: typeof p.source_uri === 'string' ? p.source_uri : null,
ingested_via: typeof p.ingested_via === 'string' ? p.ingested_via : null,
...(gateTrust ? { writeGate: gateInput(gateTrust, row.id) } : {}),
// Provenance compares the caller's page with the stored one, so it runs before the server's trust marker is stamped.
prepareFrontmatter: page => {
provenance = putProvenance(row, snapshot, page);
suppliedTrustMarker = page.frontmatter.trust_tier;
if (labelGuard) heldLabels = holdPrivacyLabels(page.frontmatter, snapshot?.page.frontmatter, labelGuard);
stampPageTrustMarker(row, page.frontmatter, trust, storedTier, snapshot?.page.frontmatter);
defaultSourceWriterReaders(defaultSourceWriter, page.frontmatter, snapshot?.page, defaultSourceOwner, ownerRewrite);
if (privateRequest) assertPrivateRequestKept(row, page.frontmatter);
},
prepare: async value => { prepared = value; return value.result; },
}).catch(error => {
if (!(error instanceof ContentSanityBlockError)) throw error;
throw contentRefusalError({ code: 'content_rejected', message: error.message },
'The operator set content_sanity.junk_disposition to reject, so this content refuses on every retry. Remove the matched junk and submit the corrected content with a new request_id.');
});
signal?.throwIfAborted();
if (!prepared) {
// A remote caller's refusal names the line, never a key: keys can be private, and the receipt keeps the message.
const refusal = result.refusal && remoteSafeRefusal(row, result.refusal);
if (refusal?.code === 'file_too_large') throw contentRefusalError(refusal, PAGE_OVER_LIMIT_SUGGESTION, { legacy_error: 'request_too_large' });
if (refusal?.code === 'invalid_fence') throw contentRefusalError(refusal, `Page ${row.slug} was not written. Fix ${fenceWhere(refusal.fence)} as the message says (fence_issues lists every row and column; use the allowed values), `
+ 'or write facts with remember and takes with takes_add instead of a hand-built table, then submit the corrected content with a new request_id.', { legacy_error: 'invalid_params' });
if (refusal) throw frontmatterRefusalError(refusal);
throw opError('invalid_params', 'The content was rejected before publication.', 'Check the content and frontmatter, then submit the corrected content with a new request_id.');
}
const ready = await remoteLabelsChecked(engine, row.authority, row.slug, snapshot?.page, prepared);
if (ready.observedRevision !== observedRevision) throw pageRefusal('revision_conflict', 'The page changed during import preparation.', row,
`Page ${row.slug} was written by another request while this one was being prepared, so it published nothing. Read the current page and revision, then submit the intended change against it.`,
pageFix(row.source_id, row.slug));
if (ready.slug !== row.slug) {
await authorizeWrite(engine, row.authority, row.operation, ready.slug);
const duplicate = await engine.readPageSnapshot(ready.slug, { ...source, excludePrivate: row.authority.remote });
if (!duplicate) throw pageRefusal('permission_denied', 'The duplicate is not readable by this writer.', row,
`The content duplicates another page in source ${row.source_id} that this writer cannot read, so nothing was published. Write it under a different slug, or ask the user to make the write from a writer that can read the existing page.`);
return { observedRevision, noop: true, additionalPageKeys:[{sourceId:row.source_id,slug:ready.slug}],validate: async tx => {
await authorizeWrite(tx,row.authority,row.operation,ready.slug,true);
const current=await tx.readPageSnapshot(ready.slug,{...source,excludePrivate:row.authority.remote});
if (!current || current.page.id!==duplicate.page.id || current.revision!==duplicate.revision) throw pageRefusal('revision_conflict','The read-only duplicate changed during preparation.', row,
`Page ${ready.slug}, which this content duplicates, changed while the write was being prepared, so nothing was published. Read it, then submit the write again if it is still needed.`,
pageFix(row.source_id, ready.slug));
},
apply: async () => ({ status: 'duplicate', slug: duplicate.page.slug, duplicate_revision: duplicate.revision }) };
}
const tags = versionTags ?? [...new Set([...(snapshot?.tags ?? []), ...ready.parsedPage.tags])].sort();
const renderedPage: Page = { ...(snapshot?.page ?? { id: 0, slug: row.slug, source_id: row.source_id, created_at: new Date(), updated_at: new Date() }), ...ready.parsedPage };
const rendered = serializePageToMarkdown(renderedPage, tags);
// CEO-21: the server-stamped trust marker alone never makes a write: unchanged as stamped or as the caller sent it.
const callerPage = { ...ready.parsedPage, frontmatter: suppliedTrustMarkerView(ready.parsedPage.frontmatter, suppliedTrustMarker) };
const logicalNoop = snapshot !== null && [ready.parsedPage, callerPage].some(page => digest(canonical(snapshot.page, snapshot.tags)) === digest(canonical(page, tags)));
const noop = logicalNoop && (snapshot?.page.deleted_at != null) === targetDeleted;
const ordinaryPage = ['put_page','capture','restore_page','revert_version','edit_page'].includes(row.operation);
// A managed maintenance page (e.g. the dream write-back after grounding
// quarantine) republishes a body; its automatic links follow that body.
const autoLinkedPage = ordinaryPage || p.kind === 'managed_maintenance_page' || row.operation === 'add_timeline_entry';
const capture = row.operation === 'capture' && typeof p.capture_path === 'string' && typeof p.capture_file_hash === 'string'
? { path: p.capture_path, hash: p.capture_file_hash } : undefined;
// Projections, advisories, link resolution (links-preparation.ts), the file target and the core guard go out together.
enterClaimStep(clock, 'link_resolution', undefined, 'db');
const [project, advisories, links, target, core] = await pipelined(together, [
async () => projected ? prepareCanonicalProjections(engine,ready.parsedPage,row.slug,row.source_id,snapshot,writer,timelinePolicy) : undefined,
async () => noop || targetDeleted ? pageNoopAdvisories(row) : !ordinaryPage ? remoteLinkHint(row) : preparePageAdvisories(engine,row,ready.parsedPage,snapshot),
async () => !skipsGuestNote('auto_links', guest.write) && !noop && !targetDeleted && autoLinkedPage && (row.authority.autoLinkTrusted ?? !row.authority.remote) && await isAutoLinkEnabled(engine)
? prepareAutomaticLinks(engine,row.slug,ready.parsedPage,row.source_id,options.coordinated === true) : undefined,
() => prepareFileTarget(engine, row, snapshot, targetDeleted ? null : rendered, undefined, { capture, allowMissing: options.allowMissingFile, activePack, remote: row.authority.remote, newPageIgnoredDatabaseOnly: true, clock, labelEdit: row.operation === 'submit_job' && p.kind === 'managed_maintenance_page' ? readLabelEdit(p.label_edit) : undefined }),
// Always-loaded core tier: owner-only marking, brain-wide budget, remote-edit policy (core-guard.ts).
async () => noop ? null : prepareCoreGuard(engine, { row, snapshot, incoming: targetDeleted ? null : ready.parsedPage }),
]) as [Awaited<ReturnType<typeof prepareCanonicalProjections>> | undefined, Record<string, unknown>,
Awaited<ReturnType<typeof prepareAutomaticLinks>> | undefined, PreparedMutation['file'], Awaited<ReturnType<typeof prepareCoreGuard>> | null];
// #6188 (D12): what Tier 1 rewrote; a remote caller is never told about the takes fence it cannot read (preserved verbatim).
const shownFixes = (ready.result.fences_normalized ?? []).filter(fix => !row.authority.remote || fix.fence !== 'takes');
const fencesNormalized = shownFixes.length ? { fences_normalized: pageFencesNormalized({ sourceId: row.source_id, slug: row.slug, fixes: shownFixes,
writer: row.principal_kind, path: snapshot?.page.source_path ?? null, remote: row.authority.remote }) } : {};
const file = target && fenceRepair ? { ...target, commit: fenceRepairCommit(relative(target.root, target.path).split(sep).join('/'), fenceRepair.classes, fenceRepair.tier) } : target;
enterClaimStep(clock, 'publication_mode', undefined, 'db');
const [mintMode, databaseOnly] = await pipelined(together, [
async () => file && !snapshot?.page.source_path ? scannerSlugRootMode(engine, row.source_id, file.root) : undefined,
() => pageDatabaseOnlyPublication(engine, row, file),
]) as [Awaited<ReturnType<typeof scannerSlugRootMode>> | undefined, Pick<PreparedMutation, 'databaseOnlyReason'>];
const sourcePath = file && mintMode ? scannerSourcePath(file.root, file.path, mintMode) : undefined;
// An inferred mode is pinned with the first origin it mints, so later pages cannot flip the inference (#5610).
const pinMode = sourcePath && mintMode && scannerSourcePath(file!.root, file!.root) && !await readSlugRootMode(engine, row.source_id) ? mintMode : undefined;
const publication: PreparedMutation = { observedRevision, noop, additionalPageKeys:links?.pageKeys, file, ...databaseOnly,
...(core ? { exclusiveSources: core.exclusiveSources } : {}), ...(trust ? { trust } : {}), ...(ready.afterCommit ? { afterCommit: ready.afterCommit } : {}),
validate: async tx => { await ready.validate(tx); await core?.validate(tx); await assertLabelGuardUnchanged(tx, row, trust, snapshot?.page ?? null, storedTier, incoming, labelGuard); },
apply: async (tx, preimage) => {
let autoLinks: Awaited<ReturnType<NonNullable<typeof links>['apply']>> | undefined;
let removedTimeline: TimelineRowsRemoved | null = null;
let lowered: { proposal_ref: string } | null = null;
let contested: string[] = [];
let projectionPending = false;
let segmentedWrite = false;
if (!noop) {
const prior = snapshot ? await storedPageTier(tx, row.source_id, row.slug) : null;
// ENG-1: a managed fence edit keeps the page's tier; CEO-12: an agent rewrite that lowers a page files a queue item.
const applied = await (isFenceEditWrite(row) ? withTrustKeep(tx, ['pages'], () => ready.apply(tx, lean ? preimage : undefined)) : ready.apply(tx, lean ? preimage : undefined));
projectionPending = applied?.segmented?.complete === false || applied?.projectionPending === true;
segmentedWrite = applied?.segmented !== undefined;
lowered = prior ? await recordAgentPageLowering(tx, row, { tier: heldLabels && labelGuard?.tier ? maxTrust(prior, labelGuard.tier) : prior, revision: snapshot!.revision, pageTier: prior }, undefined, heldLabels) : null;
// Mandatory metadata shares publication rollback; exact no-ops never heal it. These, and the
// projections (facts, takes, timeline rows of the page the import just wrote live), are independent and sent together.
const [, pinned] = await pipelined(tx, [
async () => { if (sourcePath && !snapshot?.page.source_path) await bindOrigin(tx, { sourceId: row.source_id, slug: row.slug, sourcePath, onlyIfUnset: true }); },
async () => pinMode ? (await tx.executeRaw<{ mode: string | null }>(`UPDATE sources SET config=CASE WHEN config->>'slug_root_mode' IS NULL
THEN jsonb_set(${SOURCE_CONFIG_OBJECT_SQL},'{slug_root_mode}',to_jsonb($2::text)) ELSE config END WHERE id=$1 RETURNING config->>'slug_root_mode' AS mode`,
[row.source_id, pinMode]))[0] : undefined,
async () => { if (provenance) await tx.executeRaw(`UPDATE pages SET source_kind=$3,ingested_via=$4,ingested_at=$5::timestamptz
WHERE source_id=$1 AND slug=$2`, [row.source_id, row.slug, provenance.source_kind, provenance.ingested_via, provenance.ingested_at]); },
async () => { if (lean) ({ removedTimeline, contested } = projectedRows(await project?.(tx, applied?.pageId))); },
]) as [unknown, { mode: string | null } | undefined, unknown, unknown];
if (pinMode && pinned?.mode !== pinMode) throw pageRefusal('revision_conflict', 'The source slug-root mode changed during preparation.', row,
`Another write pinned source ${row.source_id}'s slug-root mode while ${row.slug} was being prepared, so this publication rolled back. Once the request is final, submit the write again; it is prepared under the pinned mode.`);
if (row.operation === 'restore_page') { await tx.restorePage(row.slug, source); if (snapshot) await clearOwedPurges(tx, [Number(snapshot.page.id)]); }
if (versionTags) {
for (const tag of snapshot!.tags) if (!versionTags.includes(tag)) await tx.removeTag(row.slug, tag, source);
for (const tag of versionTags) await tx.addTag(row.slug, tag, source);
}
// #6007: the page the import just wrote live is the page the projections describe; no re-read.
if (!lean) ({ removedTimeline, contested } = projectedRows(await project?.(tx, row.operation === 'restore_page' ? undefined : applied?.pageId)));
autoLinks = await links?.apply(tx);
if (lean) {
const final = await tx.readPageSnapshot(row.slug, { ...source, includeDeleted: true });
const live = final && final.page.deleted_at == null ? final : null;
await verifyPageReadable(tx, row.slug, ready.contentHash!, row.source_id, 'importFromContent', live?.page ?? null);
if (applied?.segmented) { if (applied.segmented.complete && live) await sealSegmentedPage(tx, Number(live.page.id)); }
else if (applied?.chunkerSeal !== undefined) await sealImportedPage(tx, row.slug, row.source_id, live, applied.chunkerSeal, applied.pageId);
else if (live && !applied?.projectionPending) await sealPageTextProjection(tx, row.slug, row.source_id, live);
if (core) await core.record(tx, final?.revision ?? null);
publication.postimage = final;
} else {
if (targetDeleted) await tx.softDeletePage(row.slug, source);
// Index installation and terminal receipt share this transaction. The import sealed the projection
// as its last revision-changing step; only a later revision change (restore, tags, links, delete) reseals.
if (applied?.segmented) { if (applied.segmented.complete && applied.pageId !== undefined) await sealSegmentedPage(tx, applied.pageId); }
else if (!applied?.projectionPending && !(applied?.sealed && row.operation !== 'restore_page' && !versionTags && !links && !targetDeleted)) await sealPageTextProjection(tx, row.slug, row.source_id);
if (core) await core.record(tx, (await tx.readPageSnapshot(row.slug, source))?.revision ?? null);
}
} else if (heldLabels && snapshot && labelGuard) {
// GST-2518: a write that only widened labels publishes nothing once they are kept; its request still reaches the owner.
lowered = await recordAgentPageLowering(tx, row, { tier: labelGuard.tier ?? storedTier!, revision: snapshot.revision, pageTier: storedTier }, undefined, heldLabels);
}
const coreUsage = core?.usage();
const gate = noop ? undefined : gateField(ready.result.gate, `p:${row.source_id}/${row.slug}`, null);
// #6722: a large or embed_skip page says what this write left its embedding in.
const sizeState = noop ? {} : await sizeStateField(tx, row.source_id, row.slug, ready.parsedPage);
return { ...advisories, ...(autoLinks ? {auto_links:autoLinks} : {}), ...(coreUsage ? { core: coreUsage } : {}),
...(removedTimeline ? { timeline_rows_removed: timelineRowsRemovedAdvisory(row, removedTimeline) } : {}),
status: noop ? 'skipped' : row.operation === 'restore_page' ? 'restored' : row.operation === 'revert_version' ? 'reverted' : 'created_or_updated',
slug: row.slug, source_id: row.source_id, chunks: ready.result.chunks, noop, ...(projectionPending ? { projection: 'pending' } : {}),
// Wave B: whether search sees a segmented write at commit; a pending one is re-read whenever its receipt is served (searchable.ts).
...(segmentedWrite ? { searchable: isQuarantined(ready.parsedPage.frontmatter) ? false : projectionPending ? 'pending' : true } : projectionPending ? { searchable: 'pending' } : {}),
...sizeState,
...(ready.result.chunks === 0 && !projectionPending ? {chunk_skip_reason: noop ? 'write_skipped'
: isEmbedSkipped(ready.parsedPage.frontmatter) || isQuarantined(ready.parsedPage.frontmatter) ? 'embed_skip' : 'empty_body'} : {}),
// #6259: say the gate hid the page, not only why it has no chunks.
...(!noop && quarantineOutcome(ready.parsedPage.frontmatter) ? { quarantined: quarantineOutcome(ready.parsedPage.frontmatter) } : {}),
...(row.operation === 'capture' ? { channel: 'capture', content_hash: p.capture_hash } : {}),
...(edited ? editDiff(row.slug, edited.before, edited.after) : {}), ...fencesNormalized, ...fenceRepairOutcome,
...(lowered ? { trust_lowered: lowered } : {}), ...(lowered && heldLabels ? { privacy_labels_kept: { keys: heldLabels.keys, proposal_ref: lowered.proposal_ref } } : {}), ...(gate ? { gate } : {}),
// DX-1: a guarded supersession reports contested (the first proposal; every one when the write contested several rows).
...(contested.length ? { contested: { proposal_ref: contested[0], ...(contested.length > 1 ? { proposal_refs: contested } : {}) } } : {}) };
} };
return guardGuestPublication(publication, row, guest, noop);
}
/** What a page's projections report back: removed timeline rows and the contested proposal refs (#5575 guarded supersession). */
function projectedRows(projected: { timelineRowsRemoved?: TimelineRowsRemoved | null; contested?: string[] } | undefined): { removedTimeline: TimelineRowsRemoved | null; contested: string[] } {
return { removedTimeline: projected?.timelineRowsRemoved ?? null, contested: projected?.contested ?? [] };
}
async function editLockedPage(engine: BrainEngine, row: WriteRequest, snapshot: PageSnapshot | null) {
if (!snapshot || snapshot.page.deleted_at) throw pageRefusal('page_not_found', 'Page not found.', row,
`Page ${row.slug} does not exist in source ${row.source_id} or is deleted, so the edit changed nothing. If it is soft-deleted, restore it with restore_page; otherwise write it whole with put_page.`,
pageFix(row.source_id, row.slug));
// GST-2891: an enforced member's edit (keep_hidden_rows) read the page as a remote caller does, so its diff shows that view.
const remoteView = row.authority.remote || row.intent?.keep_hidden_rows === true;
const omitRows = row.intent?.keep_hidden_rows !== true && await storedWriterReadsHeld(engine, row.authority) ? undefined
: (await loadFenceChunkOverlay(engine, { sourceId: row.source_id, slug: row.slug, ...fenceBody(snapshot.page) }, { hideHeld: true }))?.held;
return applyPageEdits(snapshot.page, snapshot.tags, remoteView, parsePageEdits(row.intent?.edits), parseEditWithin(row.intent?.within), omitRows);
}
/**
* A guest note's publication with the guest checks of guests/admission.ts added to its validate and apply. Any other
* write is returned as it is: the guest-source trigger refuses it in a source that became a guest source after it was
* admitted, so it publishes no extra statement.
*/
function guardGuestPublication(publication: PreparedMutation, row: WriteRequest, guest: GuestWrite, noop: boolean): PreparedMutation {
const { validate, apply } = publication;
const { note, audience } = guest;
if (!note || !audience) return publication;
publication.validate = async tx => { await validate?.(tx); await assertGuestWriterAtPublication(tx, row); };
publication.apply = async (tx, preimage) => {
const out = await apply(tx, preimage);
if (!noop) await insertGuestMark(tx, row, note, audience);
return out;
};
return publication;
}