@x12i/static-memorix-explorer-api 1.2.0 → 1.3.1

package/README.md

@@ -121,7 +121,9 @@ The mock server accepts the following identity keys across fetch/write engines:
 - `memoryId` — memory
 
 Endpoints like `/records/full` and `/records/content` require exactly one identity key
-per request. Memory collections are keyed by `memoryId` and stored in `./mocks/data/memory/memory.json`.
+per request. Memory collections are keyed by `memoryId`; the unprefixed
+`./mocks/data/memory/memory.json` is the seed and routed writes use the active
+Catalox-prefixed filename.
 
 ## Snapshot alias translation
 
@@ -184,7 +186,7 @@ Full implementation walkthrough: [guides/demo-app.md](./guides/demo-app.md).
 |-----|---------|-------|
 | `PORT` | `5030` | Listen port |
 | `HOST` | `0.0.0.0` | Listen host |
-| `MOCKS_DIR` | `<project>/mocks` | Fixture root |
+| `MOCKS_DIR` | bundled `<package>/mocks` | Fixture root |
 | `DISK_FLUSH_DEBOUNCE_MS` | `300` | Debounce before disk flush |
 | `MEMORIX_ORG_ID` | `memorix` | Organization prefix for DB routing |
 | `MEMORIX_AGENT_ID` | `default-agent` | Agent prefix for catalox DB routing |
@@ -193,6 +195,11 @@ Full implementation walkthrough: [guides/demo-app.md](./guides/demo-app.md).
 | `MEMORIX_EXPLORER_ENABLE_PIPELINE_WRITES` | `false` | Allow pipeline writes |
 | `MEMORIX_EXPLORER_ENABLE_REGISTRY_WRITES` | `false` | Allow registry writes |
 
+For mutation-capable installed deployments, set `MOCKS_DIR` to a writable,
+persistent directory. Routing configuration is process-scoped and resolved on
+first import; use one process per organization/agent context and one writer per
+prefix.
+
 ## DB Router Simulation
 
 The mock server does not connect to MongoDB, but it **tricks the frontend** into
@@ -207,6 +214,28 @@ These strings are derived from `MEMORIX_ORG_ID`, `MEMORIX_AGENT_ID`, and the
 `MEMORIX_DEPLOYMENT_PROFILE` (which, when set to `ebook`, forces both IDs to
 `ebooks`).
 
+### File-backed routing
+
+Those routed database names also select JSON files. The separator is `--`:
+
+```text
+mocks/data/product/neo-memorix-entities--snapshots.json
+mocks/data/product/neo-memorix-events--events.json
+mocks/data/memory/neo-agent-memorix-catalox--memory.json
+mocks/metadata/lists/neo-agent-memorix-catalox--my-plate.json
+```
+
+For `MEMORIX_ORG_ID=neo` and `MEMORIX_AGENT_ID=neo-agent`, entity-like
+collections use the first prefix, events use the second, and memory plus
+metadata use the Catalox prefix. If a routed file does not exist, the server
+loads its unprefixed counterpart as seed data, but all mutations are written
+to the routed filename. This provides database-style isolation without a
+database and preserves existing fixtures.
+
+The health response exposes the resolved values under `fileRouting`.
+See [guides/managing-json-files.md](./guides/managing-json-files.md) for the
+complete precedence and migration rules.
+
 ## Feature Flag Enforcement
 
 The mock server enforces the following feature-flag gates with error responses:
@@ -231,6 +260,8 @@ The mock's querying and writing engines now support `target=memory` and
 and `knowledgeId`.
 
 - Folder structure: `./mocks/data/memory/memory.json` (seeded with example memories).
+- Runtime memory writes persist to the active
+  `<agent>-memorix-catalox--memory.json` route.
 - Inventory engine accepts `target=memory` and includes memory collections in
   the simulated `inventorySummary`.
 - Records engine accepts `target=memory` and supports `memoryId` for fetching.
@@ -247,6 +278,25 @@ and `knowledgeId`.
 
 ## Release history
 
