fix: seed cached file provider descendants

Author: misrasaurabh1

crates/localityd/src/file_provider.rs

@@ -17,6 +17,7 @@ use locality_store::{
     ProjectionMode, ShadowRepository, StoreError, VirtualMutationRepository,
 };
 use serde::{Deserialize, Serialize};
+use std::collections::{BTreeSet, VecDeque};
 use std::path::{Path, PathBuf};
 use std::sync::atomic::{AtomicU64, Ordering};
 use std::time::{SystemTime, UNIX_EPOCH};
@@ -109,6 +110,56 @@ where
     })
 }
 
+pub fn file_provider_domain_working_set<S>(
+    store: &S,
+    state_root: &Path,
+    domain_id: &str,
+) -> LocalityResult<FileProviderDomainChildrenReport>
+where
+    S: MountRepository + EntityRepository + VirtualMutationRepository,
+{
+    let domain = file_provider_domain_children(store, domain_id)?;
+    let mut children = Vec::new();
+
+    for mount_root in domain.children {
+        let mount_id = MountId::new(mount_root.mount_id.clone());
+        let content_root = virtual_fs::virtual_fs_content_root(state_root, &mount_id);
+        let mut pending_containers = VecDeque::from([mount_root.item.identifier.clone()]);
+        let mut visited_containers = BTreeSet::new();
+        let mut visited_items = BTreeSet::new();
+        children.push(mount_root);
+
+        while let Some(container_identifier) = pending_containers.pop_front() {
+            if !visited_containers.insert(container_identifier.clone()) {
+                continue;
+            }
+            let report = virtual_fs::virtual_fs_children_with_content_root(
+                store,
+                &content_root,
+                &mount_id,
+                &container_identifier,
+            )?;
+            for item in report.children {
+                if !visited_items.insert(item.identifier.clone()) {
+                    continue;
+                }
+                if item.kind == FileProviderItemKind::Folder {
+                    pending_containers.push_back(item.identifier.clone());
+                }
+                children.push(FileProviderDomainChild {
+                    mount_id: mount_id.0.clone(),
+                    item,
+                });
+            }
+        }
+    }
+
+    Ok(FileProviderDomainChildrenReport {
+        domain_id: domain_id.to_string(),
+        children,
+    })
+}
+
 pub fn file_provider_item<S>(
     store: &S,
     mount_id: &MountId,
@@ -4050,6 +4101,139 @@ mod tests {
         assert_eq!(report.children[1].item.identifier, "mount:notion-main");
     }
 
+    #[test]
+    fn shared_macos_file_provider_working_set_recursively_lists_cached_items() {
+        let state_root = temp_root("locality-file-provider-working-set");
+        let mount_id = MountId::new("notion-main");
+        let mut store = InMemoryStateStore::new();
+        store
+            .save_mount(
+                MountConfig::new(
+                    mount_id.clone(),
+                    "notion",
+                    state_root.join("visible/notion"),
+                )
+                .projection(ProjectionMode::MacosFileProvider),
+            )
+            .expect("save notion mount");
+        for (remote_id, title, path) in [
+            ("company", "Company", "Company/page.md"),
+            ("compliance", "Compliance", "Company/Compliance/page.md"),
+            (
+                "privacy",
+                "Privacy Policy",
+                "Company/Compliance/Privacy Policy/page.md",
+            ),
+        ] {
+            store
+                .save_entity(EntityRecord::new(
+                    mount_id.clone(),
+                    RemoteId::new(remote_id),
+                    EntityKind::Page,
+                    title,
+                    path,
+                ))
+                .expect("save nested Notion page");
+        }
+
+        let report =
+            file_provider_domain_working_set(&store, &state_root, MACOS_FILE_PROVIDER_DOMAIN_ID)
+                .expect("working set");
+        let items = report
+            .children
+            .iter()
+            .map(|child| {
+                (
+                    child.mount_id.as_str(),
+                    child.item.identifier.as_str(),
+                    child.item.parent_identifier.as_deref(),
+                    child.item.filename.as_str(),
+                    child.item.path.as_str(),
+                    &child.item.kind,
+                )
+            })
+            .collect::<Vec<_>>();
+
+        assert_eq!(
+            items,
+            vec![
+                (
+                    "notion-main",
+                    "mount:notion-main",
+                    Some("root"),
+                    "notion",
+                    "notion",
+                    &FileProviderItemKind::Folder,
+                ),
+                (
+                    "notion-main",
+                    "guidance:AGENTS.md",
+                    Some("mount:notion-main"),
+                    "AGENTS.md",
+                    "AGENTS.md",
+                    &FileProviderItemKind::File,
+                ),
+                (
+                    "notion-main",
+                    "guidance:CLAUDE.md",
+                    Some("mount:notion-main"),
+                    "CLAUDE.md",
+                    "CLAUDE.md",
+                    &FileProviderItemKind::File,
+                ),
+                (
+                    "notion-main",
+                    "children:company",
+                    Some("mount:notion-main"),
+                    "Company",
+                    "Company",
+                    &FileProviderItemKind::Folder,
+                ),
+                (
+                    "notion-main",
+                    "children:compliance",
+                    Some("children:company"),
+                    "Compliance",
+                    "Company/Compliance",
+                    &FileProviderItemKind::Folder,
+                ),
+                (
+                    "notion-main",
+                    "company",
+                    Some("children:company"),
+                    "page.md",
+                    "Company/page.md",
+                    &FileProviderItemKind::File,
+                ),
+                (
+                    "notion-main",
+                    "compliance",
+                    Some("children:compliance"),
+                    "page.md",
+                    "Company/Compliance/page.md",
+                    &FileProviderItemKind::File,
+                ),
+                (
+                    "notion-main",
+                    "children:privacy",
+                    Some("children:compliance"),
+                    "Privacy Policy",
+                    "Company/Compliance/Privacy Policy",
+                    &FileProviderItemKind::Folder,
+                ),
+                (
+                    "notion-main",
+                    "privacy",
+                    Some("children:privacy"),
+                    "page.md",
+                    "Company/Compliance/Privacy Policy/page.md",
+                    &FileProviderItemKind::File,
+                ),
+            ]
+        );
+        let _ = fs::remove_dir_all(state_root);
+    }
+
     #[test]
     fn shared_macos_file_provider_domain_children_distinguish_same_connector_mount_points() {
         let mut store = InMemoryStateStore::new();

crates/localityd/src/ipc.rs

@@ -103,6 +103,9 @@ pub enum DaemonRequest {
     FileProviderDomainChildren {
         domain_id: String,
     },
+    FileProviderDomainWorkingSet {
+        domain_id: String,
+    },
 }
 
 impl DaemonRequest {
@@ -132,6 +135,7 @@ impl DaemonRequest {
             Self::FileProviderMaterialize { .. } => "file_provider_materialize",
             Self::FileProviderRead { .. } => "file_provider_read",
             Self::FileProviderDomainChildren { .. } => "file_provider_domain_children",
+            Self::FileProviderDomainWorkingSet { .. } => "file_provider_domain_working_set",
         }
     }
 }
@@ -785,6 +789,22 @@ mod tests {
         );
     }
 
