Garry's Opinionated OpenClaw/Hermes Agent Brain
Key files: Core Persistence (continued)
Subsystem index · Previous entries. Read only the entries relevant to your change. Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG. The #6188 fence check and fence repair live in fence repair. Managed connector ingestion, connector item holds and the no-op kernel (checkpoint validation and the fault seams: request indexes and fault seams). The sources refresh writer, the git gap census, declared classes, the git door and ignore rules live in Core Persistence (Git). Also the persistence verb types and errors, database-write and manual links, write attribution and loop-fact retirement; the managed purge of deleted pages is under memory purge.
src/core/persistence/{types,params,preconditions,verb-errors}.ts— public mutation receipt states, error reasons and revision/idempotency parameter contracts. Receipt serialization explicitly selects public fields; queued content and execution credentials stay internal.frozenVerbWriteErroruses MEMORY_VERBS v1's existing error enum with additivewrite_request/write_error;page_body_segmentedis a write error code, so a verb refused by a segmented target keeps it aswrite_errorand canonical code under the frozeninvalid_params(caller class, not retryable) on both the receipt and the pre-admission path (runMemoryWrite).rememberreads a segmented entity page up to PAGE_MAX_BYTES back whole (materializedPage) for its inferred-target checks and fence write; over it, a named or inferred entity refuses before admission withsegmentedRememberRefusal(fix: remember withinfer_entity: false), never a silentNO_ENTITY(test/large-pages/segmented-remember-refusal.test.ts);committedVerbOutcomerefuses pending or failed receipts.OperationErrorand the thin MCP client preserve this metadata, including when a timeout races an already-received receipt. The registry-safe parameter/schema leaf never imports operation values. Pinned bytest/persistence-write-contracts.test.ts,test/mcp-client-hardening.test.tsand a real HTTP envelope intest/mcp-client.test.ts.src/core/persistence/database-write.ts—coordinatedDatabaseWriteis the managed path for rows with no canonical file;ontology_propose(one entity page key) uses it. On a managed brain it checks the caller's durable write authority for the authority page (submissionAuthority, thenauthorizeWriteFOR SHARE inside the transaction), revalidates the source incarnation and commits insidewithCoordinatedWriteholding the given page keys. Unmanaged brains keep the engine calls. Tests:test/managed-ontology-propose.test.ts.src/core/persistence/manual-links.ts—prepareManualLinkMutation, the preparer of theadd_link/remove_linkpage mutations a managed brain submits (G5, dispatched fromservice.ts; on the IPC and semantic re-prepare lists, kept-tier fence edits intrust/page-write.ts). The authored edge is a row of the from page's## Linksfence (links-fence.ts): the preparer upserts or removes the row at the snapshot's revision (a segmented page read back whole throughwholeBodySnapshot) and publishes the page withpreparePageMutation; the publication's canonical projection and the apply both project the fence (links-fence-projection.ts), so an idempotent add (fence unchanged, a no-op publication) still has its edge.add_linkalso deletes the database-only twin of the edge it fences (same endpoints, type and provenance, no origin), and on a body with no fence it first renders the kept fence edges into the section it creates, each with the dated statements stored under its own source (keptLinksFenceRows); statements with no source (written before link_transitions had alink_sourcecolumn) go to a relationship's only row when they fit it, and otherwise the write refuseslink_dates_unattributed.remove_linkdeletes the matching database-only edges (origin_field notlinks_fence, a provenance outsideMANAGED_LINK_SOURCES) with their database-only manual statements and, when the body has no fence, the orphaned fence edges with the statements of their own source (it refuseslink_dates_unattributedwhen sourceless statements would have to be split between a removed row and a kept one), and reportsremovedas the edge count it took away; edges a reconciliation producer derives from the text stay, and the result names them (derived_from_text: [{ link_type, link_source }]plus amessageto edit the page text instead). The op handlers keep their validation,dry_runand result shape ({ status },{ status, removed }); unmanaged brains keep the engine calls. Tests:test/managed-links-fence.test.ts(+ Postgres arm),test/managed-writers-w3.test.ts.src/core/persistence/{attribution,attribution-schema,context}.ts— write attribution.withCoordinatedWrite(engine, sourceIds, fn, attribution)setsgbrain.write_sourcesand the transaction-local actor (gbrain.write_request,gbrain.write_principal_kind,gbrain.write_principal_id) in one round trip and restores them on exit; a nested scope keeps the outer actor. The argument is required:requestAttribution(row)for journaled publication (coordinator, forget),maintenanceAttribution(engine)(verified local writer, else the CLI registration, elseapplication/host:<id>; no request) for derived facts, takes/timeline/link extraction, materialization, concept provenance, connector freshness and verify cleanup,principalAttributionfor manual links (the caller) and source lifecycle (the topology principal).withWriteAttributionsets only the actor, for unmanaged legacy transactions;maintenanceTransaction(engine, fn)wraps it in one transaction, and every unmanaged direct writer runs its write (or one bounded batch) in it (thesystem-of-record.md"unattributed" list is empty; derivers pass their taint asmaintenanceTransaction(engine, fn, trust), seetrust/taint.ts).attribution-schema.ts(migrationf1_write_attribution; migration-only like the facts DDL, so columns land last on fresh and upgraded brains) adds nullable columns and BEFORE ROW triggers:facts/takes/timeline_entriescarrywrite_*(created_by, immutable once set) andlast_write_*+last_written_at(moved only when a classified content column changes; a NULL actor records an unattributed writer; undergbrain.fact_withdrawal_stamp, which only the facts insert guard sets, a facts update ofexpired_at/valid_untilalone keeps them, migration v264);pages.revision_*is stamped whenknowledge_revisionchanges;page_versions.write_*copies the snapshotted revision's actor andarchived_*names the archiving write.write_request_idispersistence_requests.idwith no foreign key; all-NULL reads as unrecorded. Every column of the three tables is classified content, projection (embeddings,takes.updated_at) or attribution, and a new column must be classified and the function re-created; the writer guard treats attribution-only facts/takes updates as projections. Tests:test/write-attribution.test.ts,test/write-attribution-legacy.test.ts(writer inventory) andtest/write-attribution-<family>.test.ts(each routed unmanaged writer path;write-attribution-timeline-10k.slow.test.tschecks bounded batches at 10k pages) on PGLite; Postgres direct and PgBouncer throughtest/e2e/write-attribution-postgres.test.ts.src/core/persistence/loop-fact-retirement.ts— #5869 commitment-fact retirement for closed loops, one coordinator mutation on every brain (operationloops_close, intentretire_loop_fact, dispatched fromservice.ts): expires the fact and strikes its## Factsfence row (contextloop closed: <status>) through the entity page publication in one transaction; no withdrawal tombstone. The shared rule (alsoloopFactDrift, used by doctorloop_facts_driftandgbrain repair loop-facts): only a fact in the loop's source that no other open loop references, re-checked under row locks at publication (shared_with_open_loop,source_mismatchotherwise).retireLoopFact(ctx, loopId)submits with the caller's grant and maps a refusal or pending write tofact_expired: false, retryable: true, reason. Tests:test/loops-close-fact.serial.test.ts(+ Postgres twin).src/core/persistence/connector-authority.ts-- classifies each Google/GitHub source asconnector_database(managed, unbound),boundorunmanagedfrompersistence_brain.enabledand the source binding row. File-lane audits (doctorundeclared_db_only_pages, backup coverage) read it so a leftover cache directory atlocal_pathis never taken for canonical files. Tests:test/doctor-silent-death-checks.test.ts,test/backup-coverage.serial.test.ts.src/core/persistence/connector-sync.ts— managed Google/GitHub API ingestion through source-scoped journaledconnector_v2_import/_delete/_checkpoint/_google_receiptsintents andmanaged-connectorcheckpoint CAS, not Git cursors. The checkpoint key, admissionconfigHash, mid-sweep change check and publicationsource_changedcheck all use the parsed-config identity fromconnector-identity.ts, so cycle stamps insources.confignever rotate them. Unbound connectors use reviewedconnector_databaseSQL-only authority; bound connectors retain canonical file publication with guarded root/hash/revision/epoch. Every managed run checks the credential's resolved account against the pin in the connector state row before reading its checkpoint (assertAccount), then applies a requested--reset-checkpoint(pending writes resolved first, pin kept). Each import or delete is first screened by runningprepareConnectorMutationon an unadmitted request through the no-op kernel; unchanged items take no admission. An unchanged checkpoint save is skipped and, when it would have stamped freshness,last_sync_atis stamped directly inside a lease-asserted coordinated write. Accepted-pending writes are progress: a 30-second total wait budget (writes committing within one second are free), at most one in-flight write per page, outstanding writes kept under the principal's outstanding and intent-byte limits, andConnectorWaitBudgetStop(awrite_pendingerror) when the budget is spent. The checkpoint never advances past a pending page; the run records its pending set in the state row, and the next run resolves it first (committed dropped, failed retried automatically through the retry-pointer path without--retry-failed, unreached failures after a complete sweep dropped and counted). Retiredmanaged_connector_*intents route toprepareOutdatedConnectorMutation, which fails themconnector_intent_outdated(detailpre_upgradebefore the v176 cutoff). Standalone entry, page reads and submissions authenticate the current source, local grant and canonical owner and settle retained worktree publications before deriving request identity. Explicit--retry-failedatomically admits a linked attempt and stores a per-base-requestmanaged-connector-retrypointer. Durable connector cursors, retry pointers and state rows survive generic seven-day checkpoint GC. Tests:test/persistence-connectors.test.ts,test/persistence-connector-retry.test.ts,test/connector-checkpoint-identity.test.ts,test/connector-wave3.test.tsandtest/helpers/connector-restart.tson PGLite and disposable Postgres. #6831: a page import whose content matches a source page purge tombstone is skipped per item instead of ending the run: screened before admission (carriesPurgedPage, the guard's content hash, read only when the source has a tombstone), and afailed/purged_contentreceipt the guard still produces (a purge that landed mid-run) is skipped wherever it surfaces (the item's wait,refreshPending,resolvePendingSet): it is dropped fromreceipts, never joins the automatic retry set, has its optimistic pending count taken back, and is counted inlast_run.purged_skippedandpurged_items. A replayed purged receipt is re-checked against the live tombstones (purgedNow) beforemayRetry: still purged, it is skipped even under--retry-failed; cleared, it gets one automatic retry. A run that ends on any error exceptLockStolenErroror an aborted caller signal recordslast_failure(code, elseconnector_error; message, the item and request when the run ended on that item's receipt,consecutive); only a completefinish()(cursor saved, nothing pending or failed) clears it. Tests:test/connector-purged-item-6831.test.ts(+test/e2e/twin).src/core/persistence/connector-identity.ts—connectorIdentity(kind, rawConfig, localPath)returns the parsed connector config and a digest over every parsed leaf except credential-delivery fields (Googleaccess/tokenCommand/tokenEnv; GitHubtokenEnvandappunderscope: repos,app.pemPathalways; underscope: autothe token env without an App and the App ids are identity).services/reposare sorted and de-duplicated; a parser leaf missing fromCONNECTOR_LEAF_RULESjoins the identity. #6561: a leaf a parser starts emitting with a behavior-preserving default declares it aselideWhen(GooglecontactsDir: 'people') and is left out of the digest while it holds it, so unchanged sources keep the pre-field key; the non-elided digest is kept asaliasDigests(connectorCheckpointKeysreturns the stable key then its alias keys;connectorIdentityMatchesaccepts an admitted write's frozenconfigHashunder either). AlsoconnectorCheckpointKeyandisConnectorIntentKind/connectorIntentSql, the one predicate for both intent namespaces. Test:test/connector-identity.test.tsenumerates every parser leaf.src/core/persistence/connector-state.ts— (fix wave 4: alsofirst_attempt_at, the autopilot connector dispatch gate, recorded before the first provider call of a validated, non-preview sync and seeded by migration v181) the per-source-incarnationop='managed-connector-state'row (fingerprintdigest({sourceId, incarnation}), independent of the identity digest): account pin, pending set{itemRef, requestId, baseRequestId, admittedAt},upgrade_recovery(resumed/rewalking_once/none) withresumed_from,continuity_unverifiedand last-run counts.writeManagedConnectorStatechecks the connector sync lease in the same statement.connector-status.tsrenders it forgbrain sources statuswithout the account. #6831:purged_items(newestCONNECTOR_PURGED_LIMITpurged skips) andlast_failure(ConnectorRunFailure);CONNECTOR_STOPPED_RUNS(3) consecutive failed runs read as stopped inconnector-status.ts(sources statuslines,readConnectorLastErrorforsync status's additiveconnector_last_error;last_error,stateandnextare untouched) and doctorsync_freshness(stoppedConnectorIssuesindoctor/sync-outcome.ts).src/core/persistence/connector-status.ts—sources statusviews of connector state and Git holds.gitHoldStatusJson(#7326) boundsgit_holdsin--json: summary by default (count,by_codecounting every hold of the source, with an example only for a code the listed items include, andby_code_complete: falsewhen the count fell back to the listed files, the firstHELD_STATUS_LIMITitems,items_complete/items_command), every item read under--holds, or apageSortedRowskeyset page by path under--limit/--cursor(test/sources-status-holds-bounded-7326.test.ts,test/sync-hold-surfaces.test.ts).src/core/connectors/item-holds.ts— fix wave 4 connector item holds, shared by Gmail and GitHub on managed and unmanaged brains:classifyConnectorError(the one table: source-scoped, rate-limit and item-scoped codes, content vs transient class) andItemHoldsRun(hold after 3 consecutive attempted runs at one upstream version; circuit breaker at 5 attempted items with half transient or 5 and half one code; backoff 1 h/6 h/24 h/daily for 7 days; cap 100,connector_holds_exhausted). A run's changes merge only infinish(), so mid-run checkpoints carry the holds the run began with and a cursor never passes an item that is not already held.carryLegacyFailCountsreads the retired Gmail ledger once.src/core/connectors/item-holds-store.ts+connector-hold-session.ts— reads holds from the cursor state (managed checkpoint row or the unmanaged state file) forsources status, doctorconnector_held_itemsandopen_loopscompleteness; theconnector-hold-retryrequest rows and the pendingmanaged-connector-retrypointerssources retry-heldwrites; the per-run session that skips held items, publishes holds on a managed abort (publishHolds), releases held items' terminal receipts from the automatic retry set and consumes retry-held keys. Git-source holds are not read here: onlysources status(persistence/connector-status.tsreadGitHoldStatuses,sources status <id>filters to one source) andsources retry-held(a Git source records async-hold-retryre-screen request for its held paths;gbrain sync --retry-heldrefuses with that pointer) show them beside connector holds. Writer deactivation and activation never read or block on them.src/core/connectors/connector-text.ts— #5752 render boundary: prose sanitized withsanitizeForJsonbbefore the no-op screen; identity fields refuse withinvalid_connector_text.src/core/persistence/connector-account.ts— resolves the credential's account before any service runs: Google throughprobeGoogleAccountingoogle/api-access.ts(Gmail profile, Calendar primary calendar or Peopleme, first enabled service that answers, else OAuth userinfo, #7073), returning the probe with every per-service error; when nothing names the account it rethrowsapi_not_enabledfirst, then another credential error, then the first other failure, soconnector_account_changedmeans a resolved account that differs from the pin (test/google-api-access-managed-7073.test.ts), GitHub App installation id from the minted token, or the/userlogin for token auth underscope: auto.src/core/persistence/connector-errors.ts—connector_account_changedwith its two-exit hint, the retired-intent messages, andreceiptDeliveredHint, which rebuildssuggestion/detail/docsfor codes delivered through a stored receipt (the coordinator persists only code and message);writeResponseapplies it.src/core/persistence/noop-kernel.ts— the #5470 no-op kernel.inspectUnchangedtakes a preparer'sPreparedMutationfor an unadmittedscreeningRequestand returnscontentUnchanged,projectionWorkRequired(safe-chunk fence, text projection behind the knowledge revision, embedded page without a contextual mode),metadataWorkRequired(source path) andobservedRevision; bound pages also need local file bytes equal to the serialized page. The page's currentknowledge_revision, read with the projection flags, must still equal the snapshot's revision (a write after the screen's snapshot admits asrevision_moved). Callers run the preparer's ownvalidatebefore counting a skip. An optionalwaivelist (#5751) lets a caller skip two admit reasons its no-op publication can never resolve, a pending contextual-mode stamp and file bytes that differ from the prepared content (never a missing file); the result lists each waiver applied inwaived; only managed working-tree sync entries andput-page-screen.tspass it. Used by connector sync,import-mutations.ts,sync-run.ts(working-tree and company-profile entries; renames and overlays always admit) andput-page-screen.ts(the managed transcript import'sput_page, waivingcanonical_file_differsfor a file the preparer accepted).chunksEmbeddedAsIs(#7866): a no-op whose chunks hold current vectors queues no embedding. Tests:test/noop-kernel-paths.test.ts,test/connector-wave3.test.ts.src/core/persistence/put-page-screen.ts— #6741 B:unchangedPutPagescreens a trusted local put_page (the transcript import) throughpreparePageAdmission(unadmitted), the page publication preparer and the no-op kernel; skips admission only on a genuine no-op with no pending request, no segmented body and no projection work. Tests:test/transcripts-managed-noop.test.ts.src/core/persistence/import-reads.ts— GBRA-75 wave 10:readImportSnapshotsreads a run of pages asreadPageSnapshot(slug, { sourceId, includeDeleted: true })returns each (soft-deleted rows, withdrawals and purge markers included) throughreadPageSnapshotsBatch({ includeDeleted, absentIsNull }), looping over its byte-budget prefixes; the managed import screen uses it for two or more new members.importGroupReadsserves an import group's preparation (group-publish.tspreparationReads): each member's first own snapshot read comes from one batch, andfindDuplicatePagecalls that arrive together (all members, or a 2 ms window) are answered by onefindDuplicatePages(engine-sql/pages.ts, same predicate and ranking per input); a failed batch falls back to each member's single read; withreread(the read-only screen) a member's later reads of its page come from the batch too. GBRA-108:sliceReadsanswers a screened slice's per-page reads (the origin claimants ofsync-origin.ts, the stored timeline and take collisions ofcanonical-projections.ts, the safe-chunk fence ofpage-state/projections.ts, matched by their exported statements) from one statement per kind over the slice, row for row; a page with stored takes, a page or path outside the slice, a signalled call or a failed slice read runs its own statement (testtest/sync-legacy-sweep-gbra108.test.ts). Tests:test/import-reads.test.ts, Postgres armtest/e2e/import-reads.test.ts.src/core/persistence/screening-paths.ts— GBRA-75 wave 7:withScreeningPaths(run)opens one screening batch's memo of root-level filesystem facts andscreeningPath(key, compute)resolves each once inside it: other sources' root realpaths (assertImportPaths), shared skillpack root canonical paths and the source root's Git scope (knowledge-guard.ts). Per-file paths are never memoized; a nested batch joins the open one; the memo closes withrun, so work that outlives it computes fresh; a throwing compute is never memoized. Opened by the managed import plan and screen loops (import-mutations.ts), each sync waiver screen (screenWaiver) andsync-run.tswaiveRun's screens. Tests:test/persistence-skip-cost.test.ts.src/core/persistence/sync-waivers.ts— managed-sync no-op waivers (#5470, #5984).waiveNoopEntryscreens a frozen, unadmitted entry: an unchanged import (unchangedSyncImport, moved here fromsync-run.ts, with the #5751 working-tree kernel waivers) or a delete whose page is already soft-deleted at the entry's frozenexpected_revisionwith its file absent (never an unowned deletion or a rename). A candidate runsvalidateSyncAuthorityfirst (a revoked grant throws before any waiver), then commits in one transaction with a fixed lock order: page guard (lockPageKeys), then the managed-sync cursor rowFOR UPDATE; it re-reads the snapshot (and, for deletes, the origin and file absence) and refuses whileUNFINISHED_PAGE_REQUEST_SQLfinds an unfinished request for the page by slug, page id or arenameFromnaming it. That lookup is threeLIMIT 1branches served bypersistence_requests_pending,persistence_requests_recoveryand the database-only pending index (EXPLAIN pinned intest/persistence-managed-sync.test.ts). A cursor that moved meanwhile is adopted instead of waived again, sowaivedcounts only increment in the winning transaction.GBRAIN_SYNC_WAIVE_NOOP=0admits every entry. #6278: the lookup also matches the entry's file path, origin and a rename from that origin (unfinishedPageRequestParams), so the hold gate insync-run.tsshares it.unchangedSyncImport(and sosameContentAtOrigin's preparation) runs the sync preparer underraceSyncBudgetagainstpersistence.sync_preparation_ms(syncPreparationBudgetMs, read at most every 5 s, default 120 s) and the run's signal: past the budget nothing is waived and the origin refusal stands (fail open, nothing counted or held,SyncPreparationBudgetExceeded); a cancelled run propagates. GBRA-75 wave 8:unchangedSyncImportprepares with{ unsaved: true }, so its validation also accepts this run's cursor with nothing pending.waiveNoopRun(up to 64 entries, one cursor write) re-reads the owner epoch under its lock (a change passes nothing; the per-entry path then refuses it) and each import's file bytes (an edit ends the prefix). Both waiver transactions read a waived import's file (a raw hash that no longer matches admits the entry) and write itssync-import-provenancerecord from the preparation'simportProvenance(waivedProvenance: disk hash and blob id of those bytes when they hold the imported ones,heldDiskBytes, #8089; the page's current revision), so a waived page carries the same record a publication writes. Tests:test/sync-waiver-budget.test.ts,test/sync-waiver-run-imports.test.ts,test/persistence-managed-sync.test.ts(#5984 waiver cases),test/persistence-sync-legacy-files-5751.test.ts.src/core/persistence/atom-maintenance.ts(write failures) — #7514: a batch whose write ended without committing (conflict,failed,cancelled) is a write failure,atomWriteFailure: its record carries the write's request id and refusal code (the code survives receipt compaction, which erases the message to "The write did not commit."), and on the drain each time the batch is met counts one strike in anop_checkpointsrow (managed-atoms-uncommitted, keyed by the failed run key) with no model call, since a failed batch is never re-extracted on its own. AtMAX_DETERMINISTIC_FAILURESstrikes a journaled failure completion (intentattempts) advances the drain-key checkpoint toheld, so the origin leaves the backlog and doctor lists it with that completion's receipt and the reviewed retry; an explicit retry records no strike. Test:test/extract-atoms-commit-failure-hold.test.ts.src/core/persistence/prepared-maintenance.ts(physical root) — #7760:maintenancePreflightre-stamps a device-only physical-root change under a no-waitacquireWorktree, as ordinary writes do (#5604); any other identity change still refuses, and a busy lock keeps thephysical_root_device_changedrefusal. Test:test/persistence-physical-root-device.test.ts.src/core/persistence/accepted-pending.ts—acceptedPendingReceipt(error): the shared test for an accepted, not yet committed write, used by managed atom publication, extract_atoms, managed import and the connector budget.publicationHold(error)returnspendingfor such a receipt orcontentionfor an OperationErrorstorage_errorwith detaildatabase_contentionand no receipt (admission rolled back, nothing recorded), else null — never from a message, a terminal receipt, a contention error carrying a receipt or a permission refusal;publishOrHold(fn)runs one publication and returns null on commit, the hold when there is one, and rethrows anything else. Used by the patterns, drift and synthesize dream phases.src/core/persistence/connector-checkpoint-migration.ts— migration 176 and orphan cleanup. The newest committed checkpoint receipt per source incarnation (found by slug, so a compacted one is still seen and re-walks) is copied to the stable key withINSERT … ON CONFLICT DO NOTHING; state rows are seeded; the cutoff is stored inop_checkpoints(op=managed-connector-migration, fingerprintv2-cutoff, excluded from the checkpoint purge).orphanConnectorCheckpointskeeps rows touched after the start, rows any registered source (archived included) can load under its stable or alias key (loadableConnectorKeys, #6561), and rows referenced by a non-terminal request or a pending set; timestamps bind as text.gbrain repair connector-checkpoints(src/core/repair/connector-checkpoints.ts, whose preview counts alias-kept rows asalias_protected) and theconnector_checkpointsdoctor check reuse it with a 7-day floor. No upgrade step rewrites alias rows (#6561):connector-sync.tsresumeCheckpointresumes from an alias row written after the stable one when the stable key has none or the alias holds the newer completed Gmail backfill, and the run's first save moves that cursor to the stable key; every checkpoint and page write compares against and writes only the stable row.connector-reset.tsguardsgbrain sync --reset-checkpointto connector sources.src/core/persistence/graduation-target.ts— engine graduation target side.resolveTargetRoutesreads the URL from--urlor the--url-envvariable and resolves the DDL route once (explicitGBRAIN_DIRECT_DATABASE_URL, else the Supabase direct derivation, else the main URL);connectTargetEngineshands that route to the connection manager as an explicit override, so no session-pooler fallback is chosen for the run.targetIdentityhashes host, port, database and user, never the password;redactTargetUrlis the only display form.probeTargetruns read-only probes inBEGIN READ ONLYsessions on both routes (server version,vectorwith halfvec, CREATE privilege,session_replication_rolepermission inside a savepoint, table ownership, seed-only emptiness, existing embedding columns, the role's superuser and BYPASSRLS standing and the auto-RLS event trigger and its function owner);targetProbeBlockers(non-superuser targets get the exact SQL a DBA runs forvector, BYPASSRLS and the event trigger) andassertTargetReachableturn a probe into plan blockers and typed refusals.crossCheckRoutesproves both routes reach one database with a transaction-scoped advisory lock keyed by a fresh nonce, read back frompg_locksthrough the other route. Tests:test/graduation-target.test.ts.src/core/persistence/graduation-drain.ts— engine graduation drain.graduationBlockerslists what keeps a brain from copying, each with its structured action: requests this host owns (drained; a live recovery blocked onunexpected_file_bytesis not drainable:needsUser, argvgbrain repair stuck-recovery --source <id> --request-id <request>), requests and host bindings owned by another host, recovering topology changes and effects (a withdrawal-mirror effect blocked onunexpected_file_bytesnames the same stuck-recovery preview,needsUser), the writer admin lock, and OAuth clients bound to a missing source (an FK only Postgres enforces; never cleared silently, since unbinding widens access).drainForGraduationrefuses up front on anything the drain cannot clear (any blocker that is not arequest, or one thatneedsUser), then publishes this host's queued, running and recovering requests with arequestsOnlyPersistenceConsumerbounded by the timeout and always runs its stop barrier before returning; thegraduation_drain_timeoutrefusal is built bygraduation-errors.ts.freezeSourcestops the resident consumer and sets the PGLite connection to read-only transactions;withSourceWritableruns one read-write transaction for custody writes. Tests:test/graduation-drain.test.ts.src/core/persistence/graduation-copy.ts— engine graduation copier (in process).copyTablereads source rows through the digest's own plan (digestPlanwith inventory transforms,rowFilter,::textvalues, COLLATE "C" keyset batches) and writes them in one target transaction per table that setsgbrain.graduation_run, bypasses user triggers (session_replication_role = replica, or DISABLE/ENABLE TRIGGER by name in the same transaction, never thegbrain_graduation_fencetriggers), deletes the target's rows (seed rows included) and inserts byte-sized batches as one$1::text::jsonbarray cast back per column type. The per-column contract (columnContract) refuses missing, retyped, target-only or differently generated columns outside the entry'scolumnAllowlist; generated columns are never inserted. Self-FKs take a second update pass under DISABLE TRIGGER.copySequencesapplies each source sequence's exact position, raised to the target column maximum.deferIndexes/buildDeferredIndexesdrop and rebuild HNSW (throughbuildDeferredAnnIndexes) and GIN indexes, keeping the pending list in the target-ownedgraduation.deferred_indexesconfig row. Tests:test/graduation-copy.test.ts,test/e2e/graduation-copy.test.ts.src/core/persistence/root-metadata.ts— engine-free ownership-marker names.isPhysicalRootMetadatamatches.gbrain-owner.json,.gbrain-owner-<sha256>.json(reservation) and.gbrain-owner.json.<uuid>.tmp(physical-root-record.tsre-exports it andPHYSICAL_ROOT_MARKER).OWNERSHIP_MARKER_GLOBS(#5186) are those names in gitignore dialect:physical-root-record.tsexcludeOwnershipMarkersappends them to<gitdir>/info/exclude(git rev-parse --git-path, idempotent, best effort) afterwritePhysicalRootStamp/adoptTransferredRootStamp, for the stamped directory, the root and the reservation's parent, and again whenassertPhysicalRootverifies a root inside a checkout whose exclude lacks them (a repo-less brain that later rangit init, #8713).PUSH_DENY_GLOBSdenies them with.gbrain-bootstrap.lock/**; the bootstrap.gitignoretemplate has them; doctortracked_ownership_markerwarns when a source checkout's index has one.withoutPhysicalRootMetadatadropsgit status --porcelainentries made only of such metadata (doctorbootstrap_push_health, stop-hook dirty probes): a stamp-only tree is clean, a real change beside the stamp, a rename across it and a quoted path still count. Test:test/persistence-root-metadata.test.ts.src/core/persistence/automatic-sync-policy.ts—automaticSyncPull(engine, source): whether an automatic sync (autopilot freshnesssyncjob, per-source fanout cycle) may request a Git pull. It needs a parsedremote_url, exactly one booleanpersistence_brainstate that is off, and no worktree binding; a managed brain or claimed source syncs local HEAD withpull: false. Missing, duplicated or non-boolean persistence metadata throwsstorage_error(why, read-onlygbrain sources writer status --probe --jsonfix) instead of granting a pull, so the caller queues nothing. Clone, immutable and federation flags grant nothing. Pinned bytest/automatic-sync-pull-policy.test.ts.src/core/persistence/native-lock.ts+native/locks/— lazy portable Node-API v3 kernel locks (flock/LockFileEx) with opaque handles, retained stable lock files, cancellable asynchronous waiting and fail-closed capability errors. Eight vendored prebuilds support script-disabled source installs; pinned Zig recipes and source/artifact hashes live inscripts/native/. Actual competing-process, crash-handoff and compiled-executable tests run across eight platform/architecture targets on Bun 1.4.4. The compiled smoke waits for child exit before cleanup;scripts/native/compiled-smoke-cleanup.tsbounds retries to transient WindowsEBUSYerrors, with persistent and permission failures pinned bytest/scripts/native-compiled-cleanup.test.ts. Windows-onlywindows-ipc.hsupplies opaque Global mutex claims (same-thread recursion refused, abandoned owner handoff) and exact-handle stale AF_UNIX deletion after a verified reparse tag under a retained binding claim. CNG hashing and native casing make pipe identities independent of homes and logon sessions. Build and ownership contract:native/locks/README.md.native/locks/package.json(private, no entry points, outsidebuildInputsandprebuilds/) is a package boundary so plugin hosts that namespace native addons by the nearest package.json do not treat the whole checkout as one package (#6026; guardtest/native-locks-package-boundary.test.ts). #6305: a failure to create or open the lock file is aNativeLockUnavailableErrorwithstage: 'open'andosError(node:fs code, or the addon's(OS error N)as its errno name);isLockOpenFailurematches only that typed shape, never message text.publishMutation(coordinator.ts) and the Postgres single-write group path (group-publish.tspublishGroup, falling through topublishMutation) release such a write asqueued/writer_lock_unavailableinstead of the terminal owner-exception path; the consumer holds that root forINSPECT_OWNER_RETRY_MS(30 s,health.ts) so it doesn't re-prepare every poll;ownerExceptionFailurereportsosErroras the owner-only errno; a Git effect counts it as a dependency wait and never parks on it. An EISDIR or EACCES on the brain path itself stays terminal (persistence-lock-open-failure.test.ts, both engines).src/core/persistence/switches.ts+preadmit-cache.ts+config-snapshot.ts— the single-write fast path for foreground page writes on Postgres.switches.tsreads every write-path kill switch (persistence.single_write_group/GBRAIN_SINGLE_WRITE_GROUP,persistence.preadmit_cache/GBRAIN_PREADMIT_CACHE,sync.waive_batch/GBRAIN_SYNC_WAIVE_BATCH,sync.foreground_priority/GBRAIN_SYNC_FOREGROUND_PRIORITY, andpersistence.preparation_deadlines/GBRAIN_PREPARATION_DEADLINES(#6278: off restores the old preparation predicate, see persistence-stalls.md); on by default,0/falseoff, env over config) in oneSELECT key,value FROM config WHERE key = ANY(...)per engine, kept 5 s (the consumer tick reads it under its phase deadline), together with the four preparation budget keys (readWriteSwitchSnapshotreturns{ switches, preparation };readPreparationPolicyis the budgets alone); read-through views register their engine (registerEngineView) to share it. Withsingle_write_groupon: the consumer publishes an eligible single page write (put_page, capture, edit/delete/restore/revert without an internalintent.kindor group key) as a group of one throughpublishGroup(publishSingleWrite; its intent carries no group marker, its effects queue withoutdeferBatchReconcile, and a group that does not commit falls back topublishMutation, reclaiming a claim its file restoration released); PGLite and refused shapes keeppublishMutation. The waiter's own wake (wake(true)) claims without the periodic scans (recovery records still block the claim throughclaimableWriteSql); preparation reads the config table once (config-snapshot.ts) and sends its independent reads together; the coordinated (coordinated: true) put_page apply reuses the publisher's locked read as the import base, pipelines its follow-up statements and reads the page once after its last write for the read-back check, seal, core notice and receipt. Publication, the own admission and the recovery transactions run on the consumer's reserved lane (onLane: the idle-probe connection, taken while two other pool connections stay free and kept across writes; never lent while an idle probe runs on it, and probes skip it while lent), so their prepared statements stay warm; the waiter is told of the commit before the recovery record is cleared.preadmit-cache.ts(withpreadmit_cacheon, Postgres) answers the brain id, source row, worktree binding and local-writer reads ofsubmitPageMutationfrom a per-engine cache (30 s, keyed by brain id; absences never cached); admission rechecks each under lock and the brain id against its protocol statement, and a refusal the cache could explain (source_changed,permission_denied, a changed brain) drops the cache and runs the whole preparation once more uncached. Pinned bytest/e2e/single-write-fast-path-postgres.test.ts(switches, cache rechecks, replay, restoration after a failure past the file rename, the recovery-blocked direct claim) andtest/single-write-group-parity.test.ts+test/e2e/single-write-group-parity-postgres.test.ts(row-for-row parity with the switches off); measured byscripts/bench/foreground-put-page.ts.Foreground priority (#5984 Phase 4.5,
foreground_priorityswitch,journal.ts):claimableWriteSqllets a non-sync request pass earlier queued sync rows of its root that have not started and do not name its page (slug, page id orintent.renameFrom.slug), claims it first, and holds a passed sync row while that request runs;claimNextLaneHeadstarts no lane head while such a request is unfinished, except one head per foreground commit since the run's last head claim (seen_sequence). A write queued behind an earlier queued write that waits on a sync row naming its page holds back nothing, since it cannot go first either (pinned bytest/claim-fifo-foreground-waiting.test.ts). Both claims find that commit throughFOREGROUND_WAITING_ON's probe, served bypersistence_requests_foreground_committed(#7649, a partial index on committed non-sync rows by worktree and sequence, see request indexes), so a consumer's first claims after a restart, when the bound is 0, stay index probes on a large request table. A consumer whose claimed write passed sync rows (passed_sync) claims plain FIFO on that root after it commits (owesSyncTurn), so a stream of writes cannot starve the drain. The sync side's pauses (no admit-ahead for 60 s after a write, no group while one is queued, the 25-page credit wait) apply only with the switch off. Receipt health judges a claimed write only against earlier started writes. Pinned bytest/managed-sync-foreground-priority.test.ts(two processes) andtest/persistence-diagnostics.test.ts.src/core/postgres-engine/reserved-transactions.tswithisPersistenceDeclaration(src/core/persistence/protocol.ts) — BEGIN pipelining.isPersistenceDeclaration(GBRA-156) accepts exactly theprotocol.tsdeclarations (transaction-localset_configcalls and the brain row FOR SHARE). Admission, the FIFO claim, the effect claims and source guards, the receipt true-up, the single publication (coordinator.ts) and the consumer's lent lane transactions (consumer.tsonLane, throughreservedTransactions) pass it asTransactionOptions.pipelineFirst, so behind a transaction-mode pooler the declaration goes out with BEGIN (one round trip less per transaction) while every later statement still waits for BEGIN's answer; if BEGIN fails, only the declaration has run, in autocommit, where it changes nothing. A reserved transaction gates every statement its body can reach, savepoint and nested-transaction bodies andfile()included. A sync lane group's publication passes none: its begun mark must follow BEGIN's answer (sync-lanes.tsawaitLaneBegin). Tests:test/persistence-pipeline-first.test.ts(the predicate and the reviewed call sites),test/e2e/pgbouncer-transaction-pipeline-6930.test.ts.src/core/links-fence.ts+src/core/links-fence-projection.ts— the## Linksfence (G5): the markdown form of authored (manual) edges,<!--- gbrain:links:begin -->/endaround| to | type | source | valid_from | valid_until | context |, one row per (to, type, source), source defaulting tomanual; a reconciliation-managed provenance (MANAGED_LINK_SOURCES, exported here and re-exported byops/links.ts), a bad date or a duplicate key is a skipped row with a warning.parseLinksFence(stateabsent/parsed/malformed), the deterministicrenderLinksFence(rows sorted by key),upsertLinksFenceRow(omitted context and dates keep the stored ones; identical row = unchanged body),removeLinksFenceRows(leaves an empty fence),replaceOrInsertLinksFence(a## Linkssection at the end of compiled_truth, above an unclosed code block) andmaskLinksFence, whichextractBodyLinksapplies so the fence cells are never also extracted as markdown, wikilink or bare-slug edges. A rewrite of a fence that parses with warnings throwsLinksFenceRewriteRefusal. Cells useescapeFenceCellplus the same one-level marker encoding forgbrain:links:*.projectLinksFence(tx, page, rows)reconciles only what the page's fence owns: edges with origin_page_id = the page and origin_fieldlinks_fence(deleted, context-updated, inserted by key) andmanualtransitions with origin_page_id = the page, compared per row by (to, type, link_source, kind, date) and written with the row's source inlink_source, then refreshes the touched relationships; a row whose target is not a live page in the source yields no edge.linksFenceProjectionRowsreturns null for an absent or malformed fence, so such a body changes no edge (an absent fence retires nothing, as for facts; unlike facts no held generation is recorded, so after a hand deletion of the whole section the database keeps edges git no longer has untilremove_linkor the G3 indexer), and drops rows typed with a link type the active pack does not declare. Callers:prepareCanonicalProjections(every projected page publication, quarantined and segmented-unread bodies excepted),prepareAutomaticLinks(put_page auto-links and the managed links maintenance, soextract --stalerestores a lost fence edge) andpersistence/manual-links.ts. Database-only manual edges (origin_field NULL) are never touched by any of them. Pinned bytest/links-fence.test.tsandtest/managed-links-fence.test.ts.src/core/persistence/source-lifecycle.tsretire batches withtopology-transaction.ts(#7702/#8905) — everytopologyTransactionruns understatement_timeout=5sandlock_timeout=1sand maps SQLSTATE 57014/55P03 towrite_pending, so a managedremoveorpurgefirst deletes the source's pages in batches ofSOURCE_RETIRE_BATCH_PAGES(500; about 110 ms per batch with chunks and links on Postgres) under the native lockswithTopologyLocksholds, each batch its owntopologyTransaction. A batch re-checks the final transaction's preconditions (admin state,lockTopologyRows, the incarnation read before the locks, archived orEXPIRED_ARCHIVE_SQLdue, no prior receipt other than this request's own admission, nooauth_clientsreference,assertTopologyRequestsSettledfromtopology-locks.ts,lockTopologyPrincipal, and on the first batchadmitTopologyRetirefromtopology-receipts.ts, which checks the receipt quotas at the largest receipt and records the admission) and, when one would refuse or replay, stops without deleting so the final transaction reports it, or throws that refusal before deleting; a batch that failswrite_pendingis retried at half the size (floor 1), so heavy pages still fit the bound; a refusal after some batches committed says how many pages that run already deleted; a dry run, a missing checkout, an unconfirmed operation and an admission-hooked call never batch. The final transaction'ssourcesdelete runsremovedSourceScrubCtes(#9068: the source's retrieval and volunteer rows, and its slugs in eval candidates), so a run that stops after some batches leaves those rows until a retry commits. Each batch deletes insidewithCoordinatedWritewith local-CLI attribution (thepagesguard needs the source ingbrain.write_sources; only the finalsourcesdelete setsgbrain.topology_change). Committed batches are durable: a retry (same or new request_id) resumes, and the receipt'spages_deletedcounts the pages deleted by the run that commits it. #8984: the first batch's transaction records the admission, apersistence_topology_changesrow in staterecoveringwith no recovery record, bound to the source incarnation it deletes from (isRetireAdmission);recordTopologyChangesettles itcommitted, and a remove or purge that deletes that incarnation under another request, or any other lifecycle operation that commits a change to it (archive, restore, rebind, claim), settles itfailed(supersedeTopologyRetires, which skips only the caller's own principal and request_id pair). A retry of the request_id against another incarnation (the source was removed and re-added) refusessource_retire_superseded, settles the admissionfailedand deletes nothing, also when a since-replaced CLI registration (another principal) admitted that request_id for a remove or purge, since idempotency is per principal; an admission bound to the current incarnation still resumes under the new registration; deactivation and graduation list an unsettled admission as a blocker that names its request_id and asks the user whether to finish it or keep what is left; an automatic expired-archive purge's admission (expired_onlyin its outcome) is left to the next automatic run withneedsUser: false, andsources writer status --jsonlists the stopped and superseded requests (topology_requests). Tests:test/source-retire-batched.test.ts(PGLite),test/e2e/source-retire-batched-postgres.test.ts(60,000 pages),test/source-retire-incarnation.test.tsandtest/e2e/source-retire-incarnation-postgres.test.ts.src/core/persistence/label-edit.ts+src/core/repair/label-write.ts(GST-2468) — the label-only page write of operator repairs (repair visibility,repair private-labels).label-edit.ts:LABEL_KEYS(visibility, access, confidentiality),readLabelEditvalidates amanaged_maintenance_pageintent'slabel_edit(setplain-word values,removekeys),spliceLabelLinesremoves, replaces or appends label lines in a file's frontmatter text and declines (null) a block or multi-line value, a duplicate key or a file with no frontmatter block.page-prepare.tslabelEditFileuses it incompareFileTargetwhen the file matches the snapshot: the edited file (or its edited head over the write's body, for a fence row) must read back as the file the write would render, else the write refuseslabel_edit_refused(GST-2603; reasonfile_differswith the differing keys indetail, orlabel_line); the file is never re-rendered under a label edit. GST-2603:labelEditFit(also used bywriteLabelFile) aligns the file with the stored page before comparing, andalign-stored.tskeepStoredOnlyStamps(used byalignWithStoredand sync'skeepStoredStamps) keeps the stamps gbrain holds only in the database (thevalidate: falsegrandfather stamp and a storedlegacy_typewhose aligned type is the page's), so they never count as a difference;fileSnapshotDifferencelists the differing keys (frontmatter keys, title, type, tags, body, timeline) for the raw and inferred reading andfileMatchesSnapshotis its empty case.label-write.tslabelFileRefusalis a write-free preflight (managed:prepareFileTarget, with the drift's keys fromerror.localEditandgbrain sources reconcile <id> <slug> --previewas next step; unmanaged:ownerRepairFile, next stepgbrain sync --source <id>; repo-less or no file: null);visibility.tsholds refusing pages in the preview (details.held,residuals.held_file_drift/held_label_edit, outside the hash and approved set) andlabelWrite/private-labels.tsprepareWritethrow only itslabel_edit_refusedbefore writing.repair/core.tscountslabel_edit_refusedas declined and never towarditem_failures_systemic. Test:test/label-repair-derived-stamps-gst2603.test.ts.label-write.ts:writeLabelPagepublishes through the maintenance door withkeep_trustand the edit on a managed brain, elseimportAtRevision(maintenance transaction, page lock,withTrustKeep);filesInCheckoutnames the unmanaged pages whose checkout file would undo a database-only write; for those,writeLabelFileapplieslabelEditFileto the file's own bytes (it must still hold the page,ownerRepairFile), imports it underwithTrustKeepand writes it back throughwritePageThrough(fileText, preimage checked) in one transaction; drift or a file edited mid-write throwssource_changed, and a file it cannot write (sync.write_throughoff,url_clone, an unresolvable target, a write error) returns a heldfile_backedoutcome with the import rolled back.repair visibilitycalls it directly;private-labelsstill holds those pages asfile_backed;repair/origin-carry.ts(GST-2689) useswriteLabelFile,importAtRevisionandpublishMaintenancePagesthe same way to label derived pages private before their origin row goes, and parks the origin when one returns held or throws. GST-2476:label-edit.tsalso editsreadable_by(READERS_KEY,EDIT_KEYS;settakes a plain-word list, renderedreadable_by: [a, b]), andwriteLabelPagetakes a maintenancebatch(thenpublishMaintenancePages([page], {batch})).src/core/repair/readers.tsisrepair visibility --readers:checkedReaders(members exist and are enabled, groups exist, elseaccess_member_invalid; a list that leaves out the owner refuses unlessallowWithoutOwner),planReaders(named pages or a--slugs-file, up toREADERS_MAX_PAGES, approved set bound to each page's live readers)readersWrite(re-checks a page, holds a segmented one, renders the edit) andapplyReaders(phaseREADERS_PHASE, one label-only write);visibility.tsapplyBatchadmits a managed source's run of readers items together throughpublishMaintenancePagesunder the run's batch (Postgres publishes them in groups of up to 8), so the Git effect commits a window's ready files together;readersGitCountsreports the run's Git effect states.visibility.tslabelWriteholds a managed page with no canonical file outsidestorage.db_onlyascanonical_file_missing. GST-2519, labels understorage.db_only:sync-classify.tsgitVerdictkeeps a strict source'sdb_aheadpath whenstate.dbOnly(a label repair on a page whose file Git still tracks there survives later syncs; a commit that moved still imports);sync-prepare.tsimports a db_only file over a live page throughwithStoredLabels(text, stored, incoming), which adds eachEDIT_KEYSlabel the row holds and the file does not state, so an import there never widens (a label the file states applies, wider included);page-prepare.tsprepareFileTargetlets a label repair of a strict page stampedgit_ignored, with no recorded file and a path Git still ignores, write the database only instead of holding itcanonical_file_missing. Tests:test/db-only-labels-gst2519.test.ts,test/sync-classify-strict-g3.test.ts.src/core/persistence/page-edit.ts—edit_page(#5616): splits the canonical serialization into editable text and protected takes/facts segments whose remote view matches get_page's sanitizedcontentbyte for byte;applyPageEditsapplies ordered exact-once replacements inside editable text only (typededit_no_match/edit_ambiguous_match/edit_protected_span/edit_invalid), so canonical fences never move;editDiffcaps the caller-view diff at 8 KB;boundedUnifiedDiffkeeps its LCS table underEDIT_PAGE_DIFF_CELL_BUDGET(4M cells) by diffing only the window between common leading/trailing lines, and a window still over budget becomes one coarse hunk flaggeddiff_coarse(pinned bytest/large-pages/edit-diff-bounded.test.ts). Called at submission (page-mutations.ts, before admission; skipped for a segmented page) and again on the locked snapshot inpage-prepare.ts, which gives edit_page put_page's revision-boundeditingtimeline semantics. Pinned bytest/edit-page.test.ts.withinand the segmented path: large page writes.src/core/repair/open-facts.ts+src/commands/repair-open-facts.ts(#8194) —gbrain repair open-facts, the operator-only, explicit-only, preview-bound repair that opens facts stamped private beforefacts.default_visibility world.openFactsReasonSqlis the one exclusion expression the preview, its reason counts and the locked apply share (expired, superseded, member page, withdrawn or purged at any visibility, any pending trust proposal or a rejected or undone widening, a holding, provenance or entity page that isderivationPrivateSqlon any row with the slug, deleted or not, a missing or quarantined holding or provenance page, an unresolved provenance slug);openFactClassSqlclasses factsfenced,unfencedorunpaged:<lane>(no page or a transcript lane; opened only when named). Keyset windows (--after,--limit), the approved set binds the window and an apply refusespreview_changedwhen a new fact became eligible inside it. Writes lock the named pages FOR SHARE and each fact FOR UPDATE before the recheck: database-only rows change in place (managed: themanaged_maintenance_open_fact_visibilityintent,prepareOpenFactsIntent; else a maintenance transaction); fenced rows go through the label-only door with the cell set bystrikeFenceRow(managed:publishMaintenancePagewithopenFacts, whose keep_trust publicationopenFactsPublicationruns underpersistence/context.tswithOpenFacts, the only setter ofgbrain.write_open_facts, whichopenedFactRowSqlreads intrust/fence-guard.ts,generations/adapters/fact-rows.tsandcanonical-projections.tsso the row moves to world in place; unmanaged: the import, then the in-place update). The CLI keeps the write-ahead ledger (repairLedgerinrepair-private-labels.ts) and--undore-privates what it opened. Refuses remote callers (trusted_cli_required) andGBRAIN_ENFORCED_MEMBER(member_mode_refused). Test:test/repair-open-facts-8194.test.ts(PGLite and Postgres, with a two-session race).