+### v1.3.1
+- Rejected unsafe routing IDs, object types, and metadata keys before path use.
+- Changed malformed and empty JSON handling from silent fallback to explicit
+  startup failure, preventing accidental data loss.
+- Made JSON persistence atomic through same-directory temporary-file renames.
+- Made list deletion restart-safe with routed tombstones.
+- Fixed installed npm CLI execution through symlink-aware entry detection.
+- Added packed-install, restart, traversal, corruption, and atomic-write checks.
+- Documented writable `MOCKS_DIR`, process isolation, and single-writer limits.
+
+### v1.3.0
+- Added database-routing parity through deterministic JSON filename prefixes.
+- Added separate entity, event, and Catalox/metadata prefix resolution.
+- Added migration-safe fallback from missing routed files to unprefixed seeds;
+  writes always persist to the selected routed file.
+- Added resolved `fileRouting` prefixes to the health response.
+- Updated metadata discovery to ignore other routed tenants.
+- Added routed persistence and prefix regression coverage.
+
 ### v1.2.0
 - Added native `--port` and `--host` CLI options.
 - Added the canonical `static-memorix-explorer-api` executable while retaining

package/dist/config.d.ts

@@ -5,6 +5,7 @@ export declare const DATA_DIR: string;
 export declare const PORT: number;
 export declare const HOST: string;
 export declare const DISK_FLUSH_DEBOUNCE_MS: number;
+export declare function validateRouteId(value: string, variableName?: string): string;
 export declare const MEMORIX_ORG_ID: string;
 export declare const MEMORIX_AGENT_ID: string;
 export declare const MEMORIX_DEPLOYMENT_PROFILE: string;
@@ -18,6 +19,14 @@ export declare function buildMemorixDbString(): string;
  * e.g. "ebooks-memorix-catalox"
  */
 export declare function buildCataloxDbString(): string;
+/**
+ * Files emulate routed databases by using the resolved database name as a
+ * prefix. The `--` separator is reserved for routing and must not be used in
+ * an unprefixed fixture basename.
+ */
+export declare function buildDataFilePrefix(contentType: string): string;
+export declare function buildMetadataFilePrefix(): string;
+export declare function prefixedJsonFilename(prefix: string, basename: string): string;
 export declare const FLAGS: {
     METADATA_WRITES: boolean;
     PIPELINE_WRITES: boolean;

package/dist/config.js

@@ -20,13 +20,23 @@ function resolveOrgId() {
     if ((process.env.MEMORIX_DEPLOYMENT_PROFILE || "").toLowerCase() === "ebook") {
         return "ebooks";
     }
-    return process.env.MEMORIX_ORG_ID || "memorix";
+    return validateRouteId(process.env.MEMORIX_ORG_ID || "memorix", "MEMORIX_ORG_ID");
 }
 function resolveAgentId() {
     if ((process.env.MEMORIX_DEPLOYMENT_PROFILE || "").toLowerCase() === "ebook") {
         return "ebooks";
     }
-    return process.env.MEMORIX_AGENT_ID || "default-agent";
+    return validateRouteId(process.env.MEMORIX_AGENT_ID || "default-agent", "MEMORIX_AGENT_ID");
+}
+export function validateRouteId(value, variableName = "route ID") {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) ||
+        value.includes("--") ||
+        value === "." ||
+        value === "..") {
+        throw Object.assign(new Error(`${variableName} must contain only letters, numbers, dot, underscore, or hyphen; ` +
+            `it must not contain path separators or the reserved "--" delimiter`), { statusCode: 400 });
+    }
+    return value;
 }
 export const MEMORIX_ORG_ID = resolveOrgId();
 export const MEMORIX_AGENT_ID = resolveAgentId();
@@ -46,6 +56,30 @@ export function buildMemorixDbString() {
 export function buildCataloxDbString() {
     return `${MEMORIX_AGENT_ID}-memorix-catalox`;
 }
+/**
+ * Files emulate routed databases by using the resolved database name as a
+ * prefix. The `--` separator is reserved for routing and must not be used in
+ * an unprefixed fixture basename.
+ */
+export function buildDataFilePrefix(contentType) {
+    if (contentType === "events")
+        return `${MEMORIX_ORG_ID}-memorix-events`;
+    if (contentType === "memory")
+        return buildCataloxDbString();
+    return `${MEMORIX_ORG_ID}-memorix-entities`;
+}
+export function buildMetadataFilePrefix() {
+    return buildCataloxDbString();
+}
+export function prefixedJsonFilename(prefix, basename) {
+    validateRouteId(prefix, "file routing prefix");
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(basename) || basename.includes("--")) {
+        throw Object.assign(new Error(`Unsafe JSON fixture basename: ${basename}`), {
+            statusCode: 400,
+        });
+    }
+    return `${prefix}--${basename}.json`;
+}
 // ---------------------------------------------------------------------------
 // Feature Flag Enforcement
 // ---------------------------------------------------------------------------

package/dist/engine/inventory.js

@@ -1,13 +1,13 @@
 import path from "node:path";
 import { store } from "../storage/InMemoryStore.js";
 import { CONTENT_TYPES } from "../types.js";
-import { listJsonFiles, basenameNoExt } from "../storage/fs.js";
-import { METADATA_DIR, DATA_DIR } from "../config.js";
+import { DATA_DIR } from "../config.js";
 import fs from "node:fs";
 import { isDir } from "../storage/fs.js";
 export function listObjectTypes() {
-    const dir = path.join(METADATA_DIR, "object-types");
-    return listJsonFiles(dir).map((f) => basenameNoExt(f));
+    return store.getMetaKeys()
+        .filter((key) => key.startsWith("object-types/"))
+        .map((key) => key.slice("object-types/".length));
 }
 export function listDataObjectTypes() {
     if (!isDir(DATA_DIR))

package/dist/engine/lists.d.ts

@@ -11,7 +11,7 @@ export declare function executeListDescriptor(desc: ListDescriptor, params?: Exp
 export declare function suggestListExtensions(entityName: string): {
     entityName: string;
     suggestions: {
-        contentType: "analysis" | "decisions" | "events" | "memory";
+        contentType: "events" | "memory" | "analysis" | "decisions";
         collection: string;
         suggestion: string;
     }[];

package/dist/engine/lists.js

@@ -1,14 +1,10 @@
-import path from "node:path";
 import { store } from "../storage/InMemoryStore.js";
 import { CONTENT_TYPES } from "../types.js";
-import { listJsonFiles, basenameNoExt } from "../storage/fs.js";
-import { METADATA_DIR } from "../config.js";
 import { queryMockCollection } from "../engine/query.js";
 export function listListDescriptors(entityName) {
-    const dir = path.join(METADATA_DIR, "lists");
     const out = [];
-    for (const file of listJsonFiles(dir)) {
-        const desc = store.getMeta(`lists/${basenameNoExt(file)}`);
+    for (const key of store.getMetaKeys().filter((item) => item.startsWith("lists/"))) {
+        const desc = store.getMeta(key);
         if (desc && (!entityName || desc.entity === entityName || desc.entityName === entityName)) {
             out.push(desc);
         }

package/dist/engine/narratives.js

@@ -1,10 +1,5 @@
-import path from "node:path";
 import { store } from "../storage/InMemoryStore.js";
 import { CONTENT_TYPES } from "../types.js";
-import { listJsonFiles, basenameNoExt, readJson } from "../storage/fs.js";
-import { METADATA_DIR } from "../config.js";
-import { isDir } from "../storage/fs.js";
-import fs from "node:fs";
 /**
  * Discover narrative keys tagged on records via doc.narratives.*.
  */
@@ -40,11 +35,10 @@ export function getMergedNarratives(entityName) {
         return mergeCatalogWithSignals(authored, recordTags);
     }
     // global across all entities
-    const dir = path.join(METADATA_DIR, "narratives");
     const out = {};
-    for (const file of listJsonFiles(dir)) {
-        const name = basenameNoExt(file);
-        const authored = readJson(file, {});
+    for (const metaKey of store.getMetaKeys().filter((key) => key.startsWith("narratives/"))) {
+        const name = metaKey.slice("narratives/".length);
+        const authored = store.getMeta(metaKey) || {};
         const recordTags = discoverRecordNarrativeTags(name);
         out[name] = mergeCatalogWithSignals(authored, recordTags);
     }
@@ -67,11 +61,7 @@ export function queryNarrativeRecords(entityName, key) {
     return results;
 }
 export function listNarrativeEntities() {
-    const dir = path.join(METADATA_DIR, "narratives");
-    if (!isDir(dir))
-        return [];
-    return fs
-        .readdirSync(dir)
-        .filter((f) => f.endsWith(".json"))
-        .map((f) => basenameNoExt(f));
+    return store.getMetaKeys()
+        .filter((key) => key.startsWith("narratives/"))
+        .map((key) => key.slice("narratives/".length));
 }

package/dist/engine/write.js

@@ -1,7 +1,4 @@
-import path from "node:path";
 import { store } from "../storage/InMemoryStore.js";
-import { basenameNoExt, listJsonFiles } from "../storage/fs.js";
-import { METADATA_DIR } from "../config.js";
 export function loadWriteDescriptor(writeDescriptorId) {
     const desc = store.getMeta(`write-descriptors/${writeDescriptorId}`);
     if (!desc) {
@@ -156,10 +153,9 @@ function getNextId(collection, idField = "recordId") {
     return () => String(counter++);
 }
 export function listWriteDescriptors() {
-    const dir = path.join(METADATA_DIR, "write-descriptors");
     const out = [];
-    for (const file of listJsonFiles(dir)) {
-        const desc = store.getMeta(`write-descriptors/${basenameNoExt(file)}`);
+    for (const key of store.getMetaKeys().filter((item) => item.startsWith("write-descriptors/"))) {
+        const desc = store.getMeta(key);
         if (desc)
             out.push(desc);
     }

package/dist/routes/index.js

@@ -1,5 +1,5 @@
 import { store } from "../storage/InMemoryStore.js";
-import { buildMemorixDbString, buildCataloxDbString, metadataWritesEnabled, } from "../config.js";
+import { buildMemorixDbString, buildCataloxDbString, buildDataFilePrefix, buildMetadataFilePrefix, metadataWritesEnabled, } from "../config.js";
 import { listObjectTypes } from "../engine/inventory.js";
 import { computeInventory, computeInventorySummary, computeInventoryIssues, computeGraph, } from "../engine/inventory.js";
 import { qp, str } from "./helpers.js";
@@ -25,6 +25,12 @@ export async function registerRoutes(app) {
             discoverySample: objectTypes,
             memorixDb: buildMemorixDbString(),
             cataloxDb: buildCataloxDbString(),
+            fileRouting: {
+                entitiesPrefix: buildDataFilePrefix("snapshots"),
+                eventsPrefix: buildDataFilePrefix("events"),
+                memoryPrefix: buildDataFilePrefix("memory"),
+                metadataPrefix: buildMetadataFilePrefix(),
+            },
         };
         if (includeInventory) {
             const rows = computeInventory({ sourceLens: "catalox-first" });
@@ -222,7 +228,8 @@ export async function registerRoutes(app) {
             return { ok: false, error: "Metadata writes are disabled" };
         }
         const { listId } = request.params;
-        store.setMeta(`lists/${listId}`, undefined, false);
+        store.deleteMeta(`lists/${listId}`);
+        await store.flushAll();
         return { ok: true, deleted: listId };
     });
     // ---------- F. Narratives Engine ----------

package/dist/server.d.ts

@@ -6,6 +6,7 @@ export interface StartServerOptions {
     installSignalHandlers?: boolean;
 }
 export declare function parseCliArgs(args: string[]): StartServerOptions;
+export declare function isCliEntrypoint(argvPath: string | undefined, moduleUrl: string): boolean;
 /** Build a loaded Fastify instance without opening a network port. */
 export declare function buildServer(options?: Pick<StartServerOptions, "logger">): Promise<import("fastify").FastifyInstance<import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>, import("http").IncomingMessage, import("http").ServerResponse<import("http").IncomingMessage>, import("fastify").FastifyBaseLogger, import("fastify").FastifyTypeProviderDefault>>;
 /** Build and listen. Options override PORT/HOST environment configuration. */

package/dist/server.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import Fastify from "fastify";
+import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { store } from "./storage/InMemoryStore.js";
@@ -31,6 +32,16 @@ export function parseCliArgs(args) {
     }
     return options;
 }
+export function isCliEntrypoint(argvPath, moduleUrl) {
+    if (!argvPath)
+        return false;
+    try {
+        return fs.realpathSync(path.resolve(argvPath)) === fileURLToPath(moduleUrl);
+    }
+    catch {
+        return false;
+    }
+}
 /** Build a loaded Fastify instance without opening a network port. */
 export async function buildServer(options = {}) {
     const app = Fastify({ logger: options.logger ?? false });
@@ -74,9 +85,7 @@ export async function startServer(options = {}) {
     }
     return app;
 }
-const isCliEntry = process.argv[1]
-    ? path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
-    : false;
+const isCliEntry = isCliEntrypoint(process.argv[1], import.meta.url);
 if (isCliEntry) {
     Promise.resolve().then(() => startServer(parseCliArgs(process.argv.slice(2)))).catch((err) => {
         // eslint-disable-next-line no-console

package/dist/storage/InMemoryStore.d.ts

@@ -12,6 +12,8 @@ export declare class InMemoryStore {
     private loadDataCollections;
     getMeta<T = any>(key: string): T | undefined;
     setMeta(key: string, data: any, persist?: boolean): void;
+    /** Persist a routed tombstone so an unprefixed seed does not reappear. */
+    deleteMeta(key: string): void;
     getMetaKeys(): string[];
     getCollection(objectType: string, ct: ContentType): any[];
     setCollection(objectType: string, ct: ContentType, data: any[]): void;

package/dist/storage/InMemoryStore.js

@@ -1,11 +1,28 @@
 import fs from "node:fs";
 import path from "node:path";
 import { CONTENT_TYPES } from "../types.js";
-import { MOCKS_DIR, METADATA_DIR, DATA_DIR } from "../config.js";
+import { MOCKS_DIR, METADATA_DIR, DATA_DIR, buildDataFilePrefix, buildMetadataFilePrefix, prefixedJsonFilename, validateRouteId, } from "../config.js";
 import { validateRecordArray } from "../engine/identity.js";
 import { isDir, listJsonFiles, readJson, writeJson, basenameNoExt, } from "./fs.js";
 import { DISK_FLUSH_DEBOUNCE_MS } from "../config.js";
 const DIRTY = Symbol("dirty");
+function routedMetadataPath(key) {
+    const parts = key.split("/");
+    if (parts.length === 1 && parts[0] === "agents") {
+        return path.join(METADATA_DIR, prefixedJsonFilename(buildMetadataFilePrefix(), "agents"));
+    }
+    if (parts.length !== 2) {
+        throw Object.assign(new Error(`Unsafe metadata key: ${key}`), { statusCode: 400 });
+    }
+    const [section, name] = parts;
+    if (!["object-types", "lists", "write-descriptors", "narratives"].includes(section)) {
+        throw Object.assign(new Error(`Unsupported metadata section: ${section}`), {
+            statusCode: 400,
+        });
+    }
+    validateRouteId(name, "metadata fixture name");
+    return path.join(METADATA_DIR, section, prefixedJsonFilename(buildMetadataFilePrefix(), name));
+}
 export class InMemoryStore {
     collections = new Map(); // key: `${objectType}/${contentType}`
     metadata = new Map();
@@ -28,18 +45,33 @@ export class InMemoryStore {
             "write-descriptors": "write-descriptors",
             narratives: "narratives",
         };
+        const prefix = buildMetadataFilePrefix();
         for (const [subdir] of Object.entries(sections)) {
             const dir = path.join(METADATA_DIR, subdir);
-            for (const file of listJsonFiles(dir)) {
-                const key = `${subdir}/${basenameNoExt(file)}`;
-                this.metadata.set(key, { path: file, data: readJson(file, {}) });
+            const files = listJsonFiles(dir);
+            const logicalNames = new Set();
+            for (const file of files) {
+                const name = basenameNoExt(file);
+                if (!name.includes("--"))
+                    logicalNames.add(name);
+                if (name.startsWith(`${prefix}--`))
+                    logicalNames.add(name.slice(prefix.length + 2));
+            }
+            for (const name of logicalNames) {
+                const baseFile = path.join(dir, `${name}.json`);
+                const routedFile = path.join(dir, prefixedJsonFilename(prefix, name));
+                const source = fs.existsSync(routedFile) ? routedFile : baseFile;
+                const key = `${subdir}/${name}`;
+                this.metadata.set(key, { path: routedFile, data: readJson(source, {}) });
             }
         }
-        const agentsFile = path.join(METADATA_DIR, "agents.json");
-        if (fs.existsSync(agentsFile)) {
+        const baseAgentsFile = path.join(METADATA_DIR, "agents.json");
+        const routedAgentsFile = path.join(METADATA_DIR, prefixedJsonFilename(prefix, "agents"));
+        const agentsSource = fs.existsSync(routedAgentsFile) ? routedAgentsFile : baseAgentsFile;
+        if (fs.existsSync(agentsSource)) {
             this.metadata.set("agents", {
-                path: agentsFile,
-                data: readJson(agentsFile, { agents: [] }),
+                path: routedAgentsFile,
+                data: readJson(agentsSource, { agents: [] }),
             });
         }
     }
@@ -51,9 +83,11 @@ export class InMemoryStore {
             if (!isDir(otDir))
                 continue;
             for (const ct of CONTENT_TYPES) {
-                const file = path.join(otDir, `${ct}.json`);
+                const baseFile = path.join(otDir, `${ct}.json`);
+                const file = path.join(otDir, prefixedJsonFilename(buildDataFilePrefix(ct), ct));
                 const key = `${objectType}/${ct}`;
-                const data = readJson(file, []);
+                const source = fs.existsSync(file) ? file : baseFile;
+                const data = readJson(source, []);
                 // Startup validation: ensure records carry exactly one identity key
                 // (MemorixRecordArraySchema mock). Memory collections use memoryId.
                 const result = validateRecordArray(objectType, ct, data);
@@ -68,11 +102,13 @@ export class InMemoryStore {
                 });
             }
             // system overrides
-            const invFile = path.join(DATA_DIR, "system", "inventory.json");
-            if (objectType === "system" && fs.existsSync(invFile)) {
+            const baseInvFile = path.join(DATA_DIR, "system", "inventory.json");
+            const invFile = path.join(DATA_DIR, "system", prefixedJsonFilename(buildDataFilePrefix("snapshots"), "inventory"));
+            const invSource = fs.existsSync(invFile) ? invFile : baseInvFile;
+            if (objectType === "system" && fs.existsSync(invSource)) {
                 this.collections.set("system/inventory", {
                     path: invFile,
-                    data: readJson(invFile, []),
+                    data: readJson(invSource, []),
                 });
             }
         }
@@ -89,7 +125,7 @@ export class InMemoryStore {
         }
         else {
             this.metadata.set(key, {
-                path: path.join(METADATA_DIR, `${key}.json`),
+                path: routedMetadataPath(key),
                 data,
                 [DIRTY]: true,
             });
@@ -97,16 +133,33 @@ export class InMemoryStore {
         if (persist)
             this.scheduleMetaFlush(key);
     }
+    /** Persist a routed tombstone so an unprefixed seed does not reappear. */
+    deleteMeta(key) {
+        const existing = this.metadata.get(key);
+        if (existing) {
+            existing.data = null;
+            existing[DIRTY] = true;
+        }
+        else {
+            this.metadata.set(key, {
+                path: routedMetadataPath(key),
+                data: null,
+                [DIRTY]: true,
+            });
+        }
+        this.scheduleMetaFlush(key);
+    }
     getMetaKeys() {
         return [...this.metadata.keys()];
     }
     // ---- Collection access ----
     getCollection(objectType, ct) {
+        validateRouteId(objectType, "object type");
         const key = `${objectType}/${ct}`;
         const c = this.collections.get(key);
         if (!c) {
             const newC = {
-                path: path.join(DATA_DIR, objectType, `${ct}.json`),
+                path: path.join(DATA_DIR, objectType, prefixedJsonFilename(buildDataFilePrefix(ct), ct)),
                 data: [],
             };
             this.collections.set(key, newC);
@@ -115,6 +168,7 @@ export class InMemoryStore {
         return c.data;
     }
     setCollection(objectType, ct, data) {
+        validateRouteId(objectType, "object type");
         const key = `${objectType}/${ct}`;
         const c = this.collections.get(key);
         if (c) {
@@ -123,7 +177,7 @@ export class InMemoryStore {
         }
         else {
             this.collections.set(key, {
-                path: path.join(DATA_DIR, objectType, `${ct}.json`),
+                path: path.join(DATA_DIR, objectType, prefixedJsonFilename(buildDataFilePrefix(ct), ct)),
                 data,
                 [DIRTY]: true,
             });

package/dist/storage/fs.js

@@ -15,16 +15,31 @@ export function readJson(p, fallback) {
     try {
         const raw = fs.readFileSync(p, "utf8");
         if (!raw.trim())
-            return fallback;
+            throw new Error("file is empty");
         return JSON.parse(raw);
     }
-    catch {
-        return fallback;
+    catch (error) {
+        if (error.code === "ENOENT")
+            return fallback;
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to read JSON fixture ${p}: ${message}`);
     }
 }
 export function writeJson(p, data) {
     ensureDir(path.dirname(p));
-    fs.writeFileSync(p, JSON.stringify(data, null, 2) + "\n", "utf8");
+    const serialized = JSON.stringify(data, null, 2);
+    if (serialized === undefined) {
+        throw new Error(`Cannot serialize undefined JSON fixture: ${p}`);
+    }
+    const temp = path.join(path.dirname(p), `.${path.basename(p)}.${process.pid}.tmp`);
+    try {
+        fs.writeFileSync(temp, serialized + "\n", "utf8");
+        fs.renameSync(temp, p);
+    }
+    finally {
+        if (fs.existsSync(temp))
+            fs.unlinkSync(temp);
+    }
 }
 export function listJsonFiles(dir) {
     if (!isDir(dir))

package/guides/demo-app.md

@@ -324,7 +324,9 @@ with fields for title, area, status, priority, and assignee. On submit:
    descriptor for the chosen area (`product-task-write`, etc.).
 3. The server validates the payload against the descriptor's JSON schema.
 4. On success, the record is appended to the in-memory collection and the
-   debounced flush writes it to `mocks/data/<area>/snapshots.json` within 300 ms.
+   flush writes it to
+   `mocks/data/<area>/<org>-memorix-entities--snapshots.json`. If that routed
+   file does not exist yet, the unprefixed `snapshots.json` is used as seed data.
 5. The UI unshifts the returned record into `state.tasks`, selects it, and
    re-renders.
 
@@ -385,8 +387,9 @@ scale. For higher volume you'd model comments as `events` records keyed by
 ## Why each area is a separate collection
 
 We could have put all tasks in one `tasks` collection with an `area` field.
-The demo deliberately splits them across `product/snapshots.json`,
-`marketing/snapshots.json`, and `admin/snapshots.json` to demonstrate:
+The demo deliberately splits the seed fixtures across `product/snapshots.json`,
+`marketing/snapshots.json`, and `admin/snapshots.json`; runtime mutations go to
+their routed, prefixed counterparts. This demonstrates:
 
 1. **Multi-entity applications** — typical real apps have more than one object
    type. Showing 3 object types is more representative than 1.

package/guides/managing-json-files.md

@@ -1,5 +1,79 @@
 # Managing JSON Files
 
+## File-backed database routing
+
+The static server has no database, so database routing is represented by a
+reserved filename prefix followed by `--`.
+
+With:
+
+```bash
+MEMORIX_ORG_ID=neo
+MEMORIX_AGENT_ID=neo-agent
+```
+
+the routing matrix is:
+
+| Data kind | Filename prefix | Example |
+| --- | --- | --- |
+| Snapshots, analysis, decisions | `neo-memorix-entities--` | `data/product/neo-memorix-entities--snapshots.json` |
+| Events | `neo-memorix-events--` | `data/product/neo-memorix-events--events.json` |
+| Memory | `neo-agent-memorix-catalox--` | `data/memory/neo-agent-memorix-catalox--memory.json` |
+| Metadata | `neo-agent-memorix-catalox--` | `metadata/lists/neo-agent-memorix-catalox--my-plate.json` |
+
+### Read and write precedence
+
+1. The server first looks for the routed, prefixed file.
+2. If it does not exist, it reads the matching unprefixed file as seed data.
+3. Any mutation writes the complete resulting collection to the routed file.
+4. Unprefixed seed files are never overwritten while routed mode is active.
+5. Files belonging to a different prefix are ignored by the active process.
+
+Deleting a metadata document writes JSON `null` as a routed tombstone. This is
+intentional: removing only the routed file would cause the unprefixed seed to
+reappear on the next restart.
+
+This makes onboarding migration-safe: existing files such as
+`product/snapshots.json` continue to seed a new tenant, while the first write
+creates `product/neo-memorix-entities--snapshots.json`. Starting with another
+organization ID selects a different file and therefore different state.
+
+The delimiter `--` is reserved. Do not use it inside ordinary, unprefixed
+fixture basenames.
+
+Routing IDs are validated before any files are opened. Organization IDs,
+agent IDs, object types, and metadata names may contain letters, numbers,
+dot, underscore, and hyphen, but cannot contain path separators, `..`, or the
+reserved `--` delimiter.
+
+Malformed or empty JSON stops startup with the affected path in the error;
+it is never silently converted to an empty collection. Writes use a temporary
+file and same-directory rename so readers never observe a partially written
+JSON document.
+
+Routing is process-scoped. Run one server process per organization/agent route,
+and use only one writer process for a given prefix. Two processes writing the
+same routed file concurrently use last-writer-wins semantics.
+
+### Inspect the active route
+
+```bash
+curl http://localhost:5030/api/explorer/health
+```
+
+The response includes:
+
+```json
+{
+  "fileRouting": {
+    "entitiesPrefix": "neo-memorix-entities",
+    "eventsPrefix": "neo-memorix-events",
+    "memoryPrefix": "neo-agent-memorix-catalox",
+    "metadataPrefix": "neo-agent-memorix-catalox"
+  }
+}
+```
+
 The mock server stores all state in JSON files under the `mocks/` directory. At
 startup, every file is loaded into an in-memory store. Mutations happen in
 memory and are debounced-flushed back to disk automatically.

package/guides/running-the-service.md

@@ -104,7 +104,19 @@ All configuration is via environment variables. Defaults work out of the box.
 | --------- | ----------- | ------------------------------ |
 | `PORT`    | `5030`      | HTTP listen port               |
 | `HOST`    | `0.0.0.0`   | HTTP listen host               |
-| `MOCKS_DIR` | `<project>/mocks` | Root directory for JSON fixtures |
+| `MOCKS_DIR` | bundled `<package>/mocks` | Root directory for JSON fixtures |
+
+`MOCKS_DIR` must be writable if you use mutation endpoints. For installed or
+containerized deployments, point it at a persistent application-owned volume
+rather than relying on the package's bundled seed directory:
+
+```bash
+MOCKS_DIR=/var/lib/my-app/memorix-mocks static-memorix-explorer-api --port 5030
+```
+
+Configuration is resolved when the package is imported. In programmatic usage,
+set `process.env.MOCKS_DIR`, `MEMORIX_ORG_ID`, and `MEMORIX_AGENT_ID` before the
+first dynamic import, and run separate processes for separate routing contexts.
 
 ### DB Router Simulation
 
@@ -121,6 +133,19 @@ correct tenant.
 The health endpoint returns:
 - `memorixDb`: `"<orgId>-memorix-entities + <orgId>-memorix-events"`
 - `cataloxDb`: `"<agentId>-memorix-catalox"`
+- `fileRouting`: the concrete entity, event, memory, and metadata filename
+  prefixes selected for this process
+
+These are functional routes, not display-only labels. For example:
+
+```bash
+MEMORIX_ORG_ID=neo MEMORIX_AGENT_ID=neo-agent npm start
+```
+
+selects filenames beginning with `neo-memorix-entities--`,
+`neo-memorix-events--`, and `neo-agent-memorix-catalox--`. See
+[managing-json-files.md](./managing-json-files.md#file-backed-database-routing)
+for exact examples and fallback behavior.
 
 ### Feature flags
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/static-memorix-explorer-api",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Static mock server providing full API parity for the Memorix Explorer API.",
   "type": "module",
   "main": "dist/server.js",