+    #[test]
+    fn file_provider_domain_working_set_command_decodes() {
+        let request: DaemonRequest = serde_json::from_str(
+            r#"{"command":"file_provider_domain_working_set","domain_id":"loc"}"#,
+        )
+        .expect("decode File Provider working-set request");
+
+        assert_eq!(
+            request,
+            DaemonRequest::FileProviderDomainWorkingSet {
+                domain_id: "loc".to_string(),
+            }
+        );
+        assert_eq!(request.command_name(), "file_provider_domain_working_set");
+    }
+
     #[test]
     fn named_pipe_endpoint_reports_not_implemented() {
         let endpoint = DaemonEndpoint::WindowsNamedPipe(r"\\.\pipe\loc-test".to_string());

crates/localityd/src/runtime.rs

@@ -470,6 +470,17 @@ pub trait RuntimeJobRunner: Send + Sync + 'static {
             "runtime runner does not handle File Provider domain enumeration",
         )
     }
+
+    fn run_file_provider_domain_working_set(
+        &self,
+        _state_root: PathBuf,
+        _domain_id: String,
+    ) -> DaemonResponse {
+        DaemonResponse::error(
+            "unsupported",
+            "runtime runner does not handle File Provider working-set enumeration",
+        )
+    }
 }
 
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
@@ -902,6 +913,21 @@ impl RuntimeJobRunner for DefaultRuntimeJobRunner {
         }
     }
 
