@scalar/workspace-store 0.49.3 → 0.51.0

package/dist/persistence/index.js

@@ -3,18 +3,25 @@ import { createIndexDbConnection } from '../persistence/indexdb.js';
 import { v1InitialMigration } from '../persistence/migrations/v1-initial.js';
 import { v2TeamToLocalMigration } from '../persistence/migrations/v2-team-to-local.js';
 /**
- * Generates a workspace ID from team slug and workspace slug. Used as the key
- * in the per-workspace chunk tables (meta, documents, ...).
+ * Generates a fresh `workspaceUid` for new workspaces.
+ *
+ * Wraps `crypto.randomUUID` so every caller produces UIDs in a consistent
+ * shape and we can swap the implementation later without rippling through
+ * the codebase.
  */
-export const getWorkspaceId = (teamSlug, slug) => `${teamSlug}/${slug}`;
+export const generateWorkspaceUid = () => crypto.randomUUID();
 /**
  * Creates the persistence layer for the workspace store using IndexedDB.
- * This sets up all the required tables for storing workspace chunk information,
- * such as workspace meta, documents, original documents, intermediate documents, overrides, etc.
- * Each logical group (meta, documents, etc) gets its own table keyed appropriately for efficient sub-document access.
- * Returns an object containing `meta`, `documents`, `originalDocuments`, `intermediateDocuments`, `overrides`,
- * `documentMeta`, `documentConfigs`, and `workspace` sections, each exposing a `setItem` method
- * for upsetting records, and in the case of `workspace`, also `getItem` and `deleteItem`.
+ *
+ * Storage model:
+ * - `workspace` is the catalog. Its primary key is `workspaceUid`, a
+ *   stable UUID that does not change when the user (or the server)
+ *   renames the team or workspace slug. Two indexes back the runtime:
+ *     - `teamSlug_slug` (unique) for slug-based URL lookups.
+ *     - `teamUid` for team-scoped queries.
+ * - Every chunk table (`meta`, `documents`, ...) is keyed by
+ *   `workspaceUid` so chunks survive slug renames without ever being
+ *   re-keyed.
  */
 export const createWorkspaceStorePersistence = async () => {
     // The `tables` config below only describes the CURRENT shape for TypeScript
@@ -27,46 +34,49 @@ export const createWorkspaceStorePersistence = async () => {
         tables: {
             workspace: {
                 schema: Type.Object({
-                    /** Visual name for a given workspace */
-                    name: Type.String(),
-                    /** Slug of the team this workspace belongs to. Use 'local' for personal workspaces. */
+                    /** Stable UUID for the workspace; never changes after creation. */
+                    workspaceUid: Type.String(),
+                    /** UID of the team this workspace belongs to. Use 'local' for personal workspaces. */
+                    teamUid: Type.String({ default: 'local' }),
+                    /** Current team slug. Mutable metadata used to build URLs. */
                     teamSlug: Type.String({ default: 'local' }),
-                    /** Slug of the workspace, unique within the team. */
+                    /** Current workspace slug. Mutable metadata used to build URLs. */
                     slug: Type.String({ default: 'local' }),
+                    /** Visual name for a given workspace. */
+                    name: Type.String(),
                 }),
-                keyPath: ['teamSlug', 'slug'],
+                keyPath: ['workspaceUid'],
             },
             meta: {
-                schema: Type.Object({ workspaceId: Type.String(), data: Type.Any() }),
-                keyPath: ['workspaceId'],
+                schema: Type.Object({ workspaceUid: Type.String(), data: Type.Any() }),
+                keyPath: ['workspaceUid'],
             },
             documents: {
-                schema: Type.Object({ workspaceId: Type.String(), documentName: Type.String(), data: Type.Any() }),
-                keyPath: ['workspaceId', 'documentName'],
+                schema: Type.Object({ workspaceUid: Type.String(), documentName: Type.String(), data: Type.Any() }),
+                keyPath: ['workspaceUid', 'documentName'],
             },
             originalDocuments: {
-                schema: Type.Object({ workspaceId: Type.String(), documentName: Type.String(), data: Type.Any() }),
-                keyPath: ['workspaceId', 'documentName'],
+                schema: Type.Object({ workspaceUid: Type.String(), documentName: Type.String(), data: Type.Any() }),
+                keyPath: ['workspaceUid', 'documentName'],
             },
             intermediateDocuments: {
-                schema: Type.Object({ workspaceId: Type.String(), documentName: Type.String(), data: Type.Any() }),
-                keyPath: ['workspaceId', 'documentName'],
+                schema: Type.Object({ workspaceUid: Type.String(), documentName: Type.String(), data: Type.Any() }),
+                keyPath: ['workspaceUid', 'documentName'],
             },
             overrides: {
-                schema: Type.Object({ workspaceId: Type.String(), documentName: Type.String(), data: Type.Any() }),
-                keyPath: ['workspaceId', 'documentName'],
+                schema: Type.Object({ workspaceUid: Type.String(), documentName: Type.String(), data: Type.Any() }),
+                keyPath: ['workspaceUid', 'documentName'],
             },
             history: {
-                schema: Type.Object({ workspaceId: Type.String(), documentName: Type.String(), data: Type.Any() }),
-                keyPath: ['workspaceId', 'documentName'],
+                schema: Type.Object({ workspaceUid: Type.String(), documentName: Type.String(), data: Type.Any() }),
+                keyPath: ['workspaceUid', 'documentName'],
             },
             auth: {
-                schema: Type.Object({ workspaceId: Type.String(), documentName: Type.String(), data: Type.Any() }),
-                keyPath: ['workspaceId', 'documentName'],
+                schema: Type.Object({ workspaceUid: Type.String(), documentName: Type.String(), data: Type.Any() }),
+                keyPath: ['workspaceUid', 'documentName'],
             },
         },
     });
-    // Tables wrappers for each logical section.
     const workspaceTable = connection.get('workspace');
     const metaTable = connection.get('meta');
     const documentsTable = connection.get('documents');
@@ -75,208 +85,264 @@ export const createWorkspaceStorePersistence = async () => {
     const overridesTable = connection.get('overrides');
     const historyTable = connection.get('history');
     const authTable = connection.get('auth');
-    // The returned persistence API with logical sections for each table and mapping.
+    /**
+     * Resolves a workspace record by its `[teamSlug, slug]` pair using the
+     * unique secondary index. Returns `undefined` when no workspace matches.
+     *
+     * The compound index is unique, so at most one record is ever returned;
+     * we still go through `getRange` because the wrapper does not expose a
+     * single-key index lookup helper.
+     */
+    const findByTeamSlugAndSlug = async (teamSlug, slug) => {
+        const matches = await workspaceTable.getRange([teamSlug, slug], 'teamSlug_slug');
+        return matches[0];
+    };
+    /**
+     * Loads every chunk that belongs to a workspace and stitches them back
+     * into a single in-memory shape. Shared between `getItem` and
+     * `getItemBySlug` so both lookups produce identical output.
+     */
+    const assembleWorkspace = async (workspace) => {
+        const { workspaceUid } = workspace;
+        const [workspaceDocuments, workspaceOriginalDocuments, workspaceIntermediateDocuments, workspaceOverrides, workspaceMeta, workspaceHistory, workspaceAuth,] = await Promise.all([
+            documentsTable.getRange([workspaceUid]),
+            originalDocumentTable.getRange([workspaceUid]),
+            intermediateDocumentTable.getRange([workspaceUid]),
+            overridesTable.getRange([workspaceUid]),
+            metaTable.getItem({ workspaceUid }),
+            historyTable.getRange([workspaceUid]),
+            authTable.getRange([workspaceUid]),
+        ]);
+        return {
+            workspaceUid: workspace.workspaceUid,
+            teamUid: workspace.teamUid,
+            teamSlug: workspace.teamSlug,
+            slug: workspace.slug,
+            name: workspace.name,
+            workspace: {
+                documents: Object.fromEntries(workspaceDocuments.map((item) => [item.documentName, item.data])),
+                originalDocuments: Object.fromEntries(workspaceOriginalDocuments.map((item) => [item.documentName, item.data])),
+                intermediateDocuments: Object.fromEntries(workspaceIntermediateDocuments.map((item) => [item.documentName, item.data])),
+                overrides: Object.fromEntries(workspaceOverrides.map((item) => [item.documentName, item.data])),
+                meta: workspaceMeta?.data ?? {},
+                history: Object.fromEntries(workspaceHistory.map((item) => [item.documentName, item.data])),
+                auth: Object.fromEntries(workspaceAuth.map((item) => [item.documentName, item.data])),
+            },
+        };
+    };
     return {
         close: () => {
             connection.closeDatabase();
         },
         meta: {
             /**
-             * Set meta data for a workspace.
+             * Loads persisted workspace meta only (no document or other chunk
+             * reads). Returns an empty object when no meta row exists yet.
              */
-            setItem: async (workspaceId, data) => {
-                await metaTable.addItem({ workspaceId }, { data });
+            getItem: async (workspaceUid) => {
+                const row = await metaTable.getItem({ workspaceUid });
+                return (row?.data ?? {});
+            },
+            /** Set meta data for a workspace. */
+            setItem: async (workspaceUid, data) => {
+                await metaTable.addItem({ workspaceUid }, { data });
             },
         },
         documents: {
-            /**
-             * Set (persist) a workspace document using workspaceId and documentName as composite key.
-             */
-            setItem: async (workspaceId, documentName, data) => {
-                await documentsTable.addItem({ workspaceId, documentName }, { data });
+            /** Set (persist) a workspace document using workspaceUid and documentName as composite key. */
+            setItem: async (workspaceUid, documentName, data) => {
+                await documentsTable.addItem({ workspaceUid, documentName }, { data });
             },
         },
         originalDocuments: {
-            /**
-             * Set an original (raw) document for a workspace/document pair.
-             */
-            setItem: async (workspaceId, documentName, data) => {
-                await originalDocumentTable.addItem({ workspaceId, documentName }, { data });
+            /** Set an original (raw) document for a workspace/document pair. */
+            setItem: async (workspaceUid, documentName, data) => {
+                await originalDocumentTable.addItem({ workspaceUid, documentName }, { data });
             },
         },
         intermediateDocuments: {
-            /**
-             * Set an intermediate (transformed) document for a workspace/document pair.
-             */
-            setItem: async (workspaceId, documentName, data) => {
-                await intermediateDocumentTable.addItem({ workspaceId, documentName }, { data });
+            /** Set an intermediate (transformed) document for a workspace/document pair. */
+            setItem: async (workspaceUid, documentName, data) => {
+                await intermediateDocumentTable.addItem({ workspaceUid, documentName }, { data });
             },
         },
         overrides: {
-            /**
-             * Set document overrides for a workspace/document pair.
-             */
-            setItem: async (workspaceId, documentName, data) => {
-                await overridesTable.addItem({ workspaceId, documentName }, { data });
+            /** Set document overrides for a workspace/document pair. */
+            setItem: async (workspaceUid, documentName, data) => {
+                await overridesTable.addItem({ workspaceUid, documentName }, { data });
             },
         },
         history: {
-            /**
-             * Set history for a document.
-             */
-            setItem: async (workspaceId, documentName, data) => {
-                await historyTable.addItem({ workspaceId, documentName }, { data });
+            /** Set history for a document. */
+            setItem: async (workspaceUid, documentName, data) => {
+                await historyTable.addItem({ workspaceUid, documentName }, { data });
             },
         },
         auth: {
-            /**
-             * Set auth for a document.
-             */
-            setItem: async (workspaceId, documentName, data) => {
-                await authTable.addItem({ workspaceId, documentName }, { data });
+            /** Set auth for a document. */
+            setItem: async (workspaceUid, documentName, data) => {
+                await authTable.addItem({ workspaceUid, documentName }, { data });
             },
         },
         workspace: {
             /**
-             * Retrieves a workspace by its team + workspace slug.
-             * Returns undefined if the workspace does not exist.
-             * Gathers all workspace 'chunk' tables and assembles a full workspace shape.
+             * Retrieves a workspace by its stable UID, returning the full
+             * assembled state (chunks included). Returns `undefined` when no
+             * workspace matches.
+             *
+             * This is the primary lookup path because the UID never changes,
+             * making it safe to cache and reference across slug renames.
              */
-            getItem: async ({ teamSlug = 'local', slug, }) => {
-                const workspace = await workspaceTable.getItem({ teamSlug, slug });
+            getItem: async (workspaceUid) => {
+                const workspace = (await workspaceTable.getItem({ workspaceUid }));
                 if (!workspace) {
                     return undefined;
                 }
-                // Create a composite key for the workspace chunks.
-                const id = getWorkspaceId(teamSlug, slug);
-                // Retrieve all chunk records for this workspace.
-                const workspaceDocuments = await documentsTable.getRange([id]);
-                const workspaceOriginalDocuments = await originalDocumentTable.getRange([id]);
-                const workspaceIntermediateDocuments = await intermediateDocumentTable.getRange([id]);
-                const workspaceOverrides = await overridesTable.getRange([id]);
-                const workspaceMeta = await metaTable.getItem({ workspaceId: id });
-                const workspaceHistory = await historyTable.getRange([id]);
-                const workspaceAuth = await authTable.getRange([id]);
-                // Compose the workspace structure from table records.
-                return {
-                    name: workspace.name,
-                    teamSlug: workspace.teamSlug,
-                    slug: workspace.slug,
-                    workspace: {
-                        documents: Object.fromEntries(workspaceDocuments.map((item) => [item.documentName, item.data])),
-                        originalDocuments: Object.fromEntries(workspaceOriginalDocuments.map((item) => [item.documentName, item.data])),
-                        intermediateDocuments: Object.fromEntries(workspaceIntermediateDocuments.map((item) => [item.documentName, item.data])),
-                        overrides: Object.fromEntries(workspaceOverrides.map((item) => [item.documentName, item.data])),
-                        meta: workspaceMeta?.data,
-                        history: Object.fromEntries(workspaceHistory.map((item) => [item.documentName, item.data])),
-                        auth: Object.fromEntries(workspaceAuth.map((item) => [item.documentName, item.data])),
-                    },
-                };
+                return assembleWorkspace(workspace);
             },
             /**
-             * Retrieves all workspaces from the database.
-             * Returns only the workspace ID and name for each workspace.
-             * To get the full workspace data including documents and metadata, use getItem() with a specific ID.
-             * Returns an empty array if no workspaces exist.
+             * Retrieves a workspace by its mutable `[teamSlug, slug]` pair.
+             *
+             * Use this when the only thing you have is the URL — for example
+             * when the router needs to resolve `/@<teamSlug>/<workspaceSlug>`
+             * back to a workspace. For all other cases, prefer `getItem(uid)`
+             * because the slugs can change at any time.
+             */
+            getItemBySlug: async ({ teamSlug = 'local', slug, }) => {
+                const workspace = await findByTeamSlugAndSlug(teamSlug, slug);
+                if (!workspace) {
+                    return undefined;
+                }
+                return assembleWorkspace(workspace);
+            },
+            /**
+             * Retrieves all workspace catalog records.
+             *
+             * Only returns the workspace shell (`workspaceUid`, `teamUid`,
+             * `teamSlug`, `slug`, `name`). To get the full workspace data
+             * including documents and metadata, use `getItem(workspaceUid)`.
              */
             getAll: async () => {
-                return await workspaceTable.getAll();
+                return (await workspaceTable.getAll());
+            },
+            /**
+             * Retrieves all workspaces for a given team UID. Uses the `teamUid`
+             * index, so this is O(matches) rather than a full scan.
+             *
+             * Prefer this over `getAllByTeamSlug` because the team UID is the
+             * canonical identifier and survives team-slug renames.
+             */
+            getAllByTeamUid: async (teamUid) => {
+                return (await workspaceTable.getRange([teamUid], 'teamUid'));
             },
             /**
-             * Retrieves all workspaces for a given team slug. Uses the primary key
-             * prefix so no secondary index is required.
+             * Retrieves all workspaces for a given team slug. Uses the
+             * `teamSlug_slug` compound index as a prefix scan. Useful when the
+             * only thing on hand is the URL segment; otherwise prefer
+             * `getAllByTeamUid`.
              */
             getAllByTeamSlug: async (teamSlug) => {
-                return await workspaceTable.getRange([teamSlug]);
+                return (await workspaceTable.getRange([teamSlug], 'teamSlug_slug'));
             },
             /**
-             * Saves a workspace to the database.
-             * All chunks (meta, documents, configs, etc.) are upsert in their respective tables.
-             * If a workspace with the same ID already exists, it will be replaced.
+             * Saves a workspace and all of its chunks. The caller is responsible
+             * for providing a stable `workspaceUid` (typically `crypto.randomUUID()`
+             * for new records, or the existing UID for updates).
+             *
+             * `teamSlug` and `slug` are validated by the underlying unique index;
+             * attempting to persist a duplicate pair will reject the transaction.
              */
-            setItem: async ({ teamSlug = 'local', slug }, value) => {
-                const workspace = await workspaceTable.addItem({ teamSlug, slug }, {
-                    name: value.name,
-                });
-                const id = getWorkspaceId(teamSlug, slug);
-                // Save all meta info for workspace.
-                await metaTable.addItem({ workspaceId: id }, { data: value.workspace.meta });
-                // Persist all workspace documents (chunks).
-                await Promise.all(Object.entries(value.workspace.documents ?? {}).map(([name, data]) => {
-                    return documentsTable.addItem({ workspaceId: id, documentName: name }, { data });
-                }));
-                // Persist all original documents.
-                await Promise.all(Object.entries(value.workspace.originalDocuments ?? {}).map(([name, data]) => {
-                    return originalDocumentTable.addItem({ workspaceId: id, documentName: name }, { data });
-                }));
-                // Persist all intermediate documents.
-                await Promise.all(Object.entries(value.workspace.intermediateDocuments ?? {}).map(([name, data]) => {
-                    return intermediateDocumentTable.addItem({ workspaceId: id, documentName: name }, { data });
-                }));
-                // Persist all document overrides.
-                await Promise.all(Object.entries(value.workspace.overrides ?? {}).map(([name, data]) => {
-                    return overridesTable.addItem({ workspaceId: id, documentName: name }, { data });
-                }));
-                // Persist all history.
-                await Promise.all(Object.entries(value.workspace.history ?? {}).map(([name, data]) => {
-                    return historyTable.addItem({ workspaceId: id, documentName: name }, { data });
-                }));
-                // Persist all auth.
-                await Promise.all(Object.entries(value.workspace.auth ?? {}).map(([name, data]) => {
-                    return authTable.addItem({ workspaceId: id, documentName: name }, { data });
-                }));
+            setItem: async ({ workspaceUid, teamUid = 'local', teamSlug = 'local', slug, }, value) => {
+                const workspace = (await workspaceTable.addItem({ workspaceUid }, { teamUid, teamSlug, slug, name: value.name }));
+                await metaTable.addItem({ workspaceUid }, { data: value.workspace.meta });
+                await Promise.all([
+                    ...Object.entries(value.workspace.documents ?? {}).map(([name, data]) => documentsTable.addItem({ workspaceUid, documentName: name }, { data })),
+                    ...Object.entries(value.workspace.originalDocuments ?? {}).map(([name, data]) => originalDocumentTable.addItem({ workspaceUid, documentName: name }, { data })),
+                    ...Object.entries(value.workspace.intermediateDocuments ?? {}).map(([name, data]) => intermediateDocumentTable.addItem({ workspaceUid, documentName: name }, { data })),
+                    ...Object.entries(value.workspace.overrides ?? {}).map(([name, data]) => overridesTable.addItem({ workspaceUid, documentName: name }, { data })),
+                    ...Object.entries(value.workspace.history ?? {}).map(([name, data]) => historyTable.addItem({ workspaceUid, documentName: name }, { data })),
+                    ...Object.entries(value.workspace.auth ?? {}).map(([name, data]) => authTable.addItem({ workspaceUid, documentName: name }, { data })),
+                ]);
                 return workspace;
             },
             /**
-             * Deletes an entire workspace and all associated chunk records from all tables by ID.
+             * Deletes an entire workspace and every chunk that belongs to it.
+             * Safe to call on a workspace that does not exist — the chunk
+             * deletions are range scans that simply find nothing to delete.
              */
-            deleteItem: async ({ teamSlug = 'local', slug }) => {
-                const id = getWorkspaceId(teamSlug, slug);
-                await workspaceTable.deleteItem({ teamSlug, slug });
-                // Remove all workspace-related records from all chunk tables.
+            deleteItem: async (workspaceUid) => {
+                await workspaceTable.deleteItem({ workspaceUid });
                 await Promise.all([
-                    // By id
-                    metaTable.deleteItem({ workspaceId: id }),
-                    // By range (composite-key tables)
-                    documentsTable.deleteRange([id]),
-                    originalDocumentTable.deleteRange([id]),
-                    intermediateDocumentTable.deleteRange([id]),
-                    overridesTable.deleteRange([id]),
-                    historyTable.deleteRange([id]),
-                    authTable.deleteRange([id]),
+                    metaTable.deleteItem({ workspaceUid }),
+                    documentsTable.deleteRange([workspaceUid]),
+                    originalDocumentTable.deleteRange([workspaceUid]),
+                    intermediateDocumentTable.deleteRange([workspaceUid]),
+                    overridesTable.deleteRange([workspaceUid]),
+                    historyTable.deleteRange([workspaceUid]),
+                    authTable.deleteRange([workspaceUid]),
                 ]);
             },
             /**
-             * Deletes a single document and all related records (overrides, history, auth, etc.)
-             * for the given workspace and document name from all relevant tables.
+             * Deletes a single document and all related chunks (overrides,
+             * history, auth, ...) for the given workspace/document pair.
              */
-            deleteDocument: async (workspaceId, documentName) => {
+            deleteDocument: async (workspaceUid, documentName) => {
                 await Promise.all([
-                    documentsTable.deleteItem({ workspaceId, documentName }),
-                    intermediateDocumentTable.deleteItem({ workspaceId, documentName }),
-                    originalDocumentTable.deleteItem({ workspaceId, documentName }),
-                    overridesTable.deleteItem({ workspaceId, documentName }),
-                    historyTable.deleteItem({ workspaceId, documentName }),
-                    authTable.deleteItem({ workspaceId, documentName }),
+                    documentsTable.deleteItem({ workspaceUid, documentName }),
+                    intermediateDocumentTable.deleteItem({ workspaceUid, documentName }),
+                    originalDocumentTable.deleteItem({ workspaceUid, documentName }),
+                    overridesTable.deleteItem({ workspaceUid, documentName }),
+                    historyTable.deleteItem({ workspaceUid, documentName }),
+                    authTable.deleteItem({ workspaceUid, documentName }),
                 ]);
             },
             /**
-             * Updates the name of an existing workspace.
-             * Returns the updated workspace object, or undefined if the workspace does not exist.
+             * Updates the name of an existing workspace. Returns the updated
+             * record, or `undefined` when the workspace does not exist.
              */
-            updateName: async ({ teamSlug = 'local', slug }, name) => {
-                const workspace = await workspaceTable.getItem({ teamSlug, slug });
+            updateName: async (workspaceUid, name) => {
+                const workspace = (await workspaceTable.getItem({ workspaceUid }));
                 if (!workspace) {
                     return undefined;
                 }
-                // Update the workspace name
-                return await workspaceTable.addItem({ teamSlug, slug }, { ...workspace, name });
+                return (await workspaceTable.addItem({ workspaceUid }, { ...workspace, name }));
             },
             /**
-             * Checks if a workspace with the given team + workspace slug exists in the store.
+             * Updates the mutable slug metadata for an existing workspace.
+             * Returns the updated record, or `undefined` when the workspace
+             * does not exist, or when another workspace already owns the target
+             * `[teamSlug, slug]` pair (the `teamSlug_slug` index is unique).
+             *
+             * Use this when the server tells us a team slug or workspace slug
+             * has changed. The `workspaceUid` stays the same, so all chunk
+             * references continue to resolve.
              */
-            has: async ({ teamSlug = 'local', slug }) => {
-                return (await workspaceTable.getItem({ teamSlug, slug })) !== undefined;
+            updateSlugs: async (workspaceUid, slugs) => {
+                const workspace = (await workspaceTable.getItem({ workspaceUid }));
+                if (!workspace) {
+                    return undefined;
+                }
+                const nextTeamSlug = slugs.teamSlug ?? workspace.teamSlug;
+                const nextSlug = slugs.slug ?? workspace.slug;
+                if (nextTeamSlug !== workspace.teamSlug || nextSlug !== workspace.slug) {
+                    const occupant = await findByTeamSlugAndSlug(nextTeamSlug, nextSlug);
+                    if (occupant && occupant.workspaceUid !== workspaceUid) {
+                        return undefined;
+                    }
+                }
+                return (await workspaceTable.addItem({ workspaceUid }, {
+                    ...workspace,
+                    teamSlug: nextTeamSlug,
+                    slug: nextSlug,
+                }));
+            },
+            /** Checks if a workspace with the given UID exists. */
+            has: async (workspaceUid) => {
+                return (await workspaceTable.getItem({ workspaceUid })) !== undefined;
+            },
+            /** Checks if a workspace with the given `[teamSlug, slug]` pair exists. */
+            hasSlug: async ({ teamSlug = 'local', slug }) => {
+                return (await findByTeamSlugAndSlug(teamSlug, slug)) !== undefined;
             },
         },
         clear: async () => {

package/dist/persistence/migrations/v2-team-to-local.d.ts

@@ -1,25 +1,42 @@
 import type { Migration } from '../../persistence/indexdb.js';
 type WorkspaceRecordV1 = {
     name: string;
-    /** Old field — dropped entirely in v2. */
+    /** Team UID at the time of save. Often missing for personal workspaces. */
     teamUid?: string;
+    /** Team slug at the time of save. Doubled as the team identifier in v1. */
     namespace: string;
+    /** Workspace slug at the time of save. */
     slug: string;
 };
 type WorkspaceRecordV2 = {
-    name: string;
+    workspaceUid: string;
+    teamUid: string;
     teamSlug: string;
     slug: string;
+    name: string;
 };
 /**
  * Picks a slug that does not collide with anything in `taken`.
  * Falls back to `<slug>-2`, `<slug>-3`, ... when the desired slug is already used.
+ *
+ * Collapsing every legacy workspace into the local team can produce
+ * `[local, <slug>]` collisions whenever a team workspace shared a slug
+ * with an existing local workspace (or with another team workspace). The
+ * unique `[teamSlug, slug]` index would otherwise reject the upgrade, so
+ * this helper resolves collisions deterministically.
  */
 export declare const pickUniqueSlug: (desired: string, taken: ReadonlySet<string>) => string;
 /**
- * Computes the new shape for every workspace, preserving local entries under
- * their existing slug and relocating team entries into the local team with a
- * unique slug when needed.
+ * Computes the new shape for every workspace.
+ *
+ * Every record is collapsed into the local team: `teamUid` and `teamSlug`
+ * are both forced to `'local'`. Slug uniqueness is enforced by reserving
+ * the legacy local-team slugs first (they keep their slug verbatim), then
+ * placing every team workspace on top with a `-2`, `-3`, ... suffix when
+ * the desired slug is already taken.
+ *
+ * A fresh `workspaceUid` is generated for every record so the new
+ * identifier is stable across future slug renames.
  */
 export declare const planWorkspaceMigration: (workspaces: readonly WorkspaceRecordV1[]) => Array<{
     before: {

package/dist/persistence/migrations/v2-team-to-local.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v2-team-to-local.d.ts","sourceRoot":"","sources":["../../../src/persistence/migrations/v2-team-to-local.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AA2CtD,KAAK,iBAAiB,GAAG;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,KAAK,iBAAiB,GAAG;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,EAAE,OAAO,WAAW,CAAC,MAAM,CAAC,KAAG,MAU5E,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GACjC,YAAY,SAAS,iBAAiB,EAAE,KACvC,KAAK,CAAC;IAAE,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,CAqCjF,CAAA;AAqHD,eAAO,MAAM,sBAAsB,EAAE,SAqCpC,CAAA"}
+{"version":3,"file":"v2-team-to-local.d.ts","sourceRoot":"","sources":["../../../src/persistence/migrations/v2-team-to-local.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAoEtD,KAAK,iBAAiB,GAAG;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAA;IACjB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,KAAK,iBAAiB,GAAG;IACvB,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,EAAE,OAAO,WAAW,CAAC,MAAM,CAAC,KAAG,MAU5E,CAAA;AAcD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,GACjC,YAAY,SAAS,iBAAiB,EAAE,KACvC,KAAK,CAAC;IAAE,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,CAkCjF,CAAA;AAiDD,eAAO,MAAM,sBAAsB,EAAE,SA8GpC,CAAA"}