@gmickel/gno 2.7.1 → 2.8.1

package/src/core/memory-recall.ts

@@ -30,6 +30,9 @@ import {
 } from "./memory-fence";
 import {
   MEMORY_EMPTY_RECALL_HINT,
+  MEMORY_NO_MATCH_RECALL_HINT,
+  MEMORY_OVER_BUDGET_RECALL_HINT,
+  MEMORY_RECALL_ANY_TERM_MIN_RELATIVE_SCORE,
   MEMORY_RECALL_MAX_FACTS,
   MEMORY_RECALL_MAX_TOKENS,
   MEMORY_RECALL_RETRIEVAL_LIMIT,
@@ -40,6 +43,218 @@ import {
 
 type RetrievalLeg = { source: "bm25" | "vector"; results: SearchResult[] };
 
+/**
+ * Function words dropped from the lexical leg so a question-shaped turn
+ * retrieves on its content terms. English plus the common German, French,
+ * and Italian question and function words.
+ */
+const RECALL_STOPWORDS = new Set([
+  // English
+  "a",
+  "about",
+  "am",
+  "an",
+  "and",
+  "any",
+  "anything",
+  "are",
+  "as",
+  "at",
+  "be",
+  "been",
+  "but",
+  "by",
+  "can",
+  "could",
+  "did",
+  "do",
+  "does",
+  "for",
+  "from",
+  "had",
+  "has",
+  "have",
+  "how",
+  "how's",
+  "i",
+  "if",
+  "in",
+  "into",
+  "is",
+  "it",
+  "it's",
+  "its",
+  "know",
+  "me",
+  "my",
+  "of",
+  "on",
+  "or",
+  "our",
+  "please",
+  "should",
+  "so",
+  "tell",
+  "that",
+  "the",
+  "their",
+  "them",
+  "there",
+  "these",
+  "they",
+  "this",
+  "those",
+  "to",
+  "us",
+  "was",
+  "we",
+  "were",
+  "what",
+  "what's",
+  "when",
+  "where",
+  "where's",
+  "which",
+  "who",
+  "who's",
+  "whom",
+  "whose",
+  "why",
+  "will",
+  "with",
+  "would",
+  "you",
+  "your",
+  // German
+  "das",
+  "dem",
+  "den",
+  "der",
+  "des",
+  "ein",
+  "eine",
+  "ist",
+  "mit",
+  "oder",
+  "sind",
+  "und",
+  "uns",
+  "von",
+  "wann",
+  "warum",
+  "welche",
+  "welcher",
+  "welches",
+  "wer",
+  "wie",
+  "wir",
+  "wo",
+  "zu",
+  // French
+  "avec",
+  "comment",
+  "dans",
+  "de",
+  "du",
+  "est",
+  "et",
+  "la",
+  "le",
+  "les",
+  "nous",
+  "ou",
+  "où",
+  "pour",
+  "pourquoi",
+  "quand",
+  "que",
+  "quel",
+  "quelle",
+  "qui",
+  "quoi",
+  "sont",
+  "sur",
+  "un",
+  "une",
+  "vous",
+  // Italian
+  "che",
+  "chi",
+  "come",
+  "con",
+  "cosa",
+  "da",
+  "del",
+  "della",
+  "di",
+  "dove",
+  "il",
+  "per",
+  "perché",
+  "quale",
+  "quali",
+  "sono",
+]);
+
+/** Whitespace tokens, keeping a quoted phrase (optionally negated) whole. */
+const QUERY_TOKEN_PATTERN = /-?"[^"]*"|\S+/g;
+/** Same character class the FTS term sanitizer keeps. */
+const NON_TERM_CHARS = /[^\p{L}\p{N}'_]/gu;
+
+/**
+ * Content terms of a recall query: bare stopword tokens are dropped; quoted
+ * phrases, negations, and compounds pass through. A query with no positive
+ * content term left is returned unchanged.
+ */
+function recallContentQuery(query: string): string {
+  const tokens = query.match(QUERY_TOKEN_PATTERN) ?? [];
+  const kept = tokens.filter((token) => {
+    if (token.startsWith("-") || token.includes('"')) return true;
+    return !RECALL_STOPWORDS.has(
+      token.replace(NON_TERM_CHARS, "").toLowerCase()
+    );
+  });
+  const hasPositiveTerm = kept.some(
+    (token) =>
+      !token.startsWith("-") && token.replace(NON_TERM_CHARS, "").length > 0
+  );
+  return hasPositiveTerm ? kept.join(" ") : query;
+}
+
+/**
+ * Lexical leg: BM25 over the content terms, every term required first. When
+ * no fact carries all of them (a question-shaped turn), fall back to
+ * any-term matching so facts sharing a content term still rank, best BM25
+ * first, above a relative score floor. `null` means the query has no
+ * searchable terms.
+ */
+async function searchLexical(
+  deps: MemoryServiceDeps,
+  input: { query: string; collection: string; scopes: string[] }
+): Promise<SearchResult[] | null> {
+  const contentQuery = recallContentQuery(input.query);
+  const run = async (anyTerm: boolean) => {
+    const bm25 = await searchBm25(deps.store, contentQuery, {
+      collection: input.collection,
+      limit: MEMORY_RECALL_RETRIEVAL_LIMIT,
+      memoryFilter: { scopes: input.scopes, excludeSuperseded: true },
+      ...(anyTerm
+        ? {
+            anyTerm,
+            minRelativeScore: MEMORY_RECALL_ANY_TERM_MIN_RELATIVE_SCORE,
+          }
+        : {}),
+    });
+    if (bm25.ok) return bm25.value.results;
+    if (bm25.error.code !== "INVALID_INPUT") {
+      throw new MemoryError("MEMORY_QUERY_FAILED", bm25.error.message);
+    }
+    return null;
+  };
+  const allTerms = await run(false);
+  return allTerms?.length === 0 ? run(true) : allTerms;
+}
+
 /**
  * Retrieval legs: BM25 always; vectors when an embedding port and a searchable
  * vector index are present. The eligible set is one unbounded in-query
@@ -52,17 +267,9 @@ async function retrieveLegs(
   const { store, config } = deps;
   const { query, collection, scopes } = input;
   const legs: RetrievalLeg[] = [];
-  const bm25 = await searchBm25(store, query, {
-    collection,
-    limit: MEMORY_RECALL_RETRIEVAL_LIMIT,
-    memoryFilter: { scopes, excludeSuperseded: true },
-  });
-  if (!bm25.ok) {
-    if (bm25.error.code !== "INVALID_INPUT") {
-      throw new MemoryError("MEMORY_QUERY_FAILED", bm25.error.message);
-    }
-  } else {
-    legs.push({ source: "bm25", results: bm25.value.results });
+  const lexical = await searchLexical(deps, input);
+  if (lexical) {
+    legs.push({ source: "bm25", results: lexical });
   }
 
   const retrieval: RecallResult["retrieval"] = { mode: "lexical" };
@@ -159,7 +366,11 @@ async function materializeFacts(
   return materialized;
 }
 
-/** Token budget via the shared context-evidence selector, then the fact cap. */
+/**
+ * Token budget via the shared context-evidence selector, then the fact cap.
+ * Facts carry no facets, so the selector fills the budget in retrieval-rank
+ * order (per-fact facets would make it prefer the shortest facts).
+ */
 function selectWithinBudget(
   materialized: Array<{ fact: RecalledFact; rank: number }>,
   maxFacts: number,
@@ -176,11 +387,11 @@ function selectWithinBudget(
       sourceHash: fact.contentHash,
       mirrorHash: fact.contentHash,
       text: fact.text,
-      facets: [fact.uri],
+      facets: [],
       retrievalRank: rank,
       value: fact,
     })),
-    requestedFacets: materialized.map(({ fact }) => fact.uri),
+    requestedFacets: [],
     limits: {
       requestedBytes: maxTokens * MEMORY_TOKEN_BYTES_ESTIMATE,
       requestedTokens: maxTokens,
@@ -201,6 +412,28 @@ function selectWithinBudget(
   return selection.selected.slice(0, maxFacts).map((item) => item.value);
 }
 
+/**
+ * Why nothing came back: facts matched but none fit the budget, the scope
+ * holds facts but none matched, or the scope holds no current fact at all.
+ */
+async function emptyRecallHint(
+  deps: MemoryServiceDeps,
+  input: { collection: string; scopes: string[]; matched: number }
+): Promise<string> {
+  if (input.matched > 0) return MEMORY_OVER_BUDGET_RECALL_HINT;
+  const eligible = await deps.store.listMemoryEligibleDocuments({
+    collection: input.collection,
+    scopes: input.scopes,
+    excludeSuperseded: true,
+  });
+  if (!eligible.ok) {
+    throw new MemoryError("MEMORY_QUERY_FAILED", eligible.error.message);
+  }
+  return eligible.value.length > 0
+    ? MEMORY_NO_MATCH_RECALL_HINT
+    : MEMORY_EMPTY_RECALL_HINT;
+}
+
 export async function recallFacts(
   deps: MemoryServiceDeps,
   rawInput: RecallInput
@@ -264,6 +497,12 @@ export async function recallFacts(
             facts.map((fact) => fact.egressLineage)
           ),
         }
-      : { hint: MEMORY_EMPTY_RECALL_HINT }),
+      : {
+          hint: await emptyRecallHint(deps, {
+            collection: collection.name,
+            scopes,
+            matched: materialized.length,
+          }),
+        }),
   };
 }

package/src/core/memory-types.ts

@@ -33,11 +33,23 @@ export const MEMORY_RECALL_MAX_TOKENS = 512;
 /** Retrieval depth per leg before fusion and budgeting. */
 export const MEMORY_RECALL_RETRIEVAL_LIMIT = 32;
 export const MEMORY_RRF_K = 60;
+/**
+ * Any-term fallback floor: a fact must score at least this fraction of the
+ * best fact's raw BM25, so a term shared by most facts cannot pull them in.
+ */
+export const MEMORY_RECALL_ANY_TERM_MIN_RELATIVE_SCORE = 0.1;
 export const MEMORY_DEFAULT_LOCK_WAIT_MS = 120_000;
 export const MEMORY_TOKEN_BYTES_ESTIMATE = 4;
 
+/** Recall hint when the scope holds no current fact at all. */
 export const MEMORY_EMPTY_RECALL_HINT =
   'No memories in scope yet. Store one with: gno remember "<fact>" --scope <scope> --decision add';
+/** Recall hint when the scope holds facts but none matched the query. */
+export const MEMORY_NO_MATCH_RECALL_HINT =
+  'No memories in scope matched this query. Rephrase with words the fact uses, or store one with: gno remember "<fact>" --scope <scope> --decision add';
+/** Recall hint when facts matched but none fit the token budget. */
+export const MEMORY_OVER_BUDGET_RECALL_HINT =
+  "Matching memories did not fit the token budget. Raise --max-tokens (maxTokens) to return them.";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Errors

package/src/core/memory.ts

@@ -34,6 +34,8 @@ export {
   MEMORY_CANDIDATE_POOL,
   MEMORY_EMPTY_RECALL_HINT,
   MEMORY_LEXICAL_LIKELY_THRESHOLD,
+  MEMORY_NO_MATCH_RECALL_HINT,
+  MEMORY_OVER_BUDGET_RECALL_HINT,
   MEMORY_RECALL_MAX_FACTS,
   MEMORY_RECALL_MAX_TOKENS,
   MEMORY_SEMANTIC_LIKELY_THRESHOLD,

package/src/core/retrieval-replay-candidate.ts

@@ -303,6 +303,12 @@ export const runRetrievalReplayCandidate = async (
       retrievalScope
     );
     options.limit = scope.value.fetchLimit;
+    const scopedCollections = scope.value.collections.filter(
+      (name): name is string => name !== undefined
+    );
+    if (scopedCollections.length > 0) {
+      options.graphCollections = scopedCollections;
+    }
     const result = await runCandidateOnce(deps, source, candidate, options);
     if (!result.ok) return result;
     outputs.push(result.value);

package/src/core/retrieval-trace-request.ts

@@ -8,6 +8,7 @@ import type { RetrievalTraceTerminalStatus } from "../store/types";
 
 import { canonicalTraceJson } from "../store/retrieval-trace-codec";
 import { err, ok } from "../store/types";
+import { linkResolutionFingerprintInput } from "./link-workspace";
 import { RetrievalTraceSession } from "./retrieval-trace-session";
 
 export const retrievalTraceFailureStatus = (
@@ -45,6 +46,7 @@ export const buildRetrievalTraceFingerprints = async (input: {
 }): Promise<RetrievalTraceFingerprints> => {
   const collections = await input.store.getCollections();
   if (!collections.ok) throw new Error(collections.error.message);
+  const linkResolution = linkResolutionFingerprintInput(collections.value);
   const snapshots = [];
   for (const collection of [...collections.value].sort((left, right) =>
     left.name.localeCompare(right.name)
@@ -70,6 +72,7 @@ export const buildRetrievalTraceFingerprints = async (input: {
     index: fingerprint({
       indexName: input.indexName ?? "default",
       snapshots,
+      ...(linkResolution ? { linkResolution } : {}),
     }),
   };
 };

package/src/index.ts

@@ -18,14 +18,27 @@ import { IMPORT_CHILD_ENV } from "./sessions/import-child-env";
  * is the flush that actually waits. A closed consumer (EPIPE) settles
  * through the callback or the 'error' event.
  */
+const pendingFlushes = new WeakMap<NodeJS.WriteStream, Promise<void>>();
+
+/**
+ * Concurrent exit paths (normal completion racing a SIGINT) share one flush:
+ * a second caller must wait for the drain the first end() started, not treat
+ * the already-ended stream as flushed and exit mid-write.
+ */
 function flushStream(stream: NodeJS.WriteStream): Promise<void> {
+  const pending = pendingFlushes.get(stream);
+  if (pending) {
+    return pending;
+  }
   if (stream.destroyed || stream.writableEnded) {
     return Promise.resolve();
   }
-  return new Promise((resolve) => {
+  const flush = new Promise<void>((resolve) => {
     stream.once("error", () => resolve());
     stream.end(() => resolve());
   });
+  pendingFlushes.set(stream, flush);
+  return flush;
 }
 
 /**

package/src/ingestion/graph-reconciliation.ts

@@ -13,15 +13,25 @@ import {
   normalizeRelationEdgeType,
   normalizeRelationTarget,
 } from "../core/change-diff";
+import { LINK_RESOLVER_VERSION } from "../core/link-workspace";
 import {
   normalizeMarkdownPath,
   normalizeWikiName,
   parseTargetParts,
 } from "../core/links";
+import {
+  createInMemoryWorkspaceResolver,
+  membershipsFromCollectionRows,
+} from "../store/sqlite/workspace-link-resolver";
 import { parseFrontmatter } from "./frontmatter";
 
-const VERSION = 1;
+/**
+ * Projection version. 2: workspace-wide wiki resolution; a stored version
+ * mismatch forces one full projection on the first sync after upgrade.
+ */
+const VERSION = 2;
 const EDGE_TYPE = /^[a-z][a-z0-9_]*$/;
+const RELATIVE_REF = /^\.\.?\//;
 type ProjectionError = { relPath: string; code: string; message: string };
 
 function identity(doc: DocumentRow): GraphReferenceDocument {
@@ -38,8 +48,27 @@ function identity(doc: DocumentRow): GraphReferenceDocument {
   };
 }
 
-/** Insert once in catalog order: preserves legacy Array.find ambiguity precedence. */
-function relationResolver(docs: GraphReferenceDocument[]) {
+/**
+ * Insert once in catalog order: preserves legacy Array.find ambiguity precedence.
+ * Plain wiki-style targets from a document inside a link workspace use the
+ * shared workspace ranking (a tie resolves to nothing); URIs, docids,
+ * collection-qualified paths and relative markdown keep their contracts.
+ */
+function relationResolver(
+  docs: GraphReferenceDocument[],
+  memberships: ReturnType<typeof membershipsFromCollectionRows>
+) {
+  const workspace = createInMemoryWorkspaceResolver(
+    memberships,
+    docs.map((doc) => ({
+      id: doc.documentId,
+      docid: doc.docid,
+      collection: doc.collection,
+      relPath: doc.relPath,
+      title: doc.title,
+    }))
+  );
+  const byId = new Map(docs.map((doc) => [doc.documentId, doc]));
   const docids = new Map<string, GraphReferenceDocument>();
   const uris = new Map<string, GraphReferenceDocument>();
   const paths = new Map<string, GraphReferenceDocument>();
@@ -84,14 +113,27 @@ function relationResolver(docs: GraphReferenceDocument[]) {
         localWiki.get(`${parts.collection}\0${key}`)
       );
     const relativePath = normalizeMarkdownPath(parts.ref, source.relPath);
-    return (
-      (relativePath
-        ? paths.get(`${source.collection}/${relativePath}`)
-        : undefined) ??
-      paths.get(parts.ref) ??
-      localWiki.get(`${source.collection}\0${key}`) ??
-      wiki.get(key)
-    );
+    const relativeHit = relativePath
+      ? paths.get(`${source.collection}/${relativePath}`)
+      : undefined;
+    const ranked = workspace(source, key);
+    if (ranked === undefined) {
+      // Source outside any link workspace: the collection-scoped contract.
+      return (
+        relativeHit ??
+        paths.get(parts.ref) ??
+        localWiki.get(`${source.collection}\0${key}`) ??
+        wiki.get(key)
+      );
+    }
+    // Inside a workspace only the preserved contracts bypass the shared
+    // ranking: a collection-qualified path (`collection/relPath`) and an
+    // explicitly relative Markdown path (`./x.md`, `../x.md`). Every other
+    // name or path resolves exactly as the shared link resolver does.
+    const qualified = paths.get(parts.ref);
+    if (qualified) return qualified;
+    if (RELATIVE_REF.test(parts.ref) && relativeHit) return relativeHit;
+    return ranked?.traversable ? byId.get(ranked.target.id) : undefined;
   };
 }
 
@@ -105,12 +147,23 @@ export async function projectGraph(
   try {
     const graph = store.graphReferenceStore?.();
     let fingerprint = "";
+    // Partial ports (tests, adapters without collections) resolve links
+    // collection-scoped; the SQLite store always reports memberships.
+    const collections =
+      typeof store.getCollections === "function"
+        ? await store.getCollections()
+        : undefined;
+    if (collections && !collections.ok)
+      throw new Error(collections.error.message);
+    const memberships = membershipsFromCollectionRows(collections?.value ?? []);
     if (graph) {
-      const collections = await store.getCollections();
-      if (!collections.ok) throw new Error(collections.error.message);
+      if (!collections) throw new Error("Graph projection needs collections");
+      // Effective workspace membership (roots, nested vaults, real paths) is
+      // part of each collection row, so a membership change re-projects.
       fingerprint = new Bun.CryptoHasher("sha256")
         .update(
           JSON.stringify({
+            resolver: LINK_RESOLVER_VERSION,
             rules: options.contentTypeRules ?? [],
             collections: collections.value
               .map(({ syncedAt: _syncedAt, ...config }) => config)
@@ -138,7 +191,15 @@ export async function projectGraph(
       state.inProgress ||
       state.version !== VERSION ||
       state.configFingerprint !== fingerprint;
-    const resolve = relationResolver(current);
+    // An existing graph whose resolver or collection membership changed is
+    // rebuilt in full; report it so the fallback is never silent.
+    if (!forceFull && state && state.version !== null) {
+      if (state.version !== VERSION)
+        options.onGraphRebuild?.("resolver-upgrade");
+      else if (state.configFingerprint !== fingerprint)
+        options.onGraphRebuild?.("collections-changed");
+    }
+    const resolve = relationResolver(current, memberships);
     let selected: Set<number> | undefined;
     if (!full && graph) {
       selected = new Set(requestedSources);
@@ -165,7 +226,8 @@ export async function projectGraph(
         ))
           selected.add(id);
         const resolveOld = relationResolver(
-          previous.map((row) => row.document)
+          previous.map((row) => row.document),
+          memberships
         );
         for (const row of previous) {
           const source = currentById.get(row.document.documentId);

package/src/ingestion/source-availability/darwin-path.ts

@@ -1,6 +1,7 @@
 /**
  * Metadata-free recognition of the macOS File Provider layouts covered by the
- * physical fn-118 evidence. This is intentionally narrower than all paths on
+ * physical evidence in research/file-provider/ (fn-118; Google Shared drives in
+ * fn-179). This is intentionally narrower than all paths on
  * Darwin: unknown storage must not inherit a no-materialization guarantee.
  */
 
@@ -43,8 +44,13 @@ export function classifyDarwinFileProviderPath(
     return "unsupported";
   }
   const domain = parts[2];
-  if (domain?.startsWith("GoogleDrive-") && parts[3] === "My Drive") {
-    return "google-drive";
+  if (domain?.startsWith("GoogleDrive-")) {
+    const isMyDrive = parts[3] === "My Drive";
+    const isSharedDrive =
+      parts[3] === "Shared drives" &&
+      typeof parts[4] === "string" &&
+      parts[4].length > 0;
+    return isMyDrive || isSharedDrive ? "google-drive" : "unsupported";
   }
   if (
     domain?.startsWith("OneDrive-") &&

package/src/ingestion/sync.ts

@@ -57,7 +57,6 @@ import {
 } from "../core/links";
 import { extractMemoryScopes } from "../core/memory-record";
 import { normalizeTag, validateTag } from "../core/tags";
-import { TYPED_METADATA_INGEST_VERSION } from "../core/typed-metadata";
 import { defaultChunker } from "./chunker";
 import { persistChunkLayout, prepareChunking } from "./chunking";
 import {
@@ -102,9 +101,12 @@ const MAX_CONCURRENCY = 16;
 /**
  * Current ingest schema version.
  * Increment when ingestion adds new derived data (tags, metadata, etc.)
- * Documents with ingestVersion < INGEST_VERSION will be re-processed.
+ * or changes how it is parsed. Documents with ingestVersion < INGEST_VERSION
+ * will be re-processed. Must stay >= TYPED_METADATA_INGEST_VERSION (tested).
+ * 8: wiki links with a table-escaped alias (`[[Note\|Alias]]`) and Markdown
+ * link text with square brackets parse the way Obsidian renders them.
  */
-export const INGEST_VERSION = TYPED_METADATA_INGEST_VERSION;
+export const INGEST_VERSION = 8;
 const EMPTY_CONTENT_TYPE_RULES_FINGERPRINT =
   fingerprintContentTypeMetadataRules([]);
 const NON_RETRYABLE_CONVERSION_ERROR_CODES = new Set([
@@ -2069,6 +2071,19 @@ export class SyncService {
       }
     }
 
+    // Nested vaults (their own `.obsidian/`) are discovered from the synced
+    // document directories; a change re-fingerprints the graph projection.
+    const nestedRefresh = await store.refreshCollectionNestedWorkspaces?.(
+      collection.name
+    );
+    if (nestedRefresh && !nestedRefresh.ok) {
+      errors.push({
+        relPath: "(link workspace)",
+        code: nestedRefresh.error.code,
+        message: nestedRefresh.error.message,
+      });
+    }
+
     if (syncOptions.projectTypedEdges !== false) {
       errors.push(...(await this.projectTypedEdges(store, syncOptions)));
     }
@@ -2123,8 +2138,15 @@ export class SyncService {
       results.push(result);
     }
 
+    let graphRebuild: SyncResult["graphRebuild"];
     if (results.length > 0) {
-      const projectionErrors = await this.projectTypedEdges(store, options);
+      const projectionErrors = await this.projectTypedEdges(store, {
+        ...options,
+        onGraphRebuild: (reason) => {
+          graphRebuild = reason;
+          options.onGraphRebuild?.(reason);
+        },
+      });
       results.at(-1)?.errors.push(...projectionErrors);
     }
 
@@ -2145,6 +2167,7 @@ export class SyncService {
       ...(prepared.rechunkedMirrors
         ? { rechunkedMirrors: prepared.rechunkedMirrors }
         : {}),
+      ...(graphRebuild ? { graphRebuild } : {}),
       totalDurationMs: Date.now() - startTime,
       totalFilesProcessed: totals.processed,
       totalFilesAdded: totals.added,

package/src/ingestion/types.ts

@@ -161,7 +161,19 @@ export interface ChunkerPort {
 // ─────────────────────────────────────────────────────────────────────────────
 
 /** Sync options */
+/** Why a sync rebuilt the whole link graph instead of reconciling it. */
+export type GraphRebuildReason =
+  /** Link resolution semantics changed (first sync after an upgrade). */
+  | "resolver-upgrade"
+  /** Collection settings changed, including link workspace membership. */
+  | "collections-changed";
+
 export interface SyncOptions {
+  /**
+   * Internal: called when graph reconciliation cannot proceed incrementally
+   * and falls back to a full projection of an existing graph.
+   */
+  onGraphRebuild?: (reason: GraphRebuildReason) => void;
   /** Index-wide configured policy; omitted means the existing defaults. */
   chunking?: Partial<ChunkingParams>;
   /** Internal token passed from an outer sync; never a public CLI override. */
@@ -298,6 +310,8 @@ export interface CollectionSyncResult {
 export interface SyncResult {
   /** Cached layouts updated independently of source-refresh file counters. */
   rechunkedMirrors?: number;
+  /** Present when the link graph was rebuilt in full rather than reconciled. */
+  graphRebuild?: GraphRebuildReason;
   collections: CollectionSyncResult[];
   totalDurationMs: number;
   totalFilesProcessed: number;