+    fn run_file_provider_domain_working_set(
+        &self,
+        state_root: PathBuf,
+        domain_id: String,
+    ) -> DaemonResponse {
+        let store = match SqliteStateStore::open(state_root.clone()) {
+            Ok(store) => store,
+            Err(error) => return DaemonResponse::error("store_open_failed", error.to_string()),
+        };
+        match file_provider::file_provider_domain_working_set(&store, &state_root, &domain_id) {
+            Ok(report) => DaemonResponse::ok(report),
+            Err(error) => DaemonResponse::error(locality_error_code(&error), error.to_string()),
+        }
+    }
+
     fn run_virtual_fs_commit_write(
         &self,
         state_root: PathBuf,
@@ -1773,6 +1799,13 @@ impl RuntimeState {
                     .run_file_provider_domain_children(self.config.state_root.clone(), domain_id);
                 let _ = respond_to.send(response);
             }
+            DaemonRequest::FileProviderDomainWorkingSet { domain_id } => {
+                let response = self.runner.run_file_provider_domain_working_set(
+                    self.config.state_root.clone(),
+                    domain_id,
+                );
+                let _ = respond_to.send(response);
+            }
             DaemonRequest::VirtualFsCommitWrite {
                 mount_id,
                 identifier,

crates/localityd/src/server.rs

@@ -376,7 +376,8 @@ fn trace_daemon_request_attrs(span: &mut crate::trace::TraceSpan, request: &Daem
             span.attr("projection_root", projection_root.display().to_string());
             span.attr("projection", projection.as_str());
         }
-        DaemonRequest::FileProviderDomainChildren { domain_id } => {
+        DaemonRequest::FileProviderDomainChildren { domain_id }
+        | DaemonRequest::FileProviderDomainWorkingSet { domain_id } => {
             span.attr("domain_id", domain_id.as_str());
         }
         DaemonRequest::Ping

docs/desktop-app.md

@@ -212,14 +212,17 @@ state; missing helpers or extensions remain explicit setup failures.
 Later source mounts reuse the existing shared File Provider domain. Adding a
 top-level source folder such as `google-calendar-main` signals the working-set
 enumerator because macOS can drop root-container signals when no root enumerator
-is active. Compact working-set sync anchors reference rebuildable item-version
-snapshots in the File Provider app-group cache, so change enumeration reports
-only new, changed, or deleted items while the anchor stays below macOS's
-500-byte limit. A missing or incompatible cached snapshot expires the anchor
-and lets macOS perform a clean enumeration. Adding Calendar therefore inserts
-the Calendar mount and its children without re-reporting or reimporting an
-unchanged `notion` subtree. The shared root is never reimported or
-re-registered. Registration is idempotent when the domain already exists;
+is active. The working set reads the complete known projection recursively from
+durable local daemon state; it must not make connector API requests while
+enumerating folders. This seeds already-discovered nested Notion directories in
+macOS before the user opens them. Compact sync anchors reference rebuildable
+item-version snapshots in the File Provider app-group cache, so later change
+enumeration reports only new, changed, or deleted items while the anchor stays
+below macOS's 500-byte limit. A missing or incompatible cached snapshot expires
+the anchor and lets macOS perform a clean enumeration. Adding Calendar therefore
+inserts the Calendar mount and its cached descendants without re-reporting or
+reimporting an unchanged `notion` subtree. The shared root is never reimported
+or re-registered. Registration is idempotent when the domain already exists;
 automatic setup treats that registration as authoritative rather than removing
 and recreating it to repair metadata. Reimport and readiness repair stay scoped
 to the new mount-point identifier.
@@ -234,8 +237,9 @@ CloudStorage root, and the mount root are all verified successfully.
 Do not show hydration queues, polling intervals, or low-level daemon concepts in
 the onboarding UI. Do not make the user wait for the full workspace projection
 or initial sync to finish before moving forward. Once Notion is connected, Locality
-should begin prefetching top-level directories and files so the chosen mount
-point feels populated quickly. The UI should not show an extra checklist screen
+should begin background discovery and recursively publish all already-cached
+directory and file metadata to File Provider so navigating those folders does
+not wait on a live Notion request. The UI should not show an extra checklist screen
 where most items complete instantly; once the folder and agent instructions are
 ready, route directly to the final ready screen and show background sync as a
 short supporting detail rather than a task the user waits on.

docs/enumeration-and-hydration.md

@@ -377,6 +377,15 @@ Implementation:
 macOS `enumerateItems` calls into the daemon children path. The daemon client
 maps provider children requests to `DaemonRequest::FileProviderChildren`.
 
+The special working-set enumerator uses
+`DaemonRequest::FileProviderDomainWorkingSet`. That request recursively flattens
+the complete projection already present in durable daemon state, including
+nested page directories and their `page.md` files, without running connector
+child enumeration. This lets macOS seed nested placeholders in one ingestion
+pass even when earlier per-container signals arrived before parent placeholders
+existed. Item-version snapshots make later working-set signals delta-aware, so
+unchanged sibling mounts are not re-reported.
+
 Fetching file contents uses a different path: `fetchContents` calls the daemon
 read/materialize path, which can hydrate. Folder enumeration itself is child
 metadata listing.

platform/macos/LocalityFileProvider/README.md

@@ -71,13 +71,16 @@ Finder must enter the File Provider domain so directory listings call
 
 Mount activation signals the working-set enumerator after adding a source
 because macOS can ignore a root-container signal when no root enumerator is
-active. Compact working-set sync anchors reference rebuildable item-version
-snapshots in the File Provider app-group cache; subsequent change enumerations
-report only new, changed, or deleted items while anchors stay within macOS's
-500-byte limit. A missing or incompatible snapshot expires its anchor and falls
-back to a clean enumeration. Adding a source can therefore insert its mount
-point and immediate children without updating an unchanged sibling subtree.
-Reimport and readiness repair stay scoped to the new mount-point identifier.
+active. The working set recursively reads every already-known item from local
+daemon state, without calling connector APIs, so macOS can ingest cached nested
+directories before Finder opens them. Compact sync anchors reference
+rebuildable item-version snapshots in the File Provider app-group cache;
+subsequent change enumerations report only new, changed, or deleted items while
+anchors stay within macOS's 500-byte limit. A missing or incompatible snapshot
+expires its anchor and falls back to a clean enumeration. Adding a source can
+therefore insert its mount point and cached descendants without updating an
+unchanged sibling subtree. Reimport and readiness repair stay scoped to the new
+mount-point identifier.
 Because macOS creates a source folder asynchronously, Locality waits for it
 before inspecting it and retries the scoped refresh once. Automatic activation
 never resets or re-registers the shared domain. Reconnecting an existing source