Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Held facts leave any holding page a rule narrows, with their struck rows; the preview runs the apply's planner and pending moves are reported (GBRA-449)

garrytanc5337d3a66a4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4f472e394e..4fc6f16ec7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,19 +17,19 @@ identifiers and attribution are available in the pre-removal Git revision
### Itemized changes
- `src/core/facts-fence.ts`: `isHoldingSlug` (the shared `memory/unattributed` or any `<folder>/memory/unattributed`), its SQL twin and `folderHoldingSlug`. A folder's holding page reads only entity cells of its own folder; any other is a fence problem.
-- `src/core/facts/held-fact-move.ts`: `holdingHome` replaces `holdsInGit` and names the holding page, or refuses (`page_rule`, `access_unreadable`). `moveHeldFacts` reads every holding page, moves rows into entity pages, and re-homes shared-page rows whose entity a rule now covers; the shared page's row is removed, never struck with the destination.
+- `src/core/facts/held-fact-move.ts`: `holdingHome` replaces `holdsInGit` and names the holding page, or refuses (`page_rule`, `access_unreadable`). `moveHeldFacts` reads every holding page, moves rows into entity pages, and re-homes shared-page rows whose entity a rule now covers; the shared page's row is removed, never struck with the destination. `planHeldMoves` is the one plan the move and the rule preview share: every holding page, in the order the move runs. An entity's struck (withdrawn) held rows leave the holding page with its live rows, removed rather than moved, and an entity with only struck rows gets its own removal. A move still pending when the write wait ends is reported (`pending`, with its request id) and not counted as moved.
- `src/core/persistence/memory-mutations.ts`, `memory-prepare.ts`, `facts-prepare.ts`, `facts-maintenance.ts`, `prepared-maintenance.ts`, `forget-prepare.ts`, `single-prepare.ts`, `page-identity.ts`, `model.ts`, `src/core/facts/*`, `src/core/trust/release-publish.ts`: every fact writer, forget, purge and release treats any holding page as a holding page.
- `src/core/persistence/git-declared.ts`, `verb-errors.ts`: the `facts_lane` refusal for an exact page rule carries a `put_page` fix; through `remember` it keeps the frozen `invalid_params` (and `unavailable` for `access_policy_pending`) with the canonical code, reason and fix.
- `src/core/persistence/coordinator.ts`: a held fact on a database-only folder's holding page reports `write_through: {written: false, skipped: db_only, held_for}` instead of `no_repo_configured`.
-- `src/core/search/private-visibility.ts`: a held fact is also judged by its holding page as a page, so a raw-only rule (`covers_derived: false`) hides it as it hides the page; a fact still on `memory/unattributed` for an entity a rule now covers (a rule synced from Git, until maintenance moves it) reads only for that rule's readers, and for nobody while the rule is pending.
+- `src/core/search/private-visibility.ts`: a held fact is also judged by its holding page as a page, so a raw-only rule (`covers_derived: false`) hides it as it hides the page; a fact still on a holding page for an entity a rule now narrows below that page (a folder rule over `memory/unattributed`, an exact page rule over a folder's holding page; a rule synced from Git, until the move) reads only for that rule's readers, and for nobody while the rule is pending.
- `src/core/entities/resolve.ts`: a holding page under an entity directory (`people/memory/unattributed`) is never an entity page itself.
-- `src/commands/access-rules.ts`: the rule preview lists `held_facts_moving` and the apply moves them (`held_facts: {moved, unmovable}`), for the database and git stores; `gbrain access apply` and `gbrain access resume` move them too. Each listed fact's `to` comes from `heldRowDestination`, the resolution the move itself uses, so a row saved under a bare name shows the page that name resolves to.
-- `src/core/facts/fence-fact-append.ts`, `src/core/persistence/prepared-maintenance.ts`: a held row that leaves the shared page for a page not every reader can read also leaves the page's saved versions, in the same transaction; every other byte of each version is kept, Git history is not rewritten, and the move's write receipt records it (`held_versions_edited`: the rows' fact ids, the row and version counts, where they went). The rule preview counts the rows and versions (`held_versions_editing`). A saved version stored in segments is not edited: the preview names how many (`segmented_versions_not_edited`, and a line saying readers of the shared page's saved versions can still read the moved rows there), and the apply's `held_facts` says `complete: false` with the same words.
-- `src/core/facts/purge.ts`: purge's saved-version redaction moves, unchanged in SQL and transaction, into `rewriteVersionBodies`, which the held-row edit above also calls, so the page body reader ratchet still lists one saved-version reader.
-- `src/commands/sync/perform.ts`, `src/core/cycle/extract-facts.ts`: after a managed sync releases its lease, held facts that a folder rule it applied now covers move at once; the maintenance cycle stays the fallback. Either path warns when the move left a segmented saved version unedited (`HELD_VERSIONS_NOT_EDITED` in the cycle).
+- `src/commands/access-rules.ts`: the rule preview lists `held_facts_moving` and the apply moves them (`held_facts: {moved, unmovable}`), for the database and git stores; `gbrain access apply` and `gbrain access resume` move them too. Each listed fact's `to` comes from `heldRowDestination`, the resolution the move itself uses, so a row saved under a bare name shows the page that name resolves to. The preview now runs the move's own planner: it lists every row the apply moves (`from` and `to`, and `because: its page exists` for a row that moves only because its entity's page now exists), the struck rows that leave with them (`held_struck_rows_leaving`), and per page the rows and versions the receipts will record (`held_versions_editing.pages`: the versions carrying them now plus the one each move saves). The apply reports a pending move as incomplete with its request id.
+- `src/core/facts/fence-fact-append.ts`, `src/core/persistence/prepared-maintenance.ts`: a held row that leaves a holding page (the shared page or a folder's) for a page not every reader of it can read also leaves that page's saved versions, with the entity's struck rows, in the same transaction; every other byte of each version is kept, Git history is not rewritten, and the move's write receipt records it (`held_versions_edited`: the rows' fact ids, the row and version counts, where they went). The rule preview counts the rows and versions (`held_versions_editing`). A saved version stored in segments is not edited: the preview names how many per page (`segmented_versions_not_edited`, and a line saying readers of that page's saved versions can still read the moved rows there), and the apply's `held_facts` says `complete: false` with the same words (`segmented_pages`). A saved version with no timeline keeps a NULL timeline.
+- `src/core/facts/purge.ts`: purge's saved-version redaction moves, unchanged in SQL and transaction, into `rewriteVersionBodies` (its `keepNullTimeline` flag, which purge does not pass, writes a NULL timeline back as NULL for the held-row edit), which the held-row edit above also calls, so the page body reader ratchet still lists one saved-version reader.
+- `src/commands/sync/perform.ts`, `src/core/cycle/extract-facts.ts`: after a managed sync releases its lease, held facts that a rule it applied narrows below their holding page's readers move at once (one query decides, and nothing is due when nothing changed); the maintenance cycle stays the fallback. Running it after the lease only spares a follower sync the wait: the lease is re-entrant and the move's writes are not sync rows. Either path names the page when the move left a segmented saved version unedited (`HELD_VERSIONS_NOT_EDITED` in the cycle) or is still pending (`HELD_FACT_PENDING`).
- `src/core/repair/facts-home.ts`, `src/core/facts/facts-home.ts`: `gbrain repair facts-home` writes a ruled entity's fact to its folder's page; `folder_restricted` now means only `page_rule` or `access_unreadable`.
- Docs: `git-canonical.md`, `entity-scoped-facts.md`, `access-designations.md`, `repair.md`, `write-refusals.md`, `memory-boundaries.md`, `MEMORY_VERBS_v1.md`, `error-codes.md` (regenerated).
-- Tests: new `test/folder-holding-page-gst2492.test.ts` (held in Git before the reply and kept by a rebuild from a clone; three nested rules plus a pending one; no existence leak on get_page, search, query, recall, list_pages and find_pages; a raw-only rule; the rule apply's preview and move; the owner with the opt-in on and off; the page-rule and unreadable refusals locally and over MCP; database-only folders; background writers and repair; non-strict and repo-less unchanged; a segmented saved version named by the preview and reported incomplete by the apply, the sync path and maintenance; the preview's destination for a bare-name row equal to where the apply puts it); updated GST-2492 suites; PGLite and Postgres.
+- Tests: new `test/folder-holding-page-gst2492.test.ts` (held in Git before the reply and kept by a rebuild from a clone; three nested rules plus a pending one; no existence leak on get_page, search, query, recall, list_pages and find_pages; a raw-only rule; the rule apply's preview and move; the owner with the opt-in on and off; the page-rule and unreadable refusals locally and over MCP; database-only folders; background writers and repair; non-strict and repo-less unchanged; a segmented saved version named by the preview and reported incomplete by the apply, the sync path and maintenance; the preview's destination for a bare-name row equal to where the apply puts it; an exact page rule over a folder-held row, by CLI and by sync; the preview equal to the apply and its receipts; struck rows and a struck-only entity; a pending move; a NULL timeline kept); updated GST-2492 suites; PGLite and Postgres.
## [0.60.699.0] - 2026-11-12
diff --git a/docs/architecture/system-of-record.md b/docs/architecture/system-of-record.md
index 5eb36312a0..e706c57dea 100644
--- a/docs/architecture/system-of-record.md
+++ b/docs/architecture/system-of-record.md
@@ -264,7 +264,7 @@ or a physical projection that leaves attribution untouched):
- `src/core/facts/forget.ts` (4): the legacy fence expiry, withdrawal and strike-through each run in `maintenanceTransaction` (nested inside a caller's coordinated write, they keep its actor).
- `src/core/facts/ontology-rekey.ts` (1): B-10's duplicate-observation drop runs in its caller's transaction immediately before the caller's re-key: the rename's `maintenanceTransaction`, the `relink_facts` publication, the phantom redirect's fact move and `repair facts-rehome`'s move; every caller is attributed.
- `src/core/facts/proposal-supersede.ts` (4): unmanaged `decide` proposal accept and undo run in one `maintenanceTransaction` each; managed brains publish a `decide_proposal` request.
-- `src/core/facts/purge.ts` (3): `purge_fact` rewrites purged pages' bodies, redacts their versions and replaces those versions' change reasons with `[purged]` inside `withCoordinatedWrite` with the purge request's attribution. Its saved-version rewrite (`rewriteVersionBodies`) also removes moved held rows from the shared holding page's saved versions (`heldRowsInVersions` in `fence-fact-append.ts`), inside the held-move publication's after-effects, attributed to the move request.
+- `src/core/facts/purge.ts` (3): `purge_fact` rewrites purged pages' bodies, redacts their versions and replaces those versions' change reasons with `[purged]` inside `withCoordinatedWrite` with the purge request's attribution. Its saved-version rewrite (`rewriteVersionBodies`) also removes moved held rows from the saved versions of the holding page they leave (`heldRowsInVersions` in `fence-fact-append.ts`), inside the held-move publication's after-effects, attributed to the move request.
- `src/core/facts/relink-publish.ts` (2): `relink_facts` request preparer.
- `src/core/facts/unfenced-facts.ts` (1): the cycle and v0.32.2 fence of `row_num`-NULL facts: a maintenance request on managed brains; the unmanaged row-number stamp runs in `maintenanceTransaction` (the body mirror goes through `facts/file-body-guard.ts`).
- `src/core/facts/withdrawal.ts` (1): runs inside the `forget` request's coordinated write.
@@ -301,7 +301,7 @@ or a physical projection that leaves attribution untouched):
- `src/core/persistence/memory-prepare.ts` (2): `remember` request preparer; the fence row and its facts row go through `prepareFenceFactAppend`.
- `src/core/persistence/page-append.ts` (1): segmented `append_page` / `edit_page` request preparer; the splice versions the page inside its request's publication.
- `src/core/persistence/page-prepare.ts` (12): page request preparer (including the restore of a segmented page over 24 MiB, which flips `deleted_at` without re-serializing, and the tag flip of a segmented page, which versions it and changes its tag rows and `content_hash` without re-serializing).
-- `src/core/persistence/prepared-maintenance.ts` (4): managed maintenance request preparer (consolidation closes an unfenced fact in the database and a fenced one from its published fence cell).
+- `src/core/persistence/prepared-maintenance.ts` (5): managed maintenance request preparer (consolidation closes an unfenced fact in the database and a fenced one from its published fence cell; a held move clears the row number of the struck held rows it removes from their holding page).
- `src/core/persistence/semantic-pages.ts` (1): `add_timeline_entry` request preparer.
- `src/core/persistence/sync-image.ts` (2): managed sync image request preparer; a Git rename retires the old page inside the same publication.
- `src/core/persistence/sync-prepare.ts` (4): managed sync request preparer.
diff --git a/docs/guides/git-canonical.md b/docs/guides/git-canonical.md
index 8938e77eee..6d83cb4fa9 100644
--- a/docs/guides/git-canonical.md
+++ b/docs/guides/git-canonical.md
@@ -194,19 +194,26 @@ Every write goes through the same door, whoever sends it:
of its own apply (`gbrain access rule add` previews them as
`held_facts_moving`; `gbrain access apply` and `gbrain access resume` move
them too). A rule that arrives through a sync of the policy file moves them
- as soon as that sync releases its lease, so for the seconds the sync pass
- takes the row is still in the shared page's body (its fact already reads only
- for the rule's readers); if the process stops in between, the next
- maintenance cycle moves them. The move also removes those rows from the
- shared page's saved versions in the database (the rule's preview counts
- them, and the move's write receipt records which rows, how many versions and
- where they went). A saved version stored in segments (a shared page over
- 1 MiB with `pages.segmented_storage` on) is not edited: the preview names how
- many there are (`segmented_versions_not_edited`), the apply's result says it
- is incomplete (`complete: false`), and readers of the shared page's saved
- versions can still read the moved rows in up to that many versions. The
- preview names each held fact's destination as the move resolves it, so a row
- saved under a bare name shows the page that name resolves to. Git history is never rewritten: the shared page's earlier
+ as soon as that sync releases its lease (an exact page rule on an entity
+ held on its folder's page moves that row into the entity's page the same
+ way), so for the seconds the sync pass takes the row is still in the holding
+ page's body (its fact already reads only for the rule's readers); if the
+ process stops in between, the next maintenance cycle moves them. The move
+ also removes those rows, and the struck (withdrawn) rows of the same
+ entities, from the holding page it leaves and from that page's saved
+ versions in the database (the rule's preview counts them per page, and the
+ move's write receipt records which rows, how many versions and where they
+ went). A saved version stored in segments (a holding page over 1 MiB with
+ `pages.segmented_storage` on) is not edited: the preview names how many
+ there are (`segmented_versions_not_edited`), the apply's result says it is
+ incomplete (`complete: false`), and readers of that page's saved versions
+ can still read the moved rows in up to that many versions. A move still
+ pending when the apply stops waiting is reported incomplete the same way,
+ with its request id, and is not counted as moved. The preview lists every
+ held fact the apply moves, with its destination as the move resolves it, so
+ a row saved under a bare name shows the page that name resolves to, and a
+ row that moves only because its entity's page now exists says so
+ (`because`). Git history is never rewritten: the holding page's earlier
commits keep the row as it was before the rule. An entity under an exact page rule (a rule on the
entity's own slug) has no holding page with its readers: the fact is refused
with [`git_home_required`](write-refusals.md#git_home_required) (reason
diff --git a/src/commands/access-rules.ts b/src/commands/access-rules.ts
index e25818ea7e..f462c14cdf 100644
--- a/src/commands/access-rules.ts
+++ b/src/commands/access-rules.ts
@@ -121,9 +121,11 @@ export interface RulePreview {
* GST-2492: facts a strict source holds on memory/unattributed for an entity this change starts covering, and the page
* the apply moves each to (its folder's holding page, or the entity's own page, created for an exact page rule).
*/
- held_facts_moving: Array<{ fact_id: number; entity_slug: string; to: string }>;
+ held_facts_moving: Array<{ fact_id: number; entity_slug: string; from: string; to: string; because?: 'its page exists' }>;
+ /** Struck (withdrawn) held rows of those entities, removed from their holding page with them. */
+ held_struck_rows_leaving: number;
/** The rows of those facts in the shared page's saved versions, and those versions, the apply removes them from (database only; the version the move itself saves is edited too). */
- held_versions_editing: { rows: number; versions: number; segmented_versions_not_edited?: number };
+ held_versions_editing: { rows: number; versions: number; pages?: Array<{ slug: string; rows: number; versions: number; segmented_versions_not_edited?: number }>; segmented_versions_not_edited?: number };
}
async function previewRules(engine: BrainEngine, sourceId: string, store: AccessStore, persisted: boolean, desired: FolderRule[]): Promise<RulePreview> {
@@ -149,12 +151,9 @@ async function previewRules(engine: BrainEngine, sourceId: string, store: Access
}
const credentials: RulePreview['credentials_losing'] = [];
for (const m of losing) for (const c of await boundCredentials(engine, m)) credentials.push({ member: m, kind: c.kind, name: c.name });
- // A narrowing applies at once, so the held facts it covers leave the world-readable holding page in the same apply.
- const heldRows = await engine.executeRaw<{ id: number; entity_slug: string; fact: string }>(`SELECT f.id::int AS id, f.entity_slug, f.fact
- FROM facts f WHERE f.source_id=$1 AND f.source_markdown_slug=$2 AND f.row_num IS NOT NULL AND f.expired_at IS NULL AND f.dimension IS NULL
- AND f.entity_slug IS NOT NULL AND f.entity_slug <> $2 ORDER BY f.id`, [sourceId, UNATTRIBUTED_MEMORY_SLUG]);
- // C4: each row's `to` is where the apply's move puts it (heldRowDestination), with the desired rules deciding a page-less entity's home.
- const { heldRowDestination, holdingHome } = await import('../core/facts/held-fact-move.ts');
+ // A narrowing applies at once, so the held facts it covers leave their holding page in the same apply. The preview runs
+ // the apply's own planner (planHeldMoves, every holding page), with the desired rules deciding a page-less entity's home.
+ const { planHeldMoves, holdingHome } = await import('../core/facts/held-fact-move.ts');
const covers = (slug: string) => cls.target.some(rule => ruleCovers(slug, rule.prefix));
const desiredHome = async (key: string) => {
const now = await holdingHome(engine, sourceId, key);
@@ -162,18 +161,29 @@ async function previewRules(engine: BrainEngine, sourceId: string, store: Access
if (cls.target.some(rule => rule.prefix === key)) return { refused: 'page_rule' as const };
return { slug: covers(key) ? folderHoldingSlug(key) : UNATTRIBUTED_MEMORY_SLUG };
};
- const destinations = new Map<string, string | null>();
- for (const key of new Set(heldRows.map(row => row.entity_slug))) {
- const dest = await heldRowDestination(engine, sourceId, key, UNATTRIBUTED_MEMORY_SLUG, desiredHome);
- destinations.set(key, dest && 'slug' in dest && covers(dest.slug) ? dest.slug : null);
+ const plan = await planHeldMoves(engine, sourceId, { home: desiredHome, hidden: covers });
+ // A row the apply moves only because its entity's page now exists (as the next maintenance cycle would) says so.
+ const moving = plan.groups.flatMap(g => g.group.map(row => ({ fact_id: Number(row.id), entity_slug: row.entity_slug!, from: g.from, to: g.slug,
+ ...(g.kind === 'page' && !covers(g.slug) ? { because: 'its page exists' as const } : {}) })));
+ // A2: each move whose note is `moved` also removes its rows (and the entity's struck rows) from the saved versions of the
+ // page it leaves (database only; Git history stays): the versions carrying them now, plus the one each move on that page
+ // saves before it (the k-th move there finds its rows in k such versions).
+ const pages = new Map<string, { slug: string; rows: number; versions: number; segmented_versions_not_edited?: number }>(), moves = new Map<string, number>();
+ for (const g of plan.groups) {
+ const k = (moves.get(g.from) ?? 0) + 1;
+ moves.set(g.from, k);
+ if (g.note !== 'moved') continue;
+ const keys = [...g.group.map(row => ({ entity: row.entity_slug!, claim: row.fact })), ...g.struck];
+ const v = await heldRowsInVersions(engine, sourceId, g.from, keys, false);
+ const page = pages.get(g.from) ?? { slug: g.from, rows: 0, versions: 0 };
+ pages.set(g.from, { ...page, rows: page.rows + v.rows + k * keys.length, versions: page.versions + v.versions + k, ...(v.segmented ? { segmented_versions_not_edited: v.segmented } : {}) });
}
- const covered = heldRows.filter(row => destinations.get(row.entity_slug));
- const moving = covered.map(row => ({ fact_id: Number(row.id), entity_slug: row.entity_slug, to: destinations.get(row.entity_slug)! }));
- // A2: the apply also removes those rows from the shared page's saved versions (database only; Git history stays).
- const versions = await heldRowsInVersions(engine, sourceId, UNATTRIBUTED_MEMORY_SLUG, covered.map(row => ({ entity: row.entity_slug, claim: row.fact })), false);
+ const edits = [...pages.values()], segmented = Math.max(0, ...edits.map(p => p.segmented_versions_not_edited ?? 0));
return { source_id: sourceId, store, store_persisted: persisted, expect, desired, changes: cls.changes, held: cls.held, matched_pages: matched,
unknown_readers: unknown, members_losing: losing, credentials_losing: credentials, held_facts_moving: moving,
- held_versions_editing: { rows: versions.rows, versions: versions.versions, ...(versions.segmented ? { segmented_versions_not_edited: versions.segmented } : {}) } };
+ held_struck_rows_leaving: plan.groups.reduce((n, g) => n + (g.note === 'moved' ? g.struck.length : 0), 0),
+ held_versions_editing: { rows: edits.reduce((n, p) => n + p.rows, 0), versions: edits.reduce((n, p) => n + p.versions, 0),
+ ...(edits.length ? { pages: edits } : {}), ...(segmented ? { segmented_versions_not_edited: segmented } : {}) } };
}
function previewLines(p: RulePreview, rerun: string): string[] {
@@ -184,9 +194,11 @@ function previewLines(p: RulePreview, rerun: string): string[] {
...(p.unknown_readers.length ? [` Unknown readers (no such member or group; they match nobody): ${p.unknown_readers.join(', ')}`] : []),
...(p.members_losing.length ? [` Members losing access: ${p.members_losing.join(', ')}`] : []),
...(p.credentials_losing.length ? [` Credentials losing access: ${p.credentials_losing.map(c => `${c.kind} ${c.name} (${c.member})`).join(', ')}`] : []),
- ...(p.held_facts_moving.length ? [` Held facts leaving ${UNATTRIBUTED_MEMORY_SLUG} with this change: ${p.held_facts_moving.length} (${p.held_facts_moving.slice(0, 10).map(m => `fact ${m.fact_id} for ${m.entity_slug} to ${m.to}${m.to === m.entity_slug ? ' (its page)' : ''}`).join(', ')}${p.held_facts_moving.length > 10 ? ', ...' : ''})`] : []),
- ...(p.held_versions_editing.versions ? [` Their rows also leave ${p.held_versions_editing.versions} saved version(s) of ${UNATTRIBUTED_MEMORY_SLUG} (${p.held_versions_editing.rows} row(s); database only, Git history is not rewritten)`] : []),
- ...(p.held_versions_editing.segmented_versions_not_edited ? [` Not edited: ${p.held_versions_editing.segmented_versions_not_edited} saved version(s) of ${UNATTRIBUTED_MEMORY_SLUG} are stored in segments, which this apply cannot edit. ${segmentedConsequence(p.held_versions_editing.segmented_versions_not_edited)} The apply will report itself incomplete.`] : []),
+ ...(p.held_facts_moving.length ? [` Held facts leaving their holding page with this change: ${p.held_facts_moving.length} (${p.held_facts_moving.slice(0, 10).map(m => `fact ${m.fact_id} for ${m.entity_slug} from ${m.from} to ${m.to}${m.to === m.entity_slug ? ' (its page)' : ''}${m.because ? `, because ${m.because}` : ''}`).join(', ')}${p.held_facts_moving.length > 10 ? ', ...' : ''})`] : []),
+ ...(p.held_struck_rows_leaving ? [` ${p.held_struck_rows_leaving} struck (withdrawn) held row(s) of those entities leave their holding page with them`] : []),
+ ...(p.held_versions_editing.pages ?? []).flatMap(e => [
+ ...(e.versions ? [` Their rows also leave ${e.versions} saved version(s) of ${e.slug} (${e.rows} row(s); database only, Git history is not rewritten)`] : []),
+ ...(e.segmented_versions_not_edited ? [` Not edited: ${e.segmented_versions_not_edited} saved version(s) of ${e.slug} are stored in segments, which this apply cannot edit. ${segmentedConsequence(e.slug, e.segmented_versions_not_edited)} The apply will report itself incomplete.`] : [])]),
'Pages under no rule are unchanged; unbound credentials and stdio read no page under a rule.',
`Nothing written. To approve, add --yes --expect ${p.expect} (${rerun}).`,
];
@@ -206,16 +218,17 @@ export interface EditResult {
git?: GitPolicyReceipt;
note?: string;
/** GST-2492: held facts this apply moved off memory/unattributed to a page the new rules cover, and those that could not move. */
- held_facts?: { moved: number; unmovable: Array<{ slug: string; fact_ids: number[]; reason: string }>; complete?: false; segmented_versions_not_edited?: number };
+ held_facts?: { moved: number; unmovable: Array<{ slug: string; fact_ids: number[]; reason: string }>; complete?: false; segmented_versions_not_edited?: number;
+ segmented_pages?: Array<{ slug: string; versions: number }>; pending?: Array<{ slug: string; from: string; request_id: string }> };
}
-/** GST-2492 (B): what an unedited segmented saved version of the shared page leaves readable. */
-const segmentedConsequence = (n: number) => `Readers of ${UNATTRIBUTED_MEMORY_SLUG}'s saved versions can still read the moved rows in up to ${n} of those version(s).`;
+/** GST-2492 (B): what an unedited segmented saved version of a holding page leaves readable. */
+const segmentedConsequence = (slug: string, n: number) => `Readers of ${slug}'s saved versions can still read the moved rows in up to ${n} of those version(s).`;
-/** The words of a held-fact move that left segmented saved versions of the shared page unedited. */
+/** The words of a held-fact move left incomplete: segmented saved versions of the page it left unedited, or a move still pending. */
function heldIncompleteLines(held: EditResult['held_facts']): string[] {
- const n = held?.segmented_versions_not_edited;
- return n ? [` Incomplete: the held facts moved, but ${n} saved version(s) of ${UNATTRIBUTED_MEMORY_SLUG} are stored in segments and were not edited. ${segmentedConsequence(n)}`] : [];
+ return [...(held?.segmented_pages ?? []).map(p => ` Incomplete: the held facts moved, but ${p.versions} saved version(s) of ${p.slug} are stored in segments and were not edited. ${segmentedConsequence(p.slug, p.versions)}`),
+ ...(held?.pending ?? []).map(p => ` Incomplete: the move of held facts off ${p.from} to ${p.slug} is accepted and still pending (request ${p.request_id}; gbrain write-request ${p.request_id} shows it); until it commits they read as they did on ${p.from}.`)];
}
/**
@@ -232,12 +245,13 @@ async function withHeldFactsMoved(engine: BrainEngine, result: EditResult): Prom
/** The held-fact move after any rule apply (edit, approved widening, resume); undefined when nothing was held. */
async function heldFactsMoved(engine: BrainEngine, sourceId: string): Promise<EditResult['held_facts']> {
const { moveHeldFacts } = await import('../core/facts/held-fact-move.ts');
- const moved = await moveHeldFacts(engine, sourceId).catch((error: unknown) =>
- ({ moved: 0, rehomed: 0, segmented_versions_not_edited: 0, unmovable: [{ slug: UNATTRIBUTED_MEMORY_SLUG, fact_ids: [], reason: (error instanceof Error ? error.message : String(error)).slice(0, 300) }] }));
- if (!moved.moved && !moved.rehomed && !moved.unmovable.length) return undefined;
+ const moved = await moveHeldFacts(engine, sourceId).catch((error: unknown) => ({ moved: 0, rehomed: 0, segmented_versions_not_edited: 0, segmented_pages: [], pending: [],
+ unmovable: [{ slug: UNATTRIBUTED_MEMORY_SLUG, fact_ids: [], reason: (error instanceof Error ? error.message : String(error)).slice(0, 300) }] }));
+ if (!moved.moved && !moved.rehomed && !moved.unmovable.length && !moved.pending.length) return undefined;
const segmented = moved.segmented_versions_not_edited;
return { moved: moved.moved + moved.rehomed, unmovable: moved.unmovable.map(({ slug, fact_ids, reason }) => ({ slug, fact_ids, reason })),
- ...(segmented ? { complete: false as const, segmented_versions_not_edited: segmented } : {}) };
+ ...(segmented || moved.pending.length ? { complete: false as const } : {}),
+ ...(segmented ? { segmented_versions_not_edited: segmented, segmented_pages: moved.segmented_pages } : {}), ...(moved.pending.length ? { pending: moved.pending } : {}) };
}
/** Writes a desired rulebook through the source's store (after the caller's preview) and reports the result. */
diff --git a/src/commands/sync/perform.ts b/src/commands/sync/perform.ts
index 4cd0a97410..df9e7aeb0e 100644
--- a/src/commands/sync/perform.ts
+++ b/src/commands/sync/perform.ts
@@ -205,10 +205,13 @@ async function performManagedBranch(engine: BrainEngine, outer: SyncOpts): Promi
: `[sync] following ${who}: ${done}.`);
},
}, work);
- // GST-2492 (B2): the lease is released; a folder rule this sync applied moves the held facts it covers now.
- const held = currentDrainLease(sourceId) ? null : await (await import('../../core/facts/held-fact-move.ts')).moveRuledSharedHeld(engine, sourceId)
+ // GST-2492 (B2): a rule this sync applied moves the held facts it narrows now. It runs once the lease is released only so
+ // a follower sync does not wait on the move: the lease is re-entrant and the move's maintenance writes are not sync rows
+ // (no claim waits on the lease), so running it inside would not deadlock either.
+ const moves = await import('../../core/facts/held-fact-move.ts');
+ const held = currentDrainLease(sourceId) ? null : await moves.moveRuledSharedHeld(engine, sourceId)
.catch((error: unknown) => { serr(`[sync] held facts under a new folder rule wait for the next maintenance cycle: ${error instanceof Error ? error.message : String(error)}`); return null; });
- if (held?.segmented_versions_not_edited) serr(`[sync] held facts moved under a new folder rule, incomplete: ${held.segmented_versions_not_edited} saved version(s) of memory/unattributed are stored in segments and were not edited; readers of its saved versions can still read the moved rows in up to ${held.segmented_versions_not_edited} of them.`);
+ for (const w of held ? moves.heldMoveIncomplete(held) : []) serr(`[sync] held facts moved under a new folder rule, incomplete: ${w.text}`);
if (held?.unmovable.length) serr(`[sync] ${held.unmovable.length} group(s) of held facts could not move yet; the next gbrain dream retries (gbrain repair facts-home --source ${sourceId} lists them).`);
const tailed = skips.has('sync_tail') ? drained : await withSyncTail(engine, sourceId, drained, { signal: outer.signal, deadlineAtMs: outer.deadlineAtMs });
const healed = skips.has('slug_heal') ? tailed : await healAfterManagedSync(engine, outer, tailed);
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 1ecabf96af..d58d2a81c9 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1563,7 +1563,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.693.0', id: 'member_save_withdrawn_scope_gst2346', text: 'A remote `remember` onto a member\'s own page (`memory/members/<id>`) is refused `fact_withdrawn` only when that member could read what was withdrawn: a fact on its own page, its own copy withdrawn by the brain host, or for the brain owner a fact it reads. A claim withdrawn by the brain host or the owner that the member never read no longer refuses its save: the fact saves as the member\'s own active row with the same reply as a new claim. A schema migration makes the database insert guards mark a row on a member page only by that page\'s own withdrawals; a withdrawal still expires matching rows on member pages when it is made, and strikes them in the page\'s file, so an import of a member page\'s file no longer marks a row withdrawn by a withdrawal of another subject. The same holds for each item of a `remember` batch (`items`), a replay with the same `request_id`, a `replaces` and the write receipt (`get_write_request`). Trusted local saves keep the check they had.' },
{ since: '0.60.694.0', id: 'owner_labels_guarded_gst2521', text: 'Labels the owner sets with `gbrain repair visibility` (or its `--readers` setter, or `gbrain repair private-labels`) now raise the page\'s label guard to operator_curated, so a later local agent write at the page\'s own tier that drops or widens them is held like a write over an owner page, with a `lower_page` item. A local write below operator_curated whose `readable_by` would leave the brain owner out of a page the owner reads now publishes with the owner kept in the readers (the rest of the narrowing applies), and its item records the requested readers. Accepting such an item (`gbrain trust confirm tp<id>`) on a page whose own tier is an agent\'s writes only the labels and keeps the agent\'s tier; on an owner page it still endorses the edit at the owner\'s tier. The guard is stored in the database (`page_label_guards`) and set only by label repairs run after the upgrade, so labels set earlier, and a managed Git brain rebuilt from a clone, start unguarded; re-running `gbrain repair visibility --slug` or `--readers` on a page that already has those labels raises the guard without changing them. The owner\'s own label writes, synced owner edits, agent narrowing that keeps the owner, and brains with `access.owner_reads_restricted` on are unchanged.' },
{ since: '0.60.694.0', id: 'page_label_widening_held_gst2518', text: 'A local agent write (`put_page`, `capture`, `edit_page`, `append_page`, `revert_version`, `restore_page`) less trusted than a page that drops or widens its `visibility`, `access`, `confidentiality` or `readable_by` now publishes with the page\'s earlier labels kept, in the database and in the committed file, and its receipt lists them under `privacy_labels_kept`; so does a maintenance job\'s derived page publication, and a page whose tier is still `unknown` counts as the owner\'s. A soft delete no longer lowers the page\'s tier. Before, the page became readable to remote callers and other members at once, and only a `lower_page` item waited for the owner. That item now records the requested labels: `gbrain trust confirm tp<id>` applies them if the page has not changed since, `gbrain trust drop tp<id>` keeps the earlier ones, and undoing a confirm restores them while the page is unchanged since. Narrowing writes, label-neutral writes, writers at or above the page\'s tier, synced owner edits and `gbrain repair visibility` are unchanged.' },
- { since: 'TBD', id: 'folder_holding_page_gst2492', text: 'On a source whose pages are canonical in Git (`canonical: git`), a fact for an entity with no page under a folder access rule is no longer kept in the database only: it is held on the holding page of the entity\'s folder (`partners/memory/unattributed` for `partners/acme-example`), which every rule covering the entity covers by path, so it is in Git (or database-only where the folder is, under `storage.db_only` or a path Git ignores) with exactly the readers the entity\'s page would have. The reply names that `page` and `write_through.held_for`. `gbrain access rule add` previews the held facts a new rule covers (`held_facts_moving`) and its apply moves them off `memory/unattributed` (`held_facts`), as do `gbrain access apply`, `gbrain access resume` and a sync that applies a rule from Git (right after it releases its lease; maintenance is the fallback), and removes their rows from the shared page\'s saved versions in the database (`held_versions_editing` in the preview, `held_versions_edited` on the move\'s write receipt); Git history is not rewritten. A saved version of `memory/unattributed` stored in segments is not edited: the preview names how many (`segmented_versions_not_edited`), the apply\'s `held_facts` says `complete: false`, and readers of that page\'s saved versions can still read the moved rows in up to that many versions. A held fact is now also hidden from a caller who cannot read its holding page, even under a rule with `covers_derived: false`. `gbrain repair facts-home` writes such facts to their folder\'s page and lists as `folder_restricted` only an exact page rule (`page_rule`) or unreadable rules (`access_unreadable`). A `remember` for a page-less entity under an exact page rule now refuses `git_home_required` (reason `facts_lane`, frozen `error` `invalid_params`) with a fix that creates the page, and one whose access rules this database role cannot read refuses `access_policy_pending` (`next: wait`); both wrote the fact to the database before. An existing page whose slug ends in `/memory/unattributed` is now read as a holding page: when its Facts table is next read (a sync or an extract of the page), a row with no `entity` cell becomes a fact with no entity instead of a fact about that page, a row whose `entity` cell names an entity in the page\'s own folder becomes that entity\'s held fact (and moves into the entity\'s page once it exists), a row naming an entity of another folder is a fence problem, and the page itself is never resolved as an entity page. Sources that are not strict and brains with no Git repository are unchanged.' },
+ { since: 'TBD', id: 'folder_holding_page_gst2492', text: 'On a source whose pages are canonical in Git (`canonical: git`), a fact for an entity with no page under a folder access rule is no longer kept in the database only: it is held on the holding page of the entity\'s folder (`partners/memory/unattributed` for `partners/acme-example`), which every rule covering the entity covers by path, so it is in Git (or database-only where the folder is, under `storage.db_only` or a path Git ignores) with exactly the readers the entity\'s page would have. The reply names that `page` and `write_through.held_for`. `gbrain access rule add` previews the held facts a new rule covers (`held_facts_moving`) and its apply moves them off their holding page (`held_facts`; the preview lists every row the apply moves, a row moving only because its entity\'s page exists with `because`), as do `gbrain access apply`, `gbrain access resume` and a sync that applies a rule from Git (right after it releases its lease; maintenance is the fallback), and removes their rows, with the struck (withdrawn) rows of those entities, from that page and its saved versions in the database (`held_versions_editing` per page in the preview, `held_versions_edited` on the move\'s write receipt); Git history is not rewritten. A saved version of a holding page stored in segments is not edited: the preview names how many (`segmented_versions_not_edited`), the apply\'s `held_facts` says `complete: false`, and readers of that page\'s saved versions can still read the moved rows in up to that many versions. A move still pending when the write wait ends is reported with its request id (`pending`, `complete: false`, `HELD_FACT_PENDING`) and not counted as moved. A held fact is now also hidden from a caller who cannot read its holding page, even under a rule with `covers_derived: false`. `gbrain repair facts-home` writes such facts to their folder\'s page and lists as `folder_restricted` only an exact page rule (`page_rule`) or unreadable rules (`access_unreadable`). A `remember` for a page-less entity under an exact page rule now refuses `git_home_required` (reason `facts_lane`, frozen `error` `invalid_params`) with a fix that creates the page, and one whose access rules this database role cannot read refuses `access_policy_pending` (`next: wait`); both wrote the fact to the database before. An existing page whose slug ends in `/memory/unattributed` is now read as a holding page: when its Facts table is next read (a sync or an extract of the page), a row with no `entity` cell becomes a fact with no entity instead of a fact about that page, a row whose `entity` cell names an entity in the page\'s own folder becomes that entity\'s held fact (and moves into the entity\'s page once it exists), a row naming an entity of another folder is a fence problem, and the page itself is never resolved as an entity page. Sources that are not strict and brains with no Git repository are unchanged.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/src/core/cycle/extract-facts.ts b/src/core/cycle/extract-facts.ts
index c0bfea9762..30641f5354 100644
--- a/src/core/cycle/extract-facts.ts
+++ b/src/core/cycle/extract-facts.ts
@@ -82,7 +82,7 @@ import {
} from '../facts/supersede-resolve.ts';
import { writeReceipt } from '../extract/receipt-writer.ts';
import { fenceUnfencedFacts, isFenceHold, planUnfencedFacts } from '../facts/unfenced-facts.ts';
-import { moveHeldFacts } from '../facts/held-fact-move.ts';
+import { heldMoveIncomplete, moveHeldFacts } from '../facts/held-fact-move.ts';
import { classifyRunStop, upsertExtractRollup } from '../extract/rollup-writer.ts';
import { factsFenceView } from '../facts-fence.ts';
import { fenceReadOf, publishFenceGeneration, readFenceBlocks, FACT_FENCE_KIND, type FenceRead } from '../generations/fence.ts';
@@ -860,12 +860,12 @@ export async function runExtractFacts(
result.warnings.push(`FACTS_FENCE_FAILED: ${(e instanceof Error ? e.message : String(e)).slice(0, 300)}`);
}
// GST-2492: facts a strict source holds move into their entity page once it exists, and a fact held on
- // memory/unattributed whose entity a folder rule now covers moves to that folder's holding page.
+ // memory/unattributed whose entity a folder rule now covers moves to that folder's holding page. A move still pending is reported, not counted.
try {
const held = await moveHeldFacts(engine, sourceId);
if (held.moved + held.rehomed) result.heldFactsMoved = held.moved + held.rehomed;
result.pagesFailed += held.write_errors;
- result.warnings.push(...held.unmovable.map(row => `HELD_FACT_UNMOVABLE: ${row.slug} facts ${row.fact_ids.join(',')} (${row.reason})`), ...(held.segmented_versions_not_edited ? [`HELD_VERSIONS_NOT_EDITED: ${held.segmented_versions_not_edited} saved version(s) of memory/unattributed are stored in segments and were not edited; readers of its saved versions can still read the moved rows in up to ${held.segmented_versions_not_edited} of them.`] : []));
+ result.warnings.push(...held.unmovable.map(row => `HELD_FACT_UNMOVABLE: ${row.slug} facts ${row.fact_ids.join(',')} (${row.reason})`), ...heldMoveIncomplete(held).map(w => `${w.code}: ${w.text}`));
} catch (e) {
fenceStepFailed ||= !isFenceHold(e);
result.warnings.push(`HELD_FACT_UNMOVABLE: ${(e instanceof Error ? e.message : String(e)).slice(0, 300)}`);
diff --git a/src/core/facts/fence-fact-append.ts b/src/core/facts/fence-fact-append.ts
index 21db05acb6..7e269b52a4 100644
--- a/src/core/facts/fence-fact-append.ts
+++ b/src/core/facts/fence-fact-append.ts
@@ -202,8 +202,9 @@ export async function prepareFenceFactAppend(engine: BrainEngine, row: WriteRequ
* row is gone (nothing in a file to strike). The page write is prepared unprojected, as remember's own is.
*/
export async function prepareFenceRowRetirement(engine: BrainEngine, row: WriteRequest, config: GBrainConfig, slug: string,
- retire: { rowNum: number | readonly number[]; note: string; validUntil: Date | null; forgotten?: boolean; remove?: boolean }, signal?: AbortSignal): Promise<CompanionPage | null> {
- const retired = new Set([retire.rowNum].flat());
+ retire: { rowNum: number | readonly number[]; note: string; validUntil: Date | null; forgotten?: boolean; remove?: boolean; drop?: readonly number[] }, signal?: AbortSignal):
+ Promise<(CompanionPage & { mutation: PreparedMutation }) | null> {
+ const retired = new Set([retire.rowNum].flat()), drop = new Set(retire.drop ?? []);
const snapshot = await engine.readPageSnapshot(slug, { sourceId: row.source_id, includeDeleted: true });
if (!snapshot || snapshot.page.deleted_at) return null;
if (segmentedOverCeiling(snapshot.page)) throw pageBodyOverCeilingError(snapshot.page, `${row.operation} facts fence write`);
@@ -211,19 +212,20 @@ export async function prepareFenceRowRetirement(engine: BrainEngine, row: WriteR
// #6188 / #6385 R12, as the append: the stored fence is normalized first and a residual refuses typed instead of losing the rows it skipped.
const target = await normalizeTargetFences(engine, { sourceId: row.source_id, slug, kind: 'facts', page: base });
const fenced = { compiled_truth: target.page.compiled_truth, timeline: target.page.timeline ?? '' };
- const section = (['compiled_truth', 'timeline'] as const).find(key => parseFactsFenceFor(fenced[key], { slug }).facts.some(f => retired.has(f.rowNum) && f.active));
+ const section = (['compiled_truth', 'timeline'] as const).find(key => parseFactsFenceFor(fenced[key], { slug }).facts.some(f => (retired.has(f.rowNum) && f.active) || (drop.has(f.rowNum) && !f.active)));
if (!section) return null;
const until = retire.validUntil ? formatFenceDate(retire.validUntil) : undefined;
const parsed = parseFactsFenceFor(fenced[section], { slug });
refuseUnparsedRewrite(target.page, slug, row.source_id, () => assertFenceRewritable('facts', parsed));
// GST-2492: a forgotten held row is struck as a withdrawal strikes a row (`forgotten: <note>`), so it reads back forgotten;
- // `remove` takes the rows out (a fact moved into a page not every reader can read leaves nothing on the holding page).
- const rows = parsed.facts.filter(f => !retire.remove || !retired.has(f.rowNum) || !f.active).map(f => !retired.has(f.rowNum) || !f.active ? f : retire.forgotten ? withdrawnFact(f, (retire.validUntil ?? new Date()).toISOString().slice(0, 10), retire.note)
+ // `remove` takes the rows out (a fact moved into a page not every reader can read leaves nothing on the holding page);
+ // `drop` takes out struck rows (the withdrawn held rows of an entity that leaves the holding page).
+ const rows = parsed.facts.filter(f => !(drop.has(f.rowNum) && !f.active) && (!retire.remove || !retired.has(f.rowNum) || !f.active)).map(f => !retired.has(f.rowNum) || !f.active ? f : retire.forgotten ? withdrawnFact(f, (retire.validUntil ?? new Date()).toISOString().slice(0, 10), retire.note)
: { ...f, active: false, context: [retire.note, f.context?.trim()].filter(Boolean).join(' | '), ...(until ? { validUntil: until } : {}) });
const content = serializePageToMarkdown({ ...base, ...fenced, [section]: replaceOrInsertFactsFence(fenced[section], renderFactsTable(rows)) }, snapshot.tags);
const prepared = await preparePageMutation(engine, { ...row, slug, page_id: snapshot.page.id,
intent: { ...row.intent, content, expected_revision: snapshot.revision, force: false } }, config, undefined, signal, { unprojected: true });
- return { slug, pageId: snapshot.page.id, observedRevision: prepared.observedRevision, ...(prepared.file ? { file: prepared.file } : {}),
+ return { slug, pageId: snapshot.page.id, observedRevision: prepared.observedRevision, mutation: prepared, ...(prepared.file ? { file: prepared.file } : {}),
...(prepared.validate ? { validate: (tx: BrainEngine) => prepared.validate!(tx) } : {}), apply: (tx, preimage) => prepared.apply(tx, preimage) };
}
@@ -255,7 +257,7 @@ export async function heldRowsInVersions(db: BrainEngine, sourceId: string, slug
}
};
await rewriteVersionBodies(db, { columns: '', where: `v.id>$2 AND p.slug=$3 AND (${entities.map((_, i) => carriesClaimSql('v', 4 + 2 * i)).join(' OR ')})`,
- params: after => [sourceId, after, slug, ...entities.flatMap(claimNeedles)], lock: write }, strip, (_v, _edited, changed) => { if (changed) out.versions++; }, write);
+ params: after => [sourceId, after, slug, ...entities.flatMap(claimNeedles)], lock: write, keepNullTimeline: true }, strip, (_v, _edited, changed) => { if (changed) out.versions++; }, write);
const [segmented] = await db.executeRaw<{ n: number }>(`SELECT count(*)::int AS n FROM page_versions v JOIN pages p ON p.id = v.page_id
WHERE p.source_id = $1 AND p.slug = $2 AND v.body_storage = 'segmented'`, [sourceId, slug]);
out.segmented = Number(segmented?.n ?? 0);
diff --git a/src/core/facts/held-fact-move.ts b/src/core/facts/held-fact-move.ts
index 534e35e0d0..05ef5165c9 100644
--- a/src/core/facts/held-fact-move.ts
+++ b/src/core/facts/held-fact-move.ts
@@ -11,9 +11,9 @@
* searchable, and is reported as `held_fact_unmovable`.
*/
import type { BrainEngine } from '../engine.ts';
-import { opError, type OperationContext, type OperationError } from '../ops/contract.ts';
+import { opError, OperationError, type OperationContext } from '../ops/contract.ts';
import { folderHoldingSlug, holdingSlugSql, isHoldingSlug, UNATTRIBUTED_MEMORY_SLUG } from '../facts-fence.ts';
-import { maintenancePreflight, submitPlannedFactFenceAdoption } from '../persistence/prepared-maintenance.ts';
+import { maintenancePreflight, planHeldRowDrop, submitMaintenanceIntent, submitPlannedFactFenceAdoption, type HeldDrop } from '../persistence/prepared-maintenance.ts';
import { privatePagesFilterFragment } from '../search/private-visibility.ts';
import { getWorktreeBinding } from '../persistence/ownership.ts';
import { isFenceHold, pageHasFile, planManagedPage, type UnfencedFactRow } from './unfenced-facts.ts';
@@ -27,8 +27,12 @@ export interface HeldFactMoveOutcome {
unmovable: Array<{ code: 'held_fact_unmovable'; slug: string; fact_ids: number[]; reason: string }>;
/** #8568: entities whose move threw (I/O, database), as opposed to holds the next run settles. */
write_errors: number;
- /** GST-2492 (B): saved versions of the shared page stored in segments, which the move could not edit (the most any one move counted). */
+ /** GST-2492 (B): saved versions of a holding page stored in segments, which the move could not edit (the most any one move counted). */
segmented_versions_not_edited: number;
+ /** The same, per holding page the rows left. */
+ segmented_pages: Array<{ slug: string; versions: number }>;
+ /** Moves accepted and still pending when the write wait ended: not moved yet, named by their request. */
+ pending: Array<{ slug: string; from: string; request_id: string }>;
}
/**
@@ -115,85 +119,141 @@ export async function heldRowDestination(engine: BrainEngine, sourceId: string,
return h && h.slug !== from && from === UNATTRIBUTED_MEMORY_SLUG ? { slug: h.slug, kind: 'rehome' } : null;
}
+/** One entity's held rows on one holding page, and where the move takes them (`drop`: only struck rows, removed in place). */
+export interface HeldMoveGroup {
+ slug: string; kind: 'page' | 'create' | 'rehome' | 'drop'; from: string; key: string; group: HeldRow[];
+ /** The holding row's note: `moved` removes the rows from the holding page and its saved versions. */
+ note: string;
+ /** Struck rows of the entity, removed with its live rows when the note is `moved` (empty otherwise). */
+ struck: HeldDrop[];
+}
+
/**
- * GST-2492 (B2): after a sync releases its lease, the held facts a folder rule it applied now covers leave the shared page
- * at once instead of at the next maintenance cycle (still the fallback after a crash). Null when none is due.
+ * GST-2492: the held-fact move's plan, read-only, the one enumeration the move and the rule preview share: every held row
+ * and every struck held row on every holding page, grouped by page and entity in the order the move runs them. `home`
+ * decides a page-less entity's holding page (a preview passes its desired rules); `hidden` names pages the change makes
+ * unreadable to some reader (a preview's desired rules), so their note is `moved`.
+ */
+export async function planHeldMoves(engine: BrainEngine, sourceId: string, opts: { home?: (key: string) => Promise<HoldingHome>; hidden?: (slug: string) => boolean } = {}):
+ Promise<{ groups: HeldMoveGroup[]; unmovable: HeldFactMoveOutcome['unmovable'] }> {
+ const onHolding = `f.source_id = $1 AND f.source_markdown_slug IN (SELECT hp.slug FROM pages hp WHERE hp.source_id = $1 AND ${holdingSlugSql('hp.slug')})
+ AND f.row_num IS NOT NULL AND f.dimension IS NULL AND f.entity_slug IS NOT NULL AND NOT ${holdingSlugSql('f.entity_slug')}`;
+ const rows = await engine.executeRaw<HeldRow>(
+ `SELECT id, source_id, entity_slug, fact, kind, visibility, notability, context, valid_from, valid_until, source, confidence,
+ claim_metric, claim_value, claim_unit, claim_period, attributed_to, true AS page_exists, source_markdown_slug AS from_slug
+ FROM facts f WHERE ${onHolding} AND f.expired_at IS NULL ORDER BY f.source_markdown_slug, f.entity_slug, f.id`, [sourceId]);
+ // A struck row keeps its facts row (expired) at its row number; one an active fact reuses is not struck.
+ const struck = await engine.executeRaw<{ from_slug: string; entity_slug: string; row_num: number; fact: string }>(
+ `SELECT DISTINCT ON (f.source_markdown_slug, f.row_num) f.source_markdown_slug AS from_slug, f.entity_slug, f.row_num, f.fact FROM facts f
+ WHERE ${onHolding} AND f.expired_at IS NOT NULL AND NOT EXISTS (SELECT 1 FROM facts a WHERE a.source_id = f.source_id
+ AND a.source_markdown_slug = f.source_markdown_slug AND a.row_num = f.row_num AND a.expired_at IS NULL)
+ ORDER BY f.source_markdown_slug, f.row_num, f.id DESC`, [sourceId]);
+ const keys = new Map<string, { from: string; key: string; group: HeldRow[]; struck: HeldDrop[] }>();
+ const at = (from: string, key: string) => keys.get(`${from}\0${key}`) ?? keys.set(`${from}\0${key}`, { from, key, group: [], struck: [] }).get(`${from}\0${key}`)!;
+ for (const row of rows) at(row.from_slug, row.entity_slug!).group.push(row);
+ for (const s of struck) at(s.from_slug, s.entity_slug).struck.push({ row_num: Number(s.row_num), entity: s.entity_slug, claim: s.fact });
+ const plan: Awaited<ReturnType<typeof planHeldMoves>> = { groups: [], unmovable: [] };
+ for (const { from, key, group, struck: withdrawn } of keys.values()) {
+ const dest = await heldRowDestination(engine, sourceId, key, from, opts.home);
+ if (!dest) continue;
+ if ('unmovable' in dest) {
+ if (group.length) plan.unmovable.push({ code: 'held_fact_unmovable', slug: key, fact_ids: group.map(r => Number(r.id)), reason: dest.unmovable });
+ continue;
+ }
+ // A fact moved into a page not every reader of the source can read, or off a folder's holding page, leaves the
+ // holding page with no trace of where it went.
+ const [page] = dest.kind === 'page' && from === UNATTRIBUTED_MEMORY_SLUG && !opts.hidden?.(dest.slug) ? await engine.executeRaw<{ visible: boolean }>(
+ `SELECT ${privatePagesFilterFragment('p')} AS visible FROM pages p WHERE p.source_id=$1 AND p.slug=$2 AND p.deleted_at IS NULL`, [sourceId, dest.slug]) : [];
+ const note = page?.visible === true ? `moved to ${dest.slug}` : 'moved';
+ if (group.length) plan.groups.push({ slug: dest.slug, kind: dest.kind, from, key, group, note, struck: note === 'moved' ? withdrawn : [] });
+ else if (note === 'moved') plan.groups.push({ slug: from, kind: 'drop', from, key, group, note, struck: withdrawn });
+ }
+ return plan;
+}
+
+/** The words for what a held-fact move left incomplete: each holding page whose segmented saved versions it could not edit, each move still pending. */
+export function heldMoveIncomplete(held: Pick<HeldFactMoveOutcome, 'segmented_pages' | 'pending'>): Array<{ code: 'HELD_VERSIONS_NOT_EDITED' | 'HELD_FACT_PENDING'; text: string }> {
+ return [...held.segmented_pages.map(p => ({ code: 'HELD_VERSIONS_NOT_EDITED' as const,
+ text: `${p.versions} saved version(s) of ${p.slug} are stored in segments and were not edited; readers of its saved versions can still read the moved rows in up to ${p.versions} of them.` })),
+ ...held.pending.map(p => ({ code: 'HELD_FACT_PENDING' as const,
+ text: `the move of held facts off ${p.from} to ${p.slug} is accepted and still pending (request ${p.request_id}; gbrain write-request ${p.request_id} shows it), so until it commits they read as they did on ${p.from}.` }))];
+}
+
+/**
+ * GST-2492 (B2): after a sync releases its lease, the held facts a rule it applied narrows below their holding page's
+ * readers (a folder rule over the shared page, an exact page rule over a folder's holding page, or a pending narrowing)
+ * leave that page at once instead of at the next maintenance cycle (still the fallback after a crash). Null when none is due.
*/
export async function moveRuledSharedHeld(engine: BrainEngine, sourceId: string): Promise<HeldFactMoveOutcome | null> {
- const [due] = await engine.executeRaw<{ due: boolean }>(`SELECT EXISTS (SELECT 1 FROM facts f WHERE f.source_id = $1 AND f.source_markdown_slug = $2
- AND f.row_num IS NOT NULL AND f.expired_at IS NULL AND f.entity_slug IS NOT NULL AND (gbrain_access_folder_rules(f.source_id, f.entity_slug) IS NOT NULL
- OR gbrain_access_pending_covers(f.source_id, f.entity_slug))) AS due`, [sourceId, UNATTRIBUTED_MEMORY_SLUG]);
+ const [due] = await engine.executeRaw<{ due: boolean }>(`SELECT EXISTS (SELECT 1 FROM facts f WHERE f.source_id = $1
+ AND f.source_markdown_slug IN (SELECT hp.slug FROM pages hp WHERE hp.source_id = $1 AND ${holdingSlugSql('hp.slug')})
+ AND f.row_num IS NOT NULL AND f.dimension IS NULL AND f.entity_slug IS NOT NULL AND NOT ${holdingSlugSql('f.entity_slug')}
+ AND (gbrain_access_folder_rules(f.source_id, f.entity_slug) IS DISTINCT FROM gbrain_access_folder_rules(f.source_id, f.source_markdown_slug)
+ OR (gbrain_access_pending_covers(f.source_id, f.entity_slug) AND NOT gbrain_access_pending_covers(f.source_id, f.source_markdown_slug)))) AS due`, [sourceId]);
return due?.due ? moveHeldFacts(engine, sourceId) : null;
}
export async function moveHeldFacts(engine: BrainEngine, sourceId: string): Promise<HeldFactMoveOutcome> {
- const outcome: HeldFactMoveOutcome = { moved: 0, moved_slugs: [], rehomed: 0, unmovable: [], write_errors: 0, segmented_versions_not_edited: 0 };
- const rows = await engine.executeRaw<HeldRow>(
- `SELECT id, source_id, entity_slug, fact, kind, visibility, notability, context, valid_from, valid_until, source, confidence,
- claim_metric, claim_value, claim_unit, claim_period, attributed_to, true AS page_exists, source_markdown_slug AS from_slug
- FROM facts f
- WHERE f.source_id = $1 AND f.source_markdown_slug IN (SELECT hp.slug FROM pages hp WHERE hp.source_id = $1 AND ${holdingSlugSql('hp.slug')}) AND f.row_num IS NOT NULL AND f.expired_at IS NULL AND f.dimension IS NULL
- AND f.entity_slug IS NOT NULL AND NOT ${holdingSlugSql('f.entity_slug')}
- ORDER BY f.source_markdown_slug, f.entity_slug, f.id`, [sourceId]);
- if (rows.length === 0) return outcome;
+ const outcome: HeldFactMoveOutcome = { moved: 0, moved_slugs: [], rehomed: 0, unmovable: [], write_errors: 0, segmented_versions_not_edited: 0, segmented_pages: [], pending: [] };
+ const plan = await planHeldMoves(engine, sourceId);
+ outcome.unmovable.push(...plan.unmovable);
+ if (plan.groups.length === 0) return outcome;
+ const authority = await maintenancePreflight(engine, sourceId);
+ if (!authority) return outcome;
const unmovable = (slug: string, ids: Array<string | number>, reason: string) => {
if (ids.length) outcome.unmovable.push({ code: 'held_fact_unmovable', slug, fact_ids: ids.map(Number), reason });
};
- const keys = new Map<string, HeldRow[]>();
- for (const row of rows) keys.set(`${row.from_slug}\0${row.entity_slug}`, [...keys.get(`${row.from_slug}\0${row.entity_slug}`) ?? [], row]);
// A row keyed by a bare name moves to the page that name now resolves to, which re-keys it to that page; a row of an
// entity with no page whose folder a rule now covers moves to that folder's holding page.
- const groups: Array<{ slug: string; from: string; fromEntity?: string; group: HeldRow[]; rehome: boolean }> = [];
- let authority: Awaited<ReturnType<typeof maintenancePreflight>> | undefined;
- for (const [, group] of keys) {
- const { from_slug: from, entity_slug: key } = group[0]!;
- const dest = await heldRowDestination(engine, sourceId, key!, from);
- if (!dest) continue;
- if ('unmovable' in dest) { unmovable(key!, group.map(r => r.id), dest.unmovable); continue; }
- if (dest.kind === 'create') {
- // An exact page rule on the entity: only its own page carries those readers, so the page is created for its rows.
- authority ??= await maintenancePreflight(engine, sourceId);
- if (!authority) return outcome;
- try { await ensurePageForHeldRows(engine, sourceId, key!); } catch (error) {
- unmovable(key!, group.map(r => r.id), (error instanceof Error ? error.message : String(error)).slice(0, 300));
- continue;
- }
- }
- groups.push({ slug: dest.slug, from, ...(dest.kind === 'rehome' || dest.slug === key ? {} : { fromEntity: key! }), group, rehome: dest.kind === 'rehome' });
- }
- if (groups.length === 0) return outcome;
- authority ??= await maintenancePreflight(engine, sourceId);
- if (!authority) return outcome;
- for (const { slug, from, fromEntity, group, rehome } of groups) {
+ for (const { slug, kind, from, key, group, note, struck } of plan.groups) {
+ let requestId: string | undefined;
try {
- if (rehome) await ensurePageForHeldRows(engine, sourceId, slug);
- const [page] = await engine.executeRaw<{ source_path: string | null; source_uri: string | null; visible: boolean }>(
- `SELECT p.source_path, p.source_uri, ${privatePagesFilterFragment('p')} AS visible FROM pages p WHERE p.source_id=$1 AND p.slug=$2 AND p.deleted_at IS NULL`, [sourceId, slug]);
- if (!page) { unmovable(slug, group.map(r => r.id), rehome ? 'holding_page_deleted' : 'entity_page_deleted'); continue; }
- // A held row in Git moved into a page kept out of Git would be struck there with no file holding the fact; a row
- // re-homed because a folder rule now covers it moves whatever the folder's storage class (the rule applies at once).
- const [held] = await engine.executeRaw<{ source_path: string | null; source_uri: string | null }>(
- 'SELECT source_path, source_uri FROM pages WHERE source_id=$1 AND slug=$2 AND deleted_at IS NULL', [sourceId, from]);
- if (!rehome && held && await pageHasFile(engine, sourceId, from, held) && !await pageHasFile(engine, sourceId, slug, page)) {
- unmovable(slug, group.map(r => r.id), 'entity_page_database_only'); continue;
+ if (kind === 'drop') {
+ const snapshot = await engine.readPageSnapshot(from, { sourceId });
+ if (!snapshot) continue;
+ const drop = planHeldRowDrop(authority, from, snapshot.revision, struck);
+ requestId = drop.requestId;
+ await submitMaintenanceIntent(engine, authority, from, drop.intent, drop.requestId);
+ } else {
+ if (kind === 'create') {
+ // An exact page rule on the entity: only its own page carries those readers, so the page is created for its rows.
+ try { await ensurePageForHeldRows(engine, sourceId, key); } catch (error) {
+ unmovable(key, group.map(r => r.id), (error instanceof Error ? error.message : String(error)).slice(0, 300));
+ continue;
+ }
+ }
+ if (kind === 'rehome') await ensurePageForHeldRows(engine, sourceId, slug);
+ const [page] = await engine.executeRaw<{ source_path: string | null; source_uri: string | null }>(
+ 'SELECT source_path, source_uri FROM pages WHERE source_id=$1 AND slug=$2 AND deleted_at IS NULL', [sourceId, slug]);
+ if (!page) { unmovable(slug, group.map(r => r.id), kind === 'rehome' ? 'holding_page_deleted' : 'entity_page_deleted'); continue; }
+ // A held row in Git moved into a page kept out of Git would be struck there with no file holding the fact; a row
+ // re-homed because a folder rule now covers it moves whatever the folder's storage class (the rule applies at once).
+ const [held] = await engine.executeRaw<{ source_path: string | null; source_uri: string | null }>(
+ 'SELECT source_path, source_uri FROM pages WHERE source_id=$1 AND slug=$2 AND deleted_at IS NULL', [sourceId, from]);
+ if (kind !== 'rehome' && held && await pageHasFile(engine, sourceId, from, held) && !await pageHasFile(engine, sourceId, slug, page)) {
+ unmovable(slug, group.map(r => r.id), 'entity_page_database_only'); continue;
+ }
+ const plan = await planManagedPage(engine, authority, sourceId, slug, group, { note, ...(kind === 'rehome' || slug === key ? {} : { from_entity: key }),
+ ...(from === UNATTRIBUTED_MEMORY_SLUG ? {} : { from_slug: from }), ...(struck.length ? { drop: struck } : {}) });
+ if (plan.kind === 'no_page') continue;
+ if (plan.kind === 'warnings') { unmovable(slug, group.map(r => r.id), `entity_fence_malformed: ${plan.warnings.join('; ')}`); continue; }
+ const rejected = plan.kind === 'unadoptable' ? plan.records : plan.fence.rejected;
+ for (const reason of new Set(rejected.map(r => r.class))) unmovable(slug, rejected.filter(r => r.class === reason).map(r => r.fact_id), reason);
+ if (plan.kind === 'unadoptable') continue;
+ requestId = plan.request.requestId;
+ await submitPlannedFactFenceAdoption(engine, authority, slug, plan.request, true);
+ if (kind === 'rehome') outcome.rehomed += plan.fence.assignments.length;
+ else { outcome.moved += plan.fence.assignments.length; outcome.moved_slugs.push(slug); }
}
- // A fact moved into a page not every reader of the source can read, or off a folder's holding page, leaves the
- // holding page with no trace of where it went.
- const note = !rehome && from === UNATTRIBUTED_MEMORY_SLUG && page.visible === true ? `moved to ${slug}` : 'moved';
- const plan = await planManagedPage(engine, authority, sourceId, slug, group,
- { note, ...(fromEntity ? { from_entity: fromEntity } : {}), ...(from === UNATTRIBUTED_MEMORY_SLUG ? {} : { from_slug: from }) });
- if (plan.kind === 'no_page') continue;
- if (plan.kind === 'warnings') { unmovable(slug, group.map(r => r.id), `entity_fence_malformed: ${plan.warnings.join('; ')}`); continue; }
- const rejected = plan.kind === 'unadoptable' ? plan.records : plan.fence.rejected;
- for (const reason of new Set(rejected.map(r => r.class))) unmovable(slug, rejected.filter(r => r.class === reason).map(r => r.fact_id), reason);
- if (plan.kind === 'unadoptable') continue;
- await submitPlannedFactFenceAdoption(engine, authority, slug, plan.request, true);
const [edited] = await engine.executeRaw<{ n: number | null }>(`SELECT (outcome->'held_versions_edited'->>'segmented_versions_not_edited')::int AS n
- FROM persistence_requests WHERE request_id = $1::uuid`, [plan.request.requestId]);
- outcome.segmented_versions_not_edited = Math.max(outcome.segmented_versions_not_edited, Number(edited?.n ?? 0));
- if (rehome) outcome.rehomed += plan.fence.assignments.length;
- else { outcome.moved += plan.fence.assignments.length; outcome.moved_slugs.push(slug); }
+ FROM persistence_requests WHERE request_id = $1::uuid`, [requestId]);
+ const n = Number(edited?.n ?? 0), seen = outcome.segmented_pages.find(p => p.slug === from);
+ if (n && seen) seen.versions = Math.max(seen.versions, n);
+ else if (n) outcome.segmented_pages.push({ slug: from, versions: n });
+ outcome.segmented_versions_not_edited = Math.max(outcome.segmented_versions_not_edited, n);
} catch (error) {
+ // An accepted publication still pending is neither moved nor failed: the receipt names it until it commits.
+ if (requestId && error instanceof OperationError && error.code === 'write_pending') { outcome.pending.push({ slug, from, request_id: requestId }); continue; }
unmovable(slug, group.map(r => r.id), (error instanceof Error ? error.message : String(error)).slice(0, 300));
if (!isFenceHold(error)) outcome.write_errors += 1;
}
diff --git a/src/core/facts/purge.ts b/src/core/facts/purge.ts
index 4494163707..f1bb1d2b02 100644
--- a/src/core/facts/purge.ts
+++ b/src/core/facts/purge.ts
@@ -310,10 +310,11 @@ const VERSION_REDACTION_BATCH = 5000;
* The one reader and rewriter of inline saved-version bodies, for purge's redaction and the held-fact move
* (fence-fact-append.ts heldRowsInVersions): the inline versions of source $1 matching `where` in keyset batches by id,
* `edit` applied to each body part, and the version rewritten when either part changed, unless `write` is false (a
- * preview). `visit` sees each version's edited parts. Segmented versions are each caller's own pass.
+ * preview). `visit` sees each version's edited parts. `keepNullTimeline` (the held-row edit) writes a NULL timeline back as
+ * NULL. Segmented versions are each caller's own pass.
*/
export async function rewriteVersionBodies<X extends object>(tx: BrainEngine,
- query: { columns?: string; where: string; params: (after: number) => unknown[]; lock?: boolean },
+ query: { columns?: string; where: string; params: (after: number) => unknown[]; lock?: boolean; keepNullTimeline?: boolean },
edit: (text: string, slug: string) => Promise<string> | string,
visit: (v: X & { id: number; slug: string }, edited: [string, string], changed: boolean) => void, write = true): Promise<void> {
for (let after = 0; ;) {
@@ -327,7 +328,8 @@ export async function rewriteVersionBodies<X extends object>(tx: BrainEngine,
const compiled = await edit(v.compiled_truth, v.slug);
const timeline = await edit(v.timeline ?? '', v.slug);
const changed = compiled !== v.compiled_truth || timeline !== (v.timeline ?? '');
- if (changed && write) await tx.executeRaw('UPDATE page_versions SET compiled_truth=$2,timeline=$3 WHERE id=$1', [v.id, compiled, timeline]);
+ if (changed && write) await tx.executeRaw('UPDATE page_versions SET compiled_truth=$2,timeline=$3 WHERE id=$1',
+ [v.id, compiled, query.keepNullTimeline && v.timeline === null && timeline === '' ? null : timeline]);
visit(v, [compiled, timeline], changed);
}
if (rows.length < VERSION_REDACTION_BATCH) break;
diff --git a/src/core/facts/unfenced-facts.ts b/src/core/facts/unfenced-facts.ts
index b1ee4e873c..d55c295111 100644
--- a/src/core/facts/unfenced-facts.ts
+++ b/src/core/facts/unfenced-facts.ts
@@ -69,7 +69,7 @@ import { maintenanceTransaction } from '../persistence/attribution.ts';
import { assertLifetimeIdHeadroom } from '../persistence/journal.ts';
import { OperationError, type OperationContext } from '../ops/contract.ts';
import { managedPersistenceEnabled } from '../persistence/ownership.ts';
-import { maintenancePreflight, planFactFenceAdoption, submitFactFenceAdoption, submitPlannedFactFenceAdoption, type MaintenanceAuthority } from '../persistence/prepared-maintenance.ts';
+import { maintenancePreflight, planFactFenceAdoption, submitFactFenceAdoption, submitPlannedFactFenceAdoption, type HeldDrop, type MaintenanceAuthority } from '../persistence/prepared-maintenance.ts';
import { resolveFactWriteTarget } from '../persistence/fact-write-target.ts';
import { submissionAuthority } from '../persistence/authority.ts';
import { currentVerifiedLocalWriter, registerLocalWriter } from '../persistence/identity.ts';
@@ -517,7 +517,7 @@ export async function planPageFence(engine: BrainEngine, sourceId: string, slug:
}
export async function planManagedPage(engine: BrainEngine, authority: MaintenanceAuthority, sourceId: string, entitySlug: string, group: UnfencedFactRow[],
- move?: { note: string; from_entity?: string; from_slug?: string }): Promise<ManagedPagePlan> {
+ move?: { note: string; from_entity?: string; from_slug?: string; drop?: readonly HeldDrop[] }): Promise<ManagedPagePlan> {
const planned = await planPageFence(engine, sourceId, entitySlug, group);
if (!planned) return { kind: 'no_page' };
const { snapshot, fence } = planned;
diff --git a/src/core/persistence/prepared-maintenance.ts b/src/core/persistence/prepared-maintenance.ts
index 132eb66f35..22e677d3b4 100644
--- a/src/core/persistence/prepared-maintenance.ts
+++ b/src/core/persistence/prepared-maintenance.ts
@@ -435,6 +435,8 @@ export const FACT_FENCE_PLANNER = 2;
* no page) into their entity page's fence: the rows keep their ids and move in place, and their holding rows are struck.
*/
export const HELD_FACT_MOVE = 'managed_maintenance_move_held_fact';
+/** A struck (withdrawn) held row that leaves its holding page with its entity's live rows (GST-2492). */
+export type HeldDrop = { row_num: number; entity: string; claim: string };
/** How long a refused adoption is held back; the owner that refused it may since have restarted onto code that adopts it. */
const ADOPTION_REFUSAL_HOLD_MS = 24 * 60 * 60 * 1000;
@@ -457,13 +459,13 @@ export type FactFenceAdoptionPlan =
* every cycle, so the page waits a day or a planner change.
*/
export async function planFactFenceAdoption(engine: BrainEngine, authority: MaintenanceAuthority, slug: string,
- options: { content: string; expectedRevision: string; assignments: Array<{ id: number; row_num: number }>; move?: { note: string; from_entity?: string; from_slug?: string } }): Promise<FactFenceAdoptionPlan> {
+ options: { content: string; expectedRevision: string; assignments: Array<{ id: number; row_num: number }>; move?: { note: string; from_entity?: string; from_slug?: string; drop?: readonly HeldDrop[] } }): Promise<FactFenceAdoptionPlan> {
const current = await readFacts(engine, authority.writer.sourceId, options.assignments.map(a => a.id));
const facts: FactFenceAssignment[] = options.assignments.map(a => ({ ...a, hash: digest(current.find(f => f.id === a.id)?.value ?? null) }));
const intent = { kind: options.move ? HELD_FACT_MOVE : 'managed_maintenance_adopt_fact_fence', expected_revision: options.expectedRevision,
source_incarnation: authority.writer.sourceIncarnation, content: options.content, facts, planner: FACT_FENCE_PLANNER,
...(options.move ? { note: options.move.note, ...(options.move.from_entity ? { from_entity: options.move.from_entity } : {}),
- ...(options.move.from_slug ? { from_slug: options.move.from_slug } : {}) } : {}) };
+ ...(options.move.from_slug ? { from_slug: options.move.from_slug } : {}), ...(options.move.drop?.length ? { drop: options.move.drop } : {}) } : {}) };
for (let attempt = 0; ; attempt++) {
const requestId = maintenanceRequestId({ authority: authority.writer, slug, intent, ...(attempt ? { attempt } : {}) });
const prior = await getWriteRequest(engine, authority.writer.principal, requestId);
@@ -475,6 +477,16 @@ export async function planFactFenceAdoption(engine: BrainEngine, authority: Main
}
}
+/**
+ * GST-2492: the struck held rows of an entity with no live row left on holding page `from`, removed from it (and its saved
+ * versions) once a rule narrows the entity below that page's readers. The request id is returned before the wait.
+ */
+export function planHeldRowDrop(authority: MaintenanceAuthority, from: string, revision: string, drop: readonly HeldDrop[]) {
+ const intent = { kind: HELD_FACT_MOVE, expected_revision: revision, source_incarnation: authority.writer.sourceIncarnation, facts: [], drop,
+ note: 'moved', planner: FACT_FENCE_PLANNER, ...(from === UNATTRIBUTED_MEMORY_SLUG ? {} : { from_slug: from }) };
+ return { intent, requestId: maintenanceRequestId({ authority: authority.writer, slug: from, intent }) };
+}
+
export async function submitPlannedFactFenceAdoption(engine: BrainEngine, authority: MaintenanceAuthority, slug: string,
plan: Extract<FactFenceAdoptionPlan, { kind: 'submit' }>, file: boolean): Promise<Record<string, unknown>> {
return submitMaintenance(engine, authority, slug, plan.intent, plan.requestId, file);
@@ -513,14 +525,31 @@ async function prepareFactFenceAdoption(unbounded: BrainEngine, row: WriteReques
`Fact-fence adoption request ${row.request_id} for ${row.slug} in ${row.source_id} was refused before publication; nothing changed. The plan itself is malformed, so report the request ID to the user rather than running the same backfill again.`,
{ fix: receiptFix(row) });
}
+ // The holding page a held row moves off (`from_slug`, memory/unattributed when absent), and the struck rows of the
+ // entity that leave it with the live ones (GST-2492): withdrawn, so they are removed rather than moved.
+ const fromSlug = held && typeof p.from_slug === 'string' && isHoldingSlug(p.from_slug) ? p.from_slug : UNATTRIBUTED_MEMORY_SLUG;
+ const drop = held && Array.isArray(p.drop) ? p.drop as HeldDrop[] : [];
+ const scrubbing = (keys: Array<{ entity: string; claim: string }>, after: PreparedMutation['afterEffects']) => async (tx: BrainEngine, outcome: Record<string, unknown>) => {
+ await after?.(tx, outcome);
+ const edited = await heldRowsInVersions(tx, row.source_id, fromSlug, [...keys, ...drop], true);
+ outcome.held_versions_edited = { slug: fromSlug, moved_to: facts.length ? row.slug : null, fact_ids: facts.map(f => f.id), rows: edited.rows, versions: edited.versions,
+ ...(drop.length ? { struck_rows: drop.length } : {}), ...(edited.segmented ? { segmented_versions_not_edited: edited.segmented } : {}) };
+ };
+ const unhold = (tx: BrainEngine) => tx.executeRaw('UPDATE facts SET row_num=NULL WHERE source_id=$1 AND source_markdown_slug=$2 AND row_num=ANY($3::int[]) AND expired_at IS NOT NULL',
+ [row.source_id, fromSlug, drop.map(d => d.row_num)]);
+ if (held && !facts.length) {
+ const page = await prepareFenceRowRetirement(unbounded, { ...row, intent: { kind: 'managed_maintenance_page' } }, config, fromSlug,
+ { note: 'moved', rowNum: [], validUntil: null, drop: drop.map(d => d.row_num) });
+ if (!page) throw opError('revision_conflict', 'The struck held rows already left their holding page.',
+ `The struck rows of request ${row.request_id} are no longer on ${fromSlug} in ${row.source_id}; nothing was written. The next maintenance run plans from the current page.`, { fix: receiptFix(row) });
+ return { ...page.mutation, afterEffects: scrubbing([], page.mutation.afterEffects), apply: async (tx, preimage) => { await unhold(tx); return page.mutation.apply(tx, preimage); } };
+ }
enterClaimStep(clock, 'adoption_parse_fence');
const fence = new Map(parseFactsFenceFor(p.content as string, { slug: row.slug }).facts.map(f => [f.rowNum, f]));
// GST-2492 PR 2 (gbrain repair facts-home): a database-only fact with no entity, or whose entity has no page, is adopted
// onto a holding page; its cell must name the fact's entity (none for a fact with no entity), so the projection keeps it.
// A held move onto a holding page (a held row whose entity a folder rule now covers) keeps its entity the same way.
const holdingAdoption = isHoldingSlug(row.slug);
- // The holding page a held row moves off (`from_slug`, memory/unattributed when absent).
- const fromSlug = held && typeof p.from_slug === 'string' && isHoldingSlug(p.from_slug) ? p.from_slug : UNATTRIBUTED_MEMORY_SLUG;
// A held row keyed by a bare name (`from_entity`) moves to the page that name resolved to, and is re-keyed to it.
const fromEntity = held && typeof p.from_entity === 'string' ? p.from_entity : null;
const ownsRow = (value: Record<string, unknown>, rowNum: number) => holdingAdoption
@@ -559,17 +588,12 @@ async function prepareFactFenceAdoption(unbounded: BrainEngine, row: WriteReques
const pageRow = { ...row, intent: { kind: 'managed_maintenance_page', content: p.content, expected_revision: p.expected_revision } };
const prepared = await preparePageMutation(unbounded, pageRow, config, undefined, undefined, { clock });
const holding = held ? await prepareFenceRowRetirement(unbounded, pageRow, config, fromSlug, { note: String(p.note), remove: p.note === 'moved',
- rowNum: (await readFacts(engine, row.source_id, facts.map(f => f.id))).map(f => Number(f.value.row_num)), validUntil: null }) : null;
- // GST-2492 (A2): a row removed from the shared page (it moved where not every reader of the source can read) leaves its
- // saved versions too, in this transaction; the receipt records which rows, how many versions and where they went.
- const scrub = held && p.note === 'moved' && fromSlug === UNATTRIBUTED_MEMORY_SLUG
- ? facts.map(f => ({ entity: holdingAdoption ? fence.get(f.row_num)!.entity ?? '' : fromEntity ?? row.slug, claim: fence.get(f.row_num)!.claim })) : null;
- const afterEffects = scrub ? async (tx: BrainEngine, outcome: Record<string, unknown>) => {
- await prepared.afterEffects?.(tx, outcome);
- const edited = await heldRowsInVersions(tx, row.source_id, fromSlug, scrub, true);
- outcome.held_versions_edited = { slug: fromSlug, moved_to: row.slug, fact_ids: facts.map(f => f.id), rows: edited.rows, versions: edited.versions,
- ...(edited.segmented ? { segmented_versions_not_edited: edited.segmented } : {}) };
- } : prepared.afterEffects;
+ rowNum: (await readFacts(engine, row.source_id, facts.map(f => f.id))).map(f => Number(f.value.row_num)), validUntil: null, drop: drop.map(d => d.row_num) }) : null;
+ // GST-2492 (A2): a row removed from its holding page (it moved where not every reader of that page can read) leaves the
+ // page's saved versions too, in this transaction; the receipt records which rows, how many versions and where they went.
+ const afterEffects = held && p.note === 'moved'
+ ? scrubbing(facts.map(f => ({ entity: holdingAdoption ? fence.get(f.row_num)!.entity ?? '' : fromEntity ?? row.slug, claim: fence.get(f.row_num)!.claim })), prepared.afterEffects)
+ : prepared.afterEffects;
return { ...prepared, ...(afterEffects ? { afterEffects } : {}), ...(holding ? { companions: [holding] } : {}), validate: async tx => { await prepared.validate?.(tx); await check(tx, true); }, apply: async tx => {
// Runs ahead of the page import and its canonical projection, so the
// projection's expiry pass and insertFacts see the adopted positions.
@@ -584,6 +608,7 @@ async function prepareFactFenceAdoption(unbounded: BrainEngine, row: WriteReques
`Another run adopted a legacy fact on ${row.slug} in ${row.source_id} while request ${row.request_id} was publishing, so its transaction rolled back. Read the receipt with gbrain write-request -- ${row.request_id} for the final state before planning any new adoption.`,
{ fix: receiptFix(row) });
if (held) noteBelief({ kind: 'transferred', fromSlug, table: 'facts', ids: facts.map(f => f.id) });
+ if (drop.length) await unhold(tx);
const outcome = await prepared.apply(tx);
return { ...outcome, facts_adopted: facts.length };
} };
diff --git a/src/core/search/private-visibility.ts b/src/core/search/private-visibility.ts
index 4d4634c2d3..0f23589c15 100644
--- a/src/core/search/private-visibility.ts
+++ b/src/core/search/private-visibility.ts
@@ -28,7 +28,7 @@ import { isValidSourceId } from '../source-id.ts';
import { asciiLower, asciiLowerSql, edgeTrimSql } from '../edge-whitespace.ts';
import { ACCESS_ID_RE, hasReaders, MEMBER_PAGE_PREFIX, normalizePrincipal, readersAllow, validIdentity } from '../access/principals.ts';
import { ruleCoversSql, validPrefix, validQualifiedRuleId } from '../access/folder-rules.ts';
-import { holdingSlugSql, UNATTRIBUTED_MEMORY_SLUG } from '../facts-fence.ts';
+import { holdingSlugSql } from '../facts-fence.ts';
export const REMOTE_PRIVATE_PAGES_KEY = 'search.remote_private_pages';
@@ -858,10 +858,10 @@ export function privateEntityFilterForCaller(factAlias: string, perCandidate = f
}
/**
- * GST-2492: a fact still held on the shared memory/unattributed page for an entity a folder rule now covers (a rule
- * applied by sync, or a remember planned before the rule, until the held-fact move takes it to the folder's page) reads
- * as that entity's page would: only for a caller who satisfies every covering rule, and for nobody while a pending
- * narrowing covers it. The owner under the opt-in reads it, as it reads every restricted page.
+ * GST-2492: a fact still held on a holding page for an entity a rule now narrows below that page (a folder rule over the
+ * shared page, an exact page rule over a folder's holding page; applied by sync, or a remember planned before the rule,
+ * until the held-fact move takes it away) reads as that entity's page would: only for a caller who satisfies every
+ * covering rule, and for nobody while a pending narrowing covers it. The owner under the opt-in reads it, as it reads every restricted page.
*/
function sharedHeldRuledSql(factAlias: string): string {
const access = currentCallerAccess();
@@ -869,7 +869,7 @@ function sharedHeldRuledSql(factAlias: string): string {
const satisfied = access.restricted ? access.satisfiedRuleIds : [];
const ids = satisfied.length && satisfied.every(validQualifiedRuleId) ? [...new Set(satisfied)].sort() : [];
const array = ids.length ? `ARRAY[${ids.map(id => `'${id}'`).join(', ')}]::text[]` : 'ARRAY[]::text[]';
- return ` AND NOT (${factAlias}.entity_slug IS NOT NULL AND ${factAlias}.source_markdown_slug = '${UNATTRIBUTED_MEMORY_SLUG}'`
+ return ` AND NOT (${factAlias}.entity_slug IS NOT NULL AND ${holdingSlugSql(`${factAlias}.source_markdown_slug`)}`
+ ` AND (NOT COALESCE(gbrain_access_folder_rules(${factAlias}.source_id, ${factAlias}.entity_slug) <@ ${array}, true)`
+ ` OR gbrain_access_pending_covers(${factAlias}.source_id, ${factAlias}.entity_slug)))`;
}
diff --git a/test/folder-holding-page-gst2492.test.ts b/test/folder-holding-page-gst2492.test.ts
index 02ff1ae5f1..1936f1ebd7 100644
--- a/test/folder-holding-page-gst2492.test.ts
+++ b/test/folder-holding-page-gst2492.test.ts
@@ -47,6 +47,8 @@ import { noGrantFederatedScope } from '../src/core/source-resolver.ts';
import { resolveRepairScope, type RepairKind } from '../src/core/repair/core.ts';
import { repairRunner } from '../src/core/repair/registry.ts';
import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';
+import { __setMaintenanceWriteWaitForTests } from '../src/core/persistence/maintenance-wait.ts';
+import { acquireWorktree, getWorktreeBinding } from '../src/core/persistence/ownership.ts';
import { durableGitRepo, git } from './helpers/git-publication.ts';
import { managedBrain, settleManagedGitEffects, type ManagedBrain } from './helpers/managed-brain.ts';
import { isolatedSharedSkillsEngine } from './helpers/shared-skills-engine.ts';
@@ -294,11 +296,17 @@ for (const backend of testBackends()) describe(`[${backend}] the folder-rule hol
await remember(ctx, 'The garden plan needs more compost.', 'notes/garden-plan');
await settleManagedGitEffects(engine);
for (const who of ['bob', 'unbound']) expect(await versionsText(as, who, HOLD)).toContain(claim);
+ // A saved version with no timeline keeps none (NULL, not an empty string) once its row is removed.
+ await engine.executeRaw("UPDATE page_versions SET timeline = NULL WHERE page_id = (SELECT id FROM pages WHERE source_id = 'default' AND slug = $1)", [HOLD]);
+ const nullTimelines = () => engine.executeRaw<{ id: number }>(`SELECT v.id::int AS id FROM page_versions v JOIN pages p ON p.id = v.page_id
+ WHERE p.source_id = 'default' AND p.slug = $1 AND v.timeline IS NULL ORDER BY v.id`, [HOLD]);
+ const untimed = await nullTimelines();
const before = await versionBodies(engine, HOLD);
const preview = await cli(engine, ['rule', 'add', '--prefix', 'clients/acme-example/', '--readers', 'alice-example', '--source', 'default', '--json']);
const carrying = before.filter(v => v.body.includes(claim)).length;
expect(carrying).toBeGreaterThan(0);
- expect(preview.held_versions_editing).toEqual({ rows: carrying, versions: carrying });
+ // The preview counts what the apply's receipt records: the versions carrying the row now, plus the one the move saves.
+ expect(preview.held_versions_editing).toEqual({ rows: carrying + 1, versions: carrying + 1, pages: [{ slug: HOLD, rows: carrying + 1, versions: carrying + 1 }] });
const applied = await cli(engine, ['rule', 'add', '--prefix', 'clients/acme-example/', '--readers', 'alice-example', '--source', 'default', '--yes', '--expect', String(preview.expect), '--json']);
expect(applied.held_facts).toEqual({ moved: 1, unmovable: [] });
await settleManagedGitEffects(engine);
@@ -306,6 +314,8 @@ for (const backend of testBackends()) describe(`[${backend}] the folder-rule hol
for (const v of before) {
expect(after.get(v.id)).toBe(v.body.split('\n').filter(line => !line.includes(claim)).join('\n'));
}
+ expect(untimed.length).toBe(before.length);
+ expect((await nullTimelines()).filter(v => untimed.some(u => u.id === v.id))).toEqual(untimed);
expect([...after.values()].some(body => body.includes(kept))).toBe(true);
const [fact] = await factRows(engine, claim);
// The audit counts the versions the preview listed plus the one the move itself saved (the shared page before the move).
@@ -376,7 +386,7 @@ for (const backend of testBackends()) describe(`[${backend}] the folder-rule hol
expect(await remember(ctx, claim, entity)).toMatchObject({ page: HOLD });
await settleManagedGitEffects(engine);
const preview = await cli(engine, ['rule', 'add', '--slug', entity, '--readers', 'alice-example', '--source', 'default', '--json']);
- expect(preview.held_facts_moving).toEqual([{ fact_id: expect.any(Number), entity_slug: entity, to: entity }]);
+ expect(preview.held_facts_moving).toEqual([{ fact_id: expect.any(Number), entity_slug: entity, from: HOLD, to: entity }]);
const lines: string[] = [];
const spy = spyOn(console, 'log').mockImplementation((...a: unknown[]) => { lines.push(a.map(String).join(' ')); });
try { await runAccessRules(engine, 'rule', ['add', '--slug', entity, '--readers', 'alice-example', '--source', 'default'], false); } finally { spy.mockRestore(); }
@@ -402,7 +412,7 @@ for (const backend of testBackends()) describe(`[${backend}] the folder-rule hol
expect(head(root, `${HOLD}.md`)).toContain(claim);
expect((await reads(as, 'bob', HOLD, claim)).fact).toBe(true);
const preview = await cli(engine, ['rule', 'add', '--prefix', 'clients/acme-example/', '--readers', 'alice-example', '--source', 'default', '--json']);
- expect(preview.held_facts_moving).toEqual([{ fact_id: expect.any(Number), entity_slug: entity, to: holding }]);
+ expect(preview.held_facts_moving).toEqual([{ fact_id: expect.any(Number), entity_slug: entity, from: HOLD, to: holding }]);
expect(head(root, `${HOLD}.md`)).toContain(claim);
const applied = await cli(engine, ['rule', 'add', '--prefix', 'clients/acme-example/', '--readers', 'alice-example', '--source', 'default', '--yes', '--expect', String(preview.expect), '--json']);
expect(applied).toMatchObject({ state: 'applied', held_facts: { moved: 1, unmovable: [] } });
@@ -448,7 +458,7 @@ for (const backend of testBackends()) describe(`[${backend}] the folder-rule hol
const words = await humanLines(engine, 'rule', args('clients/acme-example/'));
expect(words).toContain(`Not edited: 1 saved version(s) of ${HOLD} are stored in segments, which this apply cannot edit. ${consequence(1)} The apply will report itself incomplete.`);
const applied = await cli(engine, ['rule', ...args('clients/acme-example/'), '--yes', '--expect', String(preview.expect), '--json']);
- expect(applied.held_facts).toEqual({ moved: 1, unmovable: [], complete: false, segmented_versions_not_edited: 1 });
+ expect(applied.held_facts).toEqual({ moved: 1, unmovable: [], complete: false, segmented_versions_not_edited: 1, segmented_pages: [{ slug: HOLD, versions: 1 }] });
const second = await cli(engine, ['rule', ...args('clients/beta-example/'), '--json']);
expect(second.held_versions_editing).toMatchObject({ segmented_versions_not_edited: 1 });
const done = await humanLines(engine, 'rule', [...args('clients/beta-example/'), '--yes', '--expect', String(second.expect)]);
@@ -498,7 +508,7 @@ for (const backend of testBackends()) describe(`[${backend}] the folder-rule hol
const applied = await cli(engine, ['rule', ...args, '--yes', '--expect', String(preview.expect), '--json']);
expect(applied.held_facts).toMatchObject({ moved: 1 });
const [after] = await factRows(engine, claim);
- expect(preview.held_facts_moving).toEqual([{ fact_id: Number(saved.id), entity_slug: 'kofi-example', to: after!.source_markdown_slug }]);
+ expect(preview.held_facts_moving).toEqual([{ fact_id: Number(saved.id), entity_slug: 'kofi-example', from: HOLD, to: after!.source_markdown_slug }]);
expect(after!.source_markdown_slug).toBe('people/kofi-example');
}), 300_000);
@@ -615,6 +625,144 @@ for (const backend of testBackends()) describe(`[${backend}] the folder-rule hol
[background]: [{ entity_slug: ENTITY, source_markdown_slug: FOLDER_HOLD }] });
}), 300_000);
+ /** The held_versions_edited receipts, summed: what the preview's counts must equal. */
+ const auditSum = async (engine: BrainEngine) => (await auditRows(engine)).reduce((n, r) => ({ rows: n.rows + Number(r.audit.rows), versions: n.versions + Number(r.audit.versions) }), { rows: 0, versions: 0 });
+
+ test('an exact page rule over a row held on a folder holding page: the preview names what the apply does, and the row leaves that page\'s saved versions', () => strict(async ({ engine, ctx }) => {
+ const as = await members(engine);
+ const partners = ['add', '--prefix', 'partners/', '--readers', 'alice-example,bob-example', '--source', 'default'];
+ await cli(engine, ['rule', ...partners, '--yes', '--expect', String((await cli(engine, ['rule', ...partners, '--json'])).expect), '--json']);
+ const claim = 'The deal with acme-example has a secret side letter.';
+ const kept = 'The old notes of alice-example stay with the partners.';
+ expect(await remember(ctx, claim, ENTITY)).toMatchObject({ page: FOLDER_HOLD });
+ expect(await remember(ctx, kept, 'partners/alice-example/old-notes')).toMatchObject({ page: FOLDER_HOLD });
+ await settleManagedGitEffects(engine);
+ __resetPrivateVisibilityCacheForTests();
+ expect(await versionsText(as, 'bob', FOLDER_HOLD)).toContain(claim);
+ const exact = ['add', '--slug', ENTITY, '--readers', 'alice-example', '--source', 'default'];
+ const preview = await cli(engine, ['rule', ...exact, '--json']);
+ const [fact] = await factRows(engine, claim);
+ expect(preview.held_facts_moving).toEqual([{ fact_id: fact!.id, entity_slug: ENTITY, from: FOLDER_HOLD, to: ENTITY }]);
+ const applied = await cli(engine, ['rule', ...exact, '--yes', '--expect', String(preview.expect), '--json']);
+ expect(applied.held_facts).toEqual({ moved: preview.held_facts_moving.length, unmovable: [] });
+ expect(preview.held_versions_editing.pages).toEqual([{ slug: FOLDER_HOLD, rows: preview.held_versions_editing.rows, versions: preview.held_versions_editing.versions }]);
+ expect((await auditRows(engine)).map(r => r.audit)).toEqual([{ slug: FOLDER_HOLD, moved_to: ENTITY, fact_ids: [fact!.id], rows: preview.held_versions_editing.rows, versions: preview.held_versions_editing.versions }]);
+ expect(await auditSum(engine)).toEqual({ rows: preview.held_versions_editing.rows, versions: preview.held_versions_editing.versions });
+ expect(preview.held_versions_editing.versions).toBeGreaterThan(0);
+ await settleManagedGitEffects(engine);
+ __resetPrivateVisibilityCacheForTests();
+ expect(await versionsText(as, 'bob', FOLDER_HOLD)).not.toContain(claim);
+ expect(await factRows(engine, kept)).toMatchObject([{ source_markdown_slug: FOLDER_HOLD }]);
+ expect((await engine.getPage(FOLDER_HOLD, { sourceId: 'default' }))?.compiled_truth).toContain(kept);
+ expect((await as('bob', 'get_page', { slug: ENTITY })).isError).toBe(true);
+ expect(await reads(as, 'alice', ENTITY, claim)).toEqual({ page: true, fact: true });
+ }), 300_000);
+
+ test('the preview lists every held row the apply moves, says why one moves only because its page exists, and counts what the receipts record', () => strict(async ({ engine, ctx }) => {
+ const garden = 'The garden plan adds a pond.';
+ const claim = 'The acme-example brief carries a spaced clause.';
+ await remember(ctx, garden, 'notes/garden-plan');
+ await remember(ctx, claim, 'clients/acme-example/brief');
+ await settleManagedGitEffects(engine);
+ await call(ctx, 'put_page', { slug: 'notes/garden-plan', content: page('Garden plan') });
+ await settleManagedGitEffects(engine);
+ const [g] = await factRows(engine, garden);
+ const [a] = await engine.executeRaw<{ id: number }>("SELECT id::int AS id FROM facts WHERE source_id = 'default' AND entity_slug = 'clients/acme-example/brief' AND expired_at IS NULL");
+ const args = ['add', '--prefix', 'clients/acme-example/', '--readers', 'alice-example', '--source', 'default'];
+ const preview = await cli(engine, ['rule', ...args, '--json']);
+ expect(preview.held_facts_moving).toEqual([
+ { fact_id: a!.id, entity_slug: 'clients/acme-example/brief', from: HOLD, to: 'clients/acme-example/memory/unattributed' },
+ { fact_id: g!.id, entity_slug: 'notes/garden-plan', from: HOLD, to: 'notes/garden-plan', because: 'its page exists' }]);
+ expect(await humanLines(engine, 'rule', args)).toContain(`fact ${g!.id} for notes/garden-plan from ${HOLD} to notes/garden-plan (its page), because its page exists`);
+ const applied = await cli(engine, ['rule', ...args, '--yes', '--expect', String(preview.expect), '--json']);
+ expect(applied.held_facts).toEqual({ moved: preview.held_facts_moving.length, unmovable: [] });
+ expect(await factRows(engine, garden)).toMatchObject([{ source_markdown_slug: 'notes/garden-plan' }]);
+ expect(await auditSum(engine)).toEqual({ rows: preview.held_versions_editing.rows, versions: preview.held_versions_editing.versions });
+ expect(preview.held_versions_editing.versions).toBeGreaterThan(0);
+ }), 300_000);
+
+ test('an exact page rule that arrives by sync over a folder-held row: the excluded member reads nothing of it right after the sync; nothing changed, nothing is due', () => strict(async ({ engine, ctx, root }) => {
+ const as = await members(engine);
+ const { moveRuledSharedHeld } = await import('../src/core/facts/held-fact-move.ts');
+ const policy = (list: FolderRule[]) => commitPolicyFile(root, POLICY_FILE, () => serializePolicyYaml(list), 'access: rule');
+ const sync = () => performSync(engine, { sourceId: 'default', repoPath: root, noPull: true, noEmbed: true } as never);
+ policy([rule('partners', 'partners/', ['alice-example', 'bob-example'])]);
+ await sync();
+ const claim = 'The deal with acme-example has a synced side letter.';
+ expect(await remember(ctx, claim, ENTITY)).toMatchObject({ page: FOLDER_HOLD });
+ await settleManagedGitEffects(engine);
+ expect(await moveRuledSharedHeld(engine, 'default')).toBeNull();
+ __resetPrivateVisibilityCacheForTests();
+ expect(await reads(as, 'bob', FOLDER_HOLD, claim)).toEqual({ page: true, fact: true });
+ policy([rule('partners', 'partners/', ['alice-example', 'bob-example']), rule('deal', ENTITY, ['alice-example'])]);
+ await sync();
+ await settleManagedGitEffects(engine);
+ __resetPrivateVisibilityCacheForTests();
+ expect((await as('bob', 'get_page', { slug: FOLDER_HOLD })).text).not.toContain(claim);
+ expect((await as('bob', 'search', { query: claim, match: 'keyword', fields: 'full', limit: 20 })).text).not.toContain(claim);
+ expect((await as('bob', 'recall', { query: 'synced side letter' })).text).not.toContain(claim);
+ expect(await reads(as, 'alice', ENTITY, claim)).toEqual({ page: true, fact: true });
+ expect(await moveRuledSharedHeld(engine, 'default')).toBeNull();
+ }), 300_000);
+
+ test('struck held rows leave the holding page with their entity\'s live rows, and an entity with only struck rows leaves too', () => strict(async ({ engine, ctx }) => {
+ const as = await members(engine);
+ const gone = 'The acme-example brief once had a withdrawn clause.';
+ const memo = 'The acme-example memo was withdrawn entirely.';
+ const live = 'The acme-example brief carries a live clause.';
+ const quote = 'The garden plan quotes: The acme-example brief carries a live clause.';
+ for (const [claim, entity] of [[gone, 'clients/acme-example/brief'], [memo, 'clients/acme-example/memo']]) {
+ const saved = await remember(ctx, claim, entity);
+ await settleManagedGitEffects(engine);
+ await call(ctx, 'forget', { id: String(saved.id) });
+ }
+ await remember(ctx, live, 'clients/acme-example/brief');
+ await remember(ctx, quote, 'notes/garden-plan');
+ await settleManagedGitEffects(engine);
+ expect(await versionsText(as, 'bob', HOLD)).toContain(gone);
+ const args = ['add', '--prefix', 'clients/acme-example/', '--readers', 'alice-example', '--source', 'default'];
+ const preview = await cli(engine, ['rule', ...args, '--json']);
+ expect(preview.held_struck_rows_leaving).toBe(2);
+ const applied = await cli(engine, ['rule', ...args, '--yes', '--expect', String(preview.expect), '--json']);
+ expect(applied.held_facts).toEqual({ moved: 1, unmovable: [] });
+ expect(await auditSum(engine)).toEqual({ rows: preview.held_versions_editing.rows, versions: preview.held_versions_editing.versions });
+ await settleManagedGitEffects(engine);
+ __resetPrivateVisibilityCacheForTests();
+ for (const text of [(await as('bob', 'get_page', { slug: HOLD })).text, await versionsText(as, 'bob', HOLD)]) {
+ for (const hidden of [gone, memo, `| ${live} |`, 'clients/acme-example']) expect(text).not.toContain(hidden);
+ expect(text).toContain(quote);
+ }
+ const { moveRuledSharedHeld } = await import('../src/core/facts/held-fact-move.ts');
+ expect(await moveRuledSharedHeld(engine, 'default')).toBeNull();
+ expect((await runExtractFacts(engine, { sourceId: 'default' })).heldFactsMoved ?? 0).toBe(0);
+ }), 300_000);
+
+ test('a held-fact move still pending when the write wait ends is reported incomplete with its request, not counted as moved', () => strict(async ({ engine, ctx }) => {
+ await rules(engine, [rule('zz', 'zz-example/', ['alice-example'])]);
+ const garden = 'The garden plan adds a pending pond.';
+ await remember(ctx, garden, 'notes/garden-plan');
+ await call(ctx, 'put_page', { slug: 'notes/garden-plan', content: page('Garden plan') });
+ await settleManagedGitEffects(engine);
+ __setMaintenanceWriteWaitForTests(600);
+ const lock = (await acquireWorktree((await getWorktreeBinding(engine, 'default'))!, 1000))!;
+ let applied: Record<string, any>, words: string, upkeep: Awaited<ReturnType<typeof runExtractFacts>>;
+ try {
+ const args = (prefix: string) => ['add', '--prefix', prefix, '--readers', 'alice-example', '--source', 'default'];
+ applied = await cli(engine, ['rule', ...args('yy-example/'), '--yes', '--expect', String((await cli(engine, ['rule', ...args('yy-example/'), '--json'])).expect), '--json']);
+ words = await humanLines(engine, 'rule', [...args('xx-example/'), '--yes', '--expect', String((await cli(engine, ['rule', ...args('xx-example/'), '--json'])).expect)]);
+ upkeep = await runExtractFacts(engine, { sourceId: 'default' });
+ } finally { __setMaintenanceWriteWaitForTests(null); await lock.release(); }
+ await runExtractFacts(engine, { sourceId: 'default' });
+ const [pending] = await engine.executeRaw<{ request_id: string }>("SELECT request_id::text AS request_id FROM persistence_requests WHERE slug = 'notes/garden-plan' AND intent->>'kind' = 'managed_maintenance_move_held_fact'");
+ const request = pending!.request_id;
+ expect(applied.held_facts).toEqual({ moved: 0, unmovable: [], complete: false, pending: [{ slug: 'notes/garden-plan', from: HOLD, request_id: request }] });
+ expect(words).toContain(`Incomplete: the move of held facts off ${HOLD} to notes/garden-plan is accepted and still pending (request ${request}; gbrain write-request ${request} shows it)`);
+ expect(upkeep.heldFactsMoved ?? 0).toBe(0);
+ expect(upkeep.warnings.some(w => w.startsWith('HELD_FACT_PENDING: ') && w.includes(request))).toBe(true);
+ await settleManagedGitEffects(engine);
+ expect(await factRows(engine, garden)).toMatchObject([{ source_markdown_slug: 'notes/garden-plan' }]);
+ }), 300_000);
+
test('a source that is not strict, and a brain with no Git repository, keep a ruled entity\'s fact database-only as before', async () => {
await managedBrain(async ({ engine, ctx, root }) => {
await rules(engine, [rule('partners', 'partners/', ['alice-example'])]);