@x12i/static-memorix-explorer-api 1.3.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
@@ -253,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.
@@ -269,6 +278,16 @@ 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.

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;

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();
@@ -62,6 +72,12 @@ 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`;
 }
 // ---------------------------------------------------------------------------

package/dist/routes/index.js

@@ -228,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, buildDataFilePrefix, buildMetadataFilePrefix, prefixedJsonFilename, } 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();
@@ -108,7 +125,7 @@ export class InMemoryStore {
         }
         else {
             this.metadata.set(key, {
-                path: path.join(METADATA_DIR, `${path.dirname(key)}/${prefixedJsonFilename(buildMetadataFilePrefix(), path.basename(key))}`),
+                path: routedMetadataPath(key),
                 data,
                 [DIRTY]: true,
             });
@@ -116,11 +133,28 @@ 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) {
@@ -134,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) {

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

@@ -29,6 +29,10 @@ the routing matrix is:
 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
@@ -37,6 +41,20 @@ 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

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
 

package/package.json

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