om-memory-system 5.5.0 → 5.7.0-next.218

package/dist/services/spaces/import-space.js

@@ -0,0 +1,349 @@
+import { existsSync, readFileSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { extractScopeFromContainerTag } from "../memory-scope.js";
+import { getProjectTagInfo } from "../tags.js";
+import { tursoVectorSearch } from "../turso/vector-search.js";
+import { formatTagsForEmbedding } from "../turso/vector-utils.js";
+import { UserProfileManager } from "../user-profile/user-profile-manager.js";
+import { SPACE_EXPORT_SCHEMA_VERSION, SpaceExportDocumentSchema, } from "../../shared/api/space-export-schemas.js";
+import { createStoredSpace, removeStoredSpace } from "./registry-store.js";
+import { openSpaceStore } from "./space-store.js";
+/** The import size cap of the spec: a file larger than this is refused. */
+export const IMPORT_MAX_FILE_BYTES = 100 * 1024 * 1024;
+/** How many memories are embedded per round trip to the embedder. */
+const EMBED_BATCH_SIZE = 32;
+/** Matches `hasEnoughWorkflowSteps` in core/extraction.ts: three filled steps. */
+const MIN_WORKFLOW_STEPS = 3;
+function emptyCounts() {
+    return { projectMemories: 0, userMemories: 0, profileItems: 0, fileProjects: 0 };
+}
+function refusedImport(reason, warnings = []) {
+    return { ok: false, reason, counts: emptyCounts(), warnings };
+}
+/**
+ * The model and dimension warning of the spec: names the file's settings and
+ * the current ones, and never blocks. Undefined when both match.
+ */
+export function embeddingWarning(file, current) {
+    if (file.model === current.model && file.dimensions === current.dimensions)
+        return undefined;
+    return (`The file was embedded with ${file.model} at ${file.dimensions} dimensions; ` +
+        `this OMMS uses ${current.model} at ${current.dimensions}. ` +
+        `Import will embed every memory again with the current model.`);
+}
+function formatIssues(error) {
+    return error.issues
+        .slice(0, 5)
+        .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+        .join("; ");
+}
+/** How many profile items the manager will keep: a workflow needs three filled steps. */
+function keptProfileItems(document) {
+    const profile = document.profile;
+    if (!profile)
+        return 0;
+    const keptWorkflows = profile.workflows.filter((item) => (item.steps ?? []).filter((step) => step.trim().length > 0).length >= MIN_WORKFLOW_STEPS).length;
+    return profile.preferences.length + profile.patterns.length + keptWorkflows;
+}
+function countDocument(document) {
+    const projectTags = new Set();
+    let projectMemories = 0;
+    let userMemories = 0;
+    for (const memory of document.memories) {
+        if (memory.scope === "project") {
+            projectMemories++;
+            if (memory.projectTag)
+                projectTags.add(memory.projectTag);
+        }
+        else {
+            userMemories++;
+        }
+    }
+    return {
+        projectMemories,
+        userMemories,
+        profileItems: keptProfileItems(document),
+        fileProjects: projectTags.size,
+    };
+}
+/**
+ * Validates one parsed export document against the spec rules: the schema
+ * version, the schema itself, duplicate ids and the shape of every container
+ * tag. Pure, so the web check route can run it without creating a space.
+ */
+export function validateSpaceImportDocument(raw, embedding, userTag) {
+    if (raw === null || typeof raw !== "object") {
+        return { ok: false, reason: "The file is not a space export document." };
+    }
+    const envelope = raw;
+    if (typeof envelope.schemaVersion === "number" &&
+        envelope.schemaVersion > SPACE_EXPORT_SCHEMA_VERSION) {
+        return {
+            ok: false,
+            reason: `The file uses schema version ${envelope.schemaVersion}, which this OMMS does not know. ` +
+                `Upgrade OMMS, then import the file again.`,
+        };
+    }
+    const parsed = SpaceExportDocumentSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            reason: `The file does not match the space export schema: ${formatIssues(parsed.error)}`,
+        };
+    }
+    const document = parsed.data;
+    const ids = new Set();
+    for (const memory of document.memories) {
+        if (ids.has(memory.id)) {
+            return { ok: false, reason: `The file holds a duplicate memory id: ${memory.id}` };
+        }
+        ids.add(memory.id);
+    }
+    // Every container tag must give a scope and hash, or the write would fail
+    // after the space exists. Checked here, so a bad file creates no space.
+    const tags = new Set([userTag]);
+    for (const memory of document.memories) {
+        if (memory.scope === "project" && memory.projectTag)
+            tags.add(memory.projectTag);
+    }
+    for (const tag of tags) {
+        try {
+            extractScopeFromContainerTag(tag);
+        }
+        catch (error) {
+            return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    const counts = countDocument(document);
+    const warning = embeddingWarning(document.embedding, embedding);
+    return { ok: true, document, counts, ...(warning ? { warning } : {}) };
+}
+/** Reads and parses the export file: refused when missing, oversized or not JSON. */
+function readImportFile(filePath, maxFileBytes) {
+    let size;
+    try {
+        size = statSync(filePath).size;
+    }
+    catch {
+        return { ok: false, reason: `Cannot read the import file: ${filePath}` };
+    }
+    if (size > maxFileBytes) {
+        return {
+            ok: false,
+            reason: `The file is ${size} bytes, larger than the import limit of ${maxFileBytes} bytes.`,
+        };
+    }
+    try {
+        return { ok: true, raw: JSON.parse(readFileSync(filePath, "utf-8")) };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `The file is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+function requireDimensions(vector, dimensions, memoryId) {
+    if (vector.length !== dimensions) {
+        throw new Error(`The embedder returned ${vector.length} dimensions for memory ${memoryId}, ` +
+            `but the current settings use ${dimensions}.`);
+    }
+}
+/** Embeds every memory with the current model, in batches, then writes per scope. */
+async function writeImportedMemories(store, document, options, retagTag) {
+    const groups = new Map();
+    let projectMemories = 0;
+    let userMemories = 0;
+    for (const memory of document.memories) {
+        const containerTag = memory.scope === "user" ? options.user.userTag : (retagTag ?? memory.projectTag);
+        const { scope, hash } = extractScopeFromContainerTag(containerTag);
+        const group = groups.get(`${scope}:${hash}`) ?? [];
+        group.push({ memory, containerTag, scope, hash });
+        groups.set(`${scope}:${hash}`, group);
+        if (memory.scope === "project")
+            projectMemories++;
+        else
+            userMemories++;
+    }
+    // The file holds no vectors, so every memory is embedded again (design D7).
+    const vectors = new Map();
+    for (let start = 0; start < document.memories.length; start += EMBED_BATCH_SIZE) {
+        const batch = document.memories.slice(start, start + EMBED_BATCH_SIZE);
+        const embedded = await Promise.all(batch.map(async (memory) => {
+            const vector = await options.embed(memory.content);
+            requireDimensions(vector, options.embedding.dimensions, memory.id);
+            let tagsVector;
+            if (memory.tags && memory.tags.length > 0) {
+                tagsVector = await options.embed(formatTagsForEmbedding(memory.tags));
+                requireDimensions(tagsVector, options.embedding.dimensions, memory.id);
+            }
+            return { vector, ...(tagsVector ? { tagsVector } : {}) };
+        }));
+        batch.forEach((memory, index) => vectors.set(memory.id, embedded[index]));
+    }
+    for (const group of groups.values()) {
+        const { scope, hash } = group[0];
+        await store.shards.withScopeWriteLock(scope, hash, async () => {
+            const shard = await store.shards.getWriteShard(scope, hash);
+            const db = await store.connections.getConnection(shard.dbPath);
+            for (const item of group) {
+                const embedded = vectors.get(item.memory.id);
+                await tursoVectorSearch.insertVector(db, {
+                    id: item.memory.id,
+                    content: item.memory.content,
+                    vector: embedded.vector,
+                    ...(embedded.tagsVector ? { tagsVector: embedded.tagsVector } : {}),
+                    containerTag: item.containerTag,
+                    ...(item.memory.tags && item.memory.tags.length > 0
+                        ? { tags: item.memory.tags.join(",") }
+                        : {}),
+                    ...(item.memory.type ? { type: item.memory.type } : {}),
+                    createdAt: item.memory.createdAt,
+                    updatedAt: item.memory.updatedAt,
+                    ...(item.memory.metadata && Object.keys(item.memory.metadata).length > 0
+                        ? { metadata: JSON.stringify(item.memory.metadata) }
+                        : {}),
+                });
+                if (item.memory.isPinned) {
+                    await db.run(`UPDATE memories SET is_pinned = 1 WHERE id = ?`, [item.memory.id]);
+                }
+                await store.shards.incrementVectorCount(shard.id);
+            }
+        });
+    }
+    return { projectMemories, userMemories };
+}
+/** Maps one export item onto a preference or pattern; a missing category becomes "General". */
+function toProfileItem(item) {
+    return {
+        category: item.category?.trim() || "General",
+        description: item.description,
+        confidence: item.confidence,
+        frequency: item.frequency,
+        evidence: item.evidence,
+        lastSeen: item.lastSeen,
+        ...(item.firstSeen !== undefined ? { firstSeen: item.firstSeen } : {}),
+    };
+}
+/** Maps one export item onto a workflow; the manager drops too-short step lists. */
+function toWorkflow(item) {
+    return {
+        description: item.description,
+        steps: item.steps ?? [],
+        confidence: item.confidence,
+        frequency: item.frequency,
+        evidence: item.evidence,
+        lastSeen: item.lastSeen,
+        ...(item.firstSeen !== undefined ? { firstSeen: item.firstSeen } : {}),
+    };
+}
+/**
+ * Writes the file's profile through a manager rooted at the new folder, with
+ * the write store's connections, so one close releases every handle (design D1).
+ * Items keep every field the exporter kept; the manager drops workflows with
+ * too few steps, as it does on its own save path.
+ */
+async function writeImportedProfile(store, folder, document, user) {
+    const profile = document.profile;
+    if (!profile)
+        return 0;
+    const data = {
+        preferences: profile.preferences.map(toProfileItem),
+        patterns: profile.patterns.map(toProfileItem),
+        workflows: profile.workflows.map(toWorkflow),
+        ...(profile.learningPaths ? { learning_paths: profile.learningPaths } : {}),
+    };
+    const manager = new UserProfileManager(folder, store.connections);
+    const userId = user.userEmail || user.userName || user.userTag;
+    await manager.createProfile(userId, user.displayName || userId, user.userName || userId, user.userEmail || userId, data, profile.totalPromptsAnalyzed);
+    return data.preferences.length + data.patterns.length + data.workflows.length;
+}
+/**
+ * Removes a half-created import space. The registry entry goes first: it is the
+ * source of truth for which spaces exist, the new space was never active, and
+ * an orphan folder is inert, while a registry entry without a folder would read
+ * as a broken space. The caller has already closed the store, so no handle
+ * holds the folder (Windows-safe removal).
+ */
+async function removeFailedSpace(files, folder, spaceId, cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    try {
+        await removeStoredSpace(files, spaceId);
+        rmSync(folder, { recursive: true, force: true });
+    }
+    catch (cleanupError) {
+        const extra = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+        return (`Import failed: ${message}. Removing the new space failed too (${extra}). ` +
+            `Delete the space "${spaceId}" by hand.`);
+    }
+    return `Import failed and the new space "${spaceId}" was removed: ${message}`;
+}
+/**
+ * Imports one export file into a new, user-named space (design D7). Every
+ * refusal runs before any space exists; a failure after the space exists
+ * removes the space and its folder. The active space never changes.
+ */
+export async function importSpace(options) {
+    const maxFileBytes = options.maxFileBytes ?? IMPORT_MAX_FILE_BYTES;
+    let raw = options.document;
+    if (raw === undefined) {
+        if (!options.filePath) {
+            return refusedImport("No import file was given.");
+        }
+        const read = readImportFile(options.filePath, maxFileBytes);
+        if (!read.ok)
+            return refusedImport(read.reason);
+        raw = read.raw;
+    }
+    const validated = validateSpaceImportDocument(raw, options.embedding, options.user.userTag);
+    if (!validated.ok)
+        return refusedImport(validated.reason);
+    const warnings = [];
+    if (validated.warning)
+        warnings.push(validated.warning);
+    // The retag folder must exist before any space is created (spec).
+    let retagTag;
+    if (options.retagToProject !== undefined) {
+        if (!existsSync(options.retagToProject)) {
+            return refusedImport(`The project folder "${options.retagToProject}" does not exist, so no space was created.`);
+        }
+        retagTag = getProjectTagInfo(options.retagToProject).tag;
+    }
+    let entry;
+    try {
+        entry = await createStoredSpace(options.files, options.spaceName);
+    }
+    catch (error) {
+        return refusedImport(error instanceof Error ? error.message : String(error), warnings);
+    }
+    const folder = join(options.files.spacesRoot, entry.id);
+    const store = openSpaceStore(folder, "write");
+    try {
+        const written = await writeImportedMemories(store, validated.document, options, retagTag);
+        const profileItems = await writeImportedProfile(store, folder, validated.document, options.user);
+        if (retagTag && validated.counts.fileProjects > 1) {
+            warnings.push(`The ${validated.counts.fileProjects} projects in the file were merged onto one project tag.`);
+        }
+        if (written.projectMemories > 0 && !retagTag) {
+            warnings.push("Project tags are machine-local: a project-scope search finds these memories only " +
+                "under a matching project identity. An all-projects search always finds them.");
+        }
+        return {
+            ok: true,
+            spaceId: entry.id,
+            spaceName: entry.name,
+            folder,
+            counts: { ...written, profileItems, fileProjects: validated.counts.fileProjects },
+            warnings,
+        };
+    }
+    catch (error) {
+        // Release the handles first, then remove the space (see removeFailedSpace).
+        await store.close();
+        const reason = await removeFailedSpace(options.files, folder, entry.id, error);
+        return refusedImport(reason, warnings);
+    }
+    finally {
+        await store.close();
+    }
+}

package/dist/services/spaces/operations.d.ts

@@ -1,14 +1,62 @@
 import { type SpaceFiles } from "./registry-store.js";
+import type { SpaceTransferContext } from "./transfer-service.js";
+import type { ExportSpaceResult } from "./export-space.js";
+import type { ImportSpaceResult } from "./import-space.js";
 /**
- * The space operations an agent or a terminal may run: list, status, create, archive, unarchive
- * and use (switch). Delete, rename, backup and restore exist only in the web app (design D11),
- * because a person must confirm them. The CLI `space` command, the `memory` tool `space` mode
- * and the Claude Code plugin tool all call this one function, so the three hosts stay equal.
+ * The space operations an agent or a terminal may run: list, status, create, archive,
+ * unarchive, use (switch), preview, copy, link and unlink. Delete, rename, backup and
+ * restore exist only in the web app, because a person must confirm them, and so does a
+ * move; export and import belong to the web app and the CLI, not the `memory` tool. The
+ * CLI `space` command, the `memory` tool `space` mode and the Claude Code plugin tool
+ * all call this one function, so the hosts stay equal.
  */
 export interface SpaceOperationArgs {
     action?: string;
-    /** A space name or id. */
+    /** A space name or id: the space acted on, the transfer source, or the link target. */
     name?: string;
+    /** The transfer target (preview, copy): a space name or id. */
+    to?: string;
+    /** Inclusive ISO 8601 lower bound on the creation time (preview, copy, export). */
+    since?: string;
+    /** Inclusive ISO 8601 upper bound on the creation time (preview, copy, export). */
+    until?: string;
+    /** Only memories with this project tag, as a preview's groups show it (preview, copy). */
+    project?: string;
+    /** The space that owns the link (link, unlink); the active space when omitted. */
+    owner?: string;
+    /** Where the export file is written (export). */
+    outPath?: string;
+    /** The export file to read (import). */
+    filePath?: string;
+    /** Opt-in that adds the personal memories and the learned profile (export). */
+    includeProfile?: boolean;
+    /** Gives every imported project memory this folder's project tag (import). */
+    retagToProject?: string;
+}
+/** Folder roots and embedding settings the space-bound actions need, snapshotted by the caller. */
+export type SpaceOperationSettings = Omit<SpaceTransferContext, "files">;
+/** The export call the shared operation makes; the caller's bridge adds the CONFIG values. */
+export interface SpaceExportRequest {
+    folder: string;
+    outPath: string;
+    since?: number;
+    until?: number;
+    includeProfile?: boolean;
+}
+/** The import call the shared operation makes; the caller's bridge adds the CONFIG values. */
+export interface SpaceImportRequest {
+    filePath: string;
+    spaceName: string;
+    retagToProject?: string;
+}
+/**
+ * The export and import calls of a caller allowed to run them (the CLI). The `memory`
+ * tool passes no bridge, so its `space` mode refuses both actions; the CLI supplies
+ * one, so the operations are defined in this module once for every surface.
+ */
+export interface SpacePortability {
+    export: (request: SpaceExportRequest) => Promise<ExportSpaceResult>;
+    import: (request: SpaceImportRequest) => Promise<ImportSpaceResult>;
 }
 export interface SpaceOperationContext {
     files: SpaceFiles;
@@ -19,6 +67,10 @@ export interface SpaceOperationContext {
         customStoragePath: boolean;
         problem?: string;
     };
+    /** Needed by preview, copy and export; the caller snapshots it from CONFIG. */
+    settings?: SpaceOperationSettings;
+    /** The export and import bridge of a caller allowed to run them. */
+    portability?: SpacePortability;
 }
 /** Actions that need a person at the web app, so the CLI and the `memory` tool refuse them. */
 export declare const WEB_ONLY_SPACE_ACTIONS: string[];

package/dist/services/spaces/operations.js

@@ -1,10 +1,22 @@
-import { listSpaces, SpaceError, readRegistryFile } from "./registry.js";
-import { archiveStoredSpace, createStoredSpace, switchStoredSpace, unarchiveStoredSpace, } from "./registry-store.js";
+import { findSpace, listSpaces, readRegistryFile, resolveSpaceFolder, spaceLinks, SpaceError, } from "./registry.js";
+import { archiveStoredSpace, createStoredSpace, linkStoredSpace, switchStoredSpace, unarchiveStoredSpace, unlinkStoredSpace, } from "./registry-store.js";
 /** Actions that need a person at the web app, so the CLI and the `memory` tool refuse them. */
 export const WEB_ONLY_SPACE_ACTIONS = ["delete", "rename", "backup", "restore"];
-export const SPACE_ACTIONS = ["list", "status", "create", "archive", "unarchive", "use"];
+export const SPACE_ACTIONS = [
+    "list",
+    "status",
+    "create",
+    "archive",
+    "unarchive",
+    "use",
+    "preview",
+    "copy",
+    "link",
+    "unlink",
+];
 const WEB_ONLY = WEB_ONLY_SPACE_ACTIONS;
 const ACTIONS = SPACE_ACTIONS;
+const MOVE_REFUSAL = "Only the web app can move memories between spaces.";
 function summary(registry) {
     return listSpaces(registry).map((space) => ({
         id: space.id,
@@ -18,11 +30,145 @@ function activeOf(registry) {
     const active = listSpaces(registry).find((space) => space.id === registry.activeSpaceId);
     return { id: active.id, name: active.name };
 }
+/** An ISO 8601 date or date-time as epoch milliseconds, or the reason it is not one. */
+function epochMsOf(value, label) {
+    const ms = Date.parse(value.trim());
+    return Number.isNaN(ms) ? `The ${label} date "${value}" is not a valid ISO 8601 date.` : ms;
+}
+/** Runs a preview or a copy through the transfer service (design D3). A move never reaches here. */
+async function runTransfer(action, args, context, from, to) {
+    if (!context.settings) {
+        return {
+            success: false,
+            error: `The ${action} action needs the space settings; the caller did not supply them.`,
+        };
+    }
+    const since = args.since === undefined ? 0 : epochMsOf(args.since, "since");
+    if (typeof since === "string")
+        return { success: false, error: since };
+    const until = args.until === undefined ? Number.MAX_SAFE_INTEGER : epochMsOf(args.until, "until");
+    if (typeof until === "string")
+        return { success: false, error: until };
+    const project = args.project?.trim();
+    const filter = { since, until, ...(project ? { projectTag: project } : {}) };
+    const { previewSpaceTransfer, applySpaceTransfer } = await import("./transfer-service.js");
+    const transfer = { files: context.files, ...context.settings };
+    if (action === "preview") {
+        const outcome = await previewSpaceTransfer({ from, to, filter }, transfer);
+        if (!outcome.ok)
+            return { success: false, error: outcome.error };
+        return { success: true, preview: outcome.preview };
+    }
+    const outcome = await applySpaceTransfer({ from, to, filter, mode: "copy" }, transfer);
+    if (!outcome.ok)
+        return { success: false, error: outcome.error };
+    const result = outcome.result;
+    if (!result.ok) {
+        return {
+            success: false,
+            error: `The copy stopped at the ${result.error?.step ?? "write"} step: ${result.error?.message ?? "unknown failure"}`,
+            copied: result.copied,
+            skipped: result.skipped,
+        };
+    }
+    return {
+        success: true,
+        copied: result.copied,
+        skipped: result.skipped,
+        embeddedAgain: result.embeddedAgain,
+        message: `Copied ${result.copied} memories (${result.skipped} exact duplicates skipped).`,
+    };
+}
+/** Links or unlinks two stored spaces (design D5). The Default space owns no links. */
+async function runLink(action, args, context, target) {
+    const owner = args.owner?.trim() || context.current.name;
+    const change = action === "link" ? linkStoredSpace : unlinkStoredSpace;
+    const registry = await change(context.files, owner, target);
+    const ownerName = findSpace(registry, owner)?.name ?? owner;
+    const targetName = findSpace(registry, target)?.name ?? target;
+    return {
+        success: true,
+        message: action === "link"
+            ? `Space "${ownerName}" now links "${targetName}".`
+            : `Space "${ownerName}" no longer links "${targetName}".`,
+        links: spaceLinks(registry, ownerName),
+    };
+}
+/** Export and import: refused without a bridge (the `memory` tool), run through the CLI's one. */
+async function runPortabilityAction(action, args, context) {
+    const portability = context.portability;
+    if (!portability) {
+        return {
+            success: false,
+            error: `The memory tool cannot ${action} a space. Use the web app or the CLI.`,
+        };
+    }
+    if (action === "export") {
+        const name = args.name?.trim();
+        if (!name)
+            return { success: false, error: "The export action needs a space name." };
+        const outPath = args.outPath?.trim();
+        if (!outPath)
+            return { success: false, error: "The export action needs an output path." };
+        if (!context.settings) {
+            return {
+                success: false,
+                error: "The export action needs the space settings; the caller did not supply them.",
+            };
+        }
+        const since = args.since === undefined ? undefined : epochMsOf(args.since, "since");
+        if (typeof since === "string")
+            return { success: false, error: since };
+        const until = args.until === undefined ? undefined : epochMsOf(args.until, "until");
+        if (typeof until === "string")
+            return { success: false, error: until };
+        const read = readRegistryFile(context.files.registryPath);
+        const space = findSpace(read.registry, name);
+        if (!space)
+            return { success: false, error: `No space named "${name}".` };
+        const result = await portability.export({
+            folder: resolveSpaceFolder(space.id, context.settings.paths),
+            outPath,
+            ...(since === undefined ? {} : { since }),
+            ...(until === undefined ? {} : { until }),
+            ...(args.includeProfile ? { includeProfile: true } : {}),
+        });
+        return { success: true, export: result };
+    }
+    const filePath = args.filePath?.trim();
+    if (!filePath)
+        return { success: false, error: "The import action needs an export file." };
+    const spaceName = args.name?.trim();
+    if (!spaceName) {
+        return { success: false, error: "The import action needs a name for the new space." };
+    }
+    const retagToProject = args.retagToProject?.trim();
+    const result = await portability.import({
+        filePath,
+        spaceName,
+        ...(retagToProject ? { retagToProject } : {}),
+    });
+    if (!result.ok) {
+        return { success: false, error: result.reason, warnings: result.warnings };
+    }
+    const memories = result.counts.projectMemories + result.counts.userMemories;
+    return {
+        success: true,
+        message: `Imported ${memories} memories into the new space "${result.spaceName}".`,
+        import: { spaceId: result.spaceId, counts: result.counts, warnings: result.warnings },
+    };
+}
 export async function executeSpaceOperation(args, context) {
     const action = (args.action ?? "list").toLowerCase();
     if (WEB_ONLY.includes(action)) {
         return { success: false, error: `Only the web app can ${action} a space.` };
     }
+    if (action === "move") {
+        return { success: false, error: MOVE_REFUSAL };
+    }
+    if (action === "export" || action === "import") {
+        return runPortabilityAction(action, args, context);
+    }
     if (!ACTIONS.includes(action)) {
         return {
             success: false,
@@ -30,8 +176,12 @@ export async function executeSpaceOperation(args, context) {
         };
     }
     const name = args.name?.trim();
-    if (["create", "archive", "unarchive", "use"].includes(action) && !name) {
-        return { success: false, error: `The ${action} action needs a space name.` };
+    if (["create", "archive", "unarchive", "use", "preview", "copy", "link", "unlink"].includes(action)) {
+        if (!name)
+            return { success: false, error: `The ${action} action needs a space name.` };
+    }
+    if ((action === "preview" || action === "copy") && !args.to?.trim()) {
+        return { success: false, error: `The ${action} action needs a target space.` };
     }
     try {
         const read = readRegistryFile(context.files.registryPath);
@@ -59,6 +209,12 @@ export async function executeSpaceOperation(args, context) {
                 message: `Created space "${space.name}". Use the "use" action to make it active.`,
             };
         }
+        if (action === "preview" || action === "copy") {
+            return await runTransfer(action, args, context, name, args.to.trim());
+        }
+        if (action === "link" || action === "unlink") {
+            return await runLink(action, args, context, name);
+        }
         const change = {
             archive: archiveStoredSpace,
             unarchive: unarchiveStoredSpace,

package/dist/services/spaces/read-store-cache.d.ts

@@ -0,0 +1,13 @@
+import type { SpaceReadStore } from "./space-store.js";
+/**
+ * The process-wide cached read store of a space folder (design D2). A linked space
+ * is searched often and its folder rarely changes, so the store is opened once and
+ * reused. A reset (a space switch) or an explicit close drops it; the next call
+ * reopens the folder.
+ */
+export declare function getCachedSpaceReadStore(folder: string): SpaceReadStore;
+/** Closes and forgets the cached read store of one folder, for example before a delete. */
+export declare function closeCachedSpaceReadStore(folder: string): Promise<void>;
+/** Closes every cached read store. Registered with `resettable`, so a space switch runs it. */
+export declare function closeAllCachedSpaceReadStores(): Promise<void>;
+export declare const spaceReadStoreCache: Map<string, SpaceReadStore>;

package/dist/services/spaces/read-store-cache.js

@@ -0,0 +1,34 @@
+import { resolve } from "node:path";
+import { resettable } from "./store-handles.js";
+import { openSpaceStore } from "./space-store.js";
+const cache = new Map();
+/**
+ * The process-wide cached read store of a space folder (design D2). A linked space
+ * is searched often and its folder rarely changes, so the store is opened once and
+ * reused. A reset (a space switch) or an explicit close drops it; the next call
+ * reopens the folder.
+ */
+export function getCachedSpaceReadStore(folder) {
+    const key = resolve(folder);
+    let store = cache.get(key);
+    if (!store) {
+        store = openSpaceStore(key, "read");
+        cache.set(key, store);
+    }
+    return store;
+}
+/** Closes and forgets the cached read store of one folder, for example before a delete. */
+export async function closeCachedSpaceReadStore(folder) {
+    const key = resolve(folder);
+    const store = cache.get(key);
+    cache.delete(key);
+    if (store)
+        await store.close();
+}
+/** Closes every cached read store. Registered with `resettable`, so a space switch runs it. */
+export async function closeAllCachedSpaceReadStores() {
+    const stores = [...cache.values()];
+    cache.clear();
+    await Promise.all(stores.map((store) => store.close()));
+}
+export const spaceReadStoreCache = resettable("space-read-stores", cache, () => closeAllCachedSpaceReadStores());