@ai4b-team/fsaos-gateway-sdk 3.34.0 → 3.34.2

package/dist/index.js

@@ -76,6 +76,7 @@ __export(src_exports, {
   initSession: () => initSession,
   initVfsRealtimeWs: () => initVfsRealtimeWs,
   initializeFsaos: () => initializeFsaos,
+  initializeWorkspace: () => initializeWorkspace,
   interpretSchema: () => interpretSchema,
   invalidateAllVfs: () => invalidateAllVfs,
   invalidateChannelMessages: () => invalidateChannelMessages,
@@ -91,6 +92,7 @@ __export(src_exports, {
   isScopeReady: () => isScopeReady,
   itemsFilterFromQueryFilter: () => itemsFilterFromQueryFilter,
   listChildren: () => listChildren,
+  loadMounts: () => loadMounts,
   mount: () => mount2,
   mountRealtimeScope: () => mountRealtimeScope,
   normalizeItem: () => normalizeItem,
@@ -102,9 +104,11 @@ __export(src_exports, {
   readItem: () => readItem,
   refreshQuery: () => refreshQuery,
   registerCleanup: () => registerCleanup,
+  replaceMounts: () => replaceMounts,
   resetAllSdkState: () => resetAllSdkState,
   resolvePrincipalId: () => resolvePrincipalId,
   resubscribePath: () => resubscribePath,
+  selectMount: () => selectMount,
   serverDeadlinePassed: () => serverDeadlinePassed,
   serverMsUntil: () => serverMsUntil,
   serverNow: () => serverNow,
@@ -310,7 +314,7 @@ function notifyAnchorListeners() {
 }
 function setAnchor(ref) {
   const path = typeof ref === "string" ? ref : ref.path;
-  const changed = currentAnchorPath !== path;
+  const changed = currentAnchorPath !== path || currentAnchorRef?.id !== (typeof ref === "string" ? void 0 : ref.id);
   currentAnchorPath = path;
   currentAnchorRef = typeof ref === "string" ? null : ref;
   if (typeof ref !== "string" && !mountSet.some((m) => m.id === ref.id)) {
@@ -347,13 +351,13 @@ function isAnchorReady() {
   return anchorResolved;
 }
 var homeAnchor = null;
-function electHomeAnchor(ref) {
+function electHomeAnchor(ref, options = {}) {
   if (homeAnchor) {
     console.warn("[SDK] electHomeAnchor called twice; ignoring (logout to re-elect).");
     return;
   }
   homeAnchor = ref;
-  setAnchor(ref);
+  if (options.activate !== false) setAnchor(ref);
 }
 function getHomeAnchor() {
   return homeAnchor;
@@ -383,32 +387,33 @@ function subscribeMounts(listener) {
     mountListeners.delete(listener);
   };
 }
-function setMountsState(mounts) {
+function commitMountSelection(mounts, anchor) {
+  const mountsChanged = JSON.stringify(mountSet) !== JSON.stringify(mounts);
+  const anchorChanged = currentAnchorPath !== anchor.path || currentAnchorRef?.id !== anchor.id;
   mountSet = mounts;
-  notifyMountListeners();
-}
-function addMountState(ref) {
-  if (mountSet.some((m) => m.id === ref.id)) return;
-  mountSet = [...mountSet, ref];
-  notifyMountListeners();
-}
-function removeMountState(id) {
-  const removed = mountSet.find((m) => m.id === id);
-  if (!removed) return;
-  mountSet = mountSet.filter((m) => m.id !== id);
-  notifyMountListeners();
-  if (currentAnchorRef?.id === id && homeAnchor) {
-    setAnchor(homeAnchor);
+  currentAnchorPath = anchor.path;
+  currentAnchorRef = anchor;
+  if (!anchorResolved) {
+    anchorResolved = true;
+    resolveAnchorReady();
   }
+  if (mountsChanged) notifyMountListeners();
+  if (anchorChanged) notifyAnchorListeners();
 }
 var sessionEntry = null;
 var sessionPromise = null;
+var sessionGeneration = 0;
+function getSessionGeneration() {
+  return sessionGeneration;
+}
 async function initSession() {
   if (sessionEntry) return sessionEntry;
   if (sessionPromise) return sessionPromise;
+  const generation = sessionGeneration;
   sessionPromise = (async () => {
     const hostname = getHostname();
     const token = await getAccessToken();
+    if (generation !== sessionGeneration) throw new Error("Session changed during initialization");
     const headers = {};
     if (token) {
       headers["Authorization"] = `Bearer ${token}`;
@@ -421,6 +426,7 @@ async function initSession() {
       throw new Error(`Session init failed: ${response.status} ${response.statusText}`);
     }
     const json = await response.json();
+    if (generation !== sessionGeneration) throw new Error("Session changed during initialization");
     const entry = json.entry || json;
     sessionEntry = {
       scope_id: entry.scope_id,
@@ -434,13 +440,17 @@ async function initSession() {
       principal_id: entry.principal_id || null
     };
     return sessionEntry;
-  })();
+  })().catch((error) => {
+    if (generation === sessionGeneration) sessionPromise = null;
+    throw error;
+  });
   return sessionPromise;
 }
 function getSessionEntry() {
   return sessionEntry;
 }
 function clearSession() {
+  sessionGeneration++;
   sessionEntry = null;
   sessionPromise = null;
   currentAnchorPath = null;
@@ -455,6 +465,7 @@ function registerCleanup(fn) {
 function resetAllSdkState() {
   clearSession();
   clearCachedToken();
+  resolveAnchorReady();
   anchorResolved = false;
   anchorReady = new Promise((resolve) => {
     resolveAnchorReady = resolve;
@@ -547,24 +558,28 @@ var GatewayRequestError = class extends Error {
   }
 };
 async function gatewayCall(method, params = {}) {
+  const generation = getSessionGeneration();
+  const requestedAnchor = getAnchor();
   const hostname = getHostname();
   const url = `${GATEWAY_URL}/d/${hostname}`;
   const headers = {
     "Content-Type": "application/json"
   };
   const token = await getAccessToken();
+  if (generation !== getSessionGeneration()) throw new Error("Session changed before gateway request");
   if (token) {
     headers["Authorization"] = `Bearer ${token}`;
   }
   if (!ANCHOR_INDEPENDENT_METHODS.has(method) && !params._scope_path) {
     await awaitAnchorReady();
   }
+  if (generation !== getSessionGeneration()) throw new Error("Session changed before gateway request");
   const enrichedParams = { ...params };
   const session = getSessionEntry();
   if (!enrichedParams.domain_scope_id && session?.scope_id) {
     enrichedParams.domain_scope_id = session.scope_id;
   }
-  const anchorPath = getAnchor();
+  const anchorPath = requestedAnchor ?? getAnchor();
   if (!enrichedParams._scope_path && anchorPath) {
     enrichedParams._scope_path = anchorPath;
   }
@@ -574,6 +589,7 @@ async function gatewayCall(method, params = {}) {
     body: JSON.stringify({ method, params: enrichedParams })
   });
   const responseBody = await response.text();
+  if (generation !== getSessionGeneration()) throw new Error("Session changed during gateway request");
   let json = null;
   if (responseBody) {
     try {
@@ -680,6 +696,11 @@ function clearArrangementRefreshes(client2) {
   pending.delete(client2);
 }
 var client = null;
+registerCleanup(() => {
+  if (!client) return;
+  void client.cancelQueries({ queryKey: ["vfs"] });
+  client.removeQueries({ queryKey: ["vfs"] });
+});
 function setQueryClient(custom) {
   if (client && client !== custom) {
     throw new Error(
@@ -1957,60 +1978,40 @@ function invalidateOpenEnvelope(path, strategy) {
   }
 }
 
-// src/mounts.ts
-function declPath(memberSpacePath) {
-  return `${memberSpacePath}/settings/mounts`;
-}
-var declItemPath = null;
-async function loadMounts(memberSpacePath, resolveRef) {
-  declItemPath = declPath(memberSpacePath);
-  try {
-    const res = await gatewayCall("read", { path: declItemPath });
-    const ids = res?.item?.type_data?.mounts ?? [];
-    const refs = ids.map(resolveRef).filter((r) => r !== null);
-    const home = getHomeAnchor();
-    if (home && !refs.some((r) => r.id === home.id)) {
-      refs.unshift(home);
-    }
-    setMountsState(refs);
-    return refs;
-  } catch {
-    const home = getHomeAnchor();
-    const refs = home ? [home] : [];
-    setMountsState(refs);
-    return refs;
-  }
-}
-async function persist() {
-  if (!declItemPath) return;
-  const ids = getMounts().map((m) => m.id);
-  const lastAnchor = getAnchorRef()?.id ?? null;
-  try {
-    await gatewayCall("update", {
-      path: declItemPath,
-      type_data: { mounts: ids, last_anchor: lastAnchor }
-    });
-  } catch (e) {
-    try {
-      const parent = declItemPath.split("/").slice(0, -1).join("/");
-      await gatewayCall("create", {
-        parent_path: parent,
-        name: "mounts",
-        item_type: "file",
-        type_data: { mounts: ids, last_anchor: lastAnchor }
-      });
-    } catch (e2) {
-      console.warn("[SDK] mount declaration persist failed:", e2);
-    }
-  }
-}
-async function mount(ref) {
-  addMountState(ref);
-  await persist();
+// src/memberships.ts
+function membershipToMountRef(m) {
+  return {
+    id: m.accountId,
+    path: m.path,
+    kind: m.isSpace ? "space" : "account",
+    name: m.name,
+    grantedUnderAccountId: m.grantedUnderAccountId ?? void 0
+  };
 }
-async function unmount(id) {
-  removeMountState(id);
-  await persist();
+async function fetchMemberships() {
+  const result = await gatewayCall("list-memberships", {});
+  const memberships = result.memberships || [];
+  return memberships.map((m) => ({
+    accountId: m.account_id,
+    path: m.account_path,
+    name: m.account_name,
+    role: m.role || "member",
+    typeData: m.account_type_data || {},
+    joinedAt: m.joined_at,
+    via: m.via,
+    placement: m.placement,
+    subordinateTo: m.subordinate_to ?? null,
+    cascadeAnchorId: m.cascade_anchor_id ?? null,
+    isAccount: m.is_account ?? void 0,
+    isSpace: m.is_space ?? void 0,
+    isOwner: m.is_owner ?? void 0,
+    billingResponsible: m.billing_responsible ?? void 0,
+    grantedVia: m.granted_via ?? null,
+    grantedUnderAccountId: m.granted_under_account_id ?? null,
+    membershipPath: m.membership_path ?? null,
+    personalSpaceId: m.personal_space_id ?? null,
+    personalSpacePath: m.personal_space_path ?? null
+  }));
 }
 
 // src/vfs-realtime-ws.ts
@@ -2020,7 +2021,10 @@ var unsubCcmEvents = null;
 var debounceTimers = /* @__PURE__ */ new Map();
 var DEBOUNCE_MS = 250;
 function initVfsRealtimeWs(accountId) {
-  disposeVfsRealtimeWs();
+  if (unsubEvents) {
+    mountRealtimeScope(accountId);
+    return;
+  }
   mountRealtimeScope(accountId);
   unsubEvents = subscribeToEvents(
     "vfs_change",
@@ -2137,6 +2141,147 @@ function applyInvalidation(action, path, data, parentPath) {
   }
 }
 
+// src/mounts.ts
+var declaration = null;
+registerCleanup(() => {
+  declaration = null;
+});
+function assertCurrent(owner) {
+  if (owner !== declaration || owner.generation !== getSessionGeneration()) throw new Error("Workspace session changed");
+}
+function missing(error) {
+  return error instanceof GatewayRequestError && error.payload?.error === "item_not_found";
+}
+function canonical(owner, ref) {
+  const current = owner.resolve(ref.id);
+  if (!current || current.path !== ref.path || current.kind !== ref.kind) {
+    throw new Error("Mount is not an available membership");
+  }
+  return current;
+}
+function withHome(refs) {
+  const home = getHomeAnchor();
+  if (!home) throw new Error("Elect a home account before loading mounts");
+  return [home, ...refs.filter((ref, index) => ref.id !== home.id && refs.findIndex((r) => r.id === ref.id) === index)];
+}
+function signature(refs, anchor) {
+  return JSON.stringify({ mounts: refs.map((ref) => ref.id), last_anchor: anchor.id });
+}
+async function save(owner, refs, anchor) {
+  assertCurrent(owner);
+  const next = signature(refs, anchor);
+  if (owner.saved === next) return;
+  const type_data = JSON.parse(next);
+  await gatewayCall(owner.exists ? "update" : "create", owner.exists ? {
+    _scope_path: owner.scope,
+    path: owner.path,
+    type_data
+  } : {
+    _scope_path: owner.scope,
+    parent_path: owner.path.slice(0, owner.path.lastIndexOf("/")),
+    name: "mounts",
+    item_type: "file",
+    type_data
+  });
+  assertCurrent(owner);
+  owner.exists = true;
+  owner.saved = next;
+}
+function publish(refs, anchor) {
+  const previous = getMounts();
+  initVfsRealtimeWs(getHomeAnchor().id);
+  for (const ref of previous) if (!refs.some((r) => r.id === ref.id)) unmountRealtimeScope(ref.id);
+  for (const ref of refs) mountRealtimeScope(ref.id);
+  commitMountSelection(refs, anchor);
+}
+async function loadMounts(memberSpacePath, resolveRef, options = {}) {
+  const home = getHomeAnchor();
+  if (!home) throw new Error("Elect a home account before loading mounts");
+  const path = `${memberSpacePath}/settings/mounts`;
+  if (declaration && declaration.path !== path) throw new Error("Reset the session before changing the mount declaration owner");
+  const owner = declaration ??= {
+    generation: getSessionGeneration(),
+    path,
+    scope: home.path,
+    resolve: resolveRef,
+    exists: false,
+    ready: false,
+    saved: null,
+    queue: Promise.resolve()
+  };
+  assertCurrent(owner);
+  if (owner.loading) return owner.loading;
+  if (owner.ready) return getMounts();
+  owner.resolve = resolveRef;
+  owner.loading = (async () => {
+    let data = null;
+    try {
+      const response = await gatewayCall("read", { path, _scope_path: owner.scope });
+      assertCurrent(owner);
+      data = response.type_data ?? response.item?.type_data;
+      if (!data || !Array.isArray(data.mounts) || !data.mounts.every((id) => typeof id === "string")) {
+        throw new Error("Invalid saved mount declaration");
+      }
+      owner.exists = true;
+    } catch (error) {
+      assertCurrent(owner);
+      if (!missing(error)) throw error;
+      owner.exists = false;
+    }
+    const initial = options.initialAnchor ? canonical(owner, options.initialAnchor) : home;
+    const refs = withHome(data ? data.mounts.map(resolveRef).filter((ref) => ref !== null) : [initial]);
+    const anchor = data ? refs.find((ref) => ref.id === data.last_anchor) ?? refs.find((ref) => ref.kind === "space") ?? home : initial;
+    if (data) owner.saved = signature(refs, anchor);
+    else if (options.initialAnchor) await save(owner, refs, anchor);
+    assertCurrent(owner);
+    owner.ready = true;
+    publish(refs, anchor);
+    return refs;
+  })().finally(() => {
+    owner.loading = void 0;
+  });
+  return owner.loading;
+}
+function mutate(change) {
+  const owner = declaration;
+  if (!owner?.ready) return Promise.reject(new Error("Workspace mounts are not loaded"));
+  const task = owner.queue.then(async () => {
+    assertCurrent(owner);
+    const { refs, anchor } = change(owner);
+    await save(owner, refs, anchor);
+    assertCurrent(owner);
+    publish(refs, anchor);
+  });
+  owner.queue = task.catch(() => {
+  });
+  return task;
+}
+function mount(ref) {
+  return mutate((owner) => ({ refs: withHome([...getMounts(), canonical(owner, ref)]), anchor: getAnchorRef() }));
+}
+function unmount(id) {
+  return mutate(() => {
+    if (id === getHomeAnchor().id) throw new Error("The home account cannot be unmounted");
+    const refs = withHome(getMounts().filter((ref) => ref.id !== id));
+    const anchor = refs.find((ref) => ref.id === getAnchorRef()?.id) ?? refs.find((ref) => ref.kind === "space") ?? getHomeAnchor();
+    return { refs, anchor };
+  });
+}
+function selectMount(ref) {
+  return mutate((owner) => {
+    const anchor = canonical(owner, ref);
+    return { refs: withHome([...getMounts(), anchor]), anchor };
+  });
+}
+function replaceMounts(refs, anchor) {
+  return mutate((owner) => {
+    const next = withHome(refs.map((ref) => canonical(owner, ref)));
+    const selected = canonical(owner, anchor);
+    if (!next.some((ref) => ref.id === selected.id)) throw new Error("Selected mount must be in the working set");
+    return { refs: next, anchor: selected };
+  });
+}
+
 // src/hooks.ts
 function useScopeKey() {
   return useSyncExternalStore(subscribeScope, getScopeVersion, getScopeVersion);
@@ -2503,44 +2648,13 @@ function useScope() {
   return { data, loading, error };
 }
 var EMPTY_ACCOUNTS = [];
-function membershipToMountRef(m) {
-  return {
-    id: m.accountId,
-    path: m.path,
-    kind: m.isSpace ? "space" : "account",
-    name: m.name,
-    grantedUnderAccountId: m.grantedUnderAccountId ?? void 0
-  };
-}
 function useAccounts() {
   const { user } = useAuth();
-  const autoSelectedRef = useRef(false);
+  const autoSelectedRef = useRef(null);
+  const [mountError, setMountError] = useState(null);
   const query = useQuery({
     queryKey: vfsKeys.memberships(user?.id ?? "anonymous"),
-    queryFn: async () => {
-      const result = await gatewayCall("list-memberships", {});
-      const memberships = result.memberships || [];
-      return memberships.map((m) => ({
-        accountId: m.account_id,
-        path: m.account_path,
-        name: m.account_name,
-        role: m.role || "member",
-        typeData: m.account_type_data || {},
-        joinedAt: m.joined_at,
-        via: m.via,
-        placement: m.placement,
-        subordinateTo: m.subordinate_to ?? null,
-        cascadeAnchorId: m.cascade_anchor_id ?? null,
-        isAccount: m.is_account ?? void 0,
-        isSpace: m.is_space ?? void 0,
-        isOwner: m.is_owner ?? void 0,
-        billingResponsible: m.billing_responsible ?? void 0,
-        grantedVia: m.granted_via ?? null,
-        grantedUnderAccountId: m.granted_under_account_id ?? null,
-        personalSpaceId: m.personal_space_id ?? null,
-        personalSpacePath: m.personal_space_path ?? null
-      }));
-    },
+    queryFn: fetchMemberships,
     enabled: !!user?.id,
     staleTime: 1e3 * 60 * 2
   });
@@ -2562,50 +2676,47 @@ function useAccounts() {
   }, [anchorVersion2, allMemberships]);
   useEffect(() => {
     if (!user?.id) {
-      autoSelectedRef.current = false;
+      autoSelectedRef.current = null;
       return;
     }
-    if (autoSelectedRef.current) return;
+    if (autoSelectedRef.current === user.id) return;
+    setMountError(null);
     if (electionCandidates.length === 1) {
       const only = electionCandidates[0];
-      electHomeAnchor(membershipToMountRef(only));
+      if (!getHomeAnchor()) electHomeAnchor(membershipToMountRef(only));
       initVfsRealtimeWs(only.accountId);
       if (only.personalSpacePath) {
         loadMounts(only.personalSpacePath, (id) => {
           const m = allMemberships.find((x) => x.accountId === id);
           return m ? membershipToMountRef(m) : null;
-        }).catch(() => {
-        });
+        }).catch(setMountError);
       }
-      autoSelectedRef.current = true;
+      autoSelectedRef.current = user.id;
     } else if (electionCandidates.length > 1) {
-      autoSelectedRef.current = true;
+      autoSelectedRef.current = user.id;
     }
   }, [user?.id, electionCandidates, allMemberships]);
-  const switchAccount = useCallback((accountPath) => {
+  const switchAccount = useCallback(async (accountPath) => {
     const m = allMemberships.find((a) => a.path === accountPath);
-    if (!m) return;
+    if (!m) throw new Error("Account membership is unavailable");
     const ref = membershipToMountRef(m);
     if (!getHomeAnchor()) {
       electHomeAnchor(ref);
-      if (m.personalSpacePath) {
-        loadMounts(m.personalSpacePath, (id) => {
-          const mm = allMemberships.find((x) => x.accountId === id);
-          return mm ? membershipToMountRef(mm) : null;
-        }).catch(() => {
-        });
-      }
-    } else {
-      setAnchor(ref);
     }
+    const home = allMemberships.find((a) => a.accountId === getHomeAnchor()?.id);
+    if (!home?.personalSpacePath) throw new Error("The home membership has no mount declaration location");
+    await loadMounts(home.personalSpacePath, (id) => {
+      const member = allMemberships.find((a) => a.accountId === id);
+      return member ? membershipToMountRef(member) : null;
+    });
+    await selectMount(ref);
+    setMountError(null);
     initVfsRealtimeWs(m.accountId);
   }, [allMemberships]);
-  const mountScope = useCallback((scopePath) => {
+  const mountScope = useCallback(async (scopePath) => {
     const m = allMemberships.find((a) => a.path === scopePath);
-    if (!m) return;
-    mount(membershipToMountRef(m)).catch(() => {
-    });
-    mountRealtimeScope(scopePath);
+    if (!m) throw new Error("Scope membership is unavailable");
+    await mount(membershipToMountRef(m));
   }, [allMemberships]);
   return {
     accounts: electionCandidates,
@@ -2615,17 +2726,19 @@ function useAccounts() {
     switchAccount,
     mountScope,
     loading: query.isLoading,
-    error: query.error
+    error: query.error ?? mountError
   };
 }
 function useMounts() {
+  useScopeKey();
   const version = useSyncExternalStore(subscribeMounts, getMountVersion, getMountVersion);
   const mounts = useMemo(() => getMounts(), [version]);
   return {
     mounts,
     homeAnchor: getHomeAnchor(),
     anchor: getAnchorRef(),
-    setAnchor,
+    setAnchor: selectMount,
+    replaceMounts,
     mount,
     unmount
   };
@@ -3372,6 +3485,7 @@ function normalizeChannel(raw) {
     isPrivate: td.is_private || false,
     isDm: td.is_dm || false,
     messageCount: td.message_count || 0,
+    createdAt: raw.created_at || "",
     updatedAt: raw.updated_at || "",
     chatScopePath: lineage.context_path || "",
     contextId: raw.scope_item_id || "",
@@ -3978,6 +4092,15 @@ function usePersonalItemOrder(key, items) {
   const scopePath = getScope();
   const supported = anchor?.kind === "space";
   const query = useArrangement(supported && scopePath ? { key, scope_id: anchor.id } : null);
+  const orderedItems = useMemo(() => {
+    const arranged = query.applyTo([...items]);
+    if (key !== "channel-order") return arranged;
+    const savedIds = new Set(query.order ?? []);
+    const unplaced = arranged.filter((item) => !savedIds.has(item.id));
+    const created = (item) => Date.parse(item.createdAt ?? "") || 0;
+    unplaced.sort((a, b) => created(b) - created(a));
+    return [...unplaced, ...arranged.filter((item) => savedIds.has(item.id))];
+  }, [key, items, query.applyTo, query.order]);
   const client2 = useQueryClient();
   const pending3 = useRef(false);
   const ready = Boolean(supported && !query.error && query.arrangement?.item_id && query.resolutionLevel === "member" && query.arrangement.write_target_id === query.arrangement.item_id);
@@ -4004,7 +4127,7 @@ function usePersonalItemOrder(key, items) {
     if (cached?.item_id !== query.arrangement.item_id || JSON.stringify(cached?.type_data?.order ?? []) !== JSON.stringify(query.order ?? [])) {
       throw new Error("The saved order changed. Try dragging again");
     }
-    const current = query.applyTo([...items]).map((item) => item.id);
+    const current = orderedItems.map((item) => item.id);
     if (ids.every((id, index2) => current[index2] === id)) return;
     const visible = new Set(visibleIds);
     let index = 0;
@@ -4023,7 +4146,7 @@ function usePersonalItemOrder(key, items) {
     }
   }
   return {
-    items: query.applyTo([...items]),
+    items: orderedItems,
     ready,
     supported,
     contextKey: `${generation}:${scopePath}:${key}`,
@@ -4311,34 +4434,109 @@ function startTracking(options = {}) {
   return trackingCleanup;
 }
 
-// src/initialize.ts
+// src/workspace.ts
 var initialization;
+registerCleanup(() => {
+  initialization = void 0;
+});
+function initializeWorkspace(options) {
+  if (initialization) {
+    if (initialization.accountPath !== options.accountPath) return Promise.reject(new Error("Reset the session before changing accounts"));
+    return initialization.promise;
+  }
+  const generation = getSessionGeneration();
+  const check = () => {
+    if (generation !== getSessionGeneration()) throw new Error("Workspace session changed");
+  };
+  const promise = (async () => {
+    const entry = await initSession();
+    check();
+    if (!entry.principal_id) throw new Error("Workspace initialization requires an authenticated principal");
+    const memberships = await getQueryClient().fetchQuery({
+      queryKey: vfsKeys.memberships(entry.principal_id),
+      queryFn: fetchMemberships,
+      staleTime: 12e4,
+      retry: false
+    });
+    check();
+    const account = memberships.find((m) => m.path === options.accountPath && m.isAccount && !m.isSpace);
+    if (!account) throw new Error("Authenticated account membership is unavailable");
+    const personal = memberships.find((m) => m.isSpace && m.accountId === account.personalSpaceId && m.path === account.personalSpacePath);
+    if (!personal || !account.personalSpacePath) throw new Error("A provisioned default Space membership is required");
+    const home = membershipToMountRef(account);
+    const defaultSpace = membershipToMountRef(personal);
+    const elected = getHomeAnchor();
+    if (elected && elected.id !== home.id) throw new Error("Reset the session before changing accounts");
+    if (!elected) electHomeAnchor(home, { activate: false });
+    await loadMounts(account.personalSpacePath, (id) => {
+      const member = memberships.find((m) => m.accountId === id && (m.isAccount || m.isSpace));
+      return member ? membershipToMountRef(member) : null;
+    }, { initialAnchor: defaultSpace });
+    check();
+    return { home, defaultSpace, memberships };
+  })().catch((error) => {
+    if (generation === getSessionGeneration()) initialization = void 0;
+    throw error;
+  });
+  initialization = { accountPath: options.accountPath, promise };
+  return promise;
+}
+
+// src/initialize.ts
+var initialization2;
+var stopActiveTracking;
+var workspaceAccount;
+registerCleanup(() => {
+  stopActiveTracking?.();
+  stopActiveTracking = void 0;
+  initialization2 = void 0;
+  workspaceAccount = void 0;
+});
 function initializeFsaos(options = {}) {
-  if (initialization) return initialization;
-  initialization = (async () => {
+  if (initialization2) {
+    if (options.workspace && options.workspace.accountPath !== workspaceAccount) {
+      return Promise.reject(new Error("Initialize workspace through initializeWorkspace, or dispose the existing runtime first"));
+    }
+    return initialization2;
+  }
+  workspaceAccount = options.workspace?.accountPath;
+  const generation = getSessionGeneration();
+  initialization2 = (async () => {
     const tracking = options.tracking ?? true;
     const stopTracking = tracking === false ? () => {
     } : startTracking(typeof tracking === "object" ? tracking : {});
+    stopActiveTracking = stopTracking;
     try {
       const session = options.session === false ? null : await initSession();
+      const workspace = options.workspace ? await initializeWorkspace(options.workspace) : void 0;
+      if (generation !== getSessionGeneration()) throw new Error("Session changed during initialization");
       let disposed = false;
       const runtime = {
         session,
+        workspace,
         dispose() {
           if (disposed) return;
           disposed = true;
           stopTracking();
-          initialization = void 0;
+          if (generation === getSessionGeneration()) {
+            initialization2 = void 0;
+            workspaceAccount = void 0;
+            stopActiveTracking = void 0;
+          }
         }
       };
       return runtime;
     } catch (error) {
       stopTracking();
-      initialization = void 0;
+      if (generation === getSessionGeneration()) {
+        initialization2 = void 0;
+        workspaceAccount = void 0;
+        stopActiveTracking = void 0;
+      }
       throw error;
     }
   })();
-  return initialization;
+  return initialization2;
 }
 
 // src/execution-control.ts
@@ -5369,6 +5567,6 @@ function usePinnedItems() {
 // src/index.ts
 __registerSdkExports(src_exports);
 
-export { ComponentRenderer, EnforcementDeniedError, FormSubmissionError, GatewayRequestError, InteractionTrackingError, KernelProvider, auth, awaitAnchorReady, awaitScopeReady, callTool, cancelQueuedTurn, cancelTurn, clearCachedToken, clearSession, createItem, disconnectSSE, disposeVfsRealtimeWs, electHomeAnchor, emitEvent, fetchChannelMessages, fetchChannelMessagesPage, fetchChannelMessagesWithCards, fetchEdgesForItem, fetchItemHistory, fetchItemVersions, fetchItems, fetchMemberFocus, fetchOpenEnvelope, fetchRecentActivity, fetchResolvedItems, fetchTimelineHistory, fetchTurnQueueEntries, fetchTypeDefinitions, fetchVfsChildren, fetchVfsChildrenPage, fetchVfsItem, fetchVfsItemById, fetchVfsTree, gatewayCall, getAccessToken, getAnchor, getAnchorRef, getAnchorVersion, getAssetUrl, getDefaultSort, getHomeAnchor, getMountVersion, getMounts, getPathSubscriptionState, getQueryClient, getRequiredFormFields, getScope, getScopeVersion, getServerClockOffsetMs, getServerClockSyncedAt, getSessionEntry, hasServerClock, initSession, initVfsRealtimeWs, initializeFsaos, interpretSchema, invalidateAllVfs, invalidateChannelMessages, invalidateChildren, invalidateItem, invalidateOpenEnvelope, invalidatePathAndParent, invalidateSubtree, invalidateTypes, isAnchorReady, isChannelPath, isListableItemsFilter, isScopeReady, itemsFilterFromQueryFilter, listChildren, mount2 as mount, mountRealtimeScope, normalizeItem, onConnectionStateChange, pathSubscriptionMatches, ping, pushChanges, queryClient, readItem, refreshQuery, registerCleanup, resetAllSdkState, resolvePrincipalId, resubscribePath, serverDeadlinePassed, serverMsUntil, serverNow, setAnchor, setCachedToken, setQueryClient, setScope, setupRequireShim, signal, startTracking, steerTurn, submitForm, subscribeAnchor, subscribeArtifactStream, subscribeMounts, subscribeScope, subscribeToEvents, subscribeToPath, subscribeToScope, trackAction, trackEvent, trackPageView, unmountRealtimeScope, updateItem, uploadFile, useAccounts, useAgentTimeline, useAllChannels, useArrangement, useArtifactStream, useAsset, useAuth, useChannelMessages, useChannels, useChildren, useComponent, useCreate, useDelete, useDmChannels, useEdges, useEventStream, useFileUpload, useInfiniteChannelMessages, useInfiniteChildren, useInfiniteItems, useItem, useItemById, useItemHistory, useItemVersions, useItems, useLink, useList, useMemberFocus, useMintedAsset, useMounts, useMove, useMutation, useNotifications, useOpen, usePermission, usePermissions, usePersonalItemOrder, usePinnedItems, usePrincipal, useRealtimeQuery, useRecentActivity, useResolve, useResolvedItems, useScope, useScopeReady, useSearch, useTheme, useTimelineHistory, useTool, useTree, useType, useTypeHelpers, useTypes, useUnreadCounts, useUpdate, useUpdatePrincipal, vfsKeys, waitForPathReady };
+export { ComponentRenderer, EnforcementDeniedError, FormSubmissionError, GatewayRequestError, InteractionTrackingError, KernelProvider, auth, awaitAnchorReady, awaitScopeReady, callTool, cancelQueuedTurn, cancelTurn, clearCachedToken, clearSession, createItem, disconnectSSE, disposeVfsRealtimeWs, electHomeAnchor, emitEvent, fetchChannelMessages, fetchChannelMessagesPage, fetchChannelMessagesWithCards, fetchEdgesForItem, fetchItemHistory, fetchItemVersions, fetchItems, fetchMemberFocus, fetchOpenEnvelope, fetchRecentActivity, fetchResolvedItems, fetchTimelineHistory, fetchTurnQueueEntries, fetchTypeDefinitions, fetchVfsChildren, fetchVfsChildrenPage, fetchVfsItem, fetchVfsItemById, fetchVfsTree, gatewayCall, getAccessToken, getAnchor, getAnchorRef, getAnchorVersion, getAssetUrl, getDefaultSort, getHomeAnchor, getMountVersion, getMounts, getPathSubscriptionState, getQueryClient, getRequiredFormFields, getScope, getScopeVersion, getServerClockOffsetMs, getServerClockSyncedAt, getSessionEntry, hasServerClock, initSession, initVfsRealtimeWs, initializeFsaos, initializeWorkspace, interpretSchema, invalidateAllVfs, invalidateChannelMessages, invalidateChildren, invalidateItem, invalidateOpenEnvelope, invalidatePathAndParent, invalidateSubtree, invalidateTypes, isAnchorReady, isChannelPath, isListableItemsFilter, isScopeReady, itemsFilterFromQueryFilter, listChildren, loadMounts, mount2 as mount, mountRealtimeScope, normalizeItem, onConnectionStateChange, pathSubscriptionMatches, ping, pushChanges, queryClient, readItem, refreshQuery, registerCleanup, replaceMounts, resetAllSdkState, resolvePrincipalId, resubscribePath, selectMount, serverDeadlinePassed, serverMsUntil, serverNow, setAnchor, setCachedToken, setQueryClient, setScope, setupRequireShim, signal, startTracking, steerTurn, submitForm, subscribeAnchor, subscribeArtifactStream, subscribeMounts, subscribeScope, subscribeToEvents, subscribeToPath, subscribeToScope, trackAction, trackEvent, trackPageView, unmountRealtimeScope, updateItem, uploadFile, useAccounts, useAgentTimeline, useAllChannels, useArrangement, useArtifactStream, useAsset, useAuth, useChannelMessages, useChannels, useChildren, useComponent, useCreate, useDelete, useDmChannels, useEdges, useEventStream, useFileUpload, useInfiniteChannelMessages, useInfiniteChildren, useInfiniteItems, useItem, useItemById, useItemHistory, useItemVersions, useItems, useLink, useList, useMemberFocus, useMintedAsset, useMounts, useMove, useMutation, useNotifications, useOpen, usePermission, usePermissions, usePersonalItemOrder, usePinnedItems, usePrincipal, useRealtimeQuery, useRecentActivity, useResolve, useResolvedItems, useScope, useScopeReady, useSearch, useTheme, useTimelineHistory, useTool, useTree, useType, useTypeHelpers, useTypes, useUnreadCounts, useUpdate, useUpdatePrincipal, vfsKeys, waitForPathReady };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map