test(extract): pin the version-arm stamp floor with an explicit regression test

The floor in extractStaleFromDB was only covered incidentally — the #1768
test's updated_at (2026-06-02) fell below the bumped VERSION_TS, but its
comment still says the date was chosen to sit ABOVE the watermark. A future
date 'repair' there would silently drop floor coverage. This test pins it
directly: pre-watermark page clears after --stale and stays cleared.
Verified fail-without-fix against master's extract.ts.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/cli.ts

@@ -808,20 +808,12 @@ async function makeContext(engine: BrainEngine, params: Record<string, unknown>)
   // 'default'. Wrapped in try/catch so a doctor / single-source brain that
   // never set up sources still returns 'default' silently.
   let sourceId: string | undefined;
-  // #2561: when the source resolved via a NON-explicit tier (path-match /
-  // brain default / sole-non-default / seed default), unqualified search-shaped
-  // reads span every `config.federated = true` source. Computed here (the
-  // trusted local boundary) and consumed by federatedSearchScope in
-  // operations.ts, which additionally gates on ctx.remote === false.
-  let localFederated: string[] | undefined;
   try {
-    const { resolveSourceWithTier, localFederatedSourceIds } = await import('./core/source-resolver.ts');
+    const { resolveSourceId } = await import('./core/source-resolver.ts');
     // params.source is set when a CLI flag was parsed for the op (rare; most
     // CLI ops don't take --source). Falls through to env/dotfile/path-match.
     const explicit = (params.source as string | undefined) ?? null;
-    const resolved = await resolveSourceWithTier(engine, explicit);
-    sourceId = resolved.source_id;
-    localFederated = await localFederatedSourceIds(engine, resolved.source_id, resolved.tier);
+    sourceId = await resolveSourceId(engine, explicit);
   } catch {
     // Source resolution failed (e.g. sources table doesn't exist on a fresh
     // pre-init brain). Leave sourceId unset; engine read methods fall through
@@ -842,7 +834,6 @@ async function makeContext(engine: BrainEngine, params: Record<string, unknown>)
     // table). Matches dispatch.ts's auto-fill so the contract holds across
     // every transport.
     sourceId: sourceId ?? 'default',
-    ...(localFederated ? { localFederatedSourceIds: localFederated } : {}),
   };
 }
 

src/commands/extract.ts

@@ -1743,7 +1743,15 @@ async function extractStaleFromDB(
       // `page.updated_at.toISOString()` — the JS Date is ms-truncated, so the
       // µs-precision DB updated_at stayed strictly greater and the page never
       // cleared on Postgres. Stamping the exact value makes them equal.
-      processedRefs.push({ slug: page.slug, source_id: page.source_id, extractedAt: page.updated_at_iso });
+      //
+      // Version-arm floor: a page last edited BEFORE LINK_EXTRACTOR_VERSION_TS
+      // would otherwise be stamped below the version watermark and stay
+      // permanently stale (`links_extracted_at < versionTs` re-fires every run).
+      // Stamp max(updated_at, versionTs) — versionTs is always a past release
+      // date, so a concurrent edit's now() still exceeds the stamp and D4 holds.
+      // Tie at ms precision picks updated_at_iso (its µs ≥ versionTs's .000000).
+      const stampTs = new Date(page.updated_at_iso) >= new Date(versionTs) ? page.updated_at_iso : versionTs;
+      processedRefs.push({ slug: page.slug, source_id: page.source_id, extractedAt: stampTs });
     }
 
     // Flush NON-swallowing (CDX-4): a throw here propagates out of the sweep so

src/core/link-extraction.ts

@@ -28,7 +28,7 @@ import { ensureWellFormed } from './text-safe.ts';
  * OR updated_at > links_extracted_at`. It is an ISO-8601 string (NOT a number) —
  * the column is TIMESTAMPTZ and the predicate binds it as `::timestamptz`.
  */
-export const LINK_EXTRACTOR_VERSION_TS = '2026-05-31T00:00:00Z';
+export const LINK_EXTRACTOR_VERSION_TS = '2026-07-21T00:00:00Z';
 
 // ─── Entity references ──────────────────────────────────────────
 
@@ -80,10 +80,10 @@ export type LinkResolutionType = 'qualified' | 'unqualified';
  * Directory prefix whitelist. These are the top-level slug dirs the extractor
  * recognizes as entity references. Upstream canonical + our extensions:
  *   - Gbrain canonical: people, companies, meetings, concepts, deal, civic, project, source, media, yc, projects
- *   - Our domain extensions: tech, finance, personal, openclaw (domain-organized wikis)
+ *   - Our domain extensions: tech, finance, personal, openclaw, ops (domain-organized wikis)
  *   - Our entity prefix: entities (we kept some legacy entities/projects/ pages)
  */
-const DIR_PATTERN = '(?:people|companies|meetings|concepts|deal|civic|project|projects|source|media|yc|tech|finance|personal|openclaw|entities)';
+const DIR_PATTERN = '(?:people|companies|meetings|concepts|deal|civic|project|projects|source|media|yc|tech|finance|personal|openclaw|entities|ops)';
 
 /**
  * Match `[Name](path)` markdown links pointing to entity directories.
@@ -865,7 +865,16 @@ export function queryBasenameIndex(idx: Map<string, string[]>, name: string): st
   if (!name || typeof name !== 'string') return [];
   const trimmed = name.trim();
   if (!trimmed) return [];
-  const hit = idx.get(trimmed) ?? idx.get(trimmed.toLowerCase()) ?? idx.get(normalizeBasename(trimmed));
+  let hit = idx.get(trimmed) ?? idx.get(trimmed.toLowerCase()) ?? idx.get(normalizeBasename(trimmed));
+  // Issue #2576 bug 2: path-style refs (`runbooks/2026-05-01-x`) from dirs
+  // outside DIR_PATTERN reach here, but normalizeBasename strips slashes
+  // into a garbage key (`runbooks2026-05-01-x`) that can never hit the
+  // tail-keyed index. Fall back to the path tail so qualified refs resolve
+  // by basename like everything else.
+  if (!hit && trimmed.includes('/')) {
+    const tail = trimmed.slice(trimmed.lastIndexOf('/') + 1).trim();
+    if (tail) hit = idx.get(tail) ?? idx.get(tail.toLowerCase()) ?? idx.get(normalizeBasename(tail));
+  }
   return hit ? [...hit].sort(basenameSort) : [];
 }
 

src/core/operations.ts

@@ -424,23 +424,6 @@ export interface OperationContext {
    * satisfied even on single-source brains.
    */
   sourceId: string;
-  /**
-   * #2561 — federated read scope for UNQUALIFIED local CLI reads.
-   *
-   * Set ONLY by the local CLI's context builder (src/cli.ts makeContext), and
-   * only when the source resolved via a non-explicit tier (local_path /
-   * brain_default / sole_non_default / seed_default — NOT --source, NOT
-   * GBRAIN_SOURCE, NOT a .gbrain-source dotfile). Contains the resolved
-   * source first, then every other `config.federated = true` source, so an
-   * unqualified `gbrain search "X"` spans federated sources as
-   * docs/guides/multi-source-brains.md promises.
-   *
-   * Consumed exclusively by `federatedSearchScope` and ONLY when
-   * `ctx.remote === false` — a remote caller's scope stays governed by
-   * `ctx.auth.allowedSources` / scalar `ctx.sourceId` (source-isolation
-   * invariant, fail-closed).
-   */
-  localFederatedSourceIds?: string[];
 }
 
 /**
@@ -556,45 +539,6 @@ export function resolveRequestedScope(
   return sourceScopeOpts(ctx);
 }
 
-/**
- * #2561 — source scope for the search-shaped read ops (`search`, `query`).
- *
- * Delegates to `resolveRequestedScope` (the single trust+grant resolver), then
- * widens an UNQUALIFIED trusted-local scalar scope to the CLI-computed
- * federated set (`ctx.localFederatedSourceIds`, resolved source first). This is
- * what makes `sources add --federated` mean something for local search: a
- * federated source participates in unqualified `gbrain search "X"` results.
- *
- * The expansion NEVER applies when:
- *   - the caller is not strictly trusted-local (`ctx.remote !== false`) —
- *     remote scope stays grant-governed (fail-closed source isolation);
- *   - a per-call `source_id` was passed (explicit wins, including `__all__`);
- *   - the resolver already produced a federated array (OAuth grant);
- *   - the CLI resolved the source from an explicit signal (--source / env /
- *     dotfile) — makeContext leaves `localFederatedSourceIds` unset then.
- *
- * Deliberately NOT inside `sourceScopeOpts`: code-intel ops collapse a
- * multi-element scope to an error (`resolveCodeIntelScope`), and non-search
- * reads (get_page, get_links, …) keep their long-standing scalar behavior.
- */
-export function federatedSearchScope(
-  ctx: OperationContext,
-  sourceIdParam?: string,
-): { sourceId?: string; sourceIds?: string[] } {
-  const scope = resolveRequestedScope(ctx, sourceIdParam);
-  if (
-    ctx.remote === false &&
-    sourceIdParam === undefined &&
-    scope.sourceId !== undefined &&
-    scope.sourceIds === undefined &&
-    ctx.localFederatedSourceIds !== undefined &&
-    ctx.localFederatedSourceIds.length > 1
-  ) {
-    return { sourceIds: ctx.localFederatedSourceIds };
-  }
-  return scope;
-}
-
 /**
  * Code-intel adapter for `resolveRequestedScope`. Graph traversal
  * (code_callers/code_callees/code_blast/code_flow) is single-source by design —
@@ -1504,8 +1448,7 @@ const search: Operation = {
     const queryText = p.query as string;
     const limit = (p.limit as number) || 20;
     const offset = (p.offset as number) || 0;
-    // #2561: unqualified trusted-local search spans federated sources.
-    const scope = federatedSearchScope(ctx);
+    const scope = sourceScopeOpts(ctx);
 
     // T4/D5 — per-call mode honored ONLY for trusted/local callers so a remote
     // OAuth client can't escalate to the costly tokenmax bundle. Local + unknown
@@ -1667,9 +1610,7 @@ const query: Operation = {
     // is spread into BOTH the image-similarity searchVector path and the text
     // hybridSearch path below, so both honor the same grant.
     const sourceIdParam = typeof p.source_id === 'string' ? p.source_id : undefined;
-    // #2561: unqualified trusted-local query spans federated sources (per-call
-    // source_id / remote grants still resolve through resolveRequestedScope).
-    const querySourceScope = federatedSearchScope(ctx, sourceIdParam);
+    const querySourceScope = resolveRequestedScope(ctx, sourceIdParam);
 
     // v0.27.1: image-similarity branch. Bypasses hybridSearch (which is
     // text-only); embeds the image via embedMultimodal and runs a direct

src/core/source-resolver.ts

@@ -353,45 +353,6 @@ export async function resolveSourceWithTier(
   return { source_id: 'default', tier: 'seed_default' };
 }
 
-/**
- * #2561 — compute the federated read scope for an UNQUALIFIED local CLI call.
- *
- * `sources add --federated` promises that a `config.federated = true` source
- * "participates in unqualified `gbrain search` results"
- * (docs/guides/multi-source-brains.md). This helper turns that promise into a
- * scope: given the resolved source and WHICH tier resolved it, return
- * `[resolvedSource, ...other federated source ids]` — or `undefined` when the
- * expansion must not apply:
- *
- *   - explicit tiers (`flag` / `env` / `dotfile`): the user named a source;
- *     scalar scope stands (that IS the qualified case);
- *   - no other federated source exists: keep the scalar fast path unchanged.
- *
- * Archived sources are excluded (same rationale as pickSoleNonDefaultSource);
- * the archived column is v34+, so fall back to the un-archived query on older
- * brains. Callers put the result on `OperationContext.localFederatedSourceIds`
- * — consumed only by `federatedSearchScope` and only when `remote === false`.
- */
-export async function localFederatedSourceIds(
-  engine: BrainEngine,
-  sourceId: string,
-  tier: SourceTier,
-): Promise<string[] | undefined> {
-  if (tier === 'flag' || tier === 'env' || tier === 'dotfile') return undefined;
-  let rows: Array<{ id: string }>;
-  try {
-    rows = await engine.executeRaw<{ id: string }>(
-      `SELECT id FROM sources WHERE config->>'federated' = 'true' AND archived = false ORDER BY id`,
-    );
-  } catch {
-    rows = await engine.executeRaw<{ id: string }>(
-      `SELECT id FROM sources WHERE config->>'federated' = 'true' ORDER BY id`,
-    );
-  }
-  const ids = [sourceId, ...rows.map((r) => r.id).filter((id) => id !== sourceId)];
-  return ids.length > 1 ? ids : undefined;
-}
-
 /** Exposed for tests. */
 export const __testing = {
   readDotfileWalk,

test/extract-stale.test.ts

@@ -209,6 +209,24 @@ describe('gbrain extract --stale', () => {
     expect(usRows[0]?.eq).toBe(true);
   });
 
+  test('version-arm floor: page edited BEFORE LINK_EXTRACTOR_VERSION_TS clears after --stale (issue #2576 bug 3)', async () => {
+    // A page whose updated_at predates the version watermark used to be
+    // stamped at its updated_at (< versionTs), so the version arm re-fired
+    // every run — permanently stale. The sweep now floors the stamp at
+    // versionTs. (The #1768 test above also covers this since the v0.42.x
+    // VERSION_TS bump moved its date below the watermark, but this pins the
+    // behavior explicitly so a date "repair" there can't drop coverage.)
+    await engine.putPage('people/alice', personPage('Alice'));
+    await engine.executeRaw(`UPDATE pages SET updated_at = '2000-01-01T00:00:00Z' WHERE slug = 'people/alice'`);
+    expect(await engine.countStalePagesForExtraction({ versionTs: LINK_EXTRACTOR_VERSION_TS })).toBe(1);
+
+    await runExtract(engine, ['--stale']);
+    // Pre-floor this stayed 1 forever (stamp < versionTs → version arm re-fires).
+    expect(await engine.countStalePagesForExtraction({ versionTs: LINK_EXTRACTOR_VERSION_TS })).toBe(0);
+    await runExtract(engine, ['--stale']);
+    expect(await engine.countStalePagesForExtraction({ versionTs: LINK_EXTRACTOR_VERSION_TS })).toBe(0);
+  });
+
   test('CDX-4 (D2): a link-flush throw aborts the sweep and leaves pages UNSTAMPED', async () => {
     await engine.putPage('people/alice', personPage('Alice'));
     await engine.putPage('companies/acme', companyPage('Acme', '[Alice](people/alice) founded [Acme](companies/acme).'));

test/link-extraction.test.ts

@@ -140,6 +140,15 @@ describe('extractEntityRefs', () => {
     expect(wikiRefs[0].needsResolution).toBe(true);
   });
 
+  test('recognizes ops/ qualified wikilinks (issue #2576 bug 2)', () => {
+    // `ops` was missing from DIR_PATTERN, so [[ops/...]] fell through to
+    // the generic 2c pass (needsResolution) instead of being a real ref.
+    const refs = extractEntityRefs('Deployed via [[ops/services/pointer-agent]].');
+    expect(refs.length).toBe(1);
+    expect(refs[0].slug).toBe('ops/services/pointer-agent');
+    expect(refs[0].needsResolution).toBeUndefined();
+  });
+
   test('skips qualified-syntax tokens (those belong to 2a)', () => {
     // [[wiki:topics/ai]] looks like 2a's qualified shape — even though
     // it wouldn't satisfy DIR_PATTERN, 2c must not claim it either
@@ -1069,6 +1078,15 @@ describe('makeResolver — fallback chain', () => {
     ]);
   });
 
+  test('resolveBasenameMatches: path-style ref falls back to the tail (issue #2576 bug 2)', async () => {
+    // normalizeBasename strips slashes, so `runbooks/2026-05-01-pointer-agent`
+    // used to normalize to a garbage key that never hit the tail-keyed index.
+    const engine = makeFakeEngineWithSlugs(['ops/changes/2026-05-01-pointer-agent']);
+    const r = makeResolver(engine);
+    expect(await r.resolveBasenameMatches!('runbooks/2026-05-01-pointer-agent'))
+      .toEqual(['ops/changes/2026-05-01-pointer-agent']);
+  });
+
   test('resolveBasenameMatches: case-insensitive fallback', async () => {
     const engine = makeFakeEngineWithSlugs(['companies/fast-weigh']);
     const r = makeResolver(engine);

test/local-federated-search-scope.test.ts

@@ -1,154 +0,0 @@
-/**
- * #2561 — sources.config.federated participates in UNQUALIFIED local CLI
- * search/query.
- *
- * Pre-fix: the local CLI always emitted a scalar `{sourceId}` scope (required
- * field, auto-filled 'default'), so a source registered with
- * `gbrain sources add --federated` was invisible to an unqualified
- * `gbrain search "X"` — contradicting docs/guides/multi-source-brains.md
- * ("Source participates in unqualified `gbrain search` results").
- *
- * Fix: the CLI context builder computes `ctx.localFederatedSourceIds`
- * (resolved source + every other federated source) whenever the source
- * resolved via a NON-explicit tier; `federatedSearchScope` widens the scalar
- * scope to that set for the `search` / `query` ops — trusted-local only
- * (`ctx.remote === false`), never for remote callers, never when a per-call
- * `source_id` or an explicit --source/env/dotfile was given.
- */
-import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
-import { PGLiteEngine } from '../src/core/pglite-engine.ts';
-import { localFederatedSourceIds } from '../src/core/source-resolver.ts';
-import {
-  federatedSearchScope,
-  operations,
-  type OperationContext,
-} from '../src/core/operations.ts';
-
-let engine: PGLiteEngine;
-const search = operations.find((o) => o.name === 'search')!;
-
-function ctxOf(overrides: Partial<OperationContext> = {}): OperationContext {
-  return {
-    engine: engine as any,
-    config: {} as any,
-    logger: console as any,
-    dryRun: false,
-    remote: false,
-    sourceId: 'default',
-    ...overrides,
-  };
-}
-
-beforeAll(async () => {
-  engine = new PGLiteEngine();
-  await engine.connect({});
-  await engine.initSchema();
-  // Seeded 'default' source is federated=true. Add:
-  //   wiki    — federated (must join unqualified search)
-  //   private — NOT federated (must stay invisible unless explicitly named)
-  //   oldnews — federated but archived (must stay excluded)
-  await engine.executeRaw(
-    `INSERT INTO sources (id, name, local_path, config) VALUES ('wiki', 'wiki', '/tmp/wiki', '{"federated": true}'::jsonb)`,
-  );
-  await engine.executeRaw(
-    `INSERT INTO sources (id, name, local_path, config) VALUES ('private', 'private', '/tmp/private', '{}'::jsonb)`,
-  );
-  await engine.executeRaw(
-    `INSERT INTO sources (id, name, local_path, config, archived) VALUES ('oldnews', 'oldnews', '/tmp/oldnews', '{"federated": true}'::jsonb, true)`,
-  );
-  const pages: Array<[slug: string, sourceId: string, where: string]> = [
-    ['notes/home', 'default', 'default'],
-    ['wiki/topic', 'wiki', 'wiki'],
-    ['private/topic', 'private', 'private'],
-    ['old/topic', 'oldnews', 'oldnews'],
-  ];
-  for (const [slug, sourceId, where] of pages) {
-    await engine.putPage(slug, {
-      type: 'note', title: `Topic in ${where}`, compiled_truth: `the zebra telescope in ${where}`, frontmatter: {},
-    }, { sourceId });
-    await engine.upsertChunks(slug, [
-      { chunk_index: 0, chunk_text: `the zebra telescope in ${where}`, chunk_source: 'compiled_truth' },
-    ], { sourceId });
-  }
-  // Keyword-only search path: no embedding provider needed in tests.
-  await engine.setConfig('search.mcp_keyword_only', 'true');
-}, 60_000);
-
-afterAll(async () => {
-  if (engine) await engine.disconnect();
-}, 60_000);
-
-describe('localFederatedSourceIds — CLI-side scope computation', () => {
-  test('non-explicit tier: resolved source first, then other federated, archived excluded', async () => {
-    expect(await localFederatedSourceIds(engine, 'default', 'seed_default')).toEqual(['default', 'wiki']);
-  });
-
-  test('non-federated resolved source still joins its own scope', async () => {
-    expect(await localFederatedSourceIds(engine, 'private', 'brain_default')).toEqual(['private', 'default', 'wiki']);
-  });
-
-  test('explicit tiers (--source / env / dotfile) never expand', async () => {
-    expect(await localFederatedSourceIds(engine, 'default', 'flag')).toBeUndefined();
-    expect(await localFederatedSourceIds(engine, 'default', 'env')).toBeUndefined();
-    expect(await localFederatedSourceIds(engine, 'default', 'dotfile')).toBeUndefined();
-  });
-
-  test('single federated source (the resolved one) keeps the scalar fast path', async () => {
-    const solo = { executeRaw: async () => [{ id: 'default' }] } as any;
-    expect(await localFederatedSourceIds(solo, 'default', 'seed_default')).toBeUndefined();
-  });
-});
-
-describe('federatedSearchScope — trust + explicitness matrix', () => {
-  test('trusted local + unqualified widens to the federated set', () => {
-    const ctx = ctxOf({ localFederatedSourceIds: ['default', 'wiki'] });
-    expect(federatedSearchScope(ctx)).toEqual({ sourceIds: ['default', 'wiki'] });
-  });
-
-  test('remote caller NEVER widens (fail-closed), even if the field is set', () => {
-    const ctx = ctxOf({ remote: true, localFederatedSourceIds: ['default', 'wiki'] });
-    expect(federatedSearchScope(ctx)).toEqual({ sourceId: 'default' });
-  });
-
-  test('per-call source_id wins over the federated set', () => {
-    const ctx = ctxOf({ localFederatedSourceIds: ['default', 'wiki'] });
-    expect(federatedSearchScope(ctx, 'wiki')).toEqual({ sourceId: 'wiki' });
-  });
-
-  test('per-call __all__ keeps the whole-brain semantics for trusted local', () => {
-    const ctx = ctxOf({ localFederatedSourceIds: ['default', 'wiki'] });
-    expect(federatedSearchScope(ctx, '__all__')).toEqual({});
-  });
-
-  test('a federated OAuth grant wins over the local set', () => {
-    const ctx = ctxOf({
-      localFederatedSourceIds: ['default', 'wiki'],
-      auth: { allowedSources: ['a', 'b'] } as OperationContext['auth'],
-    });
-    expect(federatedSearchScope(ctx)).toEqual({ sourceIds: ['a', 'b'] });
-  });
-
-  test('no local federated set → unchanged scalar scope', () => {
-    expect(federatedSearchScope(ctxOf())).toEqual({ sourceId: 'default' });
-  });
-});
-
-describe('search op — unqualified local search spans federated sources', () => {
-  test('federated source results appear; non-federated + archived stay invisible', async () => {
-    const ctx = ctxOf({
-      localFederatedSourceIds: await localFederatedSourceIds(engine, 'default', 'seed_default'),
-    });
-    const results = (await search.handler(ctx, { query: 'zebra telescope' })) as Array<{ slug: string }>;
-    const slugs = results.map((r) => r.slug);
-    expect(slugs).toContain('notes/home');
-    expect(slugs).toContain('wiki/topic'); // pre-#2561 this was missing
-    expect(slugs).not.toContain('private/topic');
-    expect(slugs).not.toContain('old/topic');
-  });
-
-  test('explicit source resolution (no federated set on ctx) stays single-source', async () => {
-    const results = (await search.handler(ctxOf(), { query: 'zebra telescope' })) as Array<{ slug: string }>;
-    const slugs = results.map((r) => r.slug);
-    expect(slugs).toEqual(['notes/home']);
-  });
-});