Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Label repairs hold a checkout file they cannot write, and report unclosed fact rows by who can read them

garrytan924ae3d31609
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4c2875d7de..91c14b4dd7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,10 +20,10 @@ identifiers and attribution are available in the pre-removal Git revision
- `src/core/persistence/page-prepare.ts`: a `managed_maintenance_page` write that carries `label_edit` publishes the canonical file's own bytes with only its label lines edited (`labelEditFile`), keeping its body when it reads as the write's body, and refuses instead of re-rendering when no line edit reads back as the write.
- `src/core/persistence/prepared-maintenance.ts`: maintenance page publications carry `labelEdit`.
- `src/core/repair/label-write.ts` (new): the label-only write door both repairs use (the maintenance door with `keep_trust` on a managed brain; the import under the page lock and `withTrustKeep` otherwise); `filesInCheckout` and `importAtRevision` moved here from `private-labels.ts`.
-- `src/core/repair/visibility.ts`: page and fenced-fact items write through the label door instead of `put_page`; on a brain without managed persistence a page whose file sits in a checkout gets the same label-line edit in that file, imported with its tier kept; a segmented page is held (`segmented_page`); new `--slug` selection (class `pages`), preview-bound, tighten-only; a fenced fact row it could not make private is reported `fact_left_readable` (`NOT CLOSED` in the text output) instead of a plain skip, because remote callers can still read it.
+- `src/core/repair/visibility.ts`: page and fenced-fact items write through the label door instead of `put_page`; on a brain without managed persistence a page whose file sits in a checkout gets the same label-line edit in that file, imported with its tier kept, and a file it cannot write (`sync.write_through` off, a pulled clone, a write error) is held `file_backed` with nothing written; a segmented page is held (`segmented_page`); a page that changed after it was read is skipped (`revision_conflict`) instead of counted; new `--slug` selection (class `pages`), preview-bound, tighten-only; a fenced fact row it could not make private is reported `fact_left_readable` when remote callers can still read it, or `fact_left_world` when only its page's privacy hides it (`NOT CLOSED` in the text output for both), instead of a plain skip.
- `src/core/repair/private-labels.ts`: clears and restores carry their label edit, so the file loses or regains only those lines.
- `src/core/trust/label-lowerings.ts` (new), `src/cli/commands/trust.ts`: `gbrain trust backfill --label-lowerings [--source ID] [--json]`, read-only.
-- Tests: `test/label-only-repairs.test.ts` (managed Git source and repo-less brain, PGLite and Postgres).
+- Tests: `test/label-only-repairs.test.ts` (managed Git source and repo-less brain, PGLite and Postgres); `test/owner-member-boundary.test.ts` pins that the owner reads its private pages and pages that list it, and never another member's restricted page, on every read path.
## [0.60.678.0] - 2026-11-11
diff --git a/docs/architecture/key-files/core-persistence-continued.md b/docs/architecture/key-files/core-persistence-continued.md
index 1eaedf90b6..40e42902cb 100644
--- a/docs/architecture/key-files/core-persistence-continued.md
+++ b/docs/architecture/key-files/core-persistence-continued.md
@@ -42,4 +42,4 @@ The #6188 fence check and fence repair live in [fence repair](core-fence-repair.
- `src/core/postgres-engine/reserved-transactions.ts` with `isPersistenceDeclaration` (`src/core/persistence/protocol.ts`) — BEGIN pipelining. `isPersistenceDeclaration` (GBRA-156) accepts exactly the `protocol.ts` declarations (transaction-local `set_config` calls 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.ts` `onLane`, through `reservedTransactions`) pass it as `TransactionOptions.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 and `file()` included. A sync lane group's publication passes none: its begun mark must follow BEGIN's answer (`sync-lanes.ts` `awaitLaneBegin`). 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 `## Links` fence (G5): the markdown form of authored (manual) edges, `<!--- gbrain:links:begin -->` / `end` around `| to | type | source | valid_from | valid_until | context |`, one row per (to, type, source), source defaulting to `manual`; a reconciliation-managed provenance (`MANAGED_LINK_SOURCES`, exported here and re-exported by `ops/links.ts`), a bad date or a duplicate key is a skipped row with a warning. `parseLinksFence` (state `absent` / `parsed` / `malformed`), the deterministic `renderLinksFence` (rows sorted by key), `upsertLinksFenceRow` (omitted context and dates keep the stored ones; identical row = unchanged body), `removeLinksFenceRows` (leaves an empty fence), `replaceOrInsertLinksFence` (a `## Links` section at the end of compiled_truth, above an unclosed code block) and `maskLinksFence`, which `extractBodyLinks` applies so the fence cells are never also extracted as markdown, wikilink or bare-slug edges. A rewrite of a fence that parses with warnings throws `LinksFenceRewriteRefusal`. Cells use `escapeFenceCell` plus the same one-level marker encoding for `gbrain:links:*`. `projectLinksFence(tx, page, rows)` reconciles only what the page's fence owns: edges with origin_page_id = the page and origin_field `links_fence` (deleted, context-updated, inserted by key) and `manual` transitions with origin_page_id = the page, compared per row by (to, type, link_source, kind, date) and written with the row's source in `link_source`, then refreshes the touched relationships; a row whose target is not a live page in the source yields no edge. `linksFenceProjectionRows` returns 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 until `remove_link` or 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, so `extract --stale` restores a lost fence edge) and `persistence/manual-links.ts`. Database-only manual edges (origin_field NULL) are never touched by any of them. Pinned by `test/links-fence.test.ts` and `test/managed-links-fence.test.ts`.
- `src/core/persistence/source-lifecycle.ts` retire batches with `topology-transaction.ts` (#7702/#8905) — every `topologyTransaction` runs under `statement_timeout=5s` and `lock_timeout=1s` and maps SQLSTATE 57014/55P03 to `write_pending`, so a managed `remove` or `purge` first deletes the source's pages in batches of `SOURCE_RETIRE_BATCH_PAGES` (500; about 110 ms per batch with chunks and links on Postgres) under the native locks `withTopologyLocks` holds, each batch its own `topologyTransaction`. A batch re-checks the final transaction's preconditions (admin state, `lockTopologyRows`, the incarnation read before the locks, archived or `EXPIRED_ARCHIVE_SQL` due, no prior receipt other than this request's own admission, no `oauth_clients` reference, `assertTopologyRequestsSettled` from `topology-locks.ts`, `lockTopologyPrincipal`, and on the first batch `admitTopologyRetire` from `topology-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 fails `write_pending` is 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's `sources` delete runs `removedSourceScrubCtes` (#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 inside `withCoordinatedWrite` with local-CLI attribution (the `pages` guard needs the source in `gbrain.write_sources`; only the final `sources` delete sets `gbrain.topology_change`). Committed batches are durable: a retry (same or new request_id) resumes, and the receipt's `pages_deleted` counts the pages deleted by the run that commits it. #8984: the first batch's transaction records the admission, a `persistence_topology_changes` row in state `recovering` with no recovery record, bound to the source incarnation it deletes from (`isRetireAdmission`); `recordTopologyChange` settles it `committed`, 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 it `failed` (`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) refuses `source_retire_superseded`, settles the admission `failed` and 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_only` in its outcome) is left to the next automatic run with `needsUser: false`, and `sources writer status --json` lists 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.ts` and `test/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), `readLabelEdit` validates a `managed_maintenance_page` intent's `label_edit` (`set` plain-word values, `remove` keys), `spliceLabelLines` removes, 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.ts` `labelEditFile` uses it in `compareFileTarget` when 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 refuses `invalid_params`; the file is never re-rendered under a label edit. `label-write.ts`: `writeLabelPage` publishes through the maintenance door with `keep_trust` and the edit on a managed brain, else `importAtRevision` (maintenance transaction, page lock, `withTrustKeep`); `filesInCheckout` names the unmanaged pages whose checkout file would undo a database-only write; for those, `writeLabelFile` applies `labelEditFile` to the file's own bytes (it must still hold the page, `ownerRepairFile`), imports it under `withTrustKeep` and writes it back through `writePageThrough` (`fileText`, preimage checked) in one transaction (`private-labels` still holds them as `file_backed`).
+- `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), `readLabelEdit` validates a `managed_maintenance_page` intent's `label_edit` (`set` plain-word values, `remove` keys), `spliceLabelLines` removes, 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.ts` `labelEditFile` uses it in `compareFileTarget` when 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 refuses `invalid_params`; the file is never re-rendered under a label edit. `label-write.ts`: `writeLabelPage` publishes through the maintenance door with `keep_trust` and the edit on a managed brain, else `importAtRevision` (maintenance transaction, page lock, `withTrustKeep`); `filesInCheckout` names the unmanaged pages whose checkout file would undo a database-only write; for those, `writeLabelFile` applies `labelEditFile` to the file's own bytes (it must still hold the page, `ownerRepairFile`), imports it under `withTrustKeep` and writes it back through `writePageThrough` (`fileText`, preimage checked) in one transaction; drift or a file edited mid-write throws `source_changed`, and a file it cannot write (`sync.write_through` off, `url_clone`, an unresolvable target, a write error) returns a held `file_backed` outcome with the import rolled back. `repair visibility` calls it directly; `private-labels` still holds those pages as `file_backed`.
diff --git a/docs/guides/repair.md b/docs/guides/repair.md
index e585e40778..5640045aef 100644
--- a/docs/guides/repair.md
+++ b/docs/guides/repair.md
@@ -90,12 +90,17 @@ block) is refused with nothing written; make that edit by hand. `--slug` is the
a `put_page` that adds the label is an agent edit and lowers the page. On a brain
without managed persistence, a page whose file sits in its source's checkout gets
the same edit in that file and in the database together, so the next sync reads
-the same page.
-
-A fenced fact row the apply could not make private is counted as
-`fact_left_readable` in the outcomes (`--json`: `outcomes.fact_left_readable`,
-each row in `outcome_items`), and the text output says `NOT CLOSED`: those rows
-are still world and remote callers can still read them. Today that happens when
+the same page. A file holding an edit the database lacks refuses with nothing
+written (run `gbrain sync` first). A file the repair cannot write
+(`sync.write_through` is off, a clone gbrain pulls, a write error) is held
+`file_backed` with nothing written, because the next sync would put the old
+label back from the file; make that edit in the file by hand.
+
+A fenced fact row the apply could not make private is counted in the outcomes
+(`--json`: `outcomes`, each row in `outcome_items`), and the text output says
+`NOT CLOSED`: `fact_left_readable` when remote callers can still read the row,
+`fact_left_world` when the row is still world and only its page's privacy hides
+it from them. Today that happens when
the original row is more trusted than the repair (it is kept beside the new
private row), when the page is stored in segments, or when the row is not found
in the page's facts fence.
diff --git a/src/commands/repair.ts b/src/commands/repair.ts
index 323f03b769..c8ebb8ce78 100644
--- a/src/commands/repair.ts
+++ b/src/commands/repair.ts
@@ -459,6 +459,9 @@ export function renderRepairResult(result: RepairResult, opts: { diff: boolean }
if (result.mode === 'apply' && result.outcomes?.fact_left_readable) {
lines.push(` NOT CLOSED: ${result.outcomes.fact_left_readable} fact row(s) could not be made private and stay readable by remote callers (listed below).`);
}
+ if (result.mode === 'apply' && result.outcomes?.fact_left_world) {
+ lines.push(` NOT CLOSED: ${result.outcomes.fact_left_world} fact row(s) could not be made private and are still world; only their page's privacy hides them from remote callers (listed below).`);
+ }
for (const outcome of result.mode === 'apply' ? result.outcome_items ?? [] : []) {
if (!outcome.detail) continue;
lines.push(` ${outcome.outcome}: ${outcome.item} ${Object.entries(outcome.detail).filter(([key]) => key !== 'commit_step' && key !== 'fix').map(([k, v]) => `${k}=${v}`).join(', ')}${outcome.reason ? ` (${outcome.reason})` : ''}`);
diff --git a/src/core/repair/label-write.ts b/src/core/repair/label-write.ts
index ac036267e1..bc389c8174 100644
--- a/src/core/repair/label-write.ts
+++ b/src/core/repair/label-write.ts
@@ -5,9 +5,9 @@
* - a managed brain publishes it through the maintenance door with keep_trust and the label edit (the Git door on a
* repo source; a repo-less managed source writes the database only);
* - a brain without managed persistence imports it in a maintenance transaction under the page lock and withTrustKeep:
- * database only when the page has no file (the default keyless install), and for a page whose file sits in its
- * source's checkout (`filesInCheckout`) the file's own bytes with only the label lines edited, imported and written
- * back in that transaction, so the next sync reads the same page (writeLabelFile).
+ * database only when the page has no file (the default keyless install); a caller whose page has a file in its
+ * source's checkout (`filesInCheckout`) calls writeLabelFile, which imports the file's own bytes with only the label
+ * lines edited and writes them back in that transaction, so the next sync reads the same page.
* An ordinary put_page, local or remote, stays an agent content write (trust/channel.ts): it is never used here.
*/
import type { BrainEngine } from '../engine.ts';
@@ -19,6 +19,7 @@ import type { LabelEdit } from '../persistence/label-edit.ts';
import { managedPersistenceEnabled } from '../persistence/ownership.ts';
import { labelEditFile } from '../persistence/page-prepare.ts';
import { maintenancePreflight, publishMaintenancePage, type MaintenanceAuthority } from '../persistence/prepared-maintenance.ts';
+import type { RepairItemOutcome } from './core.ts';
const bounded = { timeoutMs: 120_000 };
@@ -55,28 +56,46 @@ export async function importAtRevision(engine: BrainEngine, page: { source_id: s
}
/**
- * T1: an unmanaged page whose file sits in its source's checkout. The file must still hold the page (a file holding an
- * edit the database lacks refuses); its own bytes with only the label lines edited (labelEditFile, the managed brain's
- * splice) are imported under withTrustKeep at `revision` and written back with their preimage checked, in one
- * transaction, so the file and the row agree and the tier is kept. A recorded file that is gone writes the database only.
+ * T1: an unmanaged page whose file (`path`, from filesInCheckout) sits in its source's checkout. The file must still hold
+ * the page (a file holding an edit the database lacks refuses `source_changed`); its own bytes with only the label lines
+ * edited (labelEditFile, the managed brain's splice) are imported under withTrustKeep at `revision` and written back with
+ * their preimage checked, in one transaction, so the file and the row agree and the tier is kept. A file edited between
+ * the read and the write refuses `source_changed` and rolls the import back. A file this repair cannot write
+ * (`sync.write_through` off, a clone gbrain pulls, an unresolvable target, a write error) is held `file_backed` with
+ * nothing written, since a database-only write would come back from the file at the next sync. A page with no file on
+ * purpose (no checkout configured, a non-canonical target) or whose recorded file is gone writes the database only.
+ * The revision written; null when the page moved.
*/
-async function writeLabelFile(engine: BrainEngine, page: { source_id: string; slug: string }, write: { revision: string; content: string; edit: LabelEdit; embed: boolean; preview: string }): Promise<string | null> {
+export async function writeLabelFile(engine: BrainEngine, page: { source_id: string; slug: string }, write: { revision: string; content: string; edit: LabelEdit; embed: boolean;
+ preview: string; path: string }): Promise<string | null | RepairItemOutcome> {
const ref = `${page.source_id}:${page.slug}`;
+ const held = (why: string): RepairItemOutcome => ({ applied: false, outcome: 'file_backed', detail: { path: write.path },
+ reason: `${ref} has a file in its source's checkout (${write.path}) that this repair cannot write (${why}), and a database-only write would come back from the file `
+ + `at the next sync. Make the change in that file by hand, commit it, then run: gbrain sync --source ${page.source_id}` });
+ const { isWriteThroughDisabled, writePageThrough } = await import('../write-through.ts');
+ if (await isWriteThroughDisabled(engine)) return held('sync.write_through is off');
const { ownerRepairFile } = await import('../trust/page-handlers.ts');
const file = await ownerRepairFile(engine, page.source_id, page.slug);
- if (!file.ok) throw opError('source_changed', `${ref} was not written: its file in the source's checkout cannot take the label edit (${file.reason}).`,
- `If the file holds the newer edit, run gbrain sync --source ${page.source_id}; then preview ${write.preview} again.`);
+ if (!file.ok && file.reason !== 'file_database_drift') return held(file.reason);
+ if (!file.ok) throw opError('source_changed', `${ref} was not written: its file in the source's checkout holds an edit the database lacks.`,
+ `Run gbrain sync --source ${page.source_id}, then preview ${write.preview} again.`);
const before = file.target?.expectedFileBytes ?? null;
const snapshot = before === null ? null : await engine.readPageSnapshot(page.slug, { sourceId: page.source_id });
if (before === null || !snapshot) return importAtRevision(engine, page, write.revision, write.content, write.embed, write.preview);
if (snapshot.revision !== write.revision) return null;
const text = labelEditFile(page.slug, Buffer.from(before, 'utf8'), write.content, write.edit, snapshot);
- const { writePageThrough } = await import('../write-through.ts');
- return importAtRevision(engine, page, write.revision, text, write.embed, write.preview, async tx => {
- const written = await writePageThrough(tx, page.slug, { sourceId: page.source_id, expectedFileBytes: before, fileText: text });
- if (!written.written) throw opError('source_changed', `${ref} was not written: its file changed or could not be written (${written.skipped ?? written.error ?? 'unknown'}).`,
- `Preview ${write.preview} again; the page is listed with its current state.`);
- });
+ let unwritable: string | undefined;
+ try {
+ return await importAtRevision(engine, page, write.revision, text, write.embed, write.preview, async tx => {
+ const written = await writePageThrough(tx, page.slug, { sourceId: page.source_id, expectedFileBytes: before, fileText: text });
+ if (written.written) return;
+ if (written.skipped !== 'file_changed') unwritable = written.skipped ?? written.error ?? 'the write failed';
+ throw opError('source_changed', `${ref} was not written: its file changed after it was read.`, `Preview ${write.preview} again; the page is listed with its current state.`);
+ });
+ } catch (error) {
+ if (unwritable) return held(unwritable);
+ throw error;
+ }
}
/**
@@ -84,10 +103,10 @@ async function writeLabelFile(engine: BrainEngine, page: { source_id: string; sl
* the import under the page lock otherwise. The revision it wrote; null when the page moved before an unmanaged import.
*/
export async function writeLabelPage(ctx: OperationContext, page: { source_id: string; slug: string }, write: { revision: string; content: string; edit: LabelEdit;
- requestId: string; embed: boolean; preview: string; /** The page has a file in its source's checkout (filesInCheckout). */ file?: boolean },
+ requestId: string; embed: boolean; preview: string },
authority?: MaintenanceAuthority | null): Promise<string | null> {
const door = authority === undefined ? await maintenancePreflight(ctx.engine, page.source_id) : authority;
- if (!door) return write.file ? writeLabelFile(ctx.engine, page, write) : importAtRevision(ctx.engine, page, write.revision, write.content, write.embed, write.preview);
+ if (!door) return importAtRevision(ctx.engine, page, write.revision, write.content, write.embed, write.preview);
await publishMaintenancePage(ctx.engine, door, page.slug, write.content, { expectedRevision: write.revision, requestId: write.requestId, keepTrust: true, labelEdit: write.edit });
return (await ctx.engine.readPageSnapshot(page.slug, { sourceId: page.source_id }))?.revision ?? null;
}
diff --git a/src/core/repair/visibility.ts b/src/core/repair/visibility.ts
index 5164eb5bd3..76cd0aa3bc 100644
--- a/src/core/repair/visibility.ts
+++ b/src/core/repair/visibility.ts
@@ -48,7 +48,7 @@ import { managedPersistenceEnabled } from '../persistence/ownership.ts';
import { maintenancePreflight, submitDatabaseMaintenanceIntent } from '../persistence/prepared-maintenance.ts';
import { isSegmentedPage } from '../page-body/page-shape.ts';
import { afterCursor, repairRequestId, type RepairHandler, type RepairItem, type RepairItemOutcome, type RepairPlan, type RepairPlanOptions, type RepairScope, type RepairCursor } from './core.ts';
-import { filesInCheckout, writeLabelPage } from './label-write.ts';
+import { filesInCheckout, writeLabelFile, writeLabelPage } from './label-write.ts';
import type { LabelEdit } from '../persistence/label-edit.ts';
import type { PageSnapshot } from '../page-state/types.ts';
import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
@@ -259,10 +259,13 @@ export async function prepareFactVisibilityTighten(engine: BrainEngine, row: Wri
* revision-bound label write (labelWrite; the projection then stores it private); a
* database-only row is updated in place (a database-only maintenance request
* on a managed brain). A page stored in segments is left for the owner. A fenced row that stays world and live is
- * reported `fact_left_readable` (counted in the apply's outcomes), never as done: remote callers still read it.
+ * reported, never as done: `fact_left_readable` when remote callers can read it now, `fact_left_world` when only its
+ * page's privacy hides it (worldFactsFromPrivateSources `readable`).
*/
-const leftReadable = (factId: number, why: string): RepairItemOutcome => ({ applied: false, outcome: 'fact_left_readable', detail: { fact_id: factId },
- reason: `${why}; the fact row is still world, so remote callers can still read it` });
+const leftWorld = (fact: { id: number; readable: boolean }, why: string): RepairItemOutcome => fact.readable
+ ? { applied: false, outcome: 'fact_left_readable', detail: { fact_id: fact.id }, reason: `${why}; the fact row is still world, so remote callers can still read it` }
+ : { applied: false, outcome: 'fact_left_world', detail: { fact_id: fact.id },
+ reason: `${why}; the fact row is still world, and only its page's privacy keeps remote callers from reading it` };
async function applyFactItem(ctx: Parameters<RepairHandler['apply']>[0], item: RepairItem, factId: number): Promise<boolean | RepairItemOutcome> {
const [fact] = await worldFactsFromPrivateSources(ctx.engine, [item.source_id], [factId]);
if (!fact) return false;
@@ -280,28 +283,32 @@ async function applyFactItem(ctx: Parameters<RepairHandler['apply']>[0], item: R
}
const snapshot = fact.source_markdown_slug ? await ctx.engine.readPageSnapshot(fact.source_markdown_slug, { sourceId: item.source_id }) : null;
if (!snapshot) return false;
- if (isSegmentedPage(snapshot.page)) return leftReadable(factId, 'its page is stored in segments, which this repair does not rewrite');
+ if (isSegmentedPage(snapshot.page)) return leftWorld(fact, 'its page is stored in segments, which this repair does not rewrite');
const body = strikeFenceRow(snapshot.page.compiled_truth ?? '', fact.row_num, row => ({ ...row, visibility: 'private' }));
- if (body === null) return leftReadable(factId, 'its row was not found in the page\'s facts fence');
+ if (body === null) return leftWorld(fact, 'its row was not found in the page\'s facts fence');
const held = await labelWrite(ctx, item, snapshot, serializePageToMarkdown({ ...snapshot.page, compiled_truth: body }, snapshot.tags), { set: {}, remove: [] });
if (held) return held;
const [stored] = await ctx.engine.executeRaw<{ visibility: string; live: boolean }>('SELECT visibility, expired_at IS NULL AS live FROM facts WHERE id=$1', [factId]);
if (!stored || stored.visibility === 'private' || !stored.live) return true;
- return leftReadable(factId, 'its fence row was written private, but the original row is more trusted than the repair and was kept beside it');
+ return leftWorld(fact, 'its fence row was written private, but the original row is more trusted than the repair and was kept beside it');
}
/**
* GST-2468: one item's page write is a label-only maintenance write (repair/label-write.ts): it keeps the page's trust
* tier, files no lower_page proposal and changes only the label lines of the page's file (a fact item: its fence row).
* On a brain without managed persistence a page whose file sits in its source's checkout gets the same splice in that
- * file (label-write.ts writeLabelFile). Null once written; the held outcome for a page stored in segments.
+ * file (label-write.ts writeLabelFile). Null once written; the held outcome for a page stored in segments or a file the
+ * repair cannot write. A page that moved since it was read throws `revision_conflict`, which the apply counts as skipped.
*/
async function labelWrite(ctx: Parameters<RepairHandler['apply']>[0], item: RepairItem, snapshot: PageSnapshot, content: string, edit: LabelEdit): Promise<RepairItemOutcome | null> {
if (isSegmentedPage(snapshot.page)) return { applied: false, outcome: 'segmented_page', reason: 'The page body is stored in segments; edit it by hand on the brain host.' };
- const file = (await filesInCheckout(ctx.engine, [Number(snapshot.page.id)])).has(Number(snapshot.page.id));
- await writeLabelPage(ctx, item, { revision: snapshot.revision, content, edit, requestId: await repairRequestId(ctx, 'visibility', item, snapshot.revision),
- embed: true, preview: 'gbrain repair visibility', file });
- return null;
+ const path = (await filesInCheckout(ctx.engine, [Number(snapshot.page.id)])).get(Number(snapshot.page.id));
+ const write = { revision: snapshot.revision, content, edit, embed: true, preview: 'gbrain repair visibility' };
+ const written = path ? await writeLabelFile(ctx.engine, item, { ...write, path })
+ : await writeLabelPage(ctx, item, { ...write, requestId: await repairRequestId(ctx, 'visibility', item, snapshot.revision) });
+ if (written === null) throw opError('revision_conflict', `${item.source_id}:${item.slug} changed after it was read, so it was not written.`,
+ 'Preview gbrain repair visibility again; the page is listed with its current state.');
+ return typeof written === 'string' ? null : written;
}
export type VisibilityClass = 'facts' | 'events' | 'aliases' | 'lineage' | 'pages';
diff --git a/test/label-only-repairs.test.ts b/test/label-only-repairs.test.ts
index 71f92a4c8b..cddbcb001c 100644
--- a/test/label-only-repairs.test.ts
+++ b/test/label-only-repairs.test.ts
@@ -15,7 +15,7 @@
*/
import { describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
@@ -23,6 +23,7 @@ import { operations, type OperationContext } from '../src/core/operations.ts';
import { importFromContent } from '../src/core/import-file.ts';
import { withCoordinatedWrite, withTrustBackfill } from '../src/core/persistence/context.ts';
import { performManagedSync } from '../src/core/persistence/sync-run.ts';
+import { _resetWriteThroughCacheForTest } from '../src/core/write-through.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { renderRepairResult, runRepairCommand } from '../src/commands/repair.ts';
import { _resetCliExitVerdictForTests } from '../src/core/cli-force-exit.ts';
@@ -130,9 +131,11 @@ for (const backend of testBackends()) describe('[' + backend + '] label-only ope
await settleManagedGitEffects(engine);
// The original world row is more trusted than the repair and stays live (GST-2487): the apply must say so, never "done".
expect(applied.applied).toBe(0);
- expect(applied.outcomes).toMatchObject({ fact_left_readable: 1 });
- expect(applied.outcome_items).toEqual([expect.objectContaining({ item: 'default:' + slug, outcome: 'fact_left_readable' })]);
- expect(renderRepairResult(applied)).toContain('NOT CLOSED: 1 fact row(s) could not be made private and stay readable by remote callers');
+ // The page is private, so only its privacy hides the row today: the apply says "still world", not "readable".
+ expect(applied.outcomes).toMatchObject({ fact_left_world: 1 });
+ expect(applied.outcomes.fact_left_readable).toBeUndefined();
+ expect(applied.outcome_items).toEqual([expect.objectContaining({ item: 'default:' + slug, outcome: 'fact_left_world' })]);
+ expect(renderRepairResult(applied)).toContain('NOT CLOSED: 1 fact row(s) could not be made private and are still world');
expect(await engine.executeRaw("SELECT visibility FROM facts WHERE source_markdown_slug=$1 AND expired_at IS NULL AND visibility='world'", [slug])).toEqual([{ visibility: 'world' }]);
expect((await page(engine, slug)).tier).toBe('operator_curated');
expect(await engine.executeRaw("SELECT id FROM trust_proposals WHERE action='lower_page'")).toEqual([]);
@@ -209,31 +212,73 @@ for (const backend of testBackends()) describe('[' + backend + '] label-only ope
} finally { rmSync(home, { recursive: true, force: true }); }
}, 180_000);
- test('without managed persistence, a page whose file is in a checkout gets the same label-line splice in its file', async () => {
+ /** A brain without managed persistence whose source `source-b` has a checkout holding the page's file. */
+ async function checkoutBrain(fn: (brain: { engine: BrainEngine; slug: string; path: string; before: string; row: () => Promise<{ tier: string; frontmatter: Record<string, unknown> }> }) => Promise<void>) {
const home = mkdtempSync(join(tmpdir(), 'gbrain-label-checkout-'));
try {
await withEnv({ GBRAIN_HOME: home, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined }, async () => {
const { engine, close } = await isolatedSharedSkillsEngine(databaseUrl);
try {
- const slug = 'notes/filed-example', checkout = join(home, 'checkout');
+ const slug = 'notes/filed-example', checkout = join(home, 'checkout'), path = join(checkout, slug + '.md');
mkdirSync(join(checkout, 'notes'), { recursive: true });
const before = file(slug);
- writeFileSync(join(checkout, slug + '.md'), before);
+ writeFileSync(path, before);
await engine.executeRaw("INSERT INTO sources (id, name, local_path) VALUES ('source-b', 'source-b', $1) ON CONFLICT (id) DO NOTHING", [checkout]);
expect((await importFromContent(engine, slug, before, { noEmbed: true, sourceId: 'source-b' })).status).toBe('imported');
await engine.transaction(tx => withCoordinatedWrite(tx, ['source-b'], () => withTrustBackfill(tx, () =>
tx.executeRaw("UPDATE pages SET trust_tier='operator_curated', source_path=$2 WHERE source_id='source-b' AND slug=$1", [slug, slug + '.md'])), TEST_WRITE_ATTRIBUTION));
- const { applied } = await previewApply(engine, ['visibility', '--source', 'source-b', '--slug', slug]);
- expect(applied.applied).toBe(1);
- const [row] = await engine.executeRaw<{ tier: string; frontmatter: Record<string, unknown> }>(
- "SELECT trust_tier::text AS tier, frontmatter FROM pages WHERE source_id='source-b' AND slug=$1", [slug]);
- expect(row!.tier).toBe('operator_curated');
- expect(row!.frontmatter.visibility).toBe('private');
- expect(row!.frontmatter.source_kind).toBe('email-example');
- expect(await proposals(engine)).toEqual([]);
- expect(readFileSync(join(checkout, slug + '.md'), 'utf8')).toBe(withLine(before, 'visibility: private'));
- } finally { await disposePersistenceConsumer(engine); await close(); }
+ const row = async () => (await engine.executeRaw<{ tier: string; frontmatter: Record<string, unknown> }>(
+ "SELECT trust_tier::text AS tier, frontmatter FROM pages WHERE source_id='source-b' AND slug=$1", [slug]))[0]!;
+ await fn({ engine, slug, path, before, row });
+ } finally { _resetWriteThroughCacheForTest(); await disposePersistenceConsumer(engine); await close(); }
});
} finally { rmSync(home, { recursive: true, force: true }); }
- }, 180_000);
+ }
+ const slugRepair = (slug: string) => ['visibility', '--source', 'source-b', '--slug', slug];
+
+ test('without managed persistence, a page whose file is in a checkout gets the same label-line splice in its file', () => checkoutBrain(async ({ engine, slug, path, before, row }) => {
+ const { applied } = await previewApply(engine, slugRepair(slug));
+ expect(applied.applied).toBe(1);
+ const stored = await row();
+ expect(stored.tier).toBe('operator_curated');
+ expect(stored.frontmatter.visibility).toBe('private');
+ expect(stored.frontmatter.source_kind).toBe('email-example');
+ expect(await proposals(engine)).toEqual([]);
+ expect(readFileSync(path, 'utf8')).toBe(withLine(before, 'visibility: private'));
+ }), 180_000);
+
+ test('a checkout file holding an edit the database lacks refuses, and neither the file nor the row changes', () => checkoutBrain(async ({ engine, slug, path, before, row }) => {
+ const preview = await repair(engine, slugRepair(slug));
+ const edited = before.replace('Second paragraph.', 'Second paragraph, edited by hand.');
+ writeFileSync(path, edited);
+ const applied = await repair(engine, [...slugRepair(slug), '--apply', '--expect', preview.preview_hash]);
+ expect(applied.applied).toBe(0);
+ expect(applied.failed).toEqual([expect.objectContaining({ item: 'source-b:' + slug, reason: 'source_changed' })]);
+ expect(readFileSync(path, 'utf8')).toBe(edited);
+ expect((await row()).frontmatter.visibility).toBeUndefined();
+ }), 180_000);
+
+ test('with sync.write_through off, the page is held file_backed instead of written to the database alone', () => checkoutBrain(async ({ engine, slug, path, before, row }) => {
+ await engine.setConfig('sync.write_through', 'false');
+ _resetWriteThroughCacheForTest();
+ const { applied } = await previewApply(engine, slugRepair(slug));
+ expect(applied.applied).toBe(0);
+ expect(applied.outcome_items).toEqual([expect.objectContaining({ item: 'source-b:' + slug, outcome: 'file_backed' })]);
+ expect(readFileSync(path, 'utf8')).toBe(before);
+ expect((await row()).frontmatter.visibility).toBeUndefined();
+ }), 180_000);
+
+ test.skipIf(process.getuid?.() === 0)('a file write that fails rolls the database back and holds the page', () => checkoutBrain(async ({ engine, slug, path, before, row }) => {
+ const dir = join(path, '..');
+ chmodSync(dir, 0o555);
+ try {
+ const { applied } = await previewApply(engine, slugRepair(slug));
+ expect(applied.applied).toBe(0);
+ expect(applied.outcome_items).toEqual([expect.objectContaining({ item: 'source-b:' + slug, outcome: 'file_backed' })]);
+ } finally { chmodSync(dir, 0o755); }
+ expect(readFileSync(path, 'utf8')).toBe(before);
+ const stored = await row();
+ expect(stored.frontmatter.visibility).toBeUndefined();
+ expect(stored.tier).toBe('operator_curated');
+ }), 180_000);
});