Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Keep each links-section row's own dates when a dropped section is re-created (GST-2228)

garrytan6dd16062149e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8b1d8ab6f4..3baa1137d5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,18 @@ credits are retained; no result has been reassigned to another provider. Origina
identifiers and attribution are available in the pre-removal Git revision
`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).
+## [Unreleased]
+
+**Each row of a page's `## Links` section now keeps its own dates, and a section that a rewrite dropped comes back with them.** A links row is keyed by target, type and source, but its `valid_from` and `valid_until` were stored per relationship (page, target, type) with no source. So two rows pointing at the same page with the same type shared one pool of dates, and after a page rewrite dropped the section, the next `add_link` wrote a section holding only the new link and deleted every other link of the old section, dates included. Dated statements now carry the row's source (`link_transitions.link_source`), and the identity index includes it. `add_link` on a page whose section is gone puts every kept row back with its own dates, `remove_link` deletes the removed row's own dates for any source (not only `manual`), and two rows that share a date both keep it. Dates stored before this change have no source: with one kept row they are that row's, and with several kept rows for one target and type the writer refuses `link_dates_unattributed` and asks for the section back through `edit_page`, instead of guessing. `append_page` now refuses text holding a links fence marker (`append_links_fence`); write links with `add_link`. A row of a dropped section whose target page never existed never became a link, so it is not brought back.
+
+### Itemized changes
+
+- Migration v297 (`src/core/schema-migrations/v297-link-transitions-source.ts`): adds the nullable `link_transitions.link_source` column (metadata only, under the schema lock timeout), builds the widened unique identity index online under a temporary name (`CREATE UNIQUE INDEX CONCURRENTLY` on Postgres), then swaps it in with one short drop-and-rename transaction. No row is rewritten. Requires Postgres 15, as gbrain already does since v011. The forward-reference bootstrap adds the column before the schema replay on an older brain.
+- `src/core/links-fence-projection.ts`: manual statements are written with their row's source and compared per row, so a row whose dates change replaces only its own.
+- `src/core/persistence/manual-links.ts`: `add_link` re-creates a dropped links section from the kept edges, each with its own dates; `remove_link` deletes the removed rows' own statements; both refuse `link_dates_unattributed` (`src/core/error-registry.ts`) when sourceless statements cannot be given to one row exactly.
+- `src/core/persistence/page-append.ts`: links fence markers in appended text refuse `append_links_fence`, whose fix names `add_link`.
+- Tests: `test/link-dates-per-row-gst2228.test.ts` (managed brain, repo-less and Git, PGLite and Postgres), `test/link-transitions-source-migration-gst2228.test.ts` (upgrade, interrupted runs, an invalid leftover index, writes between the column and the swap).
+
## [0.60.627.0] - 2026-11-09
**A webhook capture can no longer drop a page's readers (GST-2112).** `POST /ingest` wrote through a trusted local path whose only check was that the sender could read the page, so a member-bound token granted a source could replace a page whose `readable_by` named it with a body that named no readers, and every caller could then read the page. The route and the `ingest_capture` job now apply the remote `put_page` readers rule: a body that drops `readable_by` from a page that names readers, or names readers that leave out the sender, is refused `readable_by_invalid` (403 at the route, nothing queued; at write time for a job already queued). The job binds its write to the revision it checked, so readers added between the check and the write refuse the write with `revision_conflict` and the retry refuses `readable_by_invalid`. A capture already queued from a member-bound credential whose write source is `default` is refused `permission_denied` at write time, as the route refuses it before queueing. Bodies that keep the readers, and pages without readers, import as before.
diff --git a/docs/architecture/key-files/core-persistence-continued.md b/docs/architecture/key-files/core-persistence-continued.md
index d4dc45df41..da3759231c 100644
--- a/docs/architecture/key-files/core-persistence-continued.md
+++ b/docs/architecture/key-files/core-persistence-continued.md
@@ -6,7 +6,7 @@ The #6188 fence check and fence repair live in [fence repair](core-fence-repair.
- `src/core/persistence/{types,params,preconditions,verb-errors}.ts` — public mutation receipt states, error reasons and revision/idempotency parameter contracts. Receipt serialization explicitly selects public fields; queued content and execution credentials stay internal. `frozenVerbWriteError` uses MEMORY_VERBS v1's existing error enum with additive `write_request`/`write_error`; `page_body_segmented` is a write error code, so a verb refused by a segmented target keeps it as `write_error` and canonical code under the frozen `invalid_params` (caller class, not retryable) on both the receipt and the pre-admission path (`runMemoryWrite`). `remember` reads a segmented entity page up to PAGE_MAX_BYTES back whole (`materializedPage`) for its inferred-target checks and fence write; over it, a named or inferred entity refuses before admission with `segmentedRememberRefusal` (fix: remember with `infer_entity: false`), never a silent `NO_ENTITY` (`test/large-pages/segmented-remember-refusal.test.ts`); `committedVerbOutcome` refuses pending or failed receipts. `OperationError` and the thin MCP client preserve this metadata, including when a timeout races an already-received receipt. The registry-safe parameter/schema leaf never imports operation values. Pinned by `test/persistence-write-contracts.test.ts`, `test/mcp-client-hardening.test.ts` and a real HTTP envelope in `test/mcp-client.test.ts`.
- `src/core/persistence/database-write.ts` — `coordinatedDatabaseWrite` is the managed path for rows with no canonical file; `ontology_propose` (one entity page key) uses it. On a managed brain it checks the caller's durable write authority for the authority page (`submissionAuthority`, then `authorizeWrite` FOR SHARE inside the transaction), revalidates the source incarnation and commits inside `withCoordinatedWrite` holding the given page keys. Unmanaged brains keep the engine calls. Tests: `test/managed-ontology-propose.test.ts`.
-- `src/core/persistence/manual-links.ts` — `prepareManualLinkMutation`, the preparer of the `add_link` / `remove_link` page mutations a managed brain submits (G5, dispatched from `service.ts`; on the IPC and semantic re-prepare lists, kept-tier fence edits in `trust/page-write.ts`). The authored edge is a row of the from page's `## Links` fence (`links-fence.ts`): the preparer upserts or removes the row at the snapshot's revision (a segmented page read back whole through `wholeBodySnapshot`) and publishes the page with `preparePageMutation`; the publication's canonical projection and the apply both project the fence (`links-fence-projection.ts`), so an idempotent add (fence unchanged, a no-op publication) still has its edge. `add_link` also deletes the database-only twin of the edge it fences (same endpoints, type and provenance, no origin); `remove_link` deletes the matching database-only edges (origin_field not `links_fence`, a provenance outside `MANAGED_LINK_SOURCES`) and, when the body has no fence, the orphaned fence edges, with their manual dated statements, and reports `removed` as the edge count it took away; edges a reconciliation producer derives from the text stay, and the result names them (`derived_from_text: [{ link_type, link_source }]` plus a `message` to edit the page text instead). The op handlers keep their validation, `dry_run` and result shape (`{ status }`, `{ status, removed }`); unmanaged brains keep the engine calls. Tests: `test/managed-links-fence.test.ts` (+ Postgres arm), `test/managed-writers-w3.test.ts`.
+- `src/core/persistence/manual-links.ts` — `prepareManualLinkMutation`, the preparer of the `add_link` / `remove_link` page mutations a managed brain submits (G5, dispatched from `service.ts`; on the IPC and semantic re-prepare lists, kept-tier fence edits in `trust/page-write.ts`). The authored edge is a row of the from page's `## Links` fence (`links-fence.ts`): the preparer upserts or removes the row at the snapshot's revision (a segmented page read back whole through `wholeBodySnapshot`) and publishes the page with `preparePageMutation`; the publication's canonical projection and the apply both project the fence (`links-fence-projection.ts`), so an idempotent add (fence unchanged, a no-op publication) still has its edge. `add_link` also deletes the database-only twin of the edge it fences (same endpoints, type and provenance, no origin), and on a body with no fence it first renders the kept fence edges into the section it creates, each with the dated statements stored under its own source (`keptLinksFenceRows`); statements with no source (written before link_transitions had a `link_source` column) go to a relationship's only row when they fit it, and otherwise the write refuses `link_dates_unattributed`. `remove_link` deletes the matching database-only edges (origin_field not `links_fence`, a provenance outside `MANAGED_LINK_SOURCES`) with their database-only manual statements and, when the body has no fence, the orphaned fence edges with the statements of their own source (it refuses `link_dates_unattributed` when sourceless statements would have to be split between a removed row and a kept one), and reports `removed` as the edge count it took away; edges a reconciliation producer derives from the text stay, and the result names them (`derived_from_text: [{ link_type, link_source }]` plus a `message` to edit the page text instead). The op handlers keep their validation, `dry_run` and result shape (`{ status }`, `{ status, removed }`); unmanaged brains keep the engine calls. Tests: `test/managed-links-fence.test.ts` (+ Postgres arm), `test/managed-writers-w3.test.ts`.
- `src/core/persistence/{attribution,attribution-schema,context}.ts` — write attribution. `withCoordinatedWrite(engine, sourceIds, fn, attribution)` sets `gbrain.write_sources` and the transaction-local actor (`gbrain.write_request`, `gbrain.write_principal_kind`, `gbrain.write_principal_id`) in one round trip and restores them on exit; a nested scope keeps the outer actor. The argument is required: `requestAttribution(row)` for journaled publication (coordinator, forget), `maintenanceAttribution(engine)` (verified local writer, else the CLI registration, else `application`/`host:<id>`; no request) for derived facts, takes/timeline/link extraction, materialization, concept provenance, connector freshness and verify cleanup, `principalAttribution` for manual links (the caller) and source lifecycle (the topology principal). `withWriteAttribution` sets only the actor, for unmanaged legacy transactions; `maintenanceTransaction(engine, fn)` wraps it in one transaction, and every unmanaged direct writer runs its write (or one bounded batch) in it (the `system-of-record.md` "unattributed" list is empty; derivers pass their taint as `maintenanceTransaction(engine, fn, trust)`, see `trust/taint.ts`). `attribution-schema.ts` (migration `f1_write_attribution`; migration-only like the facts DDL, so columns land last on fresh and upgraded brains) adds nullable columns and BEFORE ROW triggers: `facts`/`takes`/`timeline_entries` carry `write_*` (created_by, immutable once set) and `last_write_*` + `last_written_at` (moved only when a classified content column changes; a NULL actor records an unattributed writer; under `gbrain.fact_withdrawal_stamp`, which only the facts insert guard sets, a facts update of `expired_at`/`valid_until` alone keeps them, migration v264); `pages.revision_*` is stamped when `knowledge_revision` changes; `page_versions.write_*` copies the snapshotted revision's actor and `archived_*` names the archiving write. `write_request_id` is `persistence_requests.id` with no foreign key; all-NULL reads as unrecorded. Every column of the three tables is classified content, projection (embeddings, `takes.updated_at`) or attribution, and a new column must be classified and the function re-created; the writer guard treats attribution-only facts/takes updates as projections. Tests: `test/write-attribution.test.ts`, `test/write-attribution-legacy.test.ts` (writer inventory) and `test/write-attribution-<family>.test.ts` (each routed unmanaged writer path; `write-attribution-timeline-10k.slow.test.ts` checks bounded batches at 10k pages) on PGLite; Postgres direct and PgBouncer through `test/e2e/write-attribution-postgres.test.ts`.
- `src/core/persistence/loop-fact-retirement.ts` — #5869 commitment-fact retirement for closed loops, one coordinator mutation on every brain (operation `loops_close`, intent `retire_loop_fact`, dispatched from `service.ts`): expires the fact and strikes its `## Facts` fence row (context `loop closed: <status>`) through the entity page publication in one transaction; no withdrawal tombstone. The shared rule (also `loopFactDrift`, used by doctor `loop_facts_drift` and `gbrain repair loop-facts`): only a fact in the loop's source that no other open loop references, re-checked under row locks at publication (`shared_with_open_loop`, `source_mismatch` otherwise). `retireLoopFact(ctx, loopId)` submits with the caller's grant and maps a refusal or pending write to `fact_expired: false, retryable: true, reason`. Tests: `test/loops-close-fact.serial.test.ts` (+ Postgres twin).
- `src/core/persistence/connector-authority.ts` -- classifies each Google/GitHub source as `connector_database` (managed, unbound), `bound` or `unmanaged` from `persistence_brain.enabled` and the source binding row. File-lane audits (doctor `undeclared_db_only_pages`, backup coverage) read it so a leftover cache directory at `local_path` is never taken for canonical files. Tests: `test/doctor-silent-death-checks.test.ts`, `test/backup-coverage.serial.test.ts`.
@@ -40,5 +40,5 @@ The #6188 fence check and fence repair live in [fence repair](core-fence-repair.
- Foreground priority (#5984 Phase 4.5, `foreground_priority` switch, `journal.ts`): `claimableWriteSql` lets a non-sync request pass earlier queued sync rows of its root that have not started and do not name its page (slug, page id or `intent.renameFrom.slug`), claims it first, and holds a passed sync row while that request runs; `claimNextLaneHead` starts no lane head while such a request is unfinished, except one head per foreground commit since the run's last head claim (`seen_sequence`). A write queued behind an earlier queued write that waits on a sync row naming its page holds back nothing, since it cannot go first either (pinned by `test/claim-fifo-foreground-waiting.test.ts`). Both claims find that commit through `FOREGROUND_WAITING_ON`'s probe, served by `persistence_requests_foreground_committed` (#7649, a partial index on committed non-sync rows by worktree and sequence, see [request indexes](core-persistence-request-indexes.md)), so a consumer's first claims after a restart, when the bound is 0, stay index probes on a large request table. A consumer whose claimed write passed sync rows (`passed_sync`) claims plain FIFO on that root after it commits (`owesSyncTurn`), so a stream of writes cannot starve the drain. The sync side's pauses (no admit-ahead for 60 s after a write, no group while one is queued, the 25-page credit wait) apply only with the switch off. Receipt health judges a claimed write only against earlier started writes. Pinned by `test/managed-sync-foreground-priority.test.ts` (two processes) and `test/persistence-diagnostics.test.ts`.
- `src/core/postgres-engine/reserved-transactions.ts` with `isPersistenceDeclaration` (`src/core/persistence/protocol.ts`) — BEGIN pipelining. `isPersistenceDeclaration` (GBRA-156) accepts exactly the `protocol.ts` declarations (transaction-local `set_config` calls and the brain row FOR SHARE). Admission, the FIFO claim, the effect claims and source guards, the receipt true-up, the single publication (`coordinator.ts`) and the consumer's lent lane transactions (`consumer.ts` `onLane`, through `reservedTransactions`) pass it as `TransactionOptions.pipelineFirst`, so behind a transaction-mode pooler the declaration goes out with BEGIN (one round trip less per transaction) while every later statement still waits for BEGIN's answer; if BEGIN fails, only the declaration has run, in autocommit, where it changes nothing. A reserved transaction gates every statement its body can reach, savepoint and nested-transaction bodies and `file()` included. A sync lane group's publication passes none: its begun mark must follow BEGIN's answer (`sync-lanes.ts` `awaitLaneBegin`). Tests: `test/persistence-pipeline-first.test.ts` (the predicate and the reviewed call sites), `test/e2e/pgbouncer-transaction-pipeline-6930.test.ts`.
-- `src/core/links-fence.ts` + `src/core/links-fence-projection.ts` — the `## Links` fence (G5): the markdown form of authored (manual) edges, `<!--- gbrain:links:begin -->` / `end` around `| to | type | source | valid_from | valid_until | context |`, one row per (to, type, source), source defaulting to `manual`; a reconciliation-managed provenance (`MANAGED_LINK_SOURCES`, exported here and re-exported by `ops/links.ts`), a bad date or a duplicate key is a skipped row with a warning. `parseLinksFence` (state `absent` / `parsed` / `malformed`), the deterministic `renderLinksFence` (rows sorted by key), `upsertLinksFenceRow` (omitted context and dates keep the stored ones; identical row = unchanged body), `removeLinksFenceRows` (leaves an empty fence), `replaceOrInsertLinksFence` (a `## Links` section at the end of compiled_truth, above an unclosed code block) and `maskLinksFence`, which `extractBodyLinks` applies so the fence cells are never also extracted as markdown, wikilink or bare-slug edges. A rewrite of a fence that parses with warnings throws `LinksFenceRewriteRefusal`. Cells use `escapeFenceCell` plus the same one-level marker encoding for `gbrain:links:*`. `projectLinksFence(tx, page, rows)` reconciles only what the page's fence owns: edges with origin_page_id = the page and origin_field `links_fence` (deleted, context-updated, inserted by key) and `manual` transitions with origin_page_id = the page, then refreshes the touched relationships; a row whose target is not a live page in the source yields no edge. `linksFenceProjectionRows` returns null for an absent or malformed fence, so such a body changes no edge (an absent fence retires nothing, as for facts; unlike facts no held generation is recorded, so after a hand deletion of the whole section the database keeps edges git no longer has until `remove_link` or the G3 indexer), and drops rows typed with a link type the active pack does not declare. Callers: `prepareCanonicalProjections` (every projected page publication, quarantined and segmented-unread bodies excepted), `prepareAutomaticLinks` (put_page auto-links and the managed links maintenance, so `extract --stale` restores a lost fence edge) and `persistence/manual-links.ts`. Database-only manual edges (origin_field NULL) are never touched by any of them. Pinned by `test/links-fence.test.ts` and `test/managed-links-fence.test.ts`.
+- `src/core/links-fence.ts` + `src/core/links-fence-projection.ts` — the `## Links` fence (G5): the markdown form of authored (manual) edges, `<!--- gbrain:links:begin -->` / `end` around `| to | type | source | valid_from | valid_until | context |`, one row per (to, type, source), source defaulting to `manual`; a reconciliation-managed provenance (`MANAGED_LINK_SOURCES`, exported here and re-exported by `ops/links.ts`), a bad date or a duplicate key is a skipped row with a warning. `parseLinksFence` (state `absent` / `parsed` / `malformed`), the deterministic `renderLinksFence` (rows sorted by key), `upsertLinksFenceRow` (omitted context and dates keep the stored ones; identical row = unchanged body), `removeLinksFenceRows` (leaves an empty fence), `replaceOrInsertLinksFence` (a `## Links` section at the end of compiled_truth, above an unclosed code block) and `maskLinksFence`, which `extractBodyLinks` applies so the fence cells are never also extracted as markdown, wikilink or bare-slug edges. A rewrite of a fence that parses with warnings throws `LinksFenceRewriteRefusal`. Cells use `escapeFenceCell` plus the same one-level marker encoding for `gbrain:links:*`. `projectLinksFence(tx, page, rows)` reconciles only what the page's fence owns: edges with origin_page_id = the page and origin_field `links_fence` (deleted, context-updated, inserted by key) and `manual` transitions with origin_page_id = the page, compared per row by (to, type, link_source, kind, date) and written with the row's source in `link_source`, then refreshes the touched relationships; a row whose target is not a live page in the source yields no edge. `linksFenceProjectionRows` returns null for an absent or malformed fence, so such a body changes no edge (an absent fence retires nothing, as for facts; unlike facts no held generation is recorded, so after a hand deletion of the whole section the database keeps edges git no longer has until `remove_link` or the G3 indexer), and drops rows typed with a link type the active pack does not declare. Callers: `prepareCanonicalProjections` (every projected page publication, quarantined and segmented-unread bodies excepted), `prepareAutomaticLinks` (put_page auto-links and the managed links maintenance, so `extract --stale` restores a lost fence edge) and `persistence/manual-links.ts`. Database-only manual edges (origin_field NULL) are never touched by any of them. Pinned by `test/links-fence.test.ts` and `test/managed-links-fence.test.ts`.
- `src/core/persistence/source-lifecycle.ts` retire batches with `topology-transaction.ts` (#7702/#8905) — every `topologyTransaction` runs under `statement_timeout=5s` and `lock_timeout=1s` and maps SQLSTATE 57014/55P03 to `write_pending`, so a managed `remove` or `purge` first deletes the source's pages in batches of `SOURCE_RETIRE_BATCH_PAGES` (500; about 110 ms per batch with chunks and links on Postgres) under the native locks `withTopologyLocks` holds, each batch its own `topologyTransaction`. A batch re-checks the final transaction's preconditions (admin state, `lockTopologyRows`, the incarnation read before the locks, archived or `EXPIRED_ARCHIVE_SQL` due, no prior receipt, no `oauth_clients` reference, `assertTopologyRequestsSettled` from `topology-locks.ts`, `lockTopologyPrincipal`, and `assertTopologyChangeCapacity` from `topology-receipts.ts`, the receipt quotas at the largest receipt) and, when one would refuse or replay, stops without deleting so the final transaction reports it, or throws that refusal before deleting; a batch that fails `write_pending` is retried at half the size (floor 1), so heavy pages still fit the bound; a refusal after some batches committed says how many pages that run already deleted; a dry run, a missing checkout, an unconfirmed operation and an admission-hooked call never batch. Each batch deletes inside `withCoordinatedWrite` with local-CLI attribution (the `pages` guard needs the source in `gbrain.write_sources`; only the final `sources` delete sets `gbrain.topology_change`). Committed batches are durable: a retry (same or new request_id) resumes, and the receipt's `pages_deleted` counts the pages deleted by the run that commits it. Tests: `test/source-retire-batched.test.ts` (PGLite) and `test/e2e/source-retire-batched-postgres.test.ts` (60,000 pages).
diff --git a/docs/architecture/key-files/core-services-2-continued.md b/docs/architecture/key-files/core-services-2-continued.md
index f5e43d4dc0..990618b29d 100644
--- a/docs/architecture/key-files/core-services-2-continued.md
+++ b/docs/architecture/key-files/core-services-2-continued.md
@@ -47,7 +47,7 @@ The page-state concurrency foundation under `src/core/page-state/` and the share
Writes that change part of a page in time proportional to the change (Wave B spec 6.1, 6.3): `append_page`, segmented `edit_page` and the splice engine both use. Tests: `test/large-pages/append-cost.test.ts`, `test/large-pages/append-concurrency.test.ts` and `test/large-pages/edit-segmented.test.ts`, PGLite and Postgres (helper `test/helpers/append-brain.ts`).
- `src/core/page-body/splice.ts` + `tail-digest.ts` — byte-range splices of a segmented body. `spliceSegmentedBody` replaces stored byte ranges of the live generation (`BodyReplacement`) and stages the next one from the touched segments only: segmentation resumes at the last clean entry point before the first replaced byte and stops at the first old boundary whose entry state the new run reproduces, so later segments keep their bytes, text and chunks and only move (new manifest rows under the same occurrence; content_hash midstate recomputed). An append is an insertion at its region's end: it re-segments the old tail plus the text and moves nothing; an insertion at the truth/timeline boundary belongs to truth (`replacementRegion`), so exactly one row owns it. New segments equal to a replaced one keep its occurrence; the rest are chunked with vectors reused by chunk text. A change that flips a region's fence trust restages the whole body (`rescanned`). `splicePage` reads the page row a splice needs (generation, region sizes, cr tier, corpus generation, kind); `spliceWork` counts segments segmented, bytes read and manifest rows (the cost tests' work counters). `tail-digest.ts` is the append precondition's digest for inline pages, sha256 of a region's last min(4096, region bytes) raw stored bytes (`inlineTailDigest`; segmented pages use `page-window/segmented.ts` `tailDigest`); a tail holding facts or takes text is withheld from a remote caller, since a hash of hidden text is a guessing oracle. The cost test pins that a 10 KB append to a 4 MB and a 16 MB page segments only the tail plus the text, and a forced full-rewrite probe (`appendProbe.fullRewrite`) fails the bound.
-- `src/core/persistence/page-append.ts` — `append_page`: text added to the end of a region (`region` auto/truth/timeline, `separator` auto/none), idempotent by `request_id`. `admitPageAppend` (also the upload lane's `commit_page_upload` append entry, with a staged `body_ref`) journals the text or the reference, never the body; text is capped at `APPEND_TEXT_MAX_BYTES` (4 MiB), a fence marker in it refuses `invalid_params`, and a missing or deleted page refuses `page_not_found`. `prepareAppendMutation` checks the optional preconditions on the locked snapshot (`expected_revision` gives `revision_changed`; `expected_tail_sha256` gives `tail_changed`, whose fix carries the current tail digest). A segmented page splices onto its region's tail through `prepareSegmentedSpliceMutation`, which segmented edit_page and append-mode upload commits share. It refuses a result over `pages.max_bytes` as a streamed import does (`file_too_large`, nothing written), and runs put_page's write gate over the new text only (title, frontmatter and the replacement bytes, O(text)): a flag verdict sets `content_flag` (`instruction_like`), records the page gate receipt and returns put_page's `gate` field; an allowed append never clears an existing flag, since the stored text was not re-read; it declines (null, whole-body path) for an always-loaded core page, an external_untrusted write the write gate scans whole, a change that creates or empties a region, or a file a withdrawal ledger rewrites. An inline page composes the new body on put_page's path, which promotes it past the segmented threshold. Chunks and embeddings of the appended text follow commit as for any segmented write. A remote append to the compiled truth records the bytes it added (`PreparedMutation.mentionRange`: stored truth offsets and their SHA-256, from the splice or, inline, the parsed appended bytes placed at the end of the stored truth after publication, so a Tier 1 fence normalization before them cannot shift the range) and queues a `links` effect carrying them (`data.range`, #7122; see `effect-links.ts`); timeline rows and fence projections of appended text wait for PR 4's incremental derivation. A file-backed segmented page's canonical file gains the appended bytes, its frontmatter rendered in stored key order as inline edit_page and append write-through render it.
+- `src/core/persistence/page-append.ts` — `append_page`: text added to the end of a region (`region` auto/truth/timeline, `separator` auto/none), idempotent by `request_id`. `admitPageAppend` (also the upload lane's `commit_page_upload` append entry, with a staged `body_ref`) journals the text or the reference, never the body; text is capped at `APPEND_TEXT_MAX_BYTES` (4 MiB), a facts or takes fence marker in it refuses `invalid_params` and a links fence marker `append_links_fence` (write links with `add_link`), and a missing or deleted page refuses `page_not_found`. `prepareAppendMutation` checks the optional preconditions on the locked snapshot (`expected_revision` gives `revision_changed`; `expected_tail_sha256` gives `tail_changed`, whose fix carries the current tail digest). A segmented page splices onto its region's tail through `prepareSegmentedSpliceMutation`, which segmented edit_page and append-mode upload commits share. It refuses a result over `pages.max_bytes` as a streamed import does (`file_too_large`, nothing written), and runs put_page's write gate over the new text only (title, frontmatter and the replacement bytes, O(text)): a flag verdict sets `content_flag` (`instruction_like`), records the page gate receipt and returns put_page's `gate` field; an allowed append never clears an existing flag, since the stored text was not re-read; it declines (null, whole-body path) for an always-loaded core page, an external_untrusted write the write gate scans whole, a change that creates or empties a region, or a file a withdrawal ledger rewrites. An inline page composes the new body on put_page's path, which promotes it past the segmented threshold. Chunks and embeddings of the appended text follow commit as for any segmented write. A remote append to the compiled truth records the bytes it added (`PreparedMutation.mentionRange`: stored truth offsets and their SHA-256, from the splice or, inline, the parsed appended bytes placed at the end of the stored truth after publication, so a Tier 1 fence normalization before them cannot shift the range) and queues a `links` effect carrying them (`data.range`, #7122; see `effect-links.ts`); timeline rows and fence projections of appended text wait for PR 4's incremental derivation. A file-backed segmented page's canonical file gains the appended bytes, its frontmatter rendered in stored key order as inline edit_page and append write-through render it.
- `src/core/ops/page-append.ts` — the `append_page` operation (write scope, client slug-fence allowlist, `outputRedaction: 'no_stored_text'`): params `{slug, source_id?, text, request_id, expected_revision?, expected_tail_sha256?, region?, separator?}`, returns `{slug, revision, body_bytes, appended_bytes, chunks_new, size_state, receipt}`. get_page's `body: 'none'` returns `tail_sha256` and `tail_region` for inline and segmented pages, and its window reads return `edit_target: {revision, byte_start, byte_end}` in stored coordinates (`ops/get-page-body.ts` `editTarget`), withheld from a remote caller when hidden text precedes the window end (`read-range.ts` `hiddenBefore`).
Segmented edit_page (`persistence/page-edit.ts`, entry in [Core Persistence](core-persistence.md)): optional `within: {byte_start, byte_end}` (stored coordinates, as `edit_target` returns them; `parseEditWithin`, `edit_invalid`) limits matching to one range, and a range the page no longer holds refuses `revision_conflict`. A remote caller's `within` refuses `edit_invalid` (one refusal for every range and edit, before any match or fence check) when hidden text starts before `byte_end`: on a segmented page the read projection's hidden units (`read-range.ts` `hiddenBefore`, the predicate `editTarget` withholds `edit_target` by), on an inline page a fence whose remote view differs from its stored text; such a range would measure the hidden text. A segmented page is never materialized: `prepareSegmentedEditMutation` (called first by `page-prepare.ts` `preparePageMutation`) finds each old_text by a streaming scan across segment boundaries (`locateSegmentedEdits`, with applyPageEdits' exactly-once, protected-span and remote-view rules; the scan keeps at most two matches per edit and refuses `edit_ambiguous_match` at the second, counted in `spliceWork.matches`) and splices the touched range; the receipt diff covers the touched range plus 2 KB of context, and only the first replacement past 256 KB (`diff_truncated`); its context never starts at or inside hidden facts or takes text, nor ends inside it, and its hunk lines count the caller's view (`viewNewlinesBefore`: row line counts plus, for a remote caller, each hidden run before the diff rendered as `sanitizeRemoteBody` renders it). With a withdrawal ledger that applies, the scan, the diff and those line counts read the page through its withdrawal overlay (`storedPieces` over `trustedSegments`, rows widened to whole fence blocks), on every path; a match into a block the overlay rewrote is never kept. A segmented page's remote edit view hides withdrawn rows as its remote windows do (`SEGMENTED_REMOTE_VIEW`, also on the whole-body path). A stored fence that does not compile refuses as applyPageEdits refuses it (typed `target_fence_malformed`, same location), at submission (`assertSegmentedEditFences`) and again at preparation: `scanCanonicalFences` runs over the stored fence text alone, each piece at its own line, so only segments holding fence text are read; with `within`, only the fences in the touched segments and those crossing into them. It declines to the whole-body path for an old_text naming the timeline sentinel or also found in the frontmatter head, or a miss without `within` on a page within the single-string ceiling.
diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.md
index 917a8556ba..f3f03314da 100644
--- a/docs/guides/error-codes.md
+++ b/docs/guides/error-codes.md
@@ -276,6 +276,14 @@ More: [docs/guides/retrieval-feedback.md#answer_unavailable](../../docs/guides/r
More: [docs/guides/google-connect.md#troubleshooting](../../docs/guides/google-connect.md#troubleshooting)
+### append_links_fence
+
+<a id="append_links_fence"></a>
+
+| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
+|---|---|---|---|---|---|---|
+| append_page text held a links fence marker, so nothing was appended. | A page has one links section, and the rows it lists are the page's authored links: an appended links table would replace that section and delete every link it does not list. | Write each link with add_link (from, to, link_type); it adds the row to the page's links section and keeps the rows already there. | agent | `repeat the read that failed` | 1 | no |
+
### approval_required
<a id="approval_required"></a>
@@ -2820,6 +2828,16 @@ More: [docs/guides/repair.md#legacy-twins](../../docs/guides/repair.md#legacy-tw
|---|---|---|---|---|---|---|
| A get_links / get_backlinks cursor was not one this listing returned: it belongs to another slug, direction, source scope or filter set, or is not a cursor. | A cursor is a link-id position bound to the exact listing that issued it; continuing a different listing from it could skip or repeat edges without saying so. Nothing was read. | Restart the listing with the same slug and filters and no cursor, then pass each next_cursor unchanged. Run: gbrain links '{slug}' | agent | `repeat the read that failed` | 1 | no |
+### link_dates_unattributed
+
+<a id="link_dates_unattributed"></a>
+
+| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
+|---|---|---|---|---|---|---|
+| add_link or remove_link would re-create or change a links section whose dated statements were stored before each row kept its own dates, and gbrain cannot tell which row each date belongs to; nothing was changed. | Each row of a page's links section (target, type, source) keeps its own valid_from and valid_until. Statements stored before that have no source: with several rows for one target and type, or dates that do not fit the one row, any pairing would be a guess that could put one row's dates on another. | Add the page's ## Links section back with edit_page, one row per source with that row's own valid_from and valid_until, then submit the request again. | agent | `repeat the read that failed` | 1 | no |
+
+Reasons: `several_rows`, `dates_do_not_fit`.
+
### local_conflict
<a id="local_conflict"></a>
diff --git a/docs/guides/temporal-edges.md b/docs/guides/temporal-edges.md
index 44805fe3ac..eafc1726c5 100644
--- a/docs/guides/temporal-edges.md
+++ b/docs/guides/temporal-edges.md
@@ -82,6 +82,12 @@ the page states:
Re-run `add_link` with `valid_until` to record that a relationship ended. On a
managed brain the edge and its dates are a row of the from page's `## Links` table
(`<!--- gbrain:links:begin -->`); editing or deleting that row edits or removes the edge.
+ Each row (target, type, source) keeps its own dates: if a rewrite drops the section,
+ the next `add_link` puts every kept row back with its own dates, and `remove_link`
+ with a `link_source` removes that row's dates only. Dates stored before rows kept
+ their source have none; when such dates sit on a target and type with several rows and the section
+ is gone, `add_link` and `remove_link` refuse `link_dates_unattributed` and ask you to
+ add the section back with `edit_page`, one row per source with its own dates.
Dated evidence beats undated evidence from any page: a closure on a person's timeline
ends the relationship even if the company page still lists them under `key_people`.
diff --git a/scripts/module-size-limits.tsv b/scripts/module-size-limits.tsv
index b2e0155d34..5d43df1e4f 100644
--- a/scripts/module-size-limits.tsv
+++ b/scripts/module-size-limits.tsv
@@ -47,4 +47,4 @@ src/commands/doctor/checks/extraction-sync.ts 1500 ratchet +7 GBRA-130 A-1: link
src/core/search/evidence-delivery.ts 1759 ratchet +5 W5: EvidencePlan.rankCut resolved with the plan (logic in search/page-rank-cut.ts); +20 W5 whole_pages: wholeCost prices a block as delivery would emit it whole (needs the private Block/enrichBlock internals) and the cut is wired before allocate (cutWholePages lives in search/page-rank-cut.ts); new row: crossed the 1500 unlisted cap at the #6367 merge (master 1479, its explicit-budget cap) by the C1 date header threaded through every block path, cap included; pagePlanHits (search/page-plan-hits.ts) and the header loader (evidence-date.ts blockDateHeaders) were peeled first; peel candidate: allocateCapped; +8 at the #6396 merge: page evidence text cut through the fence-chunk trust overlay and the caller minTrust floor (re-summed: our 1504 + master +8); +119 Cat 40 next wave F2: the search.long_page_unit policy (withLongPagePolicy, selectLongPages size preflight with page/byte/deadline limits) and the long-page fetch and fallback in deliverEvidence, kept in the shared seam the plan names (gbrain-evals docs/plans/2026-10-11-cat40-next-wave, F2); +17 F2 rework to the frozen-comparison policy: search.long_page_min_chars (rendered-body characters, default 20,000) read in withLongPagePolicy, a character count in the preflight, the rendered-body confirmation in deliverEvidence, and the long-page row exemption in capDeliveredSnippets (re-summed at the 0.60.225.0 merge: master 1537 + F2 136); +39 Wave B PR 2 lane 2b: planSegmentedBlock joins the windows search/segmented-evidence.ts reads around a segmented page's hits into one run-marked document (needs the private Doc/Piece/buildDoc/locateAnchor internals), planBlock's unit cut split into blockFromDoc for both, sections bounded by their run, selectionCost counts a gap between runs, and the fetch skips the whole-body fence overlay for a segmented page; +4 segmented pages read at once before planning (segmentedReads; the read is search/segmented-evidence.ts, the statements page-body/read-range.ts); +17 GBRA-156: tail trim plan flag, DeliverOptions.query, DeliveryMeta.tail_trim, the trim call and the frozen-hit score/query library fields (logic in search/evidence-tail-trim.ts; interface fields cannot move); +7 GBRA-205: EvidencePlan.titleHeader and DeliveryMeta.title_header (interface fields cannot move) and the titles option on the header loader (logic in search/evidence-date.ts; the query budget key lives in search/evidence-packing.ts); +11 #7600: assemble_evidence quotes conversation rows and capEvidenceToBudget counts the quote fence (logic in search/transcript-quote.ts); +2 GBRA-156 /ship review: the cut-path admission and title room count the quote fence; +2 GBRA-156 /ship review pass 2: capEvidenceToBudget counts the fence only for the paths that fence (quote flag; recall counts the text as returned); +4 GST-687: page evidence and the extractive fallback quote below-owner-tier text for untrusted readers (untrusted flag; logic in search/transcript-quote.ts)
src/commands/config.ts 1526 ratchet +1 GBRA-216: recall.* config set value refusal (facts/recall-config.ts); +1 GBRA-216: config set refuses a dream.claim_conflicts.mode other than propose|off (refusal in facts/claim-conflicts.ts); new row: crossed the 1500 unlisted cap in wave 15 P7.4 #5461: set-time validation of think.pages_budget_chars / think.excerpt_ceiling_chars (range + parser live in core/think/pages-budget.ts), mirroring the cycle.consolidate.cluster_threshold hook; +1 wave 16 G5.1 (#6495): set-time refusal hook for search.keyword_statement_timeout_ms (check lives in commands/config/keyword-timeout-value.ts); +1 wave 18b lane 5 (#5012 item 6): search.contextual_retrieval prints the existing-pages hint after the write (text lives in commands/config/contextual-mode-hint.ts); +1 #6712 PR 2: retired/rollback sync key dispatch line (logic in core/sync-config-keys.ts handleSyncKeyConfig); +1 #6865: sync.slug_conflicts.auto_remove boolean validation at set time (refusal text in repair/slug-autoheal.ts); +1 #6948: sync.origin_twins.auto_resolve boolean validation at set time (refusal text in repair/origin-twins-heal.ts); +2 #6795: config set chat_model/expansion_model help line and the model-pin import (shadow report and file-pin unset live in commands/config/model-pin-shadow.ts); +1 #6712 PR 4b: sync.admission set-time hook (value logic in commands/config/sync-admission-value.ts); +4 #7130: set-time refusal hook for sync.max_deletes / sync.max_delete_ratio (and .source.<id>) / purge.retention_hours (check lives in core/sync-reconcile.ts deleteSafetyConfigRefusal); +1 GBRA-150: sync.metafile_pages set-time route (body in config/sync-metafile-pages-value.ts); re-summed at the v0.60.330.0 merge (1520 measured); +2 #7242 minions.terminal_hook file-plane key and its set branch (logic in minions/terminal-hook.ts); +1 GBRA-161: generations.* set-time route (refusal in commands/config/generations-values.ts); +1 GBRA-207 #7630: sync.repo_path set-time refusal hook (refusal in core/sync-config-keys.ts syncRepoPathRefusal)
src/commands/mcp-expose.ts 1519 ratchet hosted_option: Session carries the gbrain.io coaching notice on the first-receipt run and Tailscale/service friction exits (copy, refs and gating live in core/onboard/hosted-option.ts); +7 GBRA-199: --surface help lines, surfaceChosen option field and the advertise pass-through (registrationAdvertise in core/mcp-registration.ts)
-src/core/behavior-change-notice.ts 1693 ratchet +4 train R: #7491/#7492 keyword_identifier_probe and keyword_slug_handles rows and their comment, #7175 keyword phrase row; the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +1 GBRA-156 #7593: private_pages_granted_sources row (re-summed at the 0.60.527.0 merge: 1574 + 1); +3 GBRA-200 comment, write-grant refusal and degraded-stamp rows (re-summed at the 0.60.562.0 merge: 1615 + 3); +2 GBRA-280 get_page selector-precedence row and comment (re-summed at the 0.60.569.0 merge: 1619 + 2); the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +2 GBRA-205 saved_facts_stems row and its comment (re-summed at the #7901 0.60.492.0 merge: 1541 + 2); +2 GBRA-205 search.query_facts_block default-on row and its approval comment (re-summed at the #7610 0.60.490.0 merge: 1539 + 2); +2 the #7900 content checkpoint host-move row (since TBD until the merge slot), +2 the #7897 private-hold sweep row (since TBD until the merge slot), +2 the #7880 ingest_capture and company-brain private-hold row (since TBD until the merge slot), +5 the frozen-source wave comment and four rows (#7868, #7850, #7869/#7870, #7871), +2 the #7848 visibility_noncanonical hold row (since TBD until the merge slot), +2 the #7846 extract_atoms session-source row (re-summed at the 0.60.481.0 merge: master 1524 + 2), +2 the #7805 synthesize session-source and #7841 visibility_not_applied rows (re-summed at the 0.60.480.0 merge: master 1522 + 2), +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2), +2 the #7814 retired v0.13.1 grandfather row, +2 the #7618 conversion withhold/progress/push row (master 1520 + 2); the behavior-change table split (#7607) retires this row; +4 GBRA-188 #7489: the wave comment and three rows (brain-first instructions, starter surface default, per-turn rule); +1 GBRA-188 plugin_turn_hook_gbra188 row; +1 GBRA-242 provider_key_rules_7959 row (#7959), +2 the GBRA-199 registration_lists_verbs row (since TBD until the merge slot); +2 GBRA-133 #7652: the #7611 pass_abandoned reader row and the lean read-only serve socket row (re-summed at the 0.60.503.0 merge: master 1555 + 2); +1 GBRA-243: the per-turn hook disclosure row (rows are data and cannot move); +4 GBRA-156 #7598 harness wave comment and rows (remote page cap, sources_not_readable refusal, sources add next step); +4 GBRA-156 #7601 search_quotes_transcript_rows comment and row; +1 GBRA-175 #7475 autopilot_restarts_serve_7475 row (re-summed at the #8012 merge: 1566 + 1); +3 #7997/#8014/#8015 rows (redaction markers, company db_only keep, ignored supabase_only scope); +2 #7199 (re-port of #7228) classic_drift_rescreen_7199 comment and row; +2 #7931 file_drift_agrees_7931 comment and row; +1 #7950 file_drift_slug_release_7950 row; +1 #7974 file_drift_followups_7974 row; +1 #8059 quoted_fence_marker_8059 row; +2 GBRA-247 #8009 provenance_repair_held_8009 and #7982 pass_transient_streak_7982 rows; +4 GBRA-247 #7973 plain_directory_sync_7973, #7988 managed_marker_own_directory_7988, #7985 former_binding_parked_group_7985 and settle_effects_retire_7985 rows Train S merge: 1570 base + 5 (master since the #8077 base) + 13 (#8077) = 1588.; +2 GST-687 remote_quotes_unverified_text_gst687 row and its comment (re-summed at the gate-ahead on train S 0.60.534.0: 1588 + 2); +2 #8377: the quote fence follow-ups row and its comment; +2 #8384: the quote fence follow-ups 2 row and its comment; +2 #8384 wave 3: the quote fence follow-ups 3 row and its comment; +5 GBRA-218 train M rows (A1 member_read_access_gbra218 and member_access_hatch_scope_gbra218, B shared_agent_audience_gbra231, A2 folder_access_rules_gbra218, folder_access_scoped_role_gbra218), re-summed at the train M merge of master v0.60.541.0: 1596 + 5 = 1601 measured; +3 GST-359 train C rows (C1 qm_attested_actor_gst359, C2 member_facts_gst359, D qm_memory_provider_gst359), re-summed at the train C merge of master v0.60.543.0: 1601 + 3 = 1604 measured; +2 #8424: hook_launcher_8424 row and its comment (rows are data and cannot move), re-summed at the #8418 v0.60.546.0 merge: 1604 + 2 = 1606 measured; +2 #8426: mcp_lane_launcher_8426 row and its comment (rows are data and cannot move); +2 GST-927: empty_nonstring_args_gst927 row and its comment, re-summed at the gate-ahead on master v0.60.550.0 plus #8420: 1610 measured; +2 GBRA-283 Wave A (#8460): engine_keyed_caches_gbra283 row and its comment (rows are data and cannot move); +2 GBRA-287: segmented_freeze_hold_gbra287 and segmented_reexport_gbra287 rows (rows are data and cannot move); +1 GST-1209: segmented_tiling_gst1209 row (rows are data and cannot move); +1 GST-1251: skillopt_loop_deprecated_gst1251 row (rows are data and cannot move); +1 GST-1209 follow-up: untiled_hold_repair_gst1209 row (rows are data and cannot move); +1 GBRA-283 B3a: embedded_scope_required_gbra283 row (rows are data and cannot move); re-summed at the train R merge with v0.60.574.0: 1623 + 4; +2 GST-1387: refresh_fence_refusal_gst1387 row and its comment (rows are data and cannot move); re-summed at the memory train #8481 merge with v0.60.578.0 (1643 measured); +3 GBRA-253 #8109 rows (frontmatter_drift_write_8109, contacts_activity_advance_8109, contact_rows_dedupe_8109; rows are data and cannot move), re-summed at the master v0.60.581.0 merge: 1643 + 3 = 1646 measured; +3 #8123 part C rows: sync_write_through_off_writeback_7084, managed_sync_dry_run_counts_7087, frontmatter_missing_source_dir_7889 (since TBD until the merge slot; re-summed at the 0.60.583.0 merge: 1646 + 3); +4 PR B commit_ledger_prb, doctor_foreign_writers_prb and sources_guard_prb rows and their comment (rows are data and cannot move; since TBD until the merge slot); +1 PR B #8615: file_drift_held_needs_prefer_8615 row; +1 PR B #8617: refresh_source_changed_retry_8617 row; +1 PR B #8662: commit_push_checkout_not_a_source_8662 row (since TBD until the merge slot; rows are data and cannot move); +2 PR B refresh_barrier_prb and commit_push_base_prb rows (re-summed: 1658 measured); +3 convergence PR A: the wave comment and two rows (conversion_content_evidence_pr_a, git_gap_live_pages_pr_a; since TBD until the merge slot; rows are data and cannot move); re-summed at the gate-ahead on master v0.60.592.0 plus #8711: 1658 + 3 = 1661 measured; +4 GST-1094/GST-900 rows (memory_recall scope-read, member-bound acting_user, recall max_chars, unknown_param _meta-only) and +1 qm_scope_writes_gst1113 and +1 recall_question_terms_gst1304 rows (rows are data and cannot move), re-summed at the 0.60.595.0 slot merge: 1661 + 6; +1 GST-1582 refresh_barrier_import_gst1582 row (since TBD until the merge slot; rows are data and cannot move); +2 GST-1601 source_changed_origin_gst1601 and adopt_local_edits_gst1601 rows (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.596.0 merge: 1668 + 2; +1 GST-1623 refresh_barrier_capacity_gst1623 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.599.0 merge: 1670 + 1; +2 GBRA-224 W1 release_channel_stable_default row and its comment; +1 GST-1623 refresh_barrier_later_write_gst1623 row (#8765; rows are data and cannot move); +5 #8766 GST-1623 items 4/6-9 and #8755: the wave comment and four rows (doctor_foreign_writers_partial_gst1623, commit_push_enclosing_repo_gst1623, owner_guard_fail_closed_gst1623, adopt_local_edits_hardening_8755) and +1 managed_sync_kind_reserved_8765 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on master v0.60.608.0 plus #8798: 1674 + 6; +1 GST-1853 refresh_barrier_aborted_refresh_sync_gst1853 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.613.0 merge: 1680 + 1; +1 GST-1674 refresh_refused_merge_recovery_gst1674 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.614.0 merge: 1681 + 1; +1 #8824/#8826/#8767: adopt_local_edits_replay_markers_8824 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on #8837: 1682 + 1; +1 url_source_origin row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on #8834: 1683 + 1; +1 #8828: the refresh_replan_own_commits_8828 row (1684 + 1 at the 0.60.618.0 slot); +1 the managed commit-push unpublished-count row; +1 the refresh publish-diverged default row; +1 GST-2051 ungranted_member_writes_gst2051 row (since TBD until the merge slot; rows are data and cannot move); +1 GST-731 think_window_trajectory_gst731 row and +1 GST-1602 purge_cancels_deferred_write_gst1602 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on #8915 v0.60.621.0: 1688 + 2; +1 GST-2059: owner_reads_private row; +1 #8888: the record-origin checkout lock-down row (re-summed at the Q6 stack on #8934 v0.60.625.0: 1691 + 1); +1 GST-2112: ingest_keeps_readers_gst2112 row (re-summed at the Q7 v0.60.627.0 merge: 1692 + 1)
+src/core/behavior-change-notice.ts 1694 ratchet +4 train R: #7491/#7492 keyword_identifier_probe and keyword_slug_handles rows and their comment, #7175 keyword phrase row; the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +1 GBRA-156 #7593: private_pages_granted_sources row (re-summed at the 0.60.527.0 merge: 1574 + 1); +3 GBRA-200 comment, write-grant refusal and degraded-stamp rows (re-summed at the 0.60.562.0 merge: 1615 + 3); +2 GBRA-280 get_page selector-precedence row and comment (re-summed at the 0.60.569.0 merge: 1619 + 2); the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +2 GBRA-205 saved_facts_stems row and its comment (re-summed at the #7901 0.60.492.0 merge: 1541 + 2); +2 GBRA-205 search.query_facts_block default-on row and its approval comment (re-summed at the #7610 0.60.490.0 merge: 1539 + 2); +2 the #7900 content checkpoint host-move row (since TBD until the merge slot), +2 the #7897 private-hold sweep row (since TBD until the merge slot), +2 the #7880 ingest_capture and company-brain private-hold row (since TBD until the merge slot), +5 the frozen-source wave comment and four rows (#7868, #7850, #7869/#7870, #7871), +2 the #7848 visibility_noncanonical hold row (since TBD until the merge slot), +2 the #7846 extract_atoms session-source row (re-summed at the 0.60.481.0 merge: master 1524 + 2), +2 the #7805 synthesize session-source and #7841 visibility_not_applied rows (re-summed at the 0.60.480.0 merge: master 1522 + 2), +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2), +2 the #7814 retired v0.13.1 grandfather row, +2 the #7618 conversion withhold/progress/push row (master 1520 + 2); the behavior-change table split (#7607) retires this row; +4 GBRA-188 #7489: the wave comment and three rows (brain-first instructions, starter surface default, per-turn rule); +1 GBRA-188 plugin_turn_hook_gbra188 row; +1 GBRA-242 provider_key_rules_7959 row (#7959), +2 the GBRA-199 registration_lists_verbs row (since TBD until the merge slot); +2 GBRA-133 #7652: the #7611 pass_abandoned reader row and the lean read-only serve socket row (re-summed at the 0.60.503.0 merge: master 1555 + 2); +1 GBRA-243: the per-turn hook disclosure row (rows are data and cannot move); +4 GBRA-156 #7598 harness wave comment and rows (remote page cap, sources_not_readable refusal, sources add next step); +4 GBRA-156 #7601 search_quotes_transcript_rows comment and row; +1 GBRA-175 #7475 autopilot_restarts_serve_7475 row (re-summed at the #8012 merge: 1566 + 1); +3 #7997/#8014/#8015 rows (redaction markers, company db_only keep, ignored supabase_only scope); +2 #7199 (re-port of #7228) classic_drift_rescreen_7199 comment and row; +2 #7931 file_drift_agrees_7931 comment and row; +1 #7950 file_drift_slug_release_7950 row; +1 #7974 file_drift_followups_7974 row; +1 #8059 quoted_fence_marker_8059 row; +2 GBRA-247 #8009 provenance_repair_held_8009 and #7982 pass_transient_streak_7982 rows; +4 GBRA-247 #7973 plain_directory_sync_7973, #7988 managed_marker_own_directory_7988, #7985 former_binding_parked_group_7985 and settle_effects_retire_7985 rows Train S merge: 1570 base + 5 (master since the #8077 base) + 13 (#8077) = 1588.; +2 GST-687 remote_quotes_unverified_text_gst687 row and its comment (re-summed at the gate-ahead on train S 0.60.534.0: 1588 + 2); +2 #8377: the quote fence follow-ups row and its comment; +2 #8384: the quote fence follow-ups 2 row and its comment; +2 #8384 wave 3: the quote fence follow-ups 3 row and its comment; +5 GBRA-218 train M rows (A1 member_read_access_gbra218 and member_access_hatch_scope_gbra218, B shared_agent_audience_gbra231, A2 folder_access_rules_gbra218, folder_access_scoped_role_gbra218), re-summed at the train M merge of master v0.60.541.0: 1596 + 5 = 1601 measured; +3 GST-359 train C rows (C1 qm_attested_actor_gst359, C2 member_facts_gst359, D qm_memory_provider_gst359), re-summed at the train C merge of master v0.60.543.0: 1601 + 3 = 1604 measured; +2 #8424: hook_launcher_8424 row and its comment (rows are data and cannot move), re-summed at the #8418 v0.60.546.0 merge: 1604 + 2 = 1606 measured; +2 #8426: mcp_lane_launcher_8426 row and its comment (rows are data and cannot move); +2 GST-927: empty_nonstring_args_gst927 row and its comment, re-summed at the gate-ahead on master v0.60.550.0 plus #8420: 1610 measured; +2 GBRA-283 Wave A (#8460): engine_keyed_caches_gbra283 row and its comment (rows are data and cannot move); +2 GBRA-287: segmented_freeze_hold_gbra287 and segmented_reexport_gbra287 rows (rows are data and cannot move); +1 GST-1209: segmented_tiling_gst1209 row (rows are data and cannot move); +1 GST-1251: skillopt_loop_deprecated_gst1251 row (rows are data and cannot move); +1 GST-1209 follow-up: untiled_hold_repair_gst1209 row (rows are data and cannot move); +1 GBRA-283 B3a: embedded_scope_required_gbra283 row (rows are data and cannot move); re-summed at the train R merge with v0.60.574.0: 1623 + 4; +2 GST-1387: refresh_fence_refusal_gst1387 row and its comment (rows are data and cannot move); re-summed at the memory train #8481 merge with v0.60.578.0 (1643 measured); +3 GBRA-253 #8109 rows (frontmatter_drift_write_8109, contacts_activity_advance_8109, contact_rows_dedupe_8109; rows are data and cannot move), re-summed at the master v0.60.581.0 merge: 1643 + 3 = 1646 measured; +3 #8123 part C rows: sync_write_through_off_writeback_7084, managed_sync_dry_run_counts_7087, frontmatter_missing_source_dir_7889 (since TBD until the merge slot; re-summed at the 0.60.583.0 merge: 1646 + 3); +4 PR B commit_ledger_prb, doctor_foreign_writers_prb and sources_guard_prb rows and their comment (rows are data and cannot move; since TBD until the merge slot); +1 PR B #8615: file_drift_held_needs_prefer_8615 row; +1 PR B #8617: refresh_source_changed_retry_8617 row; +1 PR B #8662: commit_push_checkout_not_a_source_8662 row (since TBD until the merge slot; rows are data and cannot move); +2 PR B refresh_barrier_prb and commit_push_base_prb rows (re-summed: 1658 measured); +3 convergence PR A: the wave comment and two rows (conversion_content_evidence_pr_a, git_gap_live_pages_pr_a; since TBD until the merge slot; rows are data and cannot move); re-summed at the gate-ahead on master v0.60.592.0 plus #8711: 1658 + 3 = 1661 measured; +4 GST-1094/GST-900 rows (memory_recall scope-read, member-bound acting_user, recall max_chars, unknown_param _meta-only) and +1 qm_scope_writes_gst1113 and +1 recall_question_terms_gst1304 rows (rows are data and cannot move), re-summed at the 0.60.595.0 slot merge: 1661 + 6; +1 GST-1582 refresh_barrier_import_gst1582 row (since TBD until the merge slot; rows are data and cannot move); +2 GST-1601 source_changed_origin_gst1601 and adopt_local_edits_gst1601 rows (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.596.0 merge: 1668 + 2; +1 GST-1623 refresh_barrier_capacity_gst1623 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.599.0 merge: 1670 + 1; +2 GBRA-224 W1 release_channel_stable_default row and its comment; +1 GST-1623 refresh_barrier_later_write_gst1623 row (#8765; rows are data and cannot move); +5 #8766 GST-1623 items 4/6-9 and #8755: the wave comment and four rows (doctor_foreign_writers_partial_gst1623, commit_push_enclosing_repo_gst1623, owner_guard_fail_closed_gst1623, adopt_local_edits_hardening_8755) and +1 managed_sync_kind_reserved_8765 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on master v0.60.608.0 plus #8798: 1674 + 6; +1 GST-1853 refresh_barrier_aborted_refresh_sync_gst1853 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.613.0 merge: 1680 + 1; +1 GST-1674 refresh_refused_merge_recovery_gst1674 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.614.0 merge: 1681 + 1; +1 #8824/#8826/#8767: adopt_local_edits_replay_markers_8824 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on #8837: 1682 + 1; +1 url_source_origin row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on #8834: 1683 + 1; +1 #8828: the refresh_replan_own_commits_8828 row (1684 + 1 at the 0.60.618.0 slot); +1 the managed commit-push unpublished-count row; +1 the refresh publish-diverged default row; +1 GST-2051 ungranted_member_writes_gst2051 row (since TBD until the merge slot; rows are data and cannot move); +1 GST-731 think_window_trajectory_gst731 row and +1 GST-1602 purge_cancels_deferred_write_gst1602 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on #8915 v0.60.621.0: 1688 + 2; +1 GST-2059: owner_reads_private row; +1 #8888: the record-origin checkout lock-down row (re-summed at the Q6 stack on #8934 v0.60.625.0: 1691 + 1); +1 GST-2112: ingest_keeps_readers_gst2112 row (re-summed at the Q7 v0.60.627.0 merge: 1692 + 1); +1 GST-2228: links_rows_keep_own_dates_gst2228 row
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 6c5239af17..21483e3980 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1495,6 +1495,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.623.0', id: 'owner_reads_private_gst2059', text: 'A brain can now name its owner: `gbrain access owner set <member>` (config `access.owner_member`, an enabled member). Every remote credential or stdio server bound to that member reads the whole brain, `visibility: private` pages, privacy-alias pages (`access: private`, ...), derived and pinned-question pages included, through `get_page`, `search`, `query`, `recall` and the other page reads in the sources its grant reads, and `recall` returns its private facts. `readable_by` and folder rules still bind it, and it is not relaxed when it speaks for a shared-room audience. A page the owner\'s credential creates in `default` through `put_page` is not kept to the owner (no `readable_by: [member:<id>]`). Other members, unbound and public callers are unchanged. `_meta.access.relaxation` reads `owner` for such a call, and `gbrain access check --token <name>` reports it. `gbrain repair private-labels` (named runs only) previews the `access: private` labels stamped on ordinary pages with counts per category, keeps real restrictions, and clears the rest in reviewed batches (`--apply --expect <hash>`), recording each change so `--class restore` can put it back. The bulk-ingestion page template no longer writes an `access:` line; what each designation means is in docs/guides/access-designations.md.' },
{ since: '0.60.626.0', id: 'record_origin_checkout_lockdown_8888', text: '`gbrain sources record-origin <id>... --remote --apply` now also turns git-lfs downloads and hooks off in each recorded source\'s existing checkout (its `.git/config`: `lfs.fetchexclude=*`, `core.hooksPath=/dev/null`, `lfs.locksverify=false`), not only on later reclones, in the repository\'s shared config, and refuses `write_failed` naming the key when a worktree-scoped or included setting still overrides one; a source already recorded as remote gets the lock-down on the next `--remote --apply` when its checkout lacks it, even when its files now use git-lfs, and a key that holds several values in that config is replaced by the one clone-time value. On a managed brain it takes the same worktree locks a reclone takes, refusing the id `source_busy` while a reclone, refresh or write holds them, and a reclone reads the record under its own locks. A write that fails is reported for its own id (`write_failed`) instead of ending the run. The git-lfs check reads a committed `.gitattributes` under a directory whose name holds a tab, ignores commented-out `filter=lfs` lines, says when a committed rule only declares an LFS filter, records a clone of an empty repository instead of refusing it, and names the cause of an `lfs_unknown` refusal.' },
{ since: '0.60.627.0', id: 'ingest_keeps_readers_gst2112', text: 'A webhook capture (`POST /ingest` with `X-Gbrain-Slug` and its `ingest_capture` job) is now refused `readable_by_invalid` when its body drops `readable_by` from a page that names readers, or names readers that leave out the sending token or client: the route answers 403 and queues nothing, and a job already queued refuses at write time. Before, such a capture replaced the page and its readers, and every caller could read it. Bodies that keep the readers, and pages without readers, import as before.' },
+ { since: 'TBD', id: 'links_rows_keep_own_dates_gst2228', text: 'Each row of a page\'s `## Links` section (target, type, source) now keeps its own `valid_from` and `valid_until`. On a page whose links section a rewrite dropped, `add_link` writes the section back with every kept row and its own dates instead of a section holding only the new link; `remove_link` with a `link_source` deletes that row\'s dates for any source, not only `manual`, and leaves other rows\' dates alone. Dates stored before rows kept their source have none: with several rows for one target and type and the section gone, `add_link` and `remove_link` refuse `link_dates_unattributed` and ask for the section back through `edit_page`, one row per source with its own dates. `append_page` text holding a links fence marker is refused with `append_links_fence`; write each link with `add_link`.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/src/core/engine-sql/bootstrap.ts b/src/core/engine-sql/bootstrap.ts
index e0dfea7532..8ca73bdf78 100644
--- a/src/core/engine-sql/bootstrap.ts
+++ b/src/core/engine-sql/bootstrap.ts
@@ -167,6 +167,8 @@ const FORWARD_REFERENCE_PROBES: readonly Probe[] = [
['facts_embedded_text_hash_exists', 'facts', 'embedded_text_hash'],
['derived_generation_items_exists', 'derived_generation_items'],
['derived_generation_items_pending_exists', 'derived_generation_items', 'pending'],
+ ['link_transitions_exists', 'link_transitions'],
+ ['link_transitions_link_source_exists', 'link_transitions', 'link_source'],
];
// Probed only where `dreamVerdictsForwardReference` (the Postgres blob).
@@ -314,6 +316,11 @@ export function forwardReferenceGaps(probe: ProbeRow, dialect: ForwardReferenceB
// (the table exists since v265) wedged on the replay before any migration ran.
const needsDerivedGenerationItemsPending = probe.derived_generation_items_exists
&& !probe.derived_generation_items_pending_exists;
+ // v297 (GST-2228): the blob's link_transitions_identity_idx includes
+ // link_source, a column only v297 adds, so a brain at v204-v296 would wedge on
+ // the replay (CREATE INDEX IF NOT EXISTS checks columns before the name).
+ const needsLinkTransitionsLinkSource = probe.link_transitions_exists
+ && !probe.link_transitions_link_source_exists;
return {
needsPagesBootstrap, needsLinksBootstrap, needsChunksBootstrap, needsPagesDeletedAt,
needsMcpLogBootstrap, needsSubagentProviderId, needsChunksEmbeddingImage, needsPagesRecency,
@@ -323,6 +330,7 @@ export function forwardReferenceGaps(probe: ProbeRow, dialect: ForwardReferenceB
needsPagesLinksExtractedAt, needsTimelineEventPageId, needsMinionJobsTimeoutAt,
needsMinionJobsIdempotencyKey, needsMinionJobsPrivateQueue, needsMinionJobsAuthority,
needsDreamVerdictsExpiresAt, needsFactEmbeddingIdentity, needsDerivedGenerationItemsPending,
+ needsLinkTransitionsLinkSource,
};
}
@@ -340,6 +348,7 @@ export async function applyForwardReferenceBootstrap(target: ForwardReferenceBoo
needsPagesLinksExtractedAt, needsTimelineEventPageId, needsMinionJobsTimeoutAt,
needsMinionJobsIdempotencyKey, needsMinionJobsPrivateQueue, needsMinionJobsAuthority,
needsDreamVerdictsExpiresAt, needsFactEmbeddingIdentity, needsDerivedGenerationItemsPending,
+ needsLinkTransitionsLinkSource,
} = gaps;
if (!needsPagesBootstrap && !needsLinksBootstrap && !needsChunksBootstrap
@@ -357,7 +366,8 @@ export async function applyForwardReferenceBootstrap(target: ForwardReferenceBoo
&& !needsMinionJobsTimeoutAt && !needsMinionJobsIdempotencyKey
&& !needsMinionJobsPrivateQueue && !needsMinionJobsAuthority
&& !needsDreamVerdictsExpiresAt && !needsFactEmbeddingIdentity
- && !needsDerivedGenerationItemsPending) return;
+ && !needsDerivedGenerationItemsPending
+ && !needsLinkTransitionsLinkSource) return;
process.stderr.write(' Schema forward-reference gap detected, applying bootstrap\n');
@@ -590,7 +600,7 @@ async function applyLaterColumnGaps(target: ForwardReferenceBootstrapTarget, gap
needsPagesGeneration, needsPagesEmbeddingSignature, needsPagesLinksExtractedAt,
needsTimelineEventPageId, needsMinionJobsTimeoutAt, needsMinionJobsIdempotencyKey,
needsDreamVerdictsExpiresAt, needsMinionJobsPrivateQueue, needsMinionJobsAuthority,
- needsDerivedGenerationItemsPending,
+ needsDerivedGenerationItemsPending, needsLinkTransitionsLinkSource,
} = gaps;
if (needsPagesLastRetrievedAt) {
@@ -730,4 +740,12 @@ async function applyLaterColumnGaps(target: ForwardReferenceBootstrapTarget, gap
ALTER TABLE derived_generation_items ADD COLUMN IF NOT EXISTS pending BOOLEAN NOT NULL DEFAULT false;
`);
}
+
+ if (needsLinkTransitionsLinkSource) {
+ // Column only, exactly as v297 adds it (nullable, no default: metadata only);
+ // v297 still runs and swaps the identity index online.
+ await exec(`
+ ALTER TABLE link_transitions ADD COLUMN IF NOT EXISTS link_source TEXT;
+ `);
+ }
}
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index af6d21fed8..cff2942004 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -91,6 +91,7 @@ export const CODES = {
answer_pending: { class: 'retryable', summary: "The rated answer is still being recorded; retry in a few seconds.", docs: 'docs/guides/retrieval-feedback.md#answer_pending' },
answer_unavailable: { class: 'caller', summary: "The rated answer is not recorded: unknown, dropped, or older than the retention window.", docs: 'docs/guides/retrieval-feedback.md#answer_unavailable' },
api_not_enabled: { class: 'host_only', summary: "Google connect credential error: api not enabled.", docs: 'docs/guides/google-connect.md#troubleshooting' },
+ append_links_fence: { class: 'caller', summary: "append_page text held a links fence marker, so nothing was appended.", why: "A page has one links section, and the rows it lists are the page's authored links: an appended links table would replace that section and delete every link it does not list.", suggestion: 'Write each link with add_link (from, to, link_type); it adds the row to the page\'s links section and keeps the rows already there.' },
approval_required: { class: 'consent', summary: "The change needs the owner's explicit approval before it can proceed." },
atom_drain_incomplete: { class: 'retryable', exit: 11, summary: "An atom drain (`gbrain dream --drain`) stopped with atoms still to extract, or with its backlog count unknown; the batches it finished stay committed and running it again continues.", why: "The drain is bounded by its window, batch cap, per-run budget, job deadline and the cycle lock, and a backlog count that fails is never read as drained; each of these stops can clear on the next run.", reasons: ['window', 'deadline', 'lock_lost', 'aborted', 'max_batches', 'budget', 'count_unavailable'], suggestion: 'Run the printed resume_command again (a budget stop also names the cap it hit).', fix: { argv: ['gbrain', 'doctor', '--only', 'extract_atoms_backlog', '--json'], consent: [], actor: 'agent', why: 'Read-only: counts the pages still waiting for atom extraction.', requires_exclusive: false, verify: { argv: ['gbrain', 'doctor', '--only', 'extract_atoms_backlog', '--json'] } } },
atom_drain_no_progress: { class: 'host_only', retryable: false, summary: "An atom drain batch extracted nothing and the backlog count did not fall, so the drain stopped instead of spending in a loop; batches it finished earlier stay committed.", why: "What is left is failing, skipped or ineligible, so running the drain unchanged repeats the same empty batch.", suggestion: 'Do not rerun this drain unchanged. Run gbrain doctor --json on the brain host and ask the operator to resolve the reported extraction blocker; earlier successful batches remain committed.', fix: { argv: ['gbrain', 'doctor', '--json'], consent: [], actor: 'host_admin', why: 'Read-only: names the extraction blocker (provider, eligibility or backlog) the drain could not get past.', requires_exclusive: false, verify: { argv: ['gbrain', 'doctor', '--only', 'extract_atoms_backlog', '--json'] } } },
@@ -456,6 +457,7 @@ export const CODES = {
legacy_lock_removal_refused: { class: 'host_only', summary: "`gbrain pglite-repair --legacy-lock` refused to move a legacy PGLite lock aside: a process on this host still uses the data dir, the data dir is on a network or shared filesystem, or gbrain could not confirm the filesystem is local.", why: "The evidence the repair reads (kill -0, the process command, an open-file scan) covers only this host and PID namespace. A process that still holds the data dir, or a filesystem other hosts can mount or whose locality cannot be confirmed (neither Linux nor macOS, a failed probe, an unrecognised type, a macOS mount without the local flag), means the old owner may still be writing, and removing its lock would let two writers corrupt the brain.", reasons: ['live_holder', 'network_filesystem', 'filesystem_unverified'], docs: 'docs/ENGINES.md#legacy-pglite-lock', suggestion: 'Stop the process the message names (on a shared filesystem: every gbrain on every host that mounts it), then preview again with gbrain pglite-repair --legacy-lock --dry-run. For filesystem_unverified, run the repair on a Linux or macOS host where the folder is on a local disk; elsewhere only the user can confirm no gbrain on any computer reaches the folder and move the lock folder aside.' },
// #6876: get_links / get_backlinks continuations are bound to their listing.
link_cursor_invalid: { class: 'caller', summary: "A get_links / get_backlinks cursor was not one this listing returned: it belongs to another slug, direction, source scope or filter set, or is not a cursor.", why: "A cursor is a link-id position bound to the exact listing that issued it; continuing a different listing from it could skip or repeat edges without saying so. Nothing was read.", legacy_error: 'invalid_params', suggestion: 'Restart the listing with the same slug and filters and no cursor, then pass each next_cursor unchanged.', fix: { argv: ['gbrain', 'links', '{slug}'], mcp: { tool: 'get_links', arguments: { slug: '{slug}' } }, consent: [], actor: 'agent', why: 'Restarts the listing from its first page (read-only); pass each next_cursor it returns unchanged.', requires_exclusive: false, verify: { mcp: { tool: 'get_links', arguments: { slug: '{slug}', limit: 1 } } } } },
+ link_dates_unattributed: { class: 'caller', summary: "add_link or remove_link would re-create or change a links section whose dated statements were stored before each row kept its own dates, and gbrain cannot tell which row each date belongs to; nothing was changed.", why: "Each row of a page's links section (target, type, source) keeps its own valid_from and valid_until. Statements stored before that have no source: with several rows for one target and type, or dates that do not fit the one row, any pairing would be a guess that could put one row's dates on another.", reasons: ['several_rows', 'dates_do_not_fit'], suggestion: "Add the page's ## Links section back with edit_page, one row per source with that row's own valid_from and valid_until, then submit the request again." },
local_conflict: { class: 'caller', summary: "A local file or registration conflicts with the requested change." },
lock_busy: { class: 'retryable', summary: "Another process holds the lock this command needs." },
loops_extraction_skipped: { class: 'unavailable', summary: "A Google sweep or the managed catch-up queued no paid loop extraction; the sync summary's `skipped_reason` says why. Nothing failed and the email pages still imported.", why: "Extraction is gated before any model call: a kill switch, a missing chat provider, the day's spend cap (`loops.extraction_max_usd_per_day`, default $2.00; `spend_cap_zero` means the user set it to 0), or an exclusion label (`g_loops_exclude_labels` / `loops.extraction_exclude_labels`) that did not resolve against the account's labels, which fails closed until a sweep resolves it.", reasons: ['no_candidates', 'extraction_disabled', 'chat_unavailable', 'enqueue_failed', 'daily_spend_cap', 'spend_cap_zero', 'excluded_label', 'excluded_label_unresolved'], docs: 'docs/guides/open-loops.md#two-detectors', suggestion: 'Read the reason. `daily_spend_cap` clears at the next UTC day or when the user raises `loops.extraction_max_usd_per_day`; `excluded_label_unresolved` names the label token to fix in `gbrain sources status <id>` or `gbrain config get loops.extraction_exclude_labels`; the threads are extracted on their next touch or by `gbrain sync --source <id> --full`.', fix: { argv: ['gbrain', 'sync', 'status', '--source', '{source_id}', '--json'], consent: [], actor: 'agent', why: 'Read-only: the last sweep\'s loop extraction report with its skipped_reason and the unresolved label tokens.', requires_exclusive: false, verify: { argv: ['gbrain', 'config', 'get', 'loops.extraction_max_usd_per_day'] } } },
diff --git a/src/core/link-temporal-apply.ts b/src/core/link-temporal-apply.ts
index 90a05351e7..8b366ce0e0 100644
--- a/src/core/link-temporal-apply.ts
+++ b/src/core/link-temporal-apply.ts
@@ -152,13 +152,16 @@ export async function writeManualTransitions(
return inserted.length;
}
-/** remove_link companion: drop manual dated statements for the removed relationship(s). */
-export async function removeManualTransitions(tx: Tx, rel: { from: string; to: string; linkType?: string; sourceId: string }): Promise<void> {
+/**
+ * remove_link companion: drop manual dated statements for the removed relationship(s). `databaseOnly` keeps the
+ * statements a links fence projected (origin_page_id set), which belong to the fence's rows, not to a database-only edge.
+ */
+export async function removeManualTransitions(tx: Tx, rel: { from: string; to: string; linkType?: string; sourceId: string; databaseOnly?: boolean }): Promise<void> {
const keys = await tx.executeRaw<RelationshipKey>(
`DELETE FROM link_transitions lt USING pages f, pages t
WHERE f.id = lt.from_page_id AND t.id = lt.to_page_id AND f.slug = $1 AND t.slug = $2
AND f.source_id = $3 AND t.source_id = $3 AND lt.producer = 'manual'
- AND ($4::text IS NULL OR lt.link_type = $4)
- RETURNING lt.from_page_id, lt.to_page_id, lt.link_type`, [rel.from, rel.to, rel.sourceId, rel.linkType ?? null]);
+ AND ($4::text IS NULL OR lt.link_type = $4) AND (NOT $5::boolean OR lt.origin_page_id IS NULL)
+ RETURNING lt.from_page_id, lt.to_page_id, lt.link_type`, [rel.from, rel.to, rel.sourceId, rel.linkType ?? null, rel.databaseOnly === true]);
if (keys.length) await refreshRelationships(tx, keys);
}
diff --git a/src/core/link-temporal-schema.ts b/src/core/link-temporal-schema.ts
index 320172d6d1..b43d25e5c7 100644
--- a/src/core/link-temporal-schema.ts
+++ b/src/core/link-temporal-schema.ts
@@ -5,8 +5,10 @@
*
* - link_transitions: dated start/end evidence for a relationship
* (from_page_id, to_page_id, link_type). Owned by the page that states it
- * (origin_page_id; NULL for manual edges) and replaced with that page's
- * derived links.
+ * (origin_page_id; NULL for database-only manual edges) and replaced with that
+ * page's derived links. link_source names the links-section row a manual
+ * statement came from (the row's source), so each row keeps its own dates; it
+ * is NULL for every other producer and for statements written before the column existed.
* - link_relationships: the derived temporal state of each relationship, one
* row per read scope ('all' = every live origin, 'world' = evidence from
* private origins excluded). valid_ranges holds the stints; readers probe it
@@ -36,10 +38,11 @@ CREATE TABLE IF NOT EXISTS link_transitions (
producer TEXT NOT NULL CHECK (producer IN ('timeline','explicit','frontmatter','manual','inline','dream')),
origin_page_id INTEGER REFERENCES pages(id) ON DELETE CASCADE,
line_hash TEXT NOT NULL DEFAULT '',
- created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ link_source TEXT
);
CREATE UNIQUE INDEX IF NOT EXISTS link_transitions_identity_idx
- ON link_transitions (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT;
+ ON link_transitions (origin_page_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer) NULLS NOT DISTINCT;
CREATE INDEX IF NOT EXISTS link_transitions_relationship_idx ON link_transitions (from_page_id, to_page_id, link_type);
CREATE INDEX IF NOT EXISTS link_transitions_origin_idx ON link_transitions (origin_page_id);
${rls('link_transitions')}
diff --git a/src/core/links-fence-projection.ts b/src/core/links-fence-projection.ts
index a071f9039d..492b1754af 100644
--- a/src/core/links-fence-projection.ts
+++ b/src/core/links-fence-projection.ts
@@ -3,7 +3,11 @@
* `link_transitions`, inside the caller's publication or maintenance
* transaction. Only rows this page's fence owns are touched: edges with
* origin_page_id = the page and origin_field = `links_fence`, and manual
- * transitions with origin_page_id = the page. Database-only manual edges
+ * transitions with origin_page_id = the page. Each manual transition carries the
+ * source of the row whose cell stated it (link_source), and transitions are
+ * compared per row, so a row whose dates changed replaces only its own
+ * statements; one with no source (written before the column existed) is
+ * replaced by the row that states the same date. Database-only manual edges
* (origin_field NULL) and every derived producer are left alone. A row whose
* target is not a live page in the source, or whose type the active schema
* pack does not declare, yields no edge and stays in the file.
@@ -43,8 +47,8 @@ export async function projectLinksFence(tx: Tx, page: { id: number | string; sou
tx.executeRaw<{ id: number; to_page_id: number; link_type: string; link_source: string; context: string }>(
'SELECT id, to_page_id, link_type, link_source, context FROM links WHERE origin_page_id=$1 AND from_page_id=$1 AND origin_field=$2',
[pageId, LINKS_FENCE_ORIGIN_FIELD]),
- tx.executeRaw<{ id: number; to_page_id: number; link_type: string; kind: string; occurred_on: string }>(
- `SELECT id, to_page_id, link_type, kind, occurred_on::text AS occurred_on FROM link_transitions
+ tx.executeRaw<{ id: number; to_page_id: number; link_type: string; link_source: string | null; kind: string; occurred_on: string }>(
+ `SELECT id, to_page_id, link_type, link_source, kind, occurred_on::text AS occurred_on FROM link_transitions
WHERE origin_page_id=$1 AND from_page_id=$1 AND producer='manual'`, [pageId]),
]);
const edgeKey = (row: { to_page_id: number; link_type: string; link_source: string }) => `${Number(row.to_page_id)}\u0000${row.link_type}\u0000${row.link_source}`;
@@ -56,12 +60,12 @@ export async function projectLinksFence(tx: Tx, page: { id: number | string; sou
const prior = have.get(edgeKey(row));
return prior && prior.context !== row.context ? [{ id: Number(prior.id), context: row.context }] : [];
});
+ const transitionKey = (row: { to_page_id: number; link_type: string; link_source: string | null; kind: string; occurred_on: string }) =>
+ `${Number(row.to_page_id)}\u0000${row.link_type}\u0000${row.link_source ?? '\u0001'}\u0000${row.kind}\u0000${row.occurred_on}`;
const transitions = new Map(desired.flatMap(row => [
- ...(row.validFrom ? [{ to_page_id: row.to_page_id, link_type: row.link_type, kind: 'start', occurred_on: row.validFrom }] : []),
- ...(row.validUntil ? [{ to_page_id: row.to_page_id, link_type: row.link_type, kind: 'end', occurred_on: row.validUntil }] : []),
- ]).map(row => [`${row.to_page_id}\u0000${row.link_type}\u0000${row.kind}\u0000${row.occurred_on}`, row]));
- const transitionKey = (row: { to_page_id: number; link_type: string; kind: string; occurred_on: string }) =>
- `${Number(row.to_page_id)}\u0000${row.link_type}\u0000${row.kind}\u0000${row.occurred_on}`;
+ ...(row.validFrom ? [{ to_page_id: row.to_page_id, link_type: row.link_type, link_source: row.link_source, kind: 'start', occurred_on: row.validFrom }] : []),
+ ...(row.validUntil ? [{ to_page_id: row.to_page_id, link_type: row.link_type, link_source: row.link_source, kind: 'end', occurred_on: row.validUntil }] : []),
+ ]).map(row => [transitionKey(row), row]));
const haveTransitions = new Set(existingTransitions.map(transitionKey));
const staleTransitions = existingTransitions.filter(row => !transitions.has(transitionKey(row)));
const newTransitions = [...transitions.entries()].filter(([key]) => !haveTransitions.has(key)).map(([, row]) => row);
@@ -74,9 +78,9 @@ export async function projectLinksFence(tx: Tx, page: { id: number | string; sou
ON CONFLICT (from_page_id, to_page_id, link_type, link_source, origin_page_id) DO UPDATE SET context=EXCLUDED.context, origin_field=EXCLUDED.origin_field`,
[pageId, LINKS_FENCE_ORIGIN_FIELD], [{ rows: additions.map(({ to_page_id, link_type, context, link_source }) => ({ to_page_id, link_type, context, link_source })) }]);
if (staleTransitions.length) await tx.executeRaw('DELETE FROM link_transitions WHERE id=ANY($1::bigint[])', [staleTransitions.map(row => Number(row.id))]);
- if (newTransitions.length) await executeRawJsonb(tx, `INSERT INTO link_transitions (source_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer, origin_page_id)
- SELECT $1, $2, v.to_page_id, v.link_type, v.kind, v.occurred_on::date, 'manual', $2
- FROM jsonb_to_recordset(($3::jsonb)->'rows') AS v(to_page_id integer, link_type text, kind text, occurred_on text)
+ if (newTransitions.length) await executeRawJsonb(tx, `INSERT INTO link_transitions (source_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer, origin_page_id)
+ SELECT $1, $2, v.to_page_id, v.link_type, v.link_source, v.kind, v.occurred_on::date, 'manual', $2
+ FROM jsonb_to_recordset(($3::jsonb)->'rows') AS v(to_page_id integer, link_type text, link_source text, kind text, occurred_on text)
ON CONFLICT DO NOTHING`, [sourceId, pageId], [{ rows: newTransitions }]);
const keys: RelationshipKey[] = [...obsolete, ...additions, ...staleTransitions, ...newTransitions]
.map(row => ({ from_page_id: pageId, to_page_id: Number(row.to_page_id), link_type: row.link_type }));
diff --git a/src/core/persistence/manual-links.ts b/src/core/persistence/manual-links.ts
index 1bfe002b0d..527f14ebc6 100644
--- a/src/core/persistence/manual-links.ts
+++ b/src/core/persistence/manual-links.ts
@@ -7,10 +7,12 @@ import { pageIdentityError } from './page-identity.ts';
import { preparePageMutation } from './page-prepare.ts';
import type { PreparedMutation } from './coordinator.ts';
import type { WriteRequest } from './model.ts';
-import { LINKS_FENCE_ORIGIN_FIELD, LinksFenceRewriteRefusal, MANAGED_LINK_SOURCES, linksFenceSection, removeLinksFenceRows,
- upsertLinksFenceRow } from '../links-fence.ts';
+import { LINKS_FENCE_ORIGIN_FIELD, LinksFenceRewriteRefusal, MANAGED_LINK_SOURCES, linksFenceSection, readPageLinksFence, removeLinksFenceRows,
+ renderLinksFence, replaceOrInsertLinksFence, upsertLinksFenceRow, type LinksFenceRow } from '../links-fence.ts';
import { linksFenceProjectionRows, projectLinksFence } from '../links-fence-projection.ts';
import { removeManualTransitions } from '../link-temporal-apply.ts';
+import { refreshRelationships, type RelationshipKey } from '../link-relationships.ts';
+import { executeRawJsonb } from '../sql-query.ts';
const optional = (value: unknown) => typeof value === 'string' && value ? value : undefined;
@@ -21,16 +23,84 @@ const RELATIONSHIP = `l.from_page_id=$1 AND l.to_page_id=t.id AND t.source_id=$2
const DATABASE_ONLY = `l.origin_field IS DISTINCT FROM '${LINKS_FENCE_ORIGIN_FIELD}' AND l.link_source <> ALL($4::text[])`;
const FENCED = `l.origin_field='${LINKS_FENCE_ORIGIN_FIELD}' AND l.origin_page_id=$1`;
+type FencedEdge = { to_page_id: number; to: string; type: string; source: string; context: string | null };
+type Statement = { to_page_id: number; type: string; source: string | null; kind: string; on: string };
+const relationship = (row: { to_page_id: number; type: string }) => `${Number(row.to_page_id)}\u0000${row.type}`;
+
+/** The edges page `pageId`'s links fence projected that are still stored, and the page's manual dated statements. */
+async function storedFenceState(engine: BrainEngine, pageId: number): Promise<{ edges: FencedEdge[]; statements: Statement[] }> {
+ const [edges, statements] = await Promise.all([
+ engine.executeRaw<FencedEdge>(
+ `SELECT l.to_page_id, t.slug AS to, l.link_type AS type, l.link_source AS source, l.context FROM links l JOIN pages t ON t.id=l.to_page_id
+ WHERE l.from_page_id=$1 AND l.origin_page_id=$1 AND l.origin_field=$2 ORDER BY t.slug, l.link_type, l.link_source`, [pageId, LINKS_FENCE_ORIGIN_FIELD]),
+ engine.executeRaw<Statement>(
+ `SELECT to_page_id, link_type AS type, link_source AS source, kind, occurred_on::text AS on FROM link_transitions
+ WHERE origin_page_id=$1 AND from_page_id=$1 AND producer='manual'`, [pageId]),
+ ]);
+ return { edges, statements };
+}
+
+/** A relationship whose dated statements predate per-row sources and cannot be given to its kept rows exactly. */
+function linkDatesUnattributed(edge: FencedEdge, rows: number, operation: string, reason: 'several_rows' | 'dates_do_not_fit') {
+ const link = `${edge.to} (${edge.type || 'untyped'})`;
+ const why = reason === 'several_rows'
+ ? `The link to ${link} has ${rows} rows on this page and dated statements stored before each row kept its own dates, so gbrain cannot tell which row each date belongs to.`
+ : `The link to ${link} has dated statements stored before each row kept its own dates, and they do not fit its one row (more than one start or end, or an end before the start).`;
+ const fix = `Add the page's ## Links section with edit_page, one row per source of ${edge.to} with that row's own valid_from and valid_until, then submit ${operation} again.`;
+ return opError('link_dates_unattributed', `${why} Nothing was changed. ${fix}`, fix, { reason });
+}
+
+/**
+ * The edges a links fence of page `pageId` projected that are still stored, as fence rows carrying their own dates. A
+ * rewrite that drops the page's links section leaves exactly these (an absent fence retires nothing); a link the user
+ * withdrew (remove_link, an empty section, a row deleted from the section) has no edge any more and is not among them.
+ * Each row gets the statements stored with its source. Statements stored before rows had sources (link_source NULL)
+ * belong to the row when it is the relationship's only row and they fit it; otherwise the write refuses
+ * `link_dates_unattributed` instead of guessing. Statements of a source with no kept row belonged to a removed row and
+ * are not rendered.
+ */
+async function keptLinksFenceRows(engine: BrainEngine, pageId: number): Promise<LinksFenceRow[]> {
+ const { edges, statements } = await storedFenceState(engine, pageId);
+ return edges.map(edge => {
+ const siblings = edges.filter(other => relationship(other) === relationship(edge)).length;
+ const related = statements.filter(statement => relationship(statement) === relationship(edge));
+ if (siblings > 1 && related.some(statement => statement.source === null)) throw linkDatesUnattributed(edge, siblings, 'add_link', 'several_rows');
+ const own = related.filter(statement => statement.source === edge.source || statement.source === null);
+ const starts = own.filter(statement => statement.kind === 'start'), ends = own.filter(statement => statement.kind === 'end');
+ if (starts.length > 1 || ends.length > 1 || (starts[0] && ends[0] && ends[0].on < starts[0].on)) throw linkDatesUnattributed(edge, 1, 'add_link', 'dates_do_not_fit');
+ return { to: edge.to, type: edge.type, source: edge.source, context: edge.context ?? '',
+ ...(starts[0] ? { validFrom: starts[0].on } : {}), ...(ends[0] ? { validUntil: ends[0].on } : {}) };
+ });
+}
+
+/**
+ * remove_link on a page whose links section is gone removes rows by (to, type, source). When the relationship keeps
+ * other rows and has statements stored before rows had sources, those statements cannot be split between the removed
+ * row and the kept ones, so the removal refuses `link_dates_unattributed`.
+ */
+async function assertRemovalAttributable(engine: BrainEngine, pageId: number, removal: { to: string; linkType?: string; linkSource?: string }) {
+ const { edges, statements } = await storedFenceState(engine, pageId);
+ const removed = (edge: FencedEdge) => edge.to === removal.to && (!removal.linkType || edge.type === removal.linkType) && (!removal.linkSource || edge.source === removal.linkSource);
+ for (const edge of edges.filter(removed)) {
+ const siblings = edges.filter(other => relationship(other) === relationship(edge));
+ if (siblings.some(other => !removed(other)) && statements.some(statement => statement.source === null && relationship(statement) === relationship(edge))) {
+ throw linkDatesUnattributed(edge, siblings.length, 'remove_link', 'several_rows');
+ }
+ }
+}
+
/**
* `add_link` / `remove_link` on a managed brain (G5): the authored edge lives in the from page's links fence
* (links-fence.ts), written through the page-mutation door like add_timeline_entry. The preparer upserts or
* removes the fence row at the snapshot's revision (a segmented page is read back whole) and publishes the page.
* The publication projects the fence (canonical-projections.ts) and the apply projects it once more, so a fence
* the write left unchanged (an idempotent add) still has its edges. `add_link` drops the database-only twin of
- * the edge it fences (same endpoints, type and provenance, no origin). `remove_link` also deletes the matching
- * database-only edges written before the fence existed, with their manual dated statements, so a removal only
- * moves the database toward git; edges a reconciliation producer derives from the page text stay, and the result
- * names them (`derived_from_text`, with `derived_message` saying to edit the page text instead).
+ * the edge it fences (same endpoints, type and provenance, no origin); on a page with no links fence, the section it
+ * creates lists the edges a dropped section left first, each with its own dates (`keptLinksFenceRows`). `remove_link`
+ * deletes the removed rows' own dated statements, whatever their source, and also the matching database-only edges
+ * written before the fence existed, with their manual dated statements, so a removal only moves the database toward
+ * git; edges a reconciliation producer derives from the page text stay, and the result names them
+ * (`derived_from_text`, with `derived_message` saying to edit the page text instead).
*/
export async function prepareManualLinkMutation(engine: BrainEngine, row: WriteRequest, config: GBrainConfig): Promise<PreparedMutation> {
const stored = await engine.readPageSnapshot(row.slug, { sourceId: row.source_id });
@@ -41,10 +111,15 @@ export async function prepareManualLinkMutation(engine: BrainEngine, row: WriteR
const to = String(p.to).toLowerCase();
const linkType = optional(p.link_type), linkSource = optional(p.link_source);
const validFrom = optional(p.valid_from), validUntil = optional(p.valid_until);
+ const pageId = Number(stored.page.id);
+ const absent = readPageLinksFence(snapshot.page).state === 'absent';
+ const kept = row.operation === 'add_link' && absent ? await keptLinksFenceRows(engine, pageId) : [];
+ if (row.operation === 'remove_link' && absent) await assertRemovalAttributable(engine, pageId, { to, linkType, linkSource });
+ const current = kept.length ? replaceOrInsertLinksFence(snapshot.page[section] ?? '', renderLinksFence(kept)) : snapshot.page[section] ?? '';
let body: string;
try {
body = row.operation === 'add_link'
- ? upsertLinksFenceRow(snapshot.page[section] ?? '', { to, type: linkType ?? '', source: linkSource ?? 'manual', context: String(p.context ?? ''),
+ ? upsertLinksFenceRow(current, { to, type: linkType ?? '', source: linkSource ?? 'manual', context: String(p.context ?? ''),
...(validFrom ? { validFrom } : {}), ...(validUntil ? { validUntil } : {}) }).body
: removeLinksFenceRows(snapshot.page[section] ?? '', { to, type: linkType, source: linkSource }).body;
} catch (error) {
@@ -58,7 +133,6 @@ export async function prepareManualLinkMutation(engine: BrainEngine, row: WriteR
expectedRevision: snapshot.revision, content: serializePageToMarkdown(page, snapshot.tags),
}, undefined, { boundedChunkWrites: true });
const origin = { id: stored.page.id, source_id: row.source_id };
- const pageId = Number(stored.page.id);
if (row.operation === 'add_link') {
return { ...prepared, apply: async tx => {
const outcome = await prepared.apply(tx);
@@ -75,9 +149,23 @@ export async function prepareManualLinkMutation(engine: BrainEngine, row: WriteR
const before = await count();
// A page whose body dropped its whole fence keeps the fence's edges (an absent fence retires nothing), so
// removing the relationship removes those orphans too: no row in git backs them.
- const dropped = await tx.executeRaw(`DELETE FROM links l USING pages t WHERE ${RELATIONSHIP}
- AND ((${DATABASE_ONLY}) OR ($7::boolean AND ${FENCED})) RETURNING l.id`, [...params, fence === null]);
- if (dropped.length && (!linkSource || linkSource === 'manual')) await removeManualTransitions(tx, { from: row.slug, to, linkType, sourceId: row.source_id });
+ const dropped = await tx.executeRaw<{ to_page_id: number; link_type: string; link_source: string; fenced: boolean }>(`DELETE FROM links l USING pages t
+ WHERE ${RELATIONSHIP} AND ((${DATABASE_ONLY}) OR ($7::boolean AND ${FENCED}))
+ RETURNING l.to_page_id, l.link_type, l.link_source, l.origin_field IS NOT DISTINCT FROM '${LINKS_FENCE_ORIGIN_FIELD}' AS fenced`, [...params, fence === null]);
+ if (dropped.some(edge => !edge.fenced) && (!linkSource || linkSource === 'manual')) {
+ await removeManualTransitions(tx, { from: row.slug, to, linkType, sourceId: row.source_id, databaseOnly: true });
+ }
+ const removedRows = dropped.filter(edge => edge.fenced);
+ // A dropped fence's removed rows take their own statements; statements stored before rows had sources go only
+ // when no row of their relationship is left (assertRemovalAttributable refused the ambiguous case).
+ const keys = removedRows.length ? await executeRawJsonb<RelationshipKey>(tx, `DELETE FROM link_transitions lt
+ USING jsonb_to_recordset(($3::jsonb)->'rows') AS v(to_page_id integer, link_type text, link_source text)
+ WHERE lt.from_page_id=$1 AND lt.origin_page_id=$1 AND lt.producer='manual' AND lt.to_page_id=v.to_page_id AND lt.link_type=v.link_type
+ AND (lt.link_source=v.link_source OR (lt.link_source IS NULL AND NOT EXISTS (SELECT 1 FROM links l WHERE l.from_page_id=$1
+ AND l.origin_page_id=$1 AND l.origin_field=$2 AND l.to_page_id=v.to_page_id AND l.link_type=v.link_type)))
+ RETURNING lt.from_page_id, lt.to_page_id, lt.link_type`, [pageId, LINKS_FENCE_ORIGIN_FIELD],
+ [{ rows: removedRows.map(({ to_page_id, link_type, link_source }) => ({ to_page_id, link_type, link_source })) }]) : [];
+ if (keys.length) await refreshRelationships(tx, keys);
const outcome = await prepared.apply(tx);
if (fence) await projectLinksFence(tx, origin, fence);
const derived = await tx.executeRaw<{ link_type: string; link_source: string }>(`SELECT DISTINCT l.link_type, l.link_source FROM links l, pages t
diff --git a/src/core/persistence/page-append.ts b/src/core/persistence/page-append.ts
index 682ac1a67e..6ca49e9080 100644
--- a/src/core/persistence/page-append.ts
+++ b/src/core/persistence/page-append.ts
@@ -29,6 +29,7 @@ import { OperationError, opError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { FACTS_FENCE_BEGIN, FACTS_FENCE_END } from '../facts-fence.ts';
import { TAKES_FENCE_BEGIN, TAKES_FENCE_END } from '../takes-fence.ts';
+import { LINKS_FENCE_BEGIN, LINKS_FENCE_END } from '../links-fence.ts';
import { parseMarkdown, serializePageToMarkdown, timelineSentinelKind } from '../markdown.ts';
import { buildContentFlagMarker, CONTENT_FLAG_KEY, isQuarantined } from '../quarantine.ts';
import { sizeStateField } from '../page-embedding-budget.ts';
@@ -112,6 +113,15 @@ function assertAppendText(text: string): void {
throw invalid('append_page text contains a protected facts or takes fence marker.',
'Write facts with remember and takes with takes_add; append_page adds ordinary text only.');
}
+ if (text.includes(LINKS_FENCE_BEGIN) || text.includes(LINKS_FENCE_END)) {
+ throw opError('append_links_fence', 'append_page text contains a links fence marker, so nothing was appended.',
+ 'Write each link with add_link (from, to, link_type); append_page adds ordinary text only.', { fix: {
+ mcp: { tool: 'add_link', arguments: { from: '<FROM>', to: '<TO>', link_type: '<LINK_TYPE>' } },
+ inputs: [{ name: 'FROM', how: 'The slug of the page you appended to.' }, { name: 'TO', how: 'The slug of the page one row of your links table points to.' },
+ { name: 'LINK_TYPE', how: 'That row\'s type (omit link_type for an untyped link).' }],
+ consent: [], actor: 'agent', requires_exclusive: false,
+ why: 'Adds the link as one row of the page\'s links section, keeping the rows already there; repeat it for each row.' } });
+ }
if (text.split('\n').some(line => timelineSentinelKind(line.trim()) === 'marker')) {
throw invalid('append_page text contains a timeline sentinel line.', 'Pass region: \'timeline\' to add to the timeline, and drop the sentinel line from text.');
}
diff --git a/src/core/pglite-schema.generated.ts b/src/core/pglite-schema.generated.ts
index e1d41ac7fe..a6e7a54be1 100644
--- a/src/core/pglite-schema.generated.ts
+++ b/src/core/pglite-schema.generated.ts
@@ -2527,10 +2527,11 @@ CREATE TABLE IF NOT EXISTS link_transitions (
producer TEXT NOT NULL CHECK (producer IN ('timeline','explicit','frontmatter','manual','inline','dream')),
origin_page_id INTEGER REFERENCES pages(id) ON DELETE CASCADE,
line_hash TEXT NOT NULL DEFAULT '',
- created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ link_source TEXT
);
CREATE UNIQUE INDEX IF NOT EXISTS link_transitions_identity_idx
- ON link_transitions (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT;
+ ON link_transitions (origin_page_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer) NULLS NOT DISTINCT;
CREATE INDEX IF NOT EXISTS link_transitions_relationship_idx ON link_transitions (from_page_id, to_page_id, link_type);
CREATE INDEX IF NOT EXISTS link_transitions_origin_idx ON link_transitions (origin_page_id);
DO \$rls\$ BEGIN
diff --git a/src/core/schema-embedded.generated.ts b/src/core/schema-embedded.generated.ts
index c3b0a2e3ac..e8ebd323b3 100644
--- a/src/core/schema-embedded.generated.ts
+++ b/src/core/schema-embedded.generated.ts
@@ -3288,10 +3288,11 @@ CREATE TABLE IF NOT EXISTS link_transitions (
producer TEXT NOT NULL CHECK (producer IN ('timeline','explicit','frontmatter','manual','inline','dream')),
origin_page_id INTEGER REFERENCES pages(id) ON DELETE CASCADE,
line_hash TEXT NOT NULL DEFAULT '',
- created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ link_source TEXT
);
CREATE UNIQUE INDEX IF NOT EXISTS link_transitions_identity_idx
- ON link_transitions (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT;
+ ON link_transitions (origin_page_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer) NULLS NOT DISTINCT;
CREATE INDEX IF NOT EXISTS link_transitions_relationship_idx ON link_transitions (from_page_id, to_page_id, link_type);
CREATE INDEX IF NOT EXISTS link_transitions_origin_idx ON link_transitions (origin_page_id);
DO \$rls\$ BEGIN
diff --git a/src/core/schema-migrations/latest.generated.ts b/src/core/schema-migrations/latest.generated.ts
index a8fdb37405..23b6b67130 100644
--- a/src/core/schema-migrations/latest.generated.ts
+++ b/src/core/schema-migrations/latest.generated.ts
@@ -4,4 +4,4 @@
// The highest schema migration version (migrate.ts LATEST_VERSION), importable without
// loading the migrations themselves.
-export const LATEST_SCHEMA_VERSION = 296;
+export const LATEST_SCHEMA_VERSION = 297;
diff --git a/src/core/schema-migrations/registry.generated.ts b/src/core/schema-migrations/registry.generated.ts
index 852ba0067c..bf88ce153a 100644
--- a/src/core/schema-migrations/registry.generated.ts
+++ b/src/core/schema-migrations/registry.generated.ts
@@ -297,6 +297,7 @@ import { v293 } from './v293-qm-attest-sources.ts';
import { v294 } from './v294-refresh-barrier-import-deferral.ts';
import { v295 } from './v295-refresh-retry-hint-history-index.ts';
import { v296 } from './v296-ingest-applied-captures.ts';
+import { v297 } from './v297-link-transitions-source.ts';
// Array order is historical (see HISTORICAL_ARRAY_ORDER in the generator); the
// runner sorts by version before applying.
@@ -592,4 +593,5 @@ export const MIGRATIONS: Migration[] = [
v294,
v295,
v296,
+ v297,
];
diff --git a/src/core/schema-migrations/v297-link-transitions-source.ts b/src/core/schema-migrations/v297-link-transitions-source.ts
new file mode 100644
index 0000000000..4f0f4ab9f4
--- /dev/null
+++ b/src/core/schema-migrations/v297-link-transitions-source.ts
@@ -0,0 +1,89 @@
+import type { BrainEngine } from '../engine.ts';
+import type { Migration } from './types.ts';
+import { buildIndexOnline, migrationNotice, runMigrationStatement } from './helpers.ts';
+import { isLockTimeoutError } from '../retry-matcher.ts';
+import { migrationStatementTimeoutMs } from '../migration-timeout.ts';
+import { resolveSchemaLockTimeoutMs, schemaLockBlockedError } from '../postgres-engine/schema-lock-timeout.ts';
+
+// Applied by src/core/migrate.ts on the next initSchema(); see docs/ENGINES.md
+// ("Canonical schema sources") for when schema.sql or a TS fragment also changes.
+//
+// GST-2228: link_transitions.link_source names the links-section row a manual
+// dated statement came from, and the identity index includes it, so two rows of
+// one relationship (same page, target and type, different sources) keep their
+// own dates. No row is rewritten: statements written before this keep a NULL
+// source, and NULLS NOT DISTINCT keeps them colliding with each other as before.
+//
+// The column is nullable with no default, so adding it changes only metadata;
+// it runs under the schema lock timeout. The index is never rebuilt inside a
+// transaction (that would hold ACCESS EXCLUSIVE on link_transitions for the
+// whole build): buildIndexOnline builds the widened index under a temporary
+// name (CONCURRENTLY on Postgres, dropping an INVALID leftover of an
+// interrupted build first), then one short transaction drops the old index and
+// renames the new one into its place, so the canonical name exists at every
+// moment. A rerun after any interruption finishes the job. The schema blob's
+// CREATE UNIQUE INDEX IF NOT EXISTS under the canonical name is a no-op on an
+// upgraded brain (the forward-reference bootstrap adds the column first).
+export const LINK_TRANSITIONS_IDENTITY_INDEX = 'link_transitions_identity_idx';
+export const LINK_TRANSITIONS_IDENTITY_NEXT_INDEX = {
+ name: 'link_transitions_identity_next_idx',
+ table: 'link_transitions',
+ sql: `CREATE UNIQUE INDEX IF NOT EXISTS link_transitions_identity_next_idx
+ ON link_transitions (origin_page_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer) NULLS NOT DISTINCT`,
+};
+
+const POSTGRES_15_GATE = `DO $$ BEGIN
+ IF current_setting('server_version_num')::int < 150000 THEN
+ RAISE EXCEPTION
+ 'v297 migration requires Postgres 15+. Current: %. '
+ 'Upgrade your Postgres (Supabase: migrate project to a newer PG major). '
+ 'This migration intentionally stops before touching the schema to preserve data integrity.',
+ current_setting('server_version');
+ END IF;
+END $$`;
+
+/** Whether the canonical identity index already includes link_source (fresh install, or a finished swap). */
+export async function identityIndexHasSource(engine: BrainEngine): Promise<boolean> {
+ const [row] = await engine.executeRaw<{ has: boolean }>(
+ `SELECT EXISTS (SELECT 1 FROM pg_index i JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = ANY(i.indkey)
+ WHERE i.indexrelid = to_regclass($1) AND a.attname = 'link_source') AS has`, [LINK_TRANSITIONS_IDENTITY_INDEX]);
+ return row?.has === true;
+}
+
+/** The swap: drop the old index and rename the built one into its place, under the schema lock timeout. */
+export async function swapIdentityIndex(engine: BrainEngine): Promise<void> {
+ const lockTimeoutMs = resolveSchemaLockTimeoutMs();
+ try {
+ await engine.transaction(async tx => {
+ if (engine.kind === 'postgres') {
+ await tx.executeRaw(`SET LOCAL statement_timeout = '${migrationStatementTimeoutMs()}'`);
+ await tx.executeRaw(`SET LOCAL lock_timeout = '${lockTimeoutMs}ms'`);
+ }
+ await tx.executeRaw(`DROP INDEX IF EXISTS ${LINK_TRANSITIONS_IDENTITY_INDEX}`);
+ await tx.executeRaw(`ALTER INDEX ${LINK_TRANSITIONS_IDENTITY_NEXT_INDEX.name} RENAME TO ${LINK_TRANSITIONS_IDENTITY_INDEX}`);
+ });
+ } catch (error) {
+ if (engine.kind === 'postgres' && isLockTimeoutError(error)) {
+ throw schemaLockBlockedError({ step: 'migration v297 (link_transitions identity index swap)', timeoutMs: lockTimeoutMs, sessions: null, sampledDuringWait: false });
+ }
+ throw error;
+ }
+}
+
+export const v297: Migration = {
+ version: 297,
+ name: 'link_transitions_source',
+ idempotent: true,
+ transaction: false,
+ sql: '',
+ handler: async engine => {
+ await runMigrationStatement(engine, 297, POSTGRES_15_GATE);
+ await runMigrationStatement(engine, 297, 'ALTER TABLE link_transitions ADD COLUMN IF NOT EXISTS link_source TEXT');
+ if (await identityIndexHasSource(engine)) return;
+ const built = await buildIndexOnline(engine, 297, LINK_TRANSITIONS_IDENTITY_NEXT_INDEX, { notice: migrationNotice });
+ if (built === 'building') {
+ throw new Error(`Another session is still building ${LINK_TRANSITIONS_IDENTITY_NEXT_INDEX.name}; when it finishes, rerun: gbrain apply-migrations --yes`);
+ }
+ await swapIdentityIndex(engine);
+ },
+};
diff --git a/src/schema.sql b/src/schema.sql
index b7f4166081..6126b0caef 100644
--- a/src/schema.sql
+++ b/src/schema.sql
@@ -3284,10 +3284,11 @@ CREATE TABLE IF NOT EXISTS link_transitions (
producer TEXT NOT NULL CHECK (producer IN ('timeline','explicit','frontmatter','manual','inline','dream')),
origin_page_id INTEGER REFERENCES pages(id) ON DELETE CASCADE,
line_hash TEXT NOT NULL DEFAULT '',
- created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ link_source TEXT
);
CREATE UNIQUE INDEX IF NOT EXISTS link_transitions_identity_idx
- ON link_transitions (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT;
+ ON link_transitions (origin_page_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer) NULLS NOT DISTINCT;
CREATE INDEX IF NOT EXISTS link_transitions_relationship_idx ON link_transitions (from_page_id, to_page_id, link_type);
CREATE INDEX IF NOT EXISTS link_transitions_origin_idx ON link_transitions (origin_page_id);
DO $rls$ BEGIN
diff --git a/test/fixtures/goldens/catalog/pglite-engine-init-default.json b/test/fixtures/goldens/catalog/pglite-engine-init-default.json
index fa40c9aaf8..d628a429de 100644
--- a/test/fixtures/goldens/catalog/pglite-engine-init-default.json
+++ b/test/fixtures/goldens/catalog/pglite-engine-init-default.json
@@ -1425,7 +1425,7 @@
"link_relationships_pkey": "CREATE UNIQUE INDEX link_relationships_pkey ON public.link_relationships USING btree (from_page_id, to_page_id, link_type, scope)",
"link_relationships_source_idx": "CREATE INDEX link_relationships_source_idx ON public.link_relationships USING btree (source_id, status_now)",
"link_relationships_to_idx": "CREATE INDEX link_relationships_to_idx ON public.link_relationships USING btree (to_page_id, link_type, scope)",
- "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT",
+ "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer) NULLS NOT DISTINCT",
"link_transitions_origin_idx": "CREATE INDEX link_transitions_origin_idx ON public.link_transitions USING btree (origin_page_id)",
"link_transitions_pkey": "CREATE UNIQUE INDEX link_transitions_pkey ON public.link_transitions USING btree (id)",
"link_transitions_relationship_idx": "CREATE INDEX link_transitions_relationship_idx ON public.link_transitions USING btree (from_page_id, to_page_id, link_type)",
@@ -2809,7 +2809,8 @@
"9 producer text/text NOT NULL",
"10 origin_page_id integer/int4 NULL",
"11 line_hash text/text NOT NULL DEFAULT ''::text",
- "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()"
+ "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()",
+ "13 link_source text/text NULL"
],
"flags": "relkind=r rls=true force_rls=false"
},
diff --git a/test/fixtures/goldens/catalog/pglite-engine-init-fts-portuguese.json b/test/fixtures/goldens/catalog/pglite-engine-init-fts-portuguese.json
index aa2c137aab..d0b8c702e6 100644
--- a/test/fixtures/goldens/catalog/pglite-engine-init-fts-portuguese.json
+++ b/test/fixtures/goldens/catalog/pglite-engine-init-fts-portuguese.json
@@ -1425,7 +1425,7 @@
"link_relationships_pkey": "CREATE UNIQUE INDEX link_relationships_pkey ON public.link_relationships USING btree (from_page_id, to_page_id, link_type, scope)",
"link_relationships_source_idx": "CREATE INDEX link_relationships_source_idx ON public.link_relationships USING btree (source_id, status_now)",
"link_relationships_to_idx": "CREATE INDEX link_relationships_to_idx ON public.link_relationships USING btree (to_page_id, link_type, scope)",
- "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT",
+ "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer) NULLS NOT DISTINCT",
"link_transitions_origin_idx": "CREATE INDEX link_transitions_origin_idx ON public.link_transitions USING btree (origin_page_id)",
"link_transitions_pkey": "CREATE UNIQUE INDEX link_transitions_pkey ON public.link_transitions USING btree (id)",
"link_transitions_relationship_idx": "CREATE INDEX link_transitions_relationship_idx ON public.link_transitions USING btree (from_page_id, to_page_id, link_type)",
@@ -2809,7 +2809,8 @@
"9 producer text/text NOT NULL",
"10 origin_page_id integer/int4 NULL",
"11 line_hash text/text NOT NULL DEFAULT ''::text",
- "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()"
+ "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()",
+ "13 link_source text/text NULL"
],
"flags": "relkind=r rls=true force_rls=false"
},
diff --git a/test/fixtures/goldens/catalog/pglite-engine-init-high-dims.json b/test/fixtures/goldens/catalog/pglite-engine-init-high-dims.json
index 22ea6da123..c8206f8fc6 100644
--- a/test/fixtures/goldens/catalog/pglite-engine-init-high-dims.json
+++ b/test/fixtures/goldens/catalog/pglite-engine-init-high-dims.json
@@ -1421,7 +1421,7 @@
"link_relationships_pkey": "CREATE UNIQUE INDEX link_relationships_pkey ON public.link_relationships USING btree (from_page_id, to_page_id, link_type, scope)",
"link_relationships_source_idx": "CREATE INDEX link_relationships_source_idx ON public.link_relationships USING btree (source_id, status_now)",
"link_relationships_to_idx": "CREATE INDEX link_relationships_to_idx ON public.link_relationships USING btree (to_page_id, link_type, scope)",
- "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT",
+ "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer) NULLS NOT DISTINCT",
"link_transitions_origin_idx": "CREATE INDEX link_transitions_origin_idx ON public.link_transitions USING btree (origin_page_id)",
"link_transitions_pkey": "CREATE UNIQUE INDEX link_transitions_pkey ON public.link_transitions USING btree (id)",
"link_transitions_relationship_idx": "CREATE INDEX link_transitions_relationship_idx ON public.link_transitions USING btree (from_page_id, to_page_id, link_type)",
@@ -2805,7 +2805,8 @@
"9 producer text/text NOT NULL",
"10 origin_page_id integer/int4 NULL",
"11 line_hash text/text NOT NULL DEFAULT ''::text",
- "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()"
+ "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()",
+ "13 link_source text/text NULL"
],
"flags": "relkind=r rls=true force_rls=false"
},
diff --git a/test/fixtures/goldens/catalog/pglite-schema-blob-default.json b/test/fixtures/goldens/catalog/pglite-schema-blob-default.json
index e5c631fe71..cbee2bdd72 100644
--- a/test/fixtures/goldens/catalog/pglite-schema-blob-default.json
+++ b/test/fixtures/goldens/catalog/pglite-schema-blob-default.json
@@ -990,7 +990,7 @@
"link_relationships_pkey": "CREATE UNIQUE INDEX link_relationships_pkey ON public.link_relationships USING btree (from_page_id, to_page_id, link_type, scope)",
"link_relationships_source_idx": "CREATE INDEX link_relationships_source_idx ON public.link_relationships USING btree (source_id, status_now)",
"link_relationships_to_idx": "CREATE INDEX link_relationships_to_idx ON public.link_relationships USING btree (to_page_id, link_type, scope)",
- "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT",
+ "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer) NULLS NOT DISTINCT",
"link_transitions_origin_idx": "CREATE INDEX link_transitions_origin_idx ON public.link_transitions USING btree (origin_page_id)",
"link_transitions_pkey": "CREATE UNIQUE INDEX link_transitions_pkey ON public.link_transitions USING btree (id)",
"link_transitions_relationship_idx": "CREATE INDEX link_transitions_relationship_idx ON public.link_transitions USING btree (from_page_id, to_page_id, link_type)",
@@ -1977,7 +1977,8 @@
"9 producer text/text NOT NULL",
"10 origin_page_id integer/int4 NULL",
"11 line_hash text/text NOT NULL DEFAULT ''::text",
- "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()"
+ "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()",
+ "13 link_source text/text NULL"
],
"flags": "relkind=r rls=true force_rls=false"
},
diff --git a/test/fixtures/goldens/catalog/pglite-schema-blob-fts-portuguese.json b/test/fixtures/goldens/catalog/pglite-schema-blob-fts-portuguese.json
index 299b03517a..531b11a7f9 100644
--- a/test/fixtures/goldens/catalog/pglite-schema-blob-fts-portuguese.json
+++ b/test/fixtures/goldens/catalog/pglite-schema-blob-fts-portuguese.json
@@ -990,7 +990,7 @@
"link_relationships_pkey": "CREATE UNIQUE INDEX link_relationships_pkey ON public.link_relationships USING btree (from_page_id, to_page_id, link_type, scope)",
"link_relationships_source_idx": "CREATE INDEX link_relationships_source_idx ON public.link_relationships USING btree (source_id, status_now)",
"link_relationships_to_idx": "CREATE INDEX link_relationships_to_idx ON public.link_relationships USING btree (to_page_id, link_type, scope)",
- "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT",
+ "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer) NULLS NOT DISTINCT",
"link_transitions_origin_idx": "CREATE INDEX link_transitions_origin_idx ON public.link_transitions USING btree (origin_page_id)",
"link_transitions_pkey": "CREATE UNIQUE INDEX link_transitions_pkey ON public.link_transitions USING btree (id)",
"link_transitions_relationship_idx": "CREATE INDEX link_transitions_relationship_idx ON public.link_transitions USING btree (from_page_id, to_page_id, link_type)",
@@ -1977,7 +1977,8 @@
"9 producer text/text NOT NULL",
"10 origin_page_id integer/int4 NULL",
"11 line_hash text/text NOT NULL DEFAULT ''::text",
- "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()"
+ "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()",
+ "13 link_source text/text NULL"
],
"flags": "relkind=r rls=true force_rls=false"
},
diff --git a/test/fixtures/goldens/catalog/pglite-schema-blob-high-dims.json b/test/fixtures/goldens/catalog/pglite-schema-blob-high-dims.json
index 64fe5cb55d..e20374528c 100644
--- a/test/fixtures/goldens/catalog/pglite-schema-blob-high-dims.json
+++ b/test/fixtures/goldens/catalog/pglite-schema-blob-high-dims.json
@@ -989,7 +989,7 @@
"link_relationships_pkey": "CREATE UNIQUE INDEX link_relationships_pkey ON public.link_relationships USING btree (from_page_id, to_page_id, link_type, scope)",
"link_relationships_source_idx": "CREATE INDEX link_relationships_source_idx ON public.link_relationships USING btree (source_id, status_now)",
"link_relationships_to_idx": "CREATE INDEX link_relationships_to_idx ON public.link_relationships USING btree (to_page_id, link_type, scope)",
- "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT",
+ "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer) NULLS NOT DISTINCT",
"link_transitions_origin_idx": "CREATE INDEX link_transitions_origin_idx ON public.link_transitions USING btree (origin_page_id)",
"link_transitions_pkey": "CREATE UNIQUE INDEX link_transitions_pkey ON public.link_transitions USING btree (id)",
"link_transitions_relationship_idx": "CREATE INDEX link_transitions_relationship_idx ON public.link_transitions USING btree (from_page_id, to_page_id, link_type)",
@@ -1976,7 +1976,8 @@
"9 producer text/text NOT NULL",
"10 origin_page_id integer/int4 NULL",
"11 line_hash text/text NOT NULL DEFAULT ''::text",
- "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()"
+ "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()",
+ "13 link_source text/text NULL"
],
"flags": "relkind=r rls=true force_rls=false"
},
diff --git a/test/fixtures/goldens/catalog/postgres-db-initschema.json b/test/fixtures/goldens/catalog/postgres-db-initschema.json
index 83a4153832..8fe1c928cf 100644
--- a/test/fixtures/goldens/catalog/postgres-db-initschema.json
+++ b/test/fixtures/goldens/catalog/postgres-db-initschema.json
@@ -1022,7 +1022,7 @@
"link_relationships_pkey": "CREATE UNIQUE INDEX link_relationships_pkey ON public.link_relationships USING btree (from_page_id, to_page_id, link_type, scope)",
"link_relationships_source_idx": "CREATE INDEX link_relationships_source_idx ON public.link_relationships USING btree (source_id, status_now)",
"link_relationships_to_idx": "CREATE INDEX link_relationships_to_idx ON public.link_relationships USING btree (to_page_id, link_type, scope)",
- "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT",
+ "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer) NULLS NOT DISTINCT",
"link_transitions_origin_idx": "CREATE INDEX link_transitions_origin_idx ON public.link_transitions USING btree (origin_page_id)",
"link_transitions_pkey": "CREATE UNIQUE INDEX link_transitions_pkey ON public.link_transitions USING btree (id)",
"link_transitions_relationship_idx": "CREATE INDEX link_transitions_relationship_idx ON public.link_transitions USING btree (from_page_id, to_page_id, link_type)",
@@ -2052,7 +2052,8 @@
"9 producer text/text NOT NULL",
"10 origin_page_id integer/int4 NULL",
"11 line_hash text/text NOT NULL DEFAULT ''::text",
- "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()"
+ "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()",
+ "13 link_source text/text NULL"
],
"flags": "relkind=r rls=true force_rls=false"
},
diff --git a/test/fixtures/goldens/catalog/postgres-engine-init-default.json b/test/fixtures/goldens/catalog/postgres-engine-init-default.json
index 8f965096b2..131f537873 100644
--- a/test/fixtures/goldens/catalog/postgres-engine-init-default.json
+++ b/test/fixtures/goldens/catalog/postgres-engine-init-default.json
@@ -1428,7 +1428,7 @@
"link_relationships_pkey": "CREATE UNIQUE INDEX link_relationships_pkey ON public.link_relationships USING btree (from_page_id, to_page_id, link_type, scope)",
"link_relationships_source_idx": "CREATE INDEX link_relationships_source_idx ON public.link_relationships USING btree (source_id, status_now)",
"link_relationships_to_idx": "CREATE INDEX link_relationships_to_idx ON public.link_relationships USING btree (to_page_id, link_type, scope)",
- "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT",
+ "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer) NULLS NOT DISTINCT",
"link_transitions_origin_idx": "CREATE INDEX link_transitions_origin_idx ON public.link_transitions USING btree (origin_page_id)",
"link_transitions_pkey": "CREATE UNIQUE INDEX link_transitions_pkey ON public.link_transitions USING btree (id)",
"link_transitions_relationship_idx": "CREATE INDEX link_transitions_relationship_idx ON public.link_transitions USING btree (from_page_id, to_page_id, link_type)",
@@ -2821,7 +2821,8 @@
"9 producer text/text NOT NULL",
"10 origin_page_id integer/int4 NULL",
"11 line_hash text/text NOT NULL DEFAULT ''::text",
- "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()"
+ "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()",
+ "13 link_source text/text NULL"
],
"flags": "relkind=r rls=true force_rls=false"
},
diff --git a/test/fixtures/goldens/catalog/postgres-engine-init-fts-portuguese.json b/test/fixtures/goldens/catalog/postgres-engine-init-fts-portuguese.json
index 1015bc6397..549bb08594 100644
--- a/test/fixtures/goldens/catalog/postgres-engine-init-fts-portuguese.json
+++ b/test/fixtures/goldens/catalog/postgres-engine-init-fts-portuguese.json
@@ -1428,7 +1428,7 @@
"link_relationships_pkey": "CREATE UNIQUE INDEX link_relationships_pkey ON public.link_relationships USING btree (from_page_id, to_page_id, link_type, scope)",
"link_relationships_source_idx": "CREATE INDEX link_relationships_source_idx ON public.link_relationships USING btree (source_id, status_now)",
"link_relationships_to_idx": "CREATE INDEX link_relationships_to_idx ON public.link_relationships USING btree (to_page_id, link_type, scope)",
- "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT",
+ "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer) NULLS NOT DISTINCT",
"link_transitions_origin_idx": "CREATE INDEX link_transitions_origin_idx ON public.link_transitions USING btree (origin_page_id)",
"link_transitions_pkey": "CREATE UNIQUE INDEX link_transitions_pkey ON public.link_transitions USING btree (id)",
"link_transitions_relationship_idx": "CREATE INDEX link_transitions_relationship_idx ON public.link_transitions USING btree (from_page_id, to_page_id, link_type)",
@@ -2821,7 +2821,8 @@
"9 producer text/text NOT NULL",
"10 origin_page_id integer/int4 NULL",
"11 line_hash text/text NOT NULL DEFAULT ''::text",
- "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()"
+ "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()",
+ "13 link_source text/text NULL"
],
"flags": "relkind=r rls=true force_rls=false"
},
diff --git a/test/fixtures/goldens/catalog/postgres-engine-init-high-dims.json b/test/fixtures/goldens/catalog/postgres-engine-init-high-dims.json
index bfd82d703f..6576df463f 100644
--- a/test/fixtures/goldens/catalog/postgres-engine-init-high-dims.json
+++ b/test/fixtures/goldens/catalog/postgres-engine-init-high-dims.json
@@ -1424,7 +1424,7 @@
"link_relationships_pkey": "CREATE UNIQUE INDEX link_relationships_pkey ON public.link_relationships USING btree (from_page_id, to_page_id, link_type, scope)",
"link_relationships_source_idx": "CREATE INDEX link_relationships_source_idx ON public.link_relationships USING btree (source_id, status_now)",
"link_relationships_to_idx": "CREATE INDEX link_relationships_to_idx ON public.link_relationships USING btree (to_page_id, link_type, scope)",
- "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT",
+ "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer) NULLS NOT DISTINCT",
"link_transitions_origin_idx": "CREATE INDEX link_transitions_origin_idx ON public.link_transitions USING btree (origin_page_id)",
"link_transitions_pkey": "CREATE UNIQUE INDEX link_transitions_pkey ON public.link_transitions USING btree (id)",
"link_transitions_relationship_idx": "CREATE INDEX link_transitions_relationship_idx ON public.link_transitions USING btree (from_page_id, to_page_id, link_type)",
@@ -2817,7 +2817,8 @@
"9 producer text/text NOT NULL",
"10 origin_page_id integer/int4 NULL",
"11 line_hash text/text NOT NULL DEFAULT ''::text",
- "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()"
+ "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()",
+ "13 link_source text/text NULL"
],
"flags": "relkind=r rls=true force_rls=false"
},
diff --git a/test/fixtures/goldens/pglite-upgrade-replay/catalog-after-boot.json b/test/fixtures/goldens/pglite-upgrade-replay/catalog-after-boot.json
index 10bacf4139..76fef2e11c 100644
--- a/test/fixtures/goldens/pglite-upgrade-replay/catalog-after-boot.json
+++ b/test/fixtures/goldens/pglite-upgrade-replay/catalog-after-boot.json
@@ -1425,7 +1425,7 @@
"link_relationships_pkey": "CREATE UNIQUE INDEX link_relationships_pkey ON public.link_relationships USING btree (from_page_id, to_page_id, link_type, scope)",
"link_relationships_source_idx": "CREATE INDEX link_relationships_source_idx ON public.link_relationships USING btree (source_id, status_now)",
"link_relationships_to_idx": "CREATE INDEX link_relationships_to_idx ON public.link_relationships USING btree (to_page_id, link_type, scope)",
- "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT",
+ "link_transitions_identity_idx": "CREATE UNIQUE INDEX link_transitions_identity_idx ON public.link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer) NULLS NOT DISTINCT",
"link_transitions_origin_idx": "CREATE INDEX link_transitions_origin_idx ON public.link_transitions USING btree (origin_page_id)",
"link_transitions_pkey": "CREATE UNIQUE INDEX link_transitions_pkey ON public.link_transitions USING btree (id)",
"link_transitions_relationship_idx": "CREATE INDEX link_transitions_relationship_idx ON public.link_transitions USING btree (from_page_id, to_page_id, link_type)",
@@ -2809,7 +2809,8 @@
"9 producer text/text NOT NULL",
"10 origin_page_id integer/int4 NULL",
"11 line_hash text/text NOT NULL DEFAULT ''::text",
- "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()"
+ "12 created_at timestamp with time zone/timestamptz NOT NULL DEFAULT now()",
+ "13 link_source text/text NULL"
],
"flags": "relkind=r rls=true force_rls=false"
},
diff --git a/test/link-dates-per-row-gst2228.test.ts b/test/link-dates-per-row-gst2228.test.ts
new file mode 100644
index 0000000000..61f4702e79
--- /dev/null
+++ b/test/link-dates-per-row-gst2228.test.ts
@@ -0,0 +1,173 @@
+/**
+ * GST-2228: each row of a page's `## Links` section keeps its own dates. A row is keyed (to, type, source), and its
+ * `valid_from` / `valid_until` cells are stored as dated statements in link_transitions together with the row's source
+ * (`link_source`). So when a writer re-creates a links section that a page rewrite dropped, each kept row gets back its
+ * own dates, and `remove_link` on one source deletes that row's dates and no other row's.
+ *
+ * Before this, statements had no source, so the rebuilt section had to pair dates to rows by position: two rows of one
+ * relationship could swap dates, a later `remove_link` on one source then deleted the other row's dates, and a row
+ * removed while the section was gone left its dates behind for the next rebuild to trip over. Statements written before
+ * the column existed have no source; with several kept rows for their relationship the writer refuses
+ * (`link_dates_unattributed`) instead of guessing, and with one kept row the dates are that row's.
+ * Managed brain, repo-less and Git-backed; PGLite, and Postgres from test/postgres-unit-arms.txt.
+ */
+import { describe, expect, test } from 'bun:test';
+import { randomUUID } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { BrainEngine } from '../src/core/engine.ts';
+import type { OperationContext } from '../src/core/ops/contract.ts';
+import { operationsByName } from '../src/core/operations.ts';
+import { parseLinksFence, readPageLinksFence, renderLinksFence, type LinksFenceRow } from '../src/core/links-fence.ts';
+import { durableGitRepo } from './helpers/git-publication.ts';
+import { managedBrain, settleManagedGitEffects } from './helpers/managed-brain.ts';
+import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';
+
+type Storage = 'repo-less' | 'git';
+const gitSetup = ({ root }: { root: string }) => { writeFileSync(join(root, '.gitignore'), '\n'); durableGitRepo(root, ['.gitignore']); };
+
+const ALICE = 'people/alice-example';
+const PERSON = (body: string) => `---\ntype: person\ntitle: Alice Example\n---\n\n# Alice Example\n\n${body}`;
+const COMPANY = (title: string) => `---\ntype: company\ntitle: ${title}\n---\n\n# ${title}\n\nA company.\n`;
+const ACME = 'companies/acme-example';
+const BETA: LinksFenceRow = { to: 'companies/beta-example', type: 'advises', source: 'manual', context: 'board seat' };
+const FIRST_STINT: LinksFenceRow = { to: ACME, type: 'works_at', source: 'manual', validFrom: '2020-01-01', validUntil: '2021-01-01', context: 'first stint' };
+const SECOND_STINT: LinksFenceRow = { to: ACME, type: 'works_at', source: 'crm-import', validFrom: '2022-01-01', context: 'second stint' };
+const SECTION = (rows: LinksFenceRow[]) => `## Links\n\n${renderLinksFence(rows)}\n`;
+const DROPPED = 'Alice, rewritten by an agent without the links section.\n';
+
+const op = (ctx: OperationContext, name: string, params: Record<string, unknown>) =>
+ operationsByName[name]!.handler(ctx, { request_id: randomUUID(), ...params }) as Promise<Record<string, unknown>>;
+const put = async (ctx: OperationContext, slug: string, content: string) => {
+ const prior = await ctx.engine.readPageSnapshot(slug, { sourceId: 'default' });
+ await op(ctx, 'put_page', { slug, content, ...(prior ? { expected_revision: prior.revision } : {}) });
+};
+const addBeta = (ctx: OperationContext) => op(ctx, 'add_link', { from: ALICE, to: BETA.to, link_type: BETA.type, context: BETA.context });
+const revision = async (engine: BrainEngine) => (await engine.readPageSnapshot(ALICE, { sourceId: 'default' }))!.revision;
+
+/** Alice's manual dated statements, one string per statement: `<to> <kind> <date> <source or NULL>`. */
+const statements = async (engine: BrainEngine) => (await engine.executeRaw<{ to: string; kind: string; on: string; source: string | null }>(
+ `SELECT t.slug AS to, lt.kind, lt.occurred_on::text AS on, lt.link_source AS source FROM link_transitions lt
+ JOIN pages f ON f.id=lt.from_page_id JOIN pages t ON t.id=lt.to_page_id
+ WHERE f.source_id='default' AND f.slug=$1 AND lt.producer='manual'`, [ALICE]))
+ .map(row => `${row.to} ${row.kind} ${row.on} ${row.source ?? 'NULL'}`).sort();
+/** The same statements without their source, so the two loss tests read the same on a brain that predates the column. */
+const dates = async (engine: BrainEngine) => (await engine.executeRaw<{ to: string; kind: string; on: string }>(
+ `SELECT t.slug AS to, lt.kind, lt.occurred_on::text AS on FROM link_transitions lt JOIN pages f ON f.id=lt.from_page_id JOIN pages t ON t.id=lt.to_page_id
+ WHERE f.source_id='default' AND f.slug=$1 AND lt.producer='manual'`, [ALICE])).map(row => `${row.to} ${row.kind} ${row.on}`).sort();
+const edges = async (engine: BrainEngine) => (await engine.executeRaw<{ to: string; source: string }>(
+ `SELECT t.slug AS to, l.link_source AS source FROM links l JOIN pages f ON f.id=l.from_page_id JOIN pages t ON t.id=l.to_page_id
+ WHERE f.source_id='default' AND f.slug=$1 AND l.origin_field='links_fence'`, [ALICE])).map(row => `${row.to} ${row.source}`).sort();
+const sortRows = (rows: LinksFenceRow[]) => [...rows].sort((a, b) => `${a.to}${a.source}`.localeCompare(`${b.to}${b.source}`));
+const pageRows = async (engine: BrainEngine) => sortRows(readPageLinksFence((await engine.readPageSnapshot(ALICE, { sourceId: 'default' }))!.page).rows);
+/** Simulates statements written before link_transitions had a source column. */
+const forgetSources = (engine: BrainEngine) => engine.executeRaw(
+ `UPDATE link_transitions SET link_source=NULL WHERE producer='manual' AND from_page_id=(SELECT id FROM pages WHERE source_id='default' AND slug=$1)`, [ALICE]);
+
+async function seed(ctx: OperationContext) {
+ await put(ctx, ACME, COMPANY('Acme Example'));
+ await put(ctx, BETA.to, COMPANY('Beta Example'));
+}
+
+for (const backend of testBackends()) {
+ const databaseUrl = backend === 'postgres' ? requirePostgresTestDatabase() : undefined;
+ for (const storage of ['repo-less', 'git'] as Storage[]) {
+ const opts = { databaseUrl, ...(storage === 'git' ? { setup: gitSetup } : {}) };
+ const fileRows = async (engine: BrainEngine, root: string) => {
+ if (storage === 'git') await settleManagedGitEffects(engine);
+ return sortRows(parseLinksFence(readFileSync(join(root, `${ALICE}.md`), 'utf8')).rows);
+ };
+
+ describe(`each links-section row keeps its own dates (${backend}, ${storage})`, () => {
+ test('two rows of one relationship from different sources: the rebuilt section keeps each row\'s dates, and remove_link on one source keeps the other\'s', () => managedBrain(async ({ engine, ctx, root }) => {
+ await seed(ctx);
+ await put(ctx, ALICE, PERSON(`Alice v1.\n\n${SECTION([FIRST_STINT, SECOND_STINT])}`));
+ await put(ctx, ALICE, PERSON(DROPPED));
+ await addBeta(ctx);
+ expect(await pageRows(engine)).toEqual(sortRows([FIRST_STINT, SECOND_STINT, BETA]));
+ await op(ctx, 'remove_link', { from: ALICE, to: ACME, link_type: 'works_at', link_source: 'crm-import' });
+ expect(await pageRows(engine)).toEqual(sortRows([FIRST_STINT, BETA]));
+ expect(await dates(engine)).toEqual([`${ACME} end 2021-01-01`, `${ACME} start 2020-01-01`]);
+ expect(await statements(engine)).toEqual([`${ACME} end 2021-01-01 manual`, `${ACME} start 2020-01-01 manual`]);
+ expect(await fileRows(engine, root)).toEqual(sortRows([FIRST_STINT, BETA]));
+ }, opts), 180_000);
+
+ test('a row removed while the section is gone takes its dates with it, and the next add_link keeps the remaining row exactly', () => managedBrain(async ({ engine, ctx, root }) => {
+ const current: LinksFenceRow = { to: ACME, type: 'works_at', source: 'manual', validFrom: '2022-01-01', context: 'current stint' };
+ const past: LinksFenceRow = { ...FIRST_STINT, source: 'crm-import' };
+ await seed(ctx);
+ await put(ctx, ALICE, PERSON(`Alice v1.\n\n${SECTION([current, past])}`));
+ await put(ctx, ALICE, PERSON(DROPPED));
+ await op(ctx, 'remove_link', { from: ALICE, to: ACME, link_type: 'works_at', link_source: 'crm-import' });
+ expect(await dates(engine)).toEqual([`${ACME} start 2022-01-01`]);
+ await addBeta(ctx);
+ expect(await pageRows(engine)).toEqual(sortRows([current, BETA]));
+ expect(await dates(engine)).toEqual([`${ACME} start 2022-01-01`]);
+ expect(await statements(engine)).toEqual([`${ACME} start 2022-01-01 manual`]);
+ expect(await fileRows(engine, root)).toEqual(sortRows([current, BETA]));
+ }, opts), 180_000);
+
+ test('two rows of one relationship sharing a date both show it after the section is rebuilt', () => managedBrain(async ({ engine, ctx }) => {
+ const fromCrm: LinksFenceRow = { to: ACME, type: 'works_at', source: 'crm-import', validFrom: '2020-01-01', context: 'from the import' };
+ const byHand: LinksFenceRow = { to: ACME, type: 'works_at', source: 'manual', validFrom: '2020-01-01', context: 'typed in' };
+ await seed(ctx);
+ await put(ctx, ALICE, PERSON(`Alice v1.\n\n${SECTION([fromCrm, byHand])}`));
+ await put(ctx, ALICE, PERSON(DROPPED));
+ await addBeta(ctx);
+ expect(await pageRows(engine)).toEqual(sortRows([fromCrm, byHand, BETA]));
+ expect(await statements(engine)).toEqual([`${ACME} start 2020-01-01 crm-import`, `${ACME} start 2020-01-01 manual`]);
+ }, opts), 180_000);
+
+ test('statements from before the source column, several kept rows: add_link and remove_link refuse link_dates_unattributed and change nothing', () => managedBrain(async ({ engine, ctx }) => {
+ await seed(ctx);
+ await put(ctx, ALICE, PERSON(`Alice v1.\n\n${SECTION([FIRST_STINT, SECOND_STINT])}`));
+ await put(ctx, ALICE, PERSON(DROPPED));
+ await forgetSources(engine);
+ const before = { revision: await revision(engine), statements: await statements(engine), edges: await edges(engine) };
+ expect(before.statements).toEqual([`${ACME} end 2021-01-01 NULL`, `${ACME} start 2020-01-01 NULL`, `${ACME} start 2022-01-01 NULL`]);
+ const refusal = { code: 'link_dates_unattributed', message: expect.stringMatching(new RegExp(`${ACME}[^]*edit_page`)) };
+ await expect(addBeta(ctx)).rejects.toMatchObject(refusal);
+ await expect(op(ctx, 'remove_link', { from: ALICE, to: ACME, link_type: 'works_at', link_source: 'crm-import' })).rejects.toMatchObject(refusal);
+ expect({ revision: await revision(engine), statements: await statements(engine), edges: await edges(engine) }).toEqual(before);
+ }, opts), 180_000);
+
+ test('statements from before the source column, one kept row: add_link puts them on that row and labels them with its source', () => managedBrain(async ({ engine, ctx, root }) => {
+ await seed(ctx);
+ await put(ctx, ALICE, PERSON(`Alice v1.\n\n${SECTION([FIRST_STINT])}`));
+ await put(ctx, ALICE, PERSON(DROPPED));
+ await forgetSources(engine);
+ await addBeta(ctx);
+ expect(await pageRows(engine)).toEqual(sortRows([FIRST_STINT, BETA]));
+ expect(await statements(engine)).toEqual([`${ACME} end 2021-01-01 manual`, `${ACME} start 2020-01-01 manual`]);
+ expect(await fileRows(engine, root)).toEqual(sortRows([FIRST_STINT, BETA]));
+ }, opts), 180_000);
+
+ test('a page that still has its links section labels statements from before the source column on its next write', () => managedBrain(async ({ engine, ctx }) => {
+ await seed(ctx);
+ await put(ctx, ALICE, PERSON(`Alice v1.\n\n${SECTION([FIRST_STINT, SECOND_STINT])}`));
+ await forgetSources(engine);
+ await put(ctx, ALICE, PERSON(`Alice v2.\n\n${SECTION([FIRST_STINT, SECOND_STINT])}`));
+ expect(await statements(engine)).toEqual([`${ACME} end 2021-01-01 manual`, `${ACME} start 2020-01-01 manual`, `${ACME} start 2022-01-01 crm-import`]);
+ }, opts), 180_000);
+
+ test('append_page text holding a links fence is refused and the page keeps its links', () => managedBrain(async ({ engine, ctx }) => {
+ await seed(ctx);
+ await put(ctx, ALICE, PERSON(`Alice v1.\n\n${SECTION([FIRST_STINT])}`));
+ await put(ctx, ALICE, PERSON(DROPPED));
+ const before = await revision(engine);
+ await expect(op(ctx, 'append_page', { slug: ALICE, text: SECTION([BETA]) })).rejects.toMatchObject({ code: 'append_links_fence' });
+ expect(await revision(engine)).toBe(before);
+ expect(await edges(engine)).toEqual([`${ACME} manual`]);
+ }, opts), 180_000);
+
+ test('append_page text without links markers is appended unchanged', () => managedBrain(async ({ engine, ctx }) => {
+ await seed(ctx);
+ await put(ctx, ALICE, PERSON(`Alice v1.\n\n${SECTION([FIRST_STINT])}`));
+ await op(ctx, 'append_page', { slug: ALICE, text: 'Alice joined the example reading group.' });
+ expect((await engine.readPageSnapshot(ALICE, { sourceId: 'default' }))!.page.compiled_truth).toContain('Alice joined the example reading group.');
+ expect(await edges(engine)).toEqual([`${ACME} manual`]);
+ expect(await pageRows(engine)).toEqual([FIRST_STINT]);
+ }, opts), 180_000);
+ });
+ }
+}
diff --git a/test/link-transitions-source-migration-gst2228.test.ts b/test/link-transitions-source-migration-gst2228.test.ts
new file mode 100644
index 0000000000..e294398f0d
--- /dev/null
+++ b/test/link-transitions-source-migration-gst2228.test.ts
@@ -0,0 +1,158 @@
+/**
+ * GST-2228: migration v297 adds link_transitions.link_source and widens the identity index to include it, without
+ * holding a long lock on a large brain and without rewriting a row.
+ *
+ * 1. Protects: the column is added on its own (metadata only), the widened index is built online under a temporary
+ * name (CONCURRENTLY on Postgres), and one short transaction swaps it into the canonical name. A rerun after the run
+ * stopped at any step finishes the job, and an INVALID leftover of an interrupted concurrent build is dropped and
+ * rebuilt. Statements stored before the column keep a NULL source and are not rewritten.
+ * 2. Writes between the column and the swap: the old index still keys a statement without its source, so a second row's
+ * statement for the same relationship and date is dropped by ON CONFLICT DO NOTHING, as before the migration; the
+ * page's next write after the swap adds it.
+ * 3. Real seams: runMigrations and buildIndexOnline on PGLite, and on Postgres when DATABASE_URL is set (testBackends).
+ */
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import type { BrainEngine } from '../src/core/engine.ts';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { MIGRATIONS, runMigrations } from '../src/core/migrate.ts';
+import { buildIndexOnline } from '../src/core/schema-migrations/helpers.ts';
+import { LINK_TRANSITIONS_IDENTITY_NEXT_INDEX } from '../src/core/schema-migrations/v297-link-transitions-source.ts';
+import { projectLinksFence } from '../src/core/links-fence-projection.ts';
+import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
+import { testBackends } from './helpers/test-backends.ts';
+
+const OLD_INDEX = `CREATE UNIQUE INDEX IF NOT EXISTS link_transitions_identity_idx
+ ON link_transitions (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT`;
+const backends = testBackends();
+const engines: Array<{ backend: string; engine: BrainEngine; alice: number; acme: number }> = [];
+let closePostgres: (() => Promise<void>) | undefined;
+
+async function withPages(backend: string, engine: BrainEngine) {
+ const page = (slug: string, title: string, type: string) => engine.putPage(slug, { type, title, compiled_truth: title, timeline: '', frontmatter: {} } as never, { sourceId: 'default' });
+ const alice = Number((await page('people/alice-example', 'Alice Example', 'person')).id);
+ const acme = Number((await page('companies/acme-example', 'Acme Example', 'company')).id);
+ engines.push({ backend, engine, alice, acme });
+}
+
+beforeAll(async () => {
+ if (backends.includes('pglite')) {
+ const engine = new PGLiteEngine();
+ await engine.connect({}); await engine.initSchema();
+ await withPages('pglite', engine);
+ }
+ if (backends.includes('postgres')) {
+ const pg = await isolatedPersistencePostgres(process.env.DATABASE_URL!);
+ closePostgres = pg.close;
+ await withPages('postgres', pg.engine);
+ }
+}, 120_000);
+
+afterAll(async () => {
+ for (const { backend, engine } of engines) if (backend === 'pglite') await engine.disconnect();
+ await closePostgres?.();
+});
+
+describe('GST-2228 v297 link_transitions_source', () => {
+ test('v297 runs outside a transaction, through its handler', () => {
+ const m = MIGRATIONS.find(x => x.name === 'link_transitions_source');
+ expect({ found: !!m, transaction: m?.transaction, sql: m?.sql, handler: typeof m?.handler }).toEqual({ found: true, transaction: false, sql: '', handler: 'function' });
+ });
+
+ for (const backend of backends) {
+ const brain = () => engines.find(e => e.backend === backend)!;
+ const identity = async () => {
+ const { engine } = brain();
+ const [row] = await engine.executeRaw<{ def: string | null; valid: boolean | null; next: boolean; column: boolean }>(
+ `SELECT pg_get_indexdef(to_regclass('link_transitions_identity_idx')) AS def,
+ (SELECT indisvalid FROM pg_index WHERE indexrelid = to_regclass('link_transitions_identity_idx')) AS valid,
+ to_regclass('link_transitions_identity_next_idx') IS NOT NULL AS next,
+ EXISTS (SELECT 1 FROM information_schema.columns WHERE table_name='link_transitions' AND column_name='link_source') AS column`);
+ return { ...row!, def: row!.def?.replace(/ public\./, ' ') ?? null };
+ };
+ const WIDENED = 'CREATE UNIQUE INDEX link_transitions_identity_idx ON link_transitions USING btree (origin_page_id, from_page_id, to_page_id, link_type, link_source, kind, occurred_on, producer) NULLS NOT DISTINCT';
+ const DONE = { def: WIDENED, valid: true, next: false, column: true };
+ /** The schema a brain one migration before v297 has: no link_source, the seven-column identity index. */
+ const beforeV297 = async () => {
+ const { engine } = brain();
+ await engine.executeRaw('DELETE FROM link_transitions');
+ await engine.executeRaw('DROP INDEX IF EXISTS link_transitions_identity_next_idx');
+ await engine.executeRaw('ALTER TABLE link_transitions DROP COLUMN IF EXISTS link_source');
+ await engine.executeRaw(OLD_INDEX);
+ await engine.setConfig('version', String(MIGRATIONS.find(m => m.name === 'link_transitions_source')!.version - 1));
+ };
+ const latest = String(Math.max(...MIGRATIONS.map(m => m.version)));
+
+ test(`[${backend}] a fresh schema has the widened index and no temporary index`, async () => {
+ expect(await identity()).toEqual(DONE);
+ });
+
+ test(`[${backend}] upgrading from the previous schema adds the column, swaps the index and rewrites no row`, async () => {
+ const { engine, alice, acme } = brain();
+ await beforeV297();
+ await engine.executeRaw(`INSERT INTO link_transitions (source_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer, origin_page_id)
+ VALUES ('default', $1, $2, 'works_at', 'start', '2020-01-01', 'manual', $1)`, [alice, acme]);
+ const [before] = await engine.executeRaw<{ id: string; xmin: string }>('SELECT id::text, xmin::text FROM link_transitions');
+ await runMigrations(engine);
+ expect(await identity()).toEqual(DONE);
+ expect(await engine.executeRaw('SELECT id::text, xmin::text, link_source FROM link_transitions')).toEqual([{ ...before, link_source: null }]);
+ expect(await engine.getConfig('version')).toBe(latest);
+ });
+
+ test(`[${backend}] stopped after the column was added: a rerun swaps the index`, async () => {
+ const { engine } = brain();
+ await beforeV297();
+ await engine.executeRaw('ALTER TABLE link_transitions ADD COLUMN link_source TEXT');
+ await runMigrations(engine);
+ expect(await identity()).toEqual(DONE);
+ });
+
+ test(`[${backend}] stopped after the build, before the swap: a rerun swaps the built index in`, async () => {
+ const { engine } = brain();
+ await beforeV297();
+ await engine.executeRaw('ALTER TABLE link_transitions ADD COLUMN link_source TEXT');
+ expect(await buildIndexOnline(engine, 297, LINK_TRANSITIONS_IDENTITY_NEXT_INDEX)).toBe('created');
+ expect((await identity()).next).toBe(true);
+ await runMigrations(engine);
+ expect(await identity()).toEqual(DONE);
+ });
+
+ if (backend === 'postgres') {
+ test('[postgres] an INVALID leftover of an interrupted concurrent build is dropped and rebuilt', async () => {
+ const { engine, alice, acme } = brain();
+ await beforeV297();
+ await engine.executeRaw('ALTER TABLE link_transitions ADD COLUMN link_source TEXT');
+ await engine.executeRaw('DROP INDEX link_transitions_identity_idx');
+ const duplicate = `INSERT INTO link_transitions (source_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer, origin_page_id)
+ VALUES ('default', $1, $2, 'works_at', 'start', '2020-01-01', 'manual', $1)`;
+ await engine.executeRaw(duplicate, [alice, acme]);
+ await engine.executeRaw(duplicate, [alice, acme]);
+ await expect(engine.executeRaw(LINK_TRANSITIONS_IDENTITY_NEXT_INDEX.sql.replace('CREATE UNIQUE INDEX', 'CREATE UNIQUE INDEX CONCURRENTLY'))).rejects.toThrow();
+ const [leftover] = await engine.executeRaw<{ valid: boolean }>(`SELECT indisvalid AS valid FROM pg_index WHERE indexrelid = to_regclass('link_transitions_identity_next_idx')`);
+ expect(leftover).toEqual({ valid: false });
+ await engine.executeRaw('DELETE FROM link_transitions WHERE id = (SELECT max(id) FROM link_transitions)');
+ await engine.executeRaw(OLD_INDEX);
+ await runMigrations(engine);
+ expect(await identity()).toEqual(DONE);
+ });
+ }
+
+ test(`[${backend}] a links-section write between the column and the swap keeps one statement per date, and the next write after the swap adds the other row's`, async () => {
+ const { engine, alice } = brain();
+ const rows = [
+ { to: 'companies/acme-example', type: 'works_at', source: 'manual', context: 'typed in', validFrom: '2020-01-01' },
+ { to: 'companies/acme-example', type: 'works_at', source: 'crm-import', context: 'from the import', validFrom: '2020-01-01' },
+ ];
+ const statements = async () => (await engine.executeRaw<{ source: string }>(
+ "SELECT link_source AS source FROM link_transitions WHERE origin_page_id=$1 AND producer='manual' ORDER BY 1", [alice])).map(r => r.source);
+ await beforeV297();
+ await engine.executeRaw('ALTER TABLE link_transitions ADD COLUMN link_source TEXT');
+ await projectLinksFence(engine, { id: alice, source_id: 'default' }, rows);
+ expect(await statements()).toEqual(['manual']);
+ await runMigrations(engine);
+ expect(await identity()).toEqual(DONE);
+ await projectLinksFence(engine, { id: alice, source_id: 'default' }, rows);
+ expect(await statements()).toEqual(['crm-import', 'manual']);
+ await engine.executeRaw('DELETE FROM links WHERE origin_page_id=$1', [alice]);
+ });
+ }
+});
diff --git a/test/postgres-unit-arms.txt b/test/postgres-unit-arms.txt
index e9e6d75f6e..373728df3f 100644
--- a/test/postgres-unit-arms.txt
+++ b/test/postgres-unit-arms.txt
@@ -255,7 +255,9 @@ test/large-pages/upload-provenance-7873.test.ts
test/large-pages/upload-review.test.ts
test/large-pages/v252-master-reader-compat.test.ts
test/link-cross-source.test.ts
+test/link-dates-per-row-gst2228.test.ts
test/link-preparation-shared-index.test.ts
+test/link-transitions-source-migration-gst2228.test.ts
test/links-attendance-blocked.test.ts
test/links-extraction-yield.test.ts
test/list-jobs-row-bound.test.ts
diff --git a/test/schema-bootstrap-coverage.test.ts b/test/schema-bootstrap-coverage.test.ts
index f27e09e815..0da560cc73 100644
--- a/test/schema-bootstrap-coverage.test.ts
+++ b/test/schema-bootstrap-coverage.test.ts
@@ -244,6 +244,9 @@ const REQUIRED_BOOTSTRAP_COVERAGE: ForwardReference[] = [
// Authority remains nullable: bootstrap must never authorize historical work.
{ kind: 'column', table: 'minion_jobs', column: 'submission_authority' },
{ kind: 'column', table: 'minion_jobs', column: 'claim_generation' },
+ // v297 (GST-2228): the blob's unique link_transitions_identity_idx includes
+ // link_source, which only v297 adds to a brain at v204-v296.
+ { kind: 'column', table: 'link_transitions', column: 'link_source' },
];
test('applyForwardReferenceBootstrap covers every forward reference declared in REQUIRED_BOOTSTRAP_COVERAGE', async () => {
@@ -372,6 +375,12 @@ test('applyForwardReferenceBootstrap covers every forward reference declared in
ALTER TABLE minion_jobs DROP COLUMN IF EXISTS private_queue_lease_until;
ALTER TABLE minion_jobs DROP COLUMN IF EXISTS submission_authority;
ALTER TABLE minion_jobs DROP COLUMN IF EXISTS claim_generation;
+
+ -- v297 strip: a v204-v296 link_transitions has no link_source and the
+ -- narrower identity index under the same name.
+ ALTER TABLE link_transitions DROP COLUMN IF EXISTS link_source;
+ CREATE UNIQUE INDEX IF NOT EXISTS link_transitions_identity_idx
+ ON link_transitions (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT;
`);
// Note: we don't strip sources.archived* here because they're inline in the
@@ -486,6 +495,12 @@ test('after bootstrap, PGLITE_SCHEMA_SQL replays without crashing on missing for
ALTER TABLE minion_jobs DROP COLUMN IF EXISTS submission_authority;
ALTER TABLE minion_jobs DROP COLUMN IF EXISTS claim_generation;
+ -- v297 strip: a v204-v296 link_transitions has no link_source and the
+ -- narrower identity index under the same name.
+ ALTER TABLE link_transitions DROP COLUMN IF EXISTS link_source;
+ CREATE UNIQUE INDEX IF NOT EXISTS link_transitions_identity_idx
+ ON link_transitions (origin_page_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer) NULLS NOT DISTINCT;
+
-- WP4 (v127) strip: surface columns + the wedge-signal index; replay
-- must succeed from the pre-v127 shape.
DROP INDEX IF EXISTS idx_minion_jobs_queue_status_updated;