om-memory-system 5.5.0 → 5.6.1

package/dist/services/spaces/registry-store.d.ts

@@ -30,3 +30,7 @@ export declare const unarchiveStoredSpace: (files: SpaceFiles, idOrName: string)
 export declare const switchStoredSpace: (files: SpaceFiles, idOrName: string) => Promise<SpaceRegistry>;
 export declare const removeStoredSpace: (files: SpaceFiles, idOrName: string) => Promise<SpaceRegistry>;
 export declare function renameStoredSpace(files: SpaceFiles, idOrName: string, name: string): Promise<SpaceRegistry>;
+/** Adds a link between two stored spaces under the lock (design D5). */
+export declare function linkStoredSpace(files: SpaceFiles, idOrName: string, targetIdOrName: string): Promise<SpaceRegistry>;
+/** Removes a link between two stored spaces under the lock (design D5). */
+export declare function unlinkStoredSpace(files: SpaceFiles, idOrName: string, targetIdOrName: string): Promise<SpaceRegistry>;

package/dist/services/spaces/registry-store.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
-import { SpaceError, archiveSpace, createSpace, readRegistryFile, removeSpace, renameSpace, switchSpace, unarchiveSpace, } from "./registry.js";
+import { SpaceError, archiveSpace, createSpace, linkSpace, readRegistryFile, removeSpace, renameSpace, switchSpace, unarchiveSpace, unlinkSpace, } from "./registry.js";
 /**
  * The one write path for `spaces.json` (design D5). The web server, the CLI and the
  * `memory` tool all change the registry through `updateRegistry`. Readers never lock.
@@ -132,3 +132,17 @@ export async function renameStoredSpace(files, idOrName, name) {
         result: 0,
     }))).registry;
 }
+/** Adds a link between two stored spaces under the lock (design D5). */
+export async function linkStoredSpace(files, idOrName, targetIdOrName) {
+    return (await updateRegistry(files, (registry) => ({
+        registry: linkSpace(registry, idOrName, targetIdOrName),
+        result: 0,
+    }))).registry;
+}
+/** Removes a link between two stored spaces under the lock (design D5). */
+export async function unlinkStoredSpace(files, idOrName, targetIdOrName) {
+    return (await updateRegistry(files, (registry) => ({
+        registry: unlinkSpace(registry, idOrName, targetIdOrName),
+        result: 0,
+    }))).registry;
+}

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

@@ -17,10 +17,14 @@ export interface SpaceEntry {
     archived: boolean;
     /** ISO 8601 time of the archive. Absent for a space archived before OMMS recorded it. */
     archivedAt?: string;
+    /** Ids of linked spaces (design D5). A link is one-way and read-only. */
+    links?: string[];
 }
 export interface SpaceRegistry {
     version: number;
     activeSpaceId: string;
+    /** Custom display name of the Default space. Absent means "Default". */
+    defaultName?: string;
     /** User-created spaces only. Default is added by `listSpaces`. */
     spaces: SpaceEntry[];
 }
@@ -56,6 +60,34 @@ export declare function unarchiveSpace(registry: SpaceRegistry, idOrName: string
 export declare function switchSpace(registry: SpaceRegistry, idOrName: string): SpaceRegistry;
 /** Removes an entry. The caller checks backup and folder removal (D8). */
 export declare function removeSpace(registry: SpaceRegistry, idOrName: string): SpaceRegistry;
+/**
+ * Adds a one-way link from one space to another (design D5). The linked space must
+ * exist, must not be the linking space itself and must not repeat. The link is
+ * stored on the linking space only, and the linked space's own links are not
+ * copied: the registry holds one level, and search follows no further.
+ *
+ * The Default space holds no links because it has no entry in `spaces.json`.
+ */
+export declare function linkSpace(registry: SpaceRegistry, idOrName: string, targetIdOrName: string): SpaceRegistry;
+/**
+ * Removes a link. The linked space may be gone from the registry, so its id is
+ * matched by id or name when it still exists and as a raw id otherwise. Removing
+ * a link deletes no memory and leaves every other link alone.
+ */
+export declare function unlinkSpace(registry: SpaceRegistry, idOrName: string, targetIdOrName: string): SpaceRegistry;
+export interface SpaceLinkInfo {
+    id: string;
+    /** The display name, or the id when the linked space is gone from the registry. */
+    name: string;
+    /** False when the linked space was deleted or archived. The link itself stays. */
+    available: boolean;
+}
+/**
+ * The links of a space with their availability, for the read paths (web layer, CLI
+ * listing). A link to a deleted or archived space stays in the registry and reads
+ * as unavailable here; search-time code skips it with a warning.
+ */
+export declare function spaceLinks(registry: SpaceRegistry, idOrName: string): SpaceLinkInfo[];
 /** The folder of a space. Refuses an id that is not safe, so a path cannot leave the spaces root. */
 export declare function resolveSpaceFolder(id: string, paths: SpacePaths): string;
 export interface RegistryReadResult {

package/dist/services/spaces/registry.js

@@ -24,12 +24,17 @@ export class SpaceError extends Error {
 export function emptyRegistry() {
     return { version: REGISTRY_VERSION, activeSpaceId: DEFAULT_SPACE_ID, spaces: [] };
 }
-function defaultEntry() {
-    return { id: DEFAULT_SPACE_ID, name: DEFAULT_SPACE_NAME, createdAt: "", archived: false };
+function defaultEntry(registry) {
+    return {
+        id: DEFAULT_SPACE_ID,
+        name: registry.defaultName ?? DEFAULT_SPACE_NAME,
+        createdAt: "",
+        archived: false,
+    };
 }
 /** Every space in display order: Default first, then user spaces in creation order. */
 export function listSpaces(registry) {
-    return [defaultEntry(), ...registry.spaces];
+    return [defaultEntry(registry), ...registry.spaces];
 }
 /** Lowercase letters, digits and single hyphens, at most 40 characters. Empty when the name has none. */
 export function spaceIdFromName(name) {
@@ -103,14 +108,19 @@ function updateSpace(registry, id, change) {
 }
 export function renameSpace(registry, idOrName, name) {
     const space = requireSpace(registry, idOrName);
-    if (space.id === DEFAULT_SPACE_ID) {
-        throw new SpaceError("protected", "The Default space cannot be renamed.");
-    }
     const display = checkedName(name);
     const clash = findByName(registry, display);
     if (clash && clash.id !== space.id) {
         throw new SpaceError("name-taken", `A space named "${clash.name}" already exists.`);
     }
+    if (space.id === DEFAULT_SPACE_ID) {
+        if (display.toLowerCase() === DEFAULT_SPACE_NAME.toLowerCase()) {
+            // "Default" means no custom name: the field is removed, not stored (design D2).
+            const { defaultName: _drop, ...rest } = registry;
+            return rest;
+        }
+        return { ...registry, defaultName: display };
+    }
     return updateSpace(registry, space.id, { name: display });
 }
 export function archiveSpace(registry, idOrName, now = new Date().toISOString()) {
@@ -148,6 +158,62 @@ export function removeSpace(registry, idOrName) {
     }
     return { ...registry, spaces: registry.spaces.filter((s) => s.id !== space.id) };
 }
+/**
+ * Adds a one-way link from one space to another (design D5). The linked space must
+ * exist, must not be the linking space itself and must not repeat. The link is
+ * stored on the linking space only, and the linked space's own links are not
+ * copied: the registry holds one level, and search follows no further.
+ *
+ * The Default space holds no links because it has no entry in `spaces.json`.
+ */
+export function linkSpace(registry, idOrName, targetIdOrName) {
+    const space = requireSpace(registry, idOrName);
+    if (space.id === DEFAULT_SPACE_ID) {
+        throw new SpaceError("protected", "The Default space cannot link other spaces.");
+    }
+    const target = requireSpace(registry, targetIdOrName);
+    if (target.id === space.id) {
+        // Code "protected" follows the "cannot do this to itself/Default" refusals.
+        throw new SpaceError("protected", `"${space.name}" cannot link to itself.`);
+    }
+    const links = space.links ?? [];
+    if (links.includes(target.id)) {
+        // Code "name-taken" is the duplicate refusal; a repeated link is the same conflict.
+        throw new SpaceError("name-taken", `"${space.name}" already links "${target.name}".`);
+    }
+    return updateSpace(registry, space.id, { links: [...links, target.id] });
+}
+/**
+ * Removes a link. The linked space may be gone from the registry, so its id is
+ * matched by id or name when it still exists and as a raw id otherwise. Removing
+ * a link deletes no memory and leaves every other link alone.
+ */
+export function unlinkSpace(registry, idOrName, targetIdOrName) {
+    const space = requireSpace(registry, idOrName);
+    if (space.id === DEFAULT_SPACE_ID) {
+        throw new SpaceError("protected", "The Default space cannot link other spaces.");
+    }
+    const target = findSpace(registry, targetIdOrName);
+    const linkedId = target ? target.id : targetIdOrName.trim();
+    const links = space.links ?? [];
+    if (!links.includes(linkedId)) {
+        throw new SpaceError("unknown", `"${space.name}" does not link "${targetIdOrName}".`);
+    }
+    const rest = links.filter((id) => id !== linkedId);
+    return updateSpace(registry, space.id, { links: rest.length > 0 ? rest : undefined });
+}
+/**
+ * The links of a space with their availability, for the read paths (web layer, CLI
+ * listing). A link to a deleted or archived space stays in the registry and reads
+ * as unavailable here; search-time code skips it with a warning.
+ */
+export function spaceLinks(registry, idOrName) {
+    const space = requireSpace(registry, idOrName);
+    return (space.links ?? []).map((id) => {
+        const target = findSpace(registry, id);
+        return { id, name: target?.name ?? id, available: target !== undefined && !target.archived };
+    });
+}
 /** The folder of a space. Refuses an id that is not safe, so a path cannot leave the spaces root. */
 export function resolveSpaceFolder(id, paths) {
     if (id === DEFAULT_SPACE_ID)
@@ -162,6 +228,9 @@ export function resolveSpaceFolder(id, paths) {
     }
     return join(paths.spacesRoot, id);
 }
+function isLinkIdList(value) {
+    return Array.isArray(value) && value.every((id) => typeof id === "string");
+}
 function parseEntry(raw) {
     if (typeof raw !== "object" || raw === null)
         return undefined;
@@ -173,7 +242,8 @@ function parseEntry(raw) {
         entry.name.trim() === "" ||
         typeof entry.createdAt !== "string" ||
         typeof entry.archived !== "boolean" ||
-        (entry.archivedAt !== undefined && typeof entry.archivedAt !== "string")) {
+        (entry.archivedAt !== undefined && typeof entry.archivedAt !== "string") ||
+        (entry.links !== undefined && !isLinkIdList(entry.links))) {
         return undefined;
     }
     return {
@@ -182,6 +252,7 @@ function parseEntry(raw) {
         createdAt: entry.createdAt,
         archived: entry.archived,
         ...(typeof entry.archivedAt === "string" ? { archivedAt: entry.archivedAt } : {}),
+        ...(isLinkIdList(entry.links) ? { links: entry.links } : {}),
     };
 }
 /**
@@ -219,6 +290,9 @@ export function readRegistryFile(path) {
         version: typeof file.version === "number" ? file.version : REGISTRY_VERSION,
         activeSpaceId: file.activeSpaceId,
         spaces,
+        ...(typeof file.defaultName === "string" && file.defaultName.trim() !== ""
+            ? { defaultName: file.defaultName }
+            : {}),
     };
     if (!listSpaces(registry).some((space) => space.id === registry.activeSpaceId)) {
         return unusable(`active space "${registry.activeSpaceId}" is not in the list`);

package/dist/services/spaces/space-store.d.ts

@@ -0,0 +1,50 @@
+import { TursoConnectionManager } from "../turso/connection-manager.js";
+import { TursoShardManager } from "../turso/shard-manager.js";
+import type { ShardInfo } from "../turso/types.js";
+import type { TursoDb } from "../turso/turso-db.js";
+export type SpaceStoreMode = "read" | "write";
+/** What both modes share: the folder, a private connection manager, and a close. */
+export interface SpaceStoreBase {
+    /** The space folder this store is bound to (design D1). */
+    readonly folder: string;
+    /** This store's own connections, allowed only inside `folder`. Closed by `close`. */
+    readonly connections: TursoConnectionManager;
+    /** Closes every connection this store opened. Call once, when the operation ends. */
+    close(): Promise<void>;
+}
+/**
+ * Write store (design D2): transfer targets, import targets and move sources.
+ * It creates shards on demand and takes the write and migration locks of `folder`,
+ * so it excludes a host that has the same space active.
+ */
+export interface SpaceWriteStore extends SpaceStoreBase {
+    readonly mode: "write";
+    /** Shard manager rooted at `folder`; its locks and migration check use the same root. */
+    readonly shards: TursoShardManager;
+}
+/**
+ * Read store (design D2): transfer copy sources, previews and linked searches.
+ * It opens only files that exist, sets `query_only`, creates no file, changes no
+ * schema and takes no lock. A missing metadata.db means an empty space.
+ */
+export interface SpaceReadStore extends SpaceStoreBase {
+    readonly mode: "read";
+    /** False when the folder holds no metadata.db: the space has no memories. */
+    readonly hasMetadata: boolean;
+    /**
+     * The registered shards of one scope. An empty `scopeHash` lists every hash of
+     * the scope, like `TursoShardManager.getAllShards`.
+     */
+    listShards(scope: "user" | "project", scopeHash: string): Promise<ShardInfo[]>;
+    /** Opens one shard database with `query_only` set. Refuses a file that is missing. */
+    openShard(dbPath: string): Promise<TursoDb>;
+}
+export type SpaceStore = SpaceWriteStore | SpaceReadStore;
+/**
+ * Opens a store bound to one space folder (design D1 and D2). The store shares no
+ * state with the active space: it brings its own connections, shard manager and
+ * locks, all rooted at `folder`. Write stores live for one operation and are closed
+ * in `finally`; read stores of linked spaces are cached (see read-store-cache.ts).
+ */
+export declare function openSpaceStore(folder: string, mode: "write"): SpaceWriteStore;
+export declare function openSpaceStore(folder: string, mode: "read"): SpaceReadStore;

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

@@ -0,0 +1,72 @@
+import { createClient } from "@libsql/client";
+import { existsSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { TursoConnectionManager } from "../turso/connection-manager.js";
+import { TursoShardManager } from "../turso/shard-manager.js";
+const METADATA_DB_NAME = "metadata.db";
+/** Read mode keeps a connection read-only, so pragmas match the host defaults plus this. */
+const READ_ONLY_PRAGMAS = [
+    "PRAGMA busy_timeout = 5000",
+    "PRAGMA foreign_keys = ON",
+    "PRAGMA query_only = ON",
+];
+/** Maps one metadata.db `shards` row onto a ShardInfo whose path is resolved at `folder`. */
+function rowToShardInfo(folder, row) {
+    const scope = String(row.scope);
+    return {
+        id: Number(row.id),
+        scope,
+        scopeHash: String(row.scope_hash),
+        shardIndex: Number(row.shard_index),
+        dbPath: resolve(join(folder, `${scope}s`, basename(String(row.db_path)))),
+        vectorCount: Number(row.vector_count),
+        isActive: Number(row.is_active) === 1,
+        createdAt: Number(row.created_at),
+    };
+}
+export function openSpaceStore(folder, mode) {
+    const root = resolve(folder);
+    const connections = new TursoConnectionManager(createClient, () => [root]);
+    if (mode === "write") {
+        const shards = new TursoShardManager({
+            root: () => root,
+            connections,
+        });
+        return {
+            mode,
+            folder: root,
+            connections,
+            shards,
+            close: () => connections.closeAll(),
+        };
+    }
+    // Read mode never calls the shard manager: its initialisation writes schema.
+    const hasMetadata = existsSync(join(root, METADATA_DB_NAME));
+    const openReadExisting = async (dbPath) => {
+        const db = await connections.getConnection(dbPath);
+        await db.setConnectionPragmas(READ_ONLY_PRAGMAS);
+        return db;
+    };
+    return {
+        mode,
+        folder: root,
+        connections,
+        hasMetadata,
+        listShards: async (scope, scopeHash) => {
+            if (!hasMetadata)
+                return [];
+            const db = await openReadExisting(join(root, METADATA_DB_NAME));
+            const rows = scopeHash === ""
+                ? await db.all(`SELECT * FROM shards WHERE scope = ? ORDER BY shard_index ASC`, [scope])
+                : await db.all(`SELECT * FROM shards WHERE scope = ? AND scope_hash = ? ORDER BY shard_index ASC`, [scope, scopeHash]);
+            return rows.map((row) => rowToShardInfo(root, row));
+        },
+        openShard: async (dbPath) => {
+            if (!existsSync(dbPath)) {
+                throw new Error(`Space shard file is missing: ${dbPath}`);
+            }
+            return openReadExisting(resolve(dbPath));
+        },
+        close: () => connections.closeAll(),
+    };
+}

package/dist/services/spaces/transfer-service.d.ts

@@ -0,0 +1,41 @@
+import { type SpacePaths } from "./registry.js";
+import type { SpaceFiles } from "./registry-store.js";
+import type { EmbeddingInfo, TransferApplyResult, TransferFilter, TransferMode, TransferPreview } from "./transfer-types.js";
+export type TransferRefusalCode = "unknown-space" | "same-space" | "archived-space" | "registry-problem";
+export interface TransferRefusal {
+    ok: false;
+    code: TransferRefusalCode;
+    error: string;
+}
+export type SpaceTransferPreviewOutcome = TransferRefusal | {
+    ok: true;
+    preview: TransferPreview;
+};
+export type SpaceTransferApplyOutcome = TransferRefusal | {
+    ok: true;
+    result: TransferApplyResult;
+};
+export interface SpaceTransferPreviewRequest {
+    from: string;
+    to: string;
+    filter: TransferFilter;
+}
+export interface SpaceTransferApplyRequest extends SpaceTransferPreviewRequest {
+    mode: TransferMode;
+    previewMatched?: number;
+}
+export interface SpaceTransferContext {
+    files: SpaceFiles;
+    paths: SpacePaths;
+    embedding: EmbeddingInfo;
+    maxVectorsPerShard: number;
+    embed?: (text: string) => Promise<Float32Array>;
+}
+/** Previews a transfer without changing either space: read stores, no locks. */
+export declare function previewSpaceTransfer(request: SpaceTransferPreviewRequest, context: SpaceTransferContext): Promise<SpaceTransferPreviewOutcome>;
+/**
+ * Runs a copy or a move. The target opens in write mode; the source opens in
+ * write mode only for a move. Engine failures land in `result.error`; the call
+ * throws only on an unexpected store failure, after logging its name.
+ */
+export declare function applySpaceTransfer(request: SpaceTransferApplyRequest, context: SpaceTransferContext): Promise<SpaceTransferApplyOutcome>;