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

package/README.md

@@ -207,6 +207,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:
@@ -247,6 +269,15 @@ and `knowledgeId`.
 
 ## Release history
 
+### 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

@@ -18,6 +18,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

@@ -46,6 +46,24 @@ 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) {
+    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" });

package/dist/storage/InMemoryStore.js

@@ -1,7 +1,7 @@
 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, } 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";
@@ -28,18 +28,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 +66,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 +85,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 +108,7 @@ export class InMemoryStore {
         }
         else {
             this.metadata.set(key, {
-                path: path.join(METADATA_DIR, `${key}.json`),
+                path: path.join(METADATA_DIR, `${path.dirname(key)}/${prefixedJsonFilename(buildMetadataFilePrefix(), path.basename(key))}`),
                 data,
                 [DIRTY]: true,
             });
@@ -106,7 +125,7 @@ export class InMemoryStore {
         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);
@@ -123,7 +142,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/guides/managing-json-files.md

@@ -1,5 +1,61 @@
 # 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.
+
+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.
+
+### 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

@@ -121,6 +121,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.0",
   "description": "Static mock server providing full API parity for the Memorix Explorer API.",
   "type": "module",
   "main": "dist/server.js",