@gmickel/gno 2.7.1 → 2.8.0

package/src/core/link-workspace.ts

@@ -0,0 +1,324 @@
+/**
+ * Link workspaces: collections whose roots share one workspace root resolve
+ * plain wiki links across each other (Obsidian vault semantics).
+ *
+ * Membership is derived from the filesystem, never stored in content: the
+ * nearest ancestor-or-self directory containing `.obsidian/`, or an explicit
+ * per-collection `workspaceRoot` (absolute path, or `false` to opt out).
+ * Ownership is finally decided per document: a nested vault (`.obsidian/`
+ * below the collection root) forms its own workspace.
+ *
+ * @module src/core/link-workspace
+ */
+
+// node:fs has no Bun equivalent for synchronous realpath/stat of directories.
+import { realpathSync, statSync } from "node:fs";
+// node:path provides platform-correct path algebra; Bun has no path utilities.
+import { dirname, isAbsolute, relative, sep } from "node:path";
+
+/** Bump when resolution semantics change; enters projection fingerprints. */
+export const LINK_RESOLVER_VERSION = 2;
+
+export const WORKSPACE_MARKER_DIR = ".obsidian";
+
+export type LinkWorkspaceSource =
+  /** No workspace root: collection-scoped resolution (today's behaviour). */
+  | "none"
+  /** Nearest `.obsidian/` ancestor-or-self of the collection root. */
+  | "detected"
+  /** Explicit absolute `workspaceRoot`. */
+  | "configured"
+  /** Explicit `workspaceRoot: false` opt-out. */
+  | "disabled"
+  /** Root or ancestors could not be inspected; fails closed to collection scope. */
+  | "unavailable";
+
+export interface CollectionWorkspaceInfo {
+  /** Canonical (real) collection root, or null when it cannot be resolved. */
+  realPath: string | null;
+  /** Canonical workspace root, or null for collection-scoped resolution. */
+  root: string | null;
+  source: LinkWorkspaceSource;
+}
+
+/** Stored membership of one collection, as read back from the index. */
+export interface CollectionWorkspaceMembership extends CollectionWorkspaceInfo {
+  collection: string;
+  /** Collection-relative POSIX prefixes that hold their own `.obsidian/`. */
+  nested: string[];
+}
+
+type DirProbe = "present" | "absent" | "error";
+
+const probeMarker = (directory: string): DirProbe => {
+  try {
+    return statSync(`${directory}${sep}${WORKSPACE_MARKER_DIR}`).isDirectory()
+      ? "present"
+      : "absent";
+  } catch (cause) {
+    const code = (cause as NodeJS.ErrnoException | undefined)?.code;
+    return code === "ENOENT" || code === "ENOTDIR" ? "absent" : "error";
+  }
+};
+
+const canonical = (path: string): string | null => {
+  try {
+    return realpathSync(path).normalize("NFC");
+  } catch {
+    return null;
+  }
+};
+
+/** Join a POSIX relative path onto a native absolute root. */
+const nativeJoin = (root: string, posixPath: string): string =>
+  `${root}${sep}${posixPath.split("/").join(sep)}`;
+
+/** True when `child` equals `parent` or sits inside it (component-wise). */
+export const pathContains = (parent: string, child: string): boolean => {
+  const rel = relative(parent, child);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+};
+
+/** POSIX path of `child` relative to `parent` ('' when equal). */
+export const posixRelative = (parent: string, child: string): string =>
+  relative(parent, child).split(sep).join("/").normalize("NFC");
+
+export type WorkspaceRootSettingError =
+  | "not_absolute"
+  | "not_found"
+  | "not_containing";
+
+/** Validate an explicit `workspaceRoot` against the collection root. */
+export const validateWorkspaceRootSetting = (
+  collectionPath: string,
+  workspaceRoot: string
+): WorkspaceRootSettingError | null => {
+  if (!isAbsolute(workspaceRoot)) return "not_absolute";
+  const root = canonical(workspaceRoot);
+  if (root === null) return "not_found";
+  try {
+    if (!statSync(root).isDirectory()) return "not_found";
+  } catch {
+    return "not_found";
+  }
+  const collectionRoot = canonical(collectionPath) ?? collectionPath;
+  return pathContains(root, collectionRoot) ? null : "not_containing";
+};
+
+export const workspaceRootSettingMessage = (
+  collection: string,
+  error: WorkspaceRootSettingError
+): string => {
+  switch (error) {
+    case "not_absolute":
+      return `Collection "${collection}": workspaceRoot must be an absolute path`;
+    case "not_found":
+      return `Collection "${collection}": workspaceRoot does not exist or is not a directory`;
+    case "not_containing":
+      return `Collection "${collection}": workspaceRoot must contain the collection root`;
+  }
+};
+
+/**
+ * Resolve one collection's workspace from its root. Real paths are used
+ * throughout; an unreadable root or ancestor never joins a broader workspace.
+ */
+export const detectCollectionWorkspace = (collection: {
+  path: string;
+  workspaceRoot?: string | false;
+}): CollectionWorkspaceInfo => {
+  const realPath = canonical(collection.path);
+  if (collection.workspaceRoot === false) {
+    return { realPath, root: null, source: "disabled" };
+  }
+  if (realPath === null) {
+    return { realPath: null, root: null, source: "unavailable" };
+  }
+  if (typeof collection.workspaceRoot === "string") {
+    const invalid = validateWorkspaceRootSetting(
+      collection.path,
+      collection.workspaceRoot
+    );
+    const root = invalid ? null : canonical(collection.workspaceRoot);
+    return root === null
+      ? { realPath, root: null, source: "unavailable" }
+      : { realPath, root, source: "configured" };
+  }
+  let current = realPath;
+  for (;;) {
+    const probe = probeMarker(current);
+    if (probe === "present") {
+      return { realPath, root: current, source: "detected" };
+    }
+    if (probe === "error") {
+      return { realPath, root: null, source: "unavailable" };
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return { realPath, root: null, source: "none" };
+    }
+    current = parent;
+  }
+};
+
+/**
+ * Find nested vaults inside a collection: every ancestor directory of an
+ * indexed document (below the collection root) that holds `.obsidian/`.
+ * Bounded by distinct directories, never by link count.
+ */
+export const detectNestedWorkspacePrefixes = (
+  realRoot: string,
+  relPaths: Iterable<string>
+): string[] => {
+  const directories = new Set<string>();
+  for (const relPath of relPaths) {
+    let directory = relPath.includes("/")
+      ? relPath.slice(0, relPath.lastIndexOf("/"))
+      : "";
+    while (directory && !directories.has(directory)) {
+      directories.add(directory);
+      directory = directory.includes("/")
+        ? directory.slice(0, directory.lastIndexOf("/"))
+        : "";
+    }
+  }
+  const nested: string[] = [];
+  for (const directory of directories) {
+    if (probeMarker(nativeJoin(realRoot, directory)) === "present") {
+      nested.push(directory.normalize("NFC"));
+    }
+  }
+  return nested.sort();
+};
+
+/**
+ * Fingerprint input for effective link resolution: resolver version plus the
+ * membership of every collection that belongs to (or contains) a workspace.
+ * Undefined when no collection is in a workspace, so collection-scoped
+ * indexes keep their existing fingerprints.
+ */
+export const linkResolutionFingerprintInput = (
+  rows: ReadonlyArray<{
+    name: string;
+    realPath?: string | null;
+    workspaceRoot?: string | null;
+    workspaceSource?: LinkWorkspaceSource;
+    workspaceNested?: string[];
+  }>
+):
+  | {
+      version: number;
+      workspaces: Array<{
+        collection: string;
+        realPath: string | null;
+        root: string | null;
+        source: LinkWorkspaceSource;
+        nested: string[];
+      }>;
+    }
+  | undefined => {
+  const workspaces = rows
+    .filter(
+      (row) =>
+        (row.workspaceRoot ?? null) !== null ||
+        (row.workspaceNested?.length ?? 0) > 0
+    )
+    .map((row) => ({
+      collection: row.name,
+      realPath: row.realPath ?? null,
+      root: row.workspaceRoot ?? null,
+      source: row.workspaceSource ?? "none",
+      nested: [...(row.workspaceNested ?? [])].sort(),
+    }))
+    .sort((left, right) =>
+      left.collection < right.collection
+        ? -1
+        : left.collection > right.collection
+          ? 1
+          : 0
+    );
+  return workspaces.length > 0
+    ? { version: LINK_RESOLVER_VERSION, workspaces }
+    : undefined;
+};
+
+/**
+ * One-line link workspace description for status output, or null for a
+ * collection that is not in a workspace. A redacted root prints no path.
+ */
+export const formatLinkWorkspace = (collection: {
+  workspaceRoot?: string | null;
+  workspaceSource?: string;
+}): string | null => {
+  switch (collection.workspaceSource) {
+    case "detected":
+    case "configured":
+      return collection.workspaceRoot
+        ? `${collection.workspaceRoot} (${collection.workspaceSource})`
+        : collection.workspaceSource;
+    case "disabled":
+      return "off (links stay inside this collection)";
+    case "unavailable":
+      return "unavailable (links stay inside this collection)";
+    default:
+      return null;
+  }
+};
+
+/** Workspace identity and workspace-relative path of one document. */
+export interface DocumentWorkspacePlacement {
+  /** Canonical workspace root (the workspace identity), or null. */
+  key: string | null;
+  /** Document path relative to the workspace root (POSIX, NFC). */
+  path: string;
+}
+
+/** Collection root relative to its workspace root, per membership object. */
+const workspacePrefixes = new WeakMap<CollectionWorkspaceMembership, string>();
+
+/**
+ * Place a document into its workspace: the deepest nested vault containing
+ * it, else its collection's workspace. Collection-scoped collections (none,
+ * disabled, unavailable) never place documents into a workspace, except that
+ * nested vaults still own their documents when the collection root is known
+ * and not opted out.
+ */
+export const placeDocument = (
+  membership: CollectionWorkspaceMembership | undefined,
+  relPath: string
+): DocumentWorkspacePlacement => {
+  const normalized = relPath.normalize("NFC");
+  if (
+    !membership ||
+    membership.realPath === null ||
+    membership.source === "disabled" ||
+    membership.source === "unavailable"
+  ) {
+    return { key: null, path: normalized };
+  }
+  let nestedPrefix: string | null = null;
+  for (const prefix of membership.nested) {
+    if (
+      normalized.startsWith(`${prefix}/`) &&
+      (nestedPrefix === null || prefix.length > nestedPrefix.length)
+    ) {
+      nestedPrefix = prefix;
+    }
+  }
+  if (nestedPrefix !== null) {
+    return {
+      key: nativeJoin(membership.realPath, nestedPrefix),
+      path: normalized.slice(nestedPrefix.length + 1),
+    };
+  }
+  if (membership.root === null) return { key: null, path: normalized };
+  let prefix = workspacePrefixes.get(membership);
+  if (prefix === undefined) {
+    prefix = posixRelative(membership.root, membership.realPath);
+    workspacePrefixes.set(membership, prefix);
+  }
+  return {
+    key: membership.root,
+    path: prefix ? `${prefix}/${normalized}` : normalized,
+  };
+};

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

@@ -2069,6 +2069,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 +2136,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 +2165,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;

package/src/llm/inference-scope.ts

@@ -169,9 +169,10 @@ export function withOwnedInferenceScope<T>(
 }
 
 /**
- * One page of a background pass: an inference deadline inside it fails only
- * that page (undefined), leaving the pass scope active for later pages.
- * Cancellation, or a deadline of the enclosing scope itself, still throws.
+ * Best-effort inference (one page of a background pass, or query expansion):
+ * an inference deadline inside it fails only this operation (undefined),
+ * leaving the enclosing scope active. Cancellation, or a deadline of the
+ * enclosing scope itself, still throws.
  */
 export async function withInferencePage<T>(
   operation: () => Promise<T>