Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

get_backlinks answers empty for a page type the brain has instead of refusing it

garrytan141e93620a6f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 06ec96a1fa..a64eba3679 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,14 @@ 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]
+
+**Agent reads answer "nothing here" instead of refusing, and say why a list came back empty.** These fixes come from agent transcripts where models kept getting refused or got bare empty answers.
+
+### Itemized changes
+
+- `get_backlinks` with a `type` that other pages in the brain have, but no page linking to this one has, now returns the normal empty answer plus a note listing the types the linking pages do have. Before, it refused with `unknown type`, so an agent walking several accounts by type was refused once per account. A type no page has is still refused, and the refusal now also lists the brain's own page types. For a remote caller, both checks count only pages that caller can read: a type found only on private pages, pages whose readers leave the caller out, deleted pages or another source is treated as a type that does not exist and is never named.
+
## [0.60.651.0] - 2026-11-10
**CI wastes fewer reruns: the macOS type check stops running out of memory, and a worktree test stops stalling for two minutes.** The macOS type check now runs on GitHub's 14 GB Intel runner. On the 7 GB arm64 runner, a check that couldn't reuse a recent saved state ran short of memory, took 7 to 15 minutes and sometimes hit its 15-minute limit. On Intel a check with no saved state takes about 4 minutes. The stale-plan worktree test no longer waits out a 2-minute lease on PGLite: its wait for commits now lets timers run, so the background writer finishes its pass.
diff --git a/docs/architecture/key-files/engines-2.md b/docs/architecture/key-files/engines-2.md
index e74f557274..ed7d6764c4 100644
--- a/docs/architecture/key-files/engines-2.md
+++ b/docs/architecture/key-files/engines-2.md
@@ -32,7 +32,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/core/search/exact-scan.ts` + `src/core/ops/search-exact.ts` + `src/cli/search-exact-format.ts` — #7191: `search_exact` (CLI `gbrain search --exact`, routed in `cli/main.ts` before ranked-search flags parse): an unranked literal scan of `content_chunks.chunk_text` (words in order, any whitespace between, case-insensitive unless `case_sensitive`; the ARE comes from `phrasePattern`, with a LIKE prefilter on the longest word) in keyset batches of pages by id (`buildExactBatchStatement`), under ranked search's visibility (live page, unarchived source, quarantine, pinned questions, `chunkVisibleFilter`, source scope, private pages and the trust floor for untrusted callers, `safeChunksFilter` for remote) and the hard-excluded prefixes. `complete` is true only when the scope was scanned to the end with no `limit` or `deadline` stop and no unreadable page (`unchunked`, `projection_pending`, remote `unsealed`, `scan_timeout`); a Postgres statement timeout halves the batch, down to one page. `resume_after` continues a bounded scan. Registered `filtered` (`min_trust`, `stampPageTrust`), output redaction `retrieval`. Guide: [exact search](../../guides/exact-search.md). Tests: `test/search-exact.test.ts`, `test/e2e/search-exact-postgres.test.ts`.
- `src/core/engine-sql/titles.ts` + `src/core/search/title-statement.ts` — the page-grain title arm (`BrainEngine.searchTitles`) for both engines: `buildSearchTitlesStatement` in `search/` (SQL composed outside engine-sql like `cjk-keyword-sql.ts`; also used by the plan-proof E2E `test/e2e/title-arm-postgres.test.ts`) and `searchTitles(scoped, query, opts, dialect)` in engine-sql, where `dialect` carries the engine differences kept from master (Postgres: 8s per-attempt `statement_timeout`, `enable_seqscan` off for the relaxed local re-run; PGLite: the timeline `stale` probe). Both orderings sort an exact-title key first (`lower(btrim(title, ' "''' || chr(160))) = normalizeAlias(query)`, bound separately from the websearch text so the OR fallback never rebinds it; #5889). The websearch text is read through `gbrain_fts_input($1)` (#6370), the same CJK/ASCII boundary split the index applies, so a glued title query matches. Safe-chunks callers and every OR re-run match `ts_filter(search_vector, '{a}') @@ q` (weight A is the title alone) and rank on the same slice: served by the expression index `idx_pages_title_search` (GBRA-156, v267), which holds title lexemes only, so a term in timeline text never makes its page a candidate; title-only for negated and phrase terms, following the stored `search_vector` language. Postgres runs each attempt with the keyword statement's `work_mem` (`statementSettings`). Pages with a NULL `search_vector` are absent from the remote arm. #7471: a 2-4 word name query ORs in its given-name variants (`titleNameVariants`: "Matt Example" also matches the title "Matthew Example"), each its own bound websearch query; the OR fallback of a query of at most `RARITY_MAX_TERMS` words runs once per word in one scoped read and `rankByRarity` puts titles holding the rarest word first (ts_rank_cd knows no term rarity, so a surname's one title used to tie thousands of first-name titles and lose on page id). #7491: OR-retry titles holding every identifier the query names (`holdsIdentifiers`, search/keyword-identifier-probe.ts) lead untagged; the rest stay `keyword_relaxed`.
-- `src/core/engine-sql/page-lookup.ts` + `src/core/page-find.ts` + `src/core/page-counts.ts` + `src/core/ops/find-pages.ts` + `src/core/ops/stats-by.ts` + `src/cli/format-page-lookup.ts` — find-by-name and grouped counts (`gbrain find` / `find_pages`, `gbrain stats --by` / `get_stats` `by`, `since`, `collapse_aliases`). `parseFindPattern` turns a glob (`*`/`?`, whole slug or source path), a slug prefix (contains `/`) or a name (title or last slug segment substring) into one `escapeLikePattern`-escaped ILIKE pattern; names are served by `idx_pages_trgm` + `idx_pages_slug_trgm`, while globs and prefixes also match `source_path` (no trigram index). Rows sort by slug then source in the C collation, carry `count(*) OVER ()` as `total`, and the op reports `complete` (limit default 50, cap 500 local, 100 remote). Find hides the ranked-search hard excludes (`resolveHardExcludes` + `buildHardExcludeClause`) unless the pattern's literal lead is inside one, and names them in `hidden_prefixes`. `countPagesBy` returns per (source, type) counts plus raw and distinct-slug totals (per type group through an `unnest` mapping and GROUPING SETS), so cross-source twins are never silently double counted; `since` is the query effective-date bound (`resolveDateBoundary`). Every caller sees live pages in unarchived sources; a remote caller's `readPolicyOpts` policy adds `pageReadFilter(..., live)`. `collapseTypes` lets the active pack decide (declared stays, alias joins canonical), else normalizes (last segment, lower case, singular) and joins a `-<name>` suffix to an existing group; each group lists `member_types` with its rule (`exact`, `pack_alias`, `normalized`, `suffix`). Without the grouping params `get_stats` returns its unchanged counters. Tests: `test/page-find-pattern-7191.test.ts`, `test/page-lookup-7191.test.ts` (Postgres arm: `test/e2e/page-lookup-7191.test.ts`).
+- `src/core/engine-sql/page-lookup.ts` + `src/core/page-find.ts` + `src/core/page-counts.ts` + `src/core/ops/find-pages.ts` + `src/core/ops/stats-by.ts` + `src/cli/format-page-lookup.ts` — find-by-name and grouped counts (`gbrain find` / `find_pages`, `gbrain stats --by` / `get_stats` `by`, `since`, `collapse_aliases`). `parseFindPattern` turns a glob (`*`/`?`, whole slug or source path), a slug prefix (contains `/`) or a name (title or last slug segment substring) into one `escapeLikePattern`-escaped ILIKE pattern; names are served by `idx_pages_trgm` + `idx_pages_slug_trgm`, while globs and prefixes also match `source_path` (no trigram index). Rows sort by slug then source in the C collation, carry `count(*) OVER ()` as `total`, and the op reports `complete` (limit default 50, cap 500 local, 100 remote). Find hides the ranked-search hard excludes (`resolveHardExcludes` + `buildHardExcludeClause`) unless the pattern's literal lead is inside one, and names them in `hidden_prefixes`. `countPagesBy` returns per (source, type) counts plus raw and distinct-slug totals (per type group through an `unnest` mapping and GROUPING SETS), so cross-source twins are never silently double counted; `since` is the query effective-date bound (`resolveDateBoundary`). Every caller sees live pages in unarchived sources; a remote caller's `readPolicyOpts` policy adds `pageReadFilter(..., live)`. `collapseTypes` lets the active pack decide (declared stays, alias joins canonical), else normalizes (last segment, lower case, singular) and joins a `-<name>` suffix to an existing group; each group lists `member_types` with its rule (`exact`, `pack_alias`, `normalized`, `suffix`). Without the grouping params `get_stats` returns its unchanged counters. `visiblePageTypes` (GBRA-449) is the same count summed per type, most pages first, for `get_backlinks`' type check and an empty `list_pages` notice. Tests: `test/page-find-pattern-7191.test.ts`, `test/page-lookup-7191.test.ts` (Postgres arm: `test/e2e/page-lookup-7191.test.ts`).
- `src/core/engine-sql/health.ts` — `BrainEngine.getHealth` once for both engines (`migrated health`). Three statements, no per-page rows returned: the counters (pages, chunks, links, embedding coverage, missing embeddings, dead links, entity link/timeline coverage), the linkable scope grouped by page type with islanded and with-timeline counts (the orphan policy rendered in SQL by `orphanExclusionSql`; the brain_score timeline grading applies per type), and `most_connected` as live, in-scope link endpoints grouped per entity page (ties break by slug in code-point order; a link whose far endpoint is soft-deleted does not count, #6940). The linkable groups are a separate statement because folding them into the counters crosses Postgres's JIT cost thresholds at about 20k pages. Per-page and per-link checks that misplan without planner statistics (PGLite before its first ANALYZE) are primary-key lookups the planner cannot reorder (scalar subqueries, a LATERAL fenced with `OFFSET 0`), so the statements stay linear with or without statistics. Scope rules: `sourceIds` > `sourceId` > brain-wide, duplicate ids count once, a link counts only when both endpoints are in scope, endpoint liveness in both directions, quarantined pages out of the entity denominators and the linkable scope. Entity pages (#4772) are the types the active schema pack(s) declare as entities, resolved per source by `HealthDeps.entityTypes` (`src/core/schema-pack/entity-types.ts`) and bound as `text[]` parameters (`entityTypePredicateSql`: one list, or a `CASE p.source_id` when sources' packs disagree); a pack that does not load binds an empty list and the result carries `entity_types_status: 'pack_unavailable'`, never the old hardcoded list. Reads take `LegacyUnscopedRead` (pool, no scope transaction). Engine deps are four functions (`embeddingColumn`, `countStalePagesForExtraction`, `getConfig`, `entityTypes`). Pinned field by field against the pre-F4a implementation (`test/helpers/legacy-get-health.ts`, whose `most_connected` was corrected for #6940 as an intended change) by `test/engine-sql-health-equality.test.ts` and `test/e2e/engine-sql-health-parity.test.ts` (direct Postgres and PgBouncer); the pack-driven entity predicate by `test/health-entity-types-pack.test.ts` and `test/e2e/health-entity-types-pack.test.ts`; `most_connected` liveness by `test/health-most-connected-liveness-6940.test.ts` (+ Postgres twin).
- `src/core/engine-sql/graph-rank.ts` — #7168: `rankEntitiesStatement(opts)`, the one `rank_entities` aggregate for both engines (a statement builder: the op runs it through `executeRaw` with its statement deadline, like `extractionLagStatement`). Edges are distinct `(from, to, link_type)` triples between live, in-scope endpoints (both endpoints scoped by `sourceIds`), self-links, non-ranking types (`rankingLinkSql`) and, unless `includeMentions`, mention rows excluded. Retired pages (`retiredPageSql`) fold into their `superseded_by`/`merged_into` target in the same source through a recursive chain over retired pages only, capped at `MAX_RETIREMENT_HOPS`; edges dedupe after folding and folded self-links drop. With `remote` every endpoint, chain hop, fold target and non-null link origin must be in scope, live, unquarantined, in an unarchived source and (with `excludePrivate`) not private, so a hidden target never folds. Ordered by the direction's count, then slug and source id (`COLLATE "C"`), LIMIT after folding. Tests: `test/rank-entities.test.ts`.
diff --git a/docs/architecture/key-files/entity-recall.md b/docs/architecture/key-files/entity-recall.md
index 8828f96ab3..b9a4e125b9 100644
--- a/docs/architecture/key-files/entity-recall.md
+++ b/docs/architecture/key-files/entity-recall.md
@@ -15,7 +15,7 @@ card and `get_backlinks`. Guide: [entity recall](../../guides/entity-recall.md).
- `src/core/mentions/coverage.ts` — `readMentionCoverage(engine, sourceIds)`: `{state, pending_pages, last_pass_at, degraded?}` from `mention_index_status` plus due pages written at or after the row's `counted_at` (states `complete`, `pending`, `disabled`, `failed`; the card adds `type_not_linkable`). A row whose version stamp differs from the binary's (counted by another release) is recounted once with `countIndexDuePages` and the count and stamp saved on the row (compare-and-set on the stored fingerprint; a failed write still returns the count), so after a version bump every page behind `MENTION_EXTRACTOR_VERSION` or `ALIAS_DERIVATION_VERSION` reads as pending whatever its `updated_at`, and later reads stay one status read plus the recent-pages query. Policy settings changes are detected by the pass, not here. `mentionCoverageNotice` builds the `mention_index` notice (kind `degraded`, a per-call code): the free catch-up sweep for pending/failed, the user's setting for disabled/type-not-linkable, each with a read-only verify.
- `src/core/mentions/referrers.ts` — the shared referrer query behind `referenced_by` and `get_backlinks {group:"page"}`: one row per referring page (every link source), semi-join over links to the target (plus identity co-members under `entity_identity.union`), canonical type via bound alias arrays, date `COALESCE(effective_date, updated_at)` with `date_source`, previews (160 characters after an optional `# ` heading, fences stripped, `redactFindings`). `readReferrerGroups`: per-type totals and a bounded top-10 per type, water-filled to 50 rows per card. `readReferrerPage`: keyset paging on `(date DESC, source_id, slug)` with an opaque cursor (microsecond UTC text). Untrusted scopes apply `privatePagesFilterFragment` to referrer and target and `privateLinkOriginFilterFragment` to the link, in rows and counts. #5575: quarantined referrers are left out (rows and counts) unless `includeQuarantined`, the scope's `eligibility` (`pageEligibleSql`) applies before LIMIT, and each row carries `trust_tier`, `origin` and `unconfirmed` from `trustFields`. Tests: `test/mentions-card-backlinks.test.ts`, `test/context-pack-newer-mentions.test.ts`, `test/entity-card-perf.slow.test.ts` (10,000-link hub gate). F1 records: `referrersCteBatched` is the same CTE with a target index (`referrerFilters` shared), `readTargetReferences` reads `referenced_by_count` plus enrolled-type records for many targets in two statements (totals per type; top `RECORD_ROWS_PER_TARGET` per target newest first; `RECORD_ROWS_PER_CALL` allotted in target order before hydration; rows, totals and cursors equal `readReferrerPage {type}`), `readRecordMetadata` adds `page_status`, `amends` (+ `since` from `link_relationships.first_start` in the caller's scope) and `supersedes`, also on `readReferrerPage {recordMetadata}` continuations. F3: `pageStatusValue` (string, trimmed, at most `PAGE_STATUS_MAX_CHARS` 40) is the one `page_status` rule; `readPageStatusByRef` reads it by `(source_id, slug)` in one statement (private pages hidden from untrusted callers, quarantined pages unless allowed) for `readReferrerPage {pageStatus}`, `get_backlinks` link rows and `context_pack` cards and newer-mention rows. Tests: `test/entity-records.test.ts`, `test/e2e/entity-records-postgres.test.ts`.
- `src/core/mentions/upgrade-notice.ts` — `gbrain post-upgrade` prints an `[AGENT]` block naming `gbrain extract --stale --catch-up` with a time estimate (`MENTION_PASS_PAGES_PER_SECOND`) while index-due pages exist (`previewMentionPass`), including every page behind the binary's mention or alias version on an unchanged brain. Post-upgrade does not run the sweep; autopilot's cycle extract phase continues it on its stale-drain budget (`CYCLE_STALE_DRAIN_BUDGET_MS`).
-- `src/core/ops/backlinks-paged.ts` — `get_backlinks`' `type` / `group` / `limit` / `cursor`. With none, `ops/links.ts` returns the legacy `Link[]`. `group: "page"` → `{rows, total, truncated, cursor, coverage}` (target = the first source in scope holding the slug; referrers from the read scope). Array mode (#6876) is the keyset-paged `Link[]` from `ops/links.ts` / `ops/link-paging.ts`; `filterBacklinkRows` only filters each page by referrer type. With `group: "page"`, `limit` outside 1..500, a foreign cursor, or an unknown type (not a pack type, alias, observed referrer type or `untyped`) is `invalid_params` naming the valid values. F3 (`entity.row_page_status`, default on): `withLinkPageStatus` adds the referring page's `page_status` to link rows, and `group: "page"` rows get it through `readReferrerPage {pageStatus}`; a record type's continuation keeps it through `recordMetadata` when the key is off.
+- `src/core/ops/backlinks-paged.ts` — `get_backlinks`' `type` / `group` / `limit` / `cursor`. With none, `ops/links.ts` returns the legacy `Link[]`. `group: "page"` → `{rows, total, truncated, cursor, coverage}` (target = the first source in scope holding the slug; referrers from the read scope). Array mode (#6876) is the keyset-paged `Link[]` from `ops/links.ts` / `ops/link-paging.ts`; `filterBacklinkRows` only filters each page by referrer type. With `group: "page"`, `limit` outside 1..500, a foreign cursor, or an unknown type (not a pack type, alias, observed referrer type, `untyped` or a type of any page the caller can read in its scope, `ops/stats-by.ts visiblePageTypes`) is `invalid_params` naming the valid values (only types of pages the caller can read); a type other visible pages have but no referrer has answers empty with an `empty_retrieval` info notice naming the referrer types (GBRA-449, `test/backlinks-type-exists-gbra449.test.ts`). F3 (`entity.row_page_status`, default on): `withLinkPageStatus` adds the referring page's `page_status` to link rows, and `group: "page"` rows get it through `readReferrerPage {pageStatus}`; a record type's continuation keeps it through `recordMetadata` when the key is off.
- `src/core/ops/graph-rank.ts` — #7168: `rank_entities` (CLI `rank-entities`): validates every parameter with `invalidParam` (no coercion; type and link-type names are pattern-checked, non-ranking link types refused, `limit` 1-100), scopes with `assertSourceInCallerScope` / `resolveRequestedScope` then `linkReadScopeOpts` (remote scalar scopes promoted to `sourceIds`), defaults `types` to `resolveEntityTypes`, runs `engine-sql/graph-rank.ts` under `RANK_ENTITIES_STATEMENT_MS` (a 57014 becomes `rank_entities_timeout`), attaches `possible_duplicates` (`readPossibleDuplicates`) to at most `RANK_ENTITIES_DUPLICATE_ROWS` top rows within a 3 s budget, and `coverage` from `readExtractionLag` per source in scope (state only for remote callers). Guide: [graph ranking](../../guides/graph-ranking.md). Tests: `test/rank-entities.test.ts`.
- `src/core/ops/whois.ts` — GBRA-156: `whois` (CLI `whois <query>`), the exact identity lookup. A query is an email address (`identityEmailKey`: NFKC, lowercase, surrounding quotes and angle brackets dropped, whole address compared) or a name (`identityNameKey`: `normalizeAlias`, surrounding straight and typographic quotes dropped, NFKD with combining marks stripped, `foldNonDecomposingLatin`). Scope: `parseSourceIdParam` + `federatedSearchScope` + `assertExplicitSourceLive`, an unscoped trusted call reading every unarchived source; `types` defaults to `resolveEntityTypes` for that scope. Candidates come from `engine-sql/exact-identity.ts`; `identityMatchKind` keeps a candidate only when a frontmatter `email`/`emails` value (email queries), the title, or a `normalizeAliasList` alias folds to exactly the query, labeled `email` > `title` > `alias` (ordered so, then source id and slug). Returns `matches`, `ambiguous` (more than one match), `types_status`, and `truncated` + `note` past `WHOIS_CANDIDATE_CAP` candidates; no match is an empty list, never a search fallback. Registered `labeled`, output redaction `retrieval`. Tests: `test/whois.test.ts`, `test/e2e/whois-postgres.test.ts`.
- `src/commands/extract-mentions-explain.ts` — `gbrain extract mentions --explain <name|slug> [--page <slug>] [--source-id <id>] [--json]` (dispatched from `extract-explain.ts`): the matched entries with origin and case flag, or one reason code (`ambiguous_first_word`, `below_min_length`, `generic_token`, `alias_collision`, `case_mismatch`, `type_not_linkable`, `linking_disabled`, `pending`, `ignored_by_page`, `ignored_by_config`, `denied_by_config`, `not_a_known_name`); only `pending` names a sweep. A slug query also lists each derived name with origin and declaring line, the rejected candidates with reasons, and the sibling decision. Tests: `test/mentions-explain.test.ts`.
diff --git a/src/core/ops/backlinks-paged.ts b/src/core/ops/backlinks-paged.ts
index 60e04eae16..db7aa433a5 100644
--- a/src/core/ops/backlinks-paged.ts
+++ b/src/core/ops/backlinks-paged.ts
@@ -19,6 +19,7 @@ import {
} from '../mentions/referrers.ts';
import { mentionCoverageNotice, readMentionCoverage, type MentionCoverage } from '../mentions/coverage.ts';
import { readEntityReferencesConfig, readRowPageStatus } from '../entity-references-config.ts';
+import { visiblePageTypes } from './stats-by.ts';
export interface BacklinkPage {
rows: ReferenceRow[];
@@ -61,15 +62,29 @@ async function referrerScope(ctx: OperationContext, slug: string, policy: PageRe
return { sources, scope: { slug, sourceId, referrerSources: sources, excludePrivate, pack, keepVisibility: excludePrivate ? ['world'] : ['private', 'world'] } };
}
+/** How many of the caller's most common page types a refusal names next to the referrer and pack types. */
+const NAMED_PAGE_TYPES = 20;
+
+/**
+ * GBRA-449: a type some page the caller can read has (in its scope) is a valid filter even when no referrer of this
+ * page has it: the read answers empty with an info notice naming the referrer types. Only a type no visible page has,
+ * outside the pack and `untyped`, is refused, and the refusal names only types of pages the caller can read.
+ */
async function assertKnownType(ctx: OperationContext, scope: ReferrerScope, type: string): Promise<void> {
const declared = (scope.pack?.page_types ?? []).flatMap(pt => [pt.name, ...(pt.aliases ?? [])]);
if (declared.includes(type) || type === 'untyped') return;
const observed = await referrerTypes(ctx.engine, scope);
if (observed.includes(type)) return;
+ const visible = (await visiblePageTypes(ctx, { sourceIds: scope.referrerSources })).map(t => t.type);
+ if (visible.includes(type)) {
+ ctx.emitNotice?.({ code: 'empty_retrieval', kind: 'info',
+ why: `No page linking to ${scope.slug} has type "${type}"; its referrers' types are ${observed.join(', ') || 'none yet'}.` });
+ return;
+ }
const canonical = (scope.pack?.page_types ?? []).map(pt => pt.name);
- const valid = [...new Set([...observed, ...canonical, 'untyped'])].sort();
+ const valid = [...new Set([...observed, ...visible.slice(0, NAMED_PAGE_TYPES), ...canonical, 'untyped'])].sort();
throw opError('invalid_params', `get_backlinks: unknown type "${type}".`,
- `Use a type this page's referrers have (${observed.join(', ') || 'none yet'}), a schema-pack type or untyped; valid values: ${valid.join(', ')}.`,
+ `Use a type this page's referrers have (${observed.join(', ') || 'none yet'}), another page type in this brain, a schema-pack type or untyped; valid values: ${valid.join(', ')}.`,
{ detail: JSON.stringify({ valid_types: valid, referrer_types: observed }) });
}
diff --git a/src/core/ops/stats-by.ts b/src/core/ops/stats-by.ts
index 4469f1b68d..6171971614 100644
--- a/src/core/ops/stats-by.ts
+++ b/src/core/ops/stats-by.ts
@@ -13,6 +13,7 @@
* count what is stored.
*/
import { collapseTypes, groupPageCounts, parseStatsBy, type StatsByResult, type StatsDimension } from '../page-counts.ts';
+import type { UntrustedReadPolicy } from '../page-find.ts';
import { loadActivePackBestEffort } from '../schema-pack/best-effort.ts';
import { resolveDateBoundary } from '../search/date-bounds.ts';
import type { OperationContext, ParamDef } from './contract.ts';
@@ -54,12 +55,26 @@ export async function statsBy(
const groupTypes = by.includes('type') && !by.includes('source')
? (types: string[]) => { const collapse = collapseFor(types); return types.map((type) => collapse?.get(type)?.group ?? type); }
: undefined;
- const policy = ctx.remote === false && !ctx.applyRemoteReadPolicy ? undefined : await readPolicyOpts(ctx, scope);
- const counts = await ctx.engine.countPagesBy({
- ...scope,
- since,
- untrusted: policy && { excludePrivate: policy.excludePrivate, minTrust: policy.minTrust, suppressFlagged: policy.suppressFlagged },
- }, groupTypes);
+ const counts = await ctx.engine.countPagesBy({ ...scope, since, untrusted: await countReadPolicy(ctx, scope) }, groupTypes);
const collapse = collapseFor([...new Set(counts.bySourceType.map((row) => row.type))]);
return groupPageCounts(counts, { by, since: since ?? null, collapse });
}
+
+/** The read policy page counts apply: none for a trusted local caller, else the caller's `readPolicyOpts` policy. */
+async function countReadPolicy(ctx: OperationContext, scope: { sourceId?: string; sourceIds?: string[] }): Promise<UntrustedReadPolicy | undefined> {
+ const policy = ctx.remote === false && !ctx.applyRemoteReadPolicy ? undefined : await readPolicyOpts(ctx, scope);
+ return policy && { excludePrivate: policy.excludePrivate, minTrust: policy.minTrust, suppressFlagged: policy.suppressFlagged };
+}
+
+/**
+ * GBRA-449: the page types this caller can read in `scope`, most pages first
+ * (ties by name), counted over the same live, visible pages as `get_stats`
+ * by type. Pages with no type are left out. get_backlinks accepts these as a
+ * `type` filter, and an empty list_pages names them.
+ */
+export async function visiblePageTypes(ctx: OperationContext, scope: { sourceId?: string; sourceIds?: string[] }): Promise<Array<{ type: string; pages: number }>> {
+ const counts = await ctx.engine.countPagesBy({ ...scope, untrusted: await countReadPolicy(ctx, scope) });
+ const byType = new Map<string, number>();
+ for (const row of counts.bySourceType) if (row.type) byType.set(row.type, (byType.get(row.type) ?? 0) + row.pages);
+ return [...byType].map(([type, pages]) => ({ type, pages })).sort((a, b) => b.pages - a.pages || a.type.localeCompare(b.type));
+}
diff --git a/test/backlinks-type-exists-gbra449.test.ts b/test/backlinks-type-exists-gbra449.test.ts
new file mode 100644
index 0000000000..6114081b10
--- /dev/null
+++ b/test/backlinks-type-exists-gbra449.test.ts
@@ -0,0 +1,126 @@
+/**
+ * GBRA-449 fix 1: get_backlinks' type filter accepts any page type the
+ * caller can see in its scope, not only the types of this page's referrers.
+ *
+ * Protects (red before: type "contract" on contracts/c1 was refused with
+ * 'unknown type "contract"' although six contract pages exist):
+ * - a type that visible pages have but no referrer of this page has answers
+ * the normal empty result (array mode and group: "page"), with an info
+ * notice naming the referrer types the page does have;
+ * - a type no page has is still refused and the refusal names the valid
+ * types;
+ * - a remote caller's "types that exist" come only from pages it can read: a
+ * type found only on a visibility: private page, a page whose readers
+ * omit the caller, a soft-deleted page or a page in a source outside its
+ * scope is refused and never named.
+ * Database-only (repo-less) brain: every page is written straight to the
+ * database with putPage, no checkout. PGLite always, Postgres when
+ * DATABASE_URL is set.
+ */
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import type { BrainEngine } from '../src/core/engine.ts';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { PostgresEngine } from '../src/core/postgres-engine.ts';
+import type { PageType } from '../src/core/types.ts';
+import { dispatchToolCall } from '../src/mcp/dispatch.ts';
+import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';
+import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';
+
+const HIDDEN_TYPES = ['memo-private', 'memo-restricted', 'memo-deleted', 'memo-elsewhere'];
+
+for (const backend of testBackends()) {
+ describe('[' + backend + '] get_backlinks type filter: existing types answer empty (GBRA-449)', () => {
+ let engine: BrainEngine;
+ const config = { engine: backend } as never;
+ const local = { remote: false, sourceId: 'default', config };
+ const remote = { remote: true, transport: 'stdio' as const, sourceId: 'default', takesHoldersAllowList: ['world'], config };
+
+ beforeAll(async () => {
+ if (backend === 'postgres') {
+ const pg = new PostgresEngine();
+ await pg.connect({ database_url: requirePostgresTestDatabase() });
+ engine = pg;
+ } else {
+ const lite = new PGLiteEngine();
+ await lite.connect({});
+ engine = lite;
+ }
+ await engine.initSchema();
+ }, 180_000);
+ afterAll(async () => { await engine.disconnect(); });
+
+ const put = (slug: string, type: string, body: string, opts: { frontmatter?: Record<string, unknown>; sourceId?: string } = {}) =>
+ engine.putPage(slug, { type: type as PageType, title: slug, compiled_truth: body, timeline: '', frontmatter: opts.frontmatter ?? {} },
+ opts.sourceId ? { sourceId: opts.sourceId } : undefined);
+
+ beforeEach(async () => {
+ await engine.executeRaw('DELETE FROM links');
+ await engine.executeRaw('DELETE FROM pages');
+ await engine.executeRaw("DELETE FROM sources WHERE id <> 'default'");
+ await engine.executeRaw("INSERT INTO sources (id, name) VALUES ('source-b', 'source-b') ON CONFLICT (id) DO NOTHING");
+ __resetPrivateVisibilityCacheForTests();
+ for (let i = 1; i <= 6; i++) await put('contracts/c' + i, 'contract', 'Contract ' + i + '. Renewal date: 2026-08-0' + i + '.');
+ await put('contracts/a1', 'amendment', 'Amendment to contracts/c1.');
+ await engine.addLink('contracts/a1', 'contracts/c1', 'amends', 'mentions');
+ await put('memos/private', 'memo-private', 'Private memo.', { frontmatter: { visibility: 'private' } });
+ await put('memos/restricted', 'memo-restricted', 'Restricted memo.', { frontmatter: { readable_by: ['alice-example'] } });
+ await put('memos/deleted', 'memo-deleted', 'Deleted memo.');
+ await engine.softDeletePage('memos/deleted', { sourceId: 'default' });
+ await put('memos/elsewhere', 'memo-elsewhere', 'Memo in another source.', { sourceId: 'source-b' });
+ });
+
+ async function call(args: Record<string, unknown>, opts: Record<string, unknown> = local) {
+ const r = await dispatchToolCall(engine, 'get_backlinks', args, opts as never);
+ const body = JSON.parse(r.content[0]!.text);
+ const error = r.isError === true ? { message: String(body.message), valid: String(body.suggestion) + '\n' + String(body.detail) } : null;
+ return { isError: r.isError === true, error, json: r.isError ? null : body, notices: r.content.slice(1).map(c => c.text).join('\n') };
+ }
+
+ test('a referrer type returns its link', async () => {
+ const r = await call({ slug: 'contracts/c1', type: 'amendment' });
+ expect(r.isError).toBe(false);
+ expect(r.json.map((l: { from_slug: string }) => l.from_slug)).toEqual(['contracts/a1']);
+ });
+
+ test('a type other pages have but no referrer has answers empty, with a notice naming the referrer types', async () => {
+ for (const opts of [local, remote]) {
+ const arr = await call({ slug: 'contracts/c1', type: 'contract' }, opts);
+ expect(arr.error).toBeNull();
+ expect(arr.json).toEqual([]);
+ expect(arr.notices).toContain('empty_retrieval');
+ expect(arr.notices).toContain('amendment');
+ const paged = await call({ slug: 'contracts/c1', type: 'contract', group: 'page' }, opts);
+ expect(paged.error).toBeNull();
+ expect(paged.json).toMatchObject({ rows: [], total: 0, truncated: false, cursor: null });
+ }
+ });
+
+ test('a type no page has is still refused and names the valid types', async () => {
+ for (const args of [{ slug: 'contracts/c1', type: 'bogus-kind' }, { slug: 'contracts/c1', type: 'bogus-kind', group: 'page' }]) {
+ const r = await call(args);
+ expect(r.error?.message).toBe('get_backlinks: unknown type "bogus-kind".');
+ for (const valid of ['amendment', 'contract', 'untyped']) expect(r.error?.valid).toContain(valid);
+ }
+ });
+
+ test('remote: a type only hidden pages have is refused and never named', async () => {
+ for (const type of HIDDEN_TYPES) {
+ for (const group of [undefined, 'page']) {
+ const r = await call({ slug: 'contracts/c1', type, ...(group ? { group } : {}) }, remote);
+ expect(r.error?.message).toBe('get_backlinks: unknown type "' + type + '".');
+ for (const hidden of HIDDEN_TYPES) expect(r.error?.valid).not.toContain(hidden);
+ expect(r.error?.valid).toContain('contract');
+ }
+ }
+ });
+
+ test('local: a private page type is accepted; a soft-deleted page type is refused and not named', async () => {
+ const priv = await call({ slug: 'contracts/c1', type: 'memo-private' });
+ expect(priv.error).toBeNull();
+ expect(priv.json).toEqual([]);
+ const gone = await call({ slug: 'contracts/c1', type: 'memo-deleted' });
+ expect(gone.error?.message).toBe('get_backlinks: unknown type "memo-deleted".');
+ expect(gone.error?.valid).not.toContain('memo-deleted');
+ });
+ });
+}
diff --git a/test/postgres-unit-arms.txt b/test/postgres-unit-arms.txt
index ed4bc6995b..9c03f66077 100644
--- a/test/postgres-unit-arms.txt
+++ b/test/postgres-unit-arms.txt
@@ -34,6 +34,7 @@ test/activation-unbound-rooted-6449.test.ts
test/adopt-local-edit.test.ts
test/alias-source-cascade-5094.test.ts
test/attribution-backfill-history.test.ts
+test/backlinks-type-exists-gbra449.test.ts
test/backstop-same-page-shadow-managed-6333.test.ts
test/behavior-change-notice.test.ts
test/belief-ledger-append-owner.test.ts