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

package/README.md

@@ -35,6 +35,12 @@ Installed CLI, using the default port `5030`:
 npx @x12i/static-memorix-explorer-api
 ```
 
+Or, after a global install:
+
+```bash
+static-memorix-explorer-api --port 5030 --host 127.0.0.1
+```
+
 Override the port from the shell:
 
 ```bash
@@ -201,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:
@@ -241,6 +269,24 @@ 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
+  `mock-memorix-explorer-api` as a compatibility alias.
+- Published TypeScript declarations for `buildServer()`, `startServer()`,
+  configuration exports, and server options.
+- Corrected the supported Node.js runtime to Node 20 or newer for Fastify 5.
+- Expanded CLI, programmatic, test, precedence, and lifecycle documentation.
+
 ### v1.1.1
 - Changed the default listen port from `4300` to `5030`.
 - Added safe programmatic APIs: `buildServer()` and `startServer(options)`.

package/dist/config.d.ts

@@ -0,0 +1,38 @@
+export declare const ROOT_DIR: string;
+export declare const MOCKS_DIR: string;
+export declare const METADATA_DIR: string;
+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 const MEMORIX_ORG_ID: string;
+export declare const MEMORIX_AGENT_ID: string;
+export declare const MEMORIX_DEPLOYMENT_PROFILE: string;
+/**
+ * Construct the router string the frontend expects.
+ * e.g. "neo-memorix-entities + neo-memorix-events" for MEMORIX_ORG_ID=neo
+ */
+export declare function buildMemorixDbString(): string;
+/**
+ * Construct the agent-scoped Catalox DB name.
+ * 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;
+    REGISTRY_WRITES: boolean;
+};
+export declare function metadataWritesEnabled(): boolean;
+export declare function pipelineWritesEnabled(): boolean;
+export declare function registryWritesEnabled(): boolean;
+export declare function metadataPath(...segments: string[]): string;
+export declare function dataPath(...segments: string[]): string;

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/aliases.d.ts

@@ -0,0 +1,32 @@
+import type { IncludeFlag } from "../types.js";
+/**
+ * Storage Alias Translation Map
+ * Client API key -> storage property / fallback.
+ */
+export interface AliasEntry {
+    clientKey: string;
+    storageProp: string;
+    fallbacks: string[];
+}
+export declare const STORAGE_ALIASES: Record<string, AliasEntry>;
+/**
+ * Resolve a normalized associated bucket from a raw document.
+ * Strips raw `associated*` fields and reconstructs the `associated` bucket
+ * using the alias map. Custom associated properties follow the pattern
+ * associated{Custom}.
+ */
+export declare function buildAssociatedBucket(rawDoc: Record<string, unknown>): {
+    associated: Record<string, unknown>;
+    strippedDoc: Record<string, unknown>;
+    properties: Array<{
+        propertyName: string;
+        source: string;
+        count: number;
+    }>;
+};
+export declare function aliasStorageToClient(storageKey: string): string;
+export declare function aliasClientToStorage(clientKey: string): {
+    primary: string;
+    fallbacks: string[];
+};
+export declare function resolveInclude(include?: string | string[]): Set<IncludeFlag> | null;

package/dist/engine/associations.d.ts

@@ -0,0 +1,26 @@
+export interface AssociationPlan {
+    objectType: string;
+    expectedPlanFingerprint: string;
+    proposedMutations: Array<{
+        recordId: string;
+        targetArray: string;
+        op: string;
+        count: number;
+    }>;
+}
+export declare function planAssociations(objectType?: string): AssociationPlan[];
+export interface ApplyResult {
+    objectType: string;
+    applied: boolean;
+    expectedPlanFingerprint: string;
+    actualFingerprint: string;
+    mismatch: boolean;
+    count: number;
+}
+export declare function applyAssociations(expectedPlanFingerprint: string, objectType?: string): ApplyResult[];
+export declare function verifyAssociations(expectedPlanFingerprint: string, objectType?: string): {
+    objectType: string;
+    expectedPlanFingerprint: string;
+    actualFingerprint: string;
+    verified: boolean;
+}[];

package/dist/engine/identity.d.ts

@@ -0,0 +1,22 @@
+import type { ContentType, IdentityKey } from "../types.js";
+/**
+ * Resolve the primary identity field for a given object type / content type.
+ * `memory` collections are keyed by `memoryId`; everything else falls back to
+ * the per-document heuristic used elsewhere.
+ */
+export declare function resolveIdField(ct: ContentType, sample?: any): IdentityKey;
+/**
+ * Mock of the production `MemorixRecordArraySchema`. Validates that each record
+ * in a collection array carries the collection's canonical identity key.
+ * Additional identity-shaped fields are allowed because they can represent
+ * relationships (for example a memory has `memoryId` and may reference an
+ * `entityId` or `eventId`).
+ */
+export declare function validateRecordArray(objectType: string, ct: ContentType, records: any[]): {
+    ok: boolean;
+    errors: string[];
+};
+/**
+ * Find a record by any of the supported identity keys.
+ */
+export declare function findByIdentity(records: any[], identity: Partial<Record<IdentityKey, string>>): any | undefined;

package/dist/engine/inventory.d.ts

@@ -0,0 +1,29 @@
+import { type ExplorerQueryParams } from "../types.js";
+export interface InventoryRow {
+    objectType: string;
+    contentType: string;
+    collection: string;
+    count: number;
+    status: "populated" | "empty" | "orphan";
+    provenance: {
+        source: "catalog" | "orphan";
+    };
+    missingCollections?: boolean;
+}
+export declare function listObjectTypes(): string[];
+export declare function listDataObjectTypes(): string[];
+export declare function computeInventory(params: ExplorerQueryParams): InventoryRow[];
+export declare function computeInventorySummary(rows: InventoryRow[], params: ExplorerQueryParams): Record<string, unknown>;
+export declare function computeInventoryIssues(rows: InventoryRow[]): InventoryRow[];
+export declare function computeGraph(rows: InventoryRow[]): {
+    nodes: {
+        id: string;
+        objectType: string;
+        populated: boolean;
+    }[];
+    edges: {
+        from: string;
+        to: string;
+        relationType?: string;
+    }[];
+};

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

@@ -0,0 +1,18 @@
+import { type ListDescriptor, type ExplorerQueryParams } from "../types.js";
+export declare function listListDescriptors(entityName?: string): ListDescriptor[];
+export declare function getListDescriptor(listId: string): ListDescriptor | undefined;
+/**
+ * Executes a list descriptor query pipeline against local data arrays.
+ */
+export declare function executeListDescriptor(desc: ListDescriptor, params?: ExplorerQueryParams): Promise<any>;
+/**
+ * Suggest extensions / analytics for unjoined content types.
+ */
+export declare function suggestListExtensions(entityName: string): {
+    entityName: string;
+    suggestions: {
+        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.d.ts

@@ -0,0 +1,16 @@
+import { type NarrativeDefinition } from "../types.js";
+/**
+ * Discover narrative keys tagged on records via doc.narratives.*.
+ */
+export declare function discoverRecordNarrativeTags(entityName: string): string[];
+export declare function mergeCatalogWithSignals(authored: Record<string, NarrativeDefinition>, recordTags: string[]): Array<NarrativeDefinition & {
+    signaled: boolean;
+}>;
+export declare function getMergedNarratives(entityName?: string): (NarrativeDefinition & {
+    signaled: boolean;
+})[] | Record<string, (NarrativeDefinition & {
+    signaled: boolean;
+})[]>;
+export declare function getRawNarratives(entityName: string): Record<string, NarrativeDefinition>;
+export declare function queryNarrativeRecords(entityName: string, key: string): any[];
+export declare function listNarrativeEntities(): string[];

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/objectTypes.d.ts

@@ -0,0 +1,11 @@
+export interface RootPropertyEntry {
+    path: string;
+    occurrencePct: number;
+    types: string[];
+    sampleValues: unknown[];
+}
+/**
+ * Full-scan all record arrays in ./data/{name}/*.json, compute property
+ * occurrence percentages, data types, and paths.
+ */
+export declare function computeRootPropertyCatalog(objectType: string): RootPropertyEntry[];

package/dist/engine/query.d.ts

@@ -0,0 +1,38 @@
+import type { ExplorerQueryParams } from "../types.js";
+export type FilterOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "nin" | "exists" | "regex";
+export interface ParsedFilter {
+    field: string;
+    op: FilterOp;
+    value: unknown;
+    raw: string;
+    isVirtual?: boolean;
+}
+export declare function parseFilterToken(token: string): ParsedFilter | null;
+export declare function coerce(value: string): unknown;
+/**
+ * Parse the filter param. Supports repeated values (array) and `;` separators.
+ * Returns virtual narrative filters separately so the caller can rewrite them.
+ */
+export declare function parseExplorerFilters(filter?: string | string[]): {
+    criteria: Record<string, unknown>;
+    virtual: ParsedFilter[];
+};
+export declare function parseSortParams(sort?: string | string[]): Record<string, 1 | -1>;
+/**
+ * Resolve virtual narrative filters into a predicate that checks
+ * doc.narratives[key] presence / truthiness.
+ */
+export declare function applyVirtualNarrativeFilters(records: any[], virtual: ParsedFilter[]): any[];
+export interface QueryResult {
+    rows: any[];
+    page: {
+        offset: number;
+        limit: number;
+        total?: number;
+    };
+}
+/**
+ * Execute a query against an in-memory record array using mingo, with
+ * full-text search, virtual narrative filters, sorting, and pagination.
+ */
+export declare function queryMockCollection(records: any[], queryParams: ExplorerQueryParams): QueryResult;

package/dist/engine/records.d.ts

@@ -0,0 +1,23 @@
+import { type ContentType, type ExplorerQueryParams, type IdentityKey } from "../types.js";
+export declare function inferIdField(entityName: string, ct: ContentType): string;
+/**
+ * Find a record within a collection using an identity map (recordId, entityId,
+ * eventId, knowledgeId, or memoryId). At least one identity key is required.
+ */
+export declare function findRecordByIdentity(entityName: string, ct: ContentType, identity: Partial<Record<IdentityKey, string>>): any | undefined;
+export declare function findRecord(entityName: string, ct: ContentType, recordId: string): any | undefined;
+export declare function getRecordsCollection(params: ExplorerQueryParams): Promise<{
+    rows: any[];
+    page: any;
+}>;
+export declare function getRecordsFull(entityName: string, recordId: string): any;
+export declare function getRecordsItem(entityName: string, recordId: string, itemDescriptor?: any): any;
+/**
+ * Fetch a single content record by id. Supports the memory tier via memoryId.
+ * If entityName is empty and contentType is "memory", defaults to "memory".
+ * Otherwise, searches across all object types in the store.
+ */
+export declare function getRecordContent(entityName: string, contentType: ContentType, identity: Partial<Record<IdentityKey, string>>): any | undefined;
+export declare function getRawCollection(entityName: string, collectionName: string): any[];
+export declare function getRawItem(collectionName: string, recordId: string): any | undefined;
+export declare function getWorkspaceRecords(params: ExplorerQueryParams): Promise<any>;

package/dist/engine/snapshots.d.ts

@@ -0,0 +1,17 @@
+export declare function getSnapshotRaw(objectType: string, recordId: string): {
+    rawDoc: any;
+    idField: string;
+} | undefined;
+export declare function getSnapshotNormalized(objectType: string, recordId: string, include?: string | string[]): any | undefined;
+export declare function getSnapshotAssociated(objectType: string, recordId: string): any | undefined;
+export declare function getSnapshotAssociatedProperty(objectType: string, recordId: string, propertyName: string): any | undefined;
+export declare function getAssociatedProperties(objectType: string): Array<{
+    propertyName: string;
+    source: string;
+    count: number;
+}>;
+/**
+ * Deterministic fingerprint for association plan/apply/verify.
+ */
+export declare function computeAssociationFingerprint(objectType: string): string;
+export declare function hashString(s: string): string;

package/dist/engine/write.d.ts

@@ -0,0 +1,30 @@
+import type { ContentType, WriteDescriptor } from "../types.js";
+export type WriteOperation = "add" | "upsert" | "patch" | "replace" | "delete";
+export declare function loadWriteDescriptor(writeDescriptorId: string): WriteDescriptor;
+export interface ValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+/**
+ * Validate input against the write descriptor schema (lightweight AJV-free check).
+ *
+ * `operation` controls how `required` is enforced:
+ *   - `add` / `replace`: every field in `schema.required` must be present.
+ *   - `upsert` / `patch` / `delete`: only the collection's identity field
+ *     (e.g. `recordId`, `memoryId`) is required; other `required` entries are
+ *     ignored because partial updates are allowed.
+ *
+ * Type checks on whatever fields ARE present always run.
+ */
+export declare function validateInputSchema(writeSpec: WriteDescriptor, input: any, operation?: WriteOperation): ValidationResult;
+export declare function parseTargetCollection(target: string): {
+    objectType: string;
+    ct: ContentType;
+};
+export declare function executeOperation(params: {
+    target: string;
+    op: WriteOperation;
+    data: any;
+    persist?: boolean;
+}): any[];
+export declare function listWriteDescriptors(): WriteDescriptor[];

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/helpers.d.ts

@@ -0,0 +1,4 @@
+import type { FastifyRequest } from "fastify";
+import type { ExplorerQueryParams } from "../types.js";
+export declare function qp(request: FastifyRequest): ExplorerQueryParams;
+export declare function str(v: unknown, fallback?: string): string;

package/dist/routes/index.d.ts

@@ -0,0 +1,2 @@
+import type { FastifyInstance } from "fastify";
+export declare function registerRoutes(app: FastifyInstance): Promise<void>;

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/server.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+export interface StartServerOptions {
+    port?: number;
+    host?: string;
+    logger?: boolean;
+    installSignalHandlers?: boolean;
+}
+export declare function parseCliArgs(args: string[]): StartServerOptions;
+/** 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. */
+export declare function startServer(options?: StartServerOptions): 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>>;

package/dist/server.js

@@ -5,6 +5,32 @@ import { fileURLToPath } from "node:url";
 import { store } from "./storage/InMemoryStore.js";
 import { registerRoutes } from "./routes/index.js";
 import { PORT, HOST, MOCKS_DIR } from "./config.js";
+export function parseCliArgs(args) {
+    const options = {};
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--port") {
+            const raw = args[++index];
+            const port = Number(raw);
+            if (!raw || !Number.isInteger(port) || port < 0 || port > 65535) {
+                throw Object.assign(new Error("--port must be an integer from 0 to 65535"), {
+                    statusCode: 400,
+                });
+            }
+            options.port = port;
+        }
+        else if (arg === "--host") {
+            const host = args[++index];
+            if (!host)
+                throw Object.assign(new Error("--host requires a value"), { statusCode: 400 });
+            options.host = host;
+        }
+        else {
+            throw Object.assign(new Error(`Unknown CLI argument: ${arg}`), { statusCode: 400 });
+        }
+    }
+    return options;
+}
 /** Build a loaded Fastify instance without opening a network port. */
 export async function buildServer(options = {}) {
     const app = Fastify({ logger: options.logger ?? false });
@@ -31,8 +57,10 @@ export async function startServer(options = {}) {
     const port = options.port ?? PORT;
     const host = options.host ?? HOST;
     await app.listen({ port, host });
+    const address = app.server.address();
+    const boundPort = typeof address === "object" && address ? address.port : port;
     // eslint-disable-next-line no-console
-    console.log(`[mock-memorix-explorer-api] listening on ${host}:${port}`);
+    console.log(`[mock-memorix-explorer-api] listening on ${host}:${boundPort}`);
     console.log(`[mock-memorix-explorer-api] mocks dir: ${MOCKS_DIR}`);
     if (options.installSignalHandlers ?? true) {
         const shutdown = async () => {
@@ -50,7 +78,7 @@ const isCliEntry = process.argv[1]
     ? path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
     : false;
 if (isCliEntry) {
-    startServer().catch((err) => {
+    Promise.resolve().then(() => startServer(parseCliArgs(process.argv.slice(2)))).catch((err) => {
         // eslint-disable-next-line no-console
         console.error(err);
         process.exit(1);

package/dist/storage/InMemoryStore.d.ts

@@ -0,0 +1,29 @@
+import { type ContentType } from "../types.js";
+export declare class InMemoryStore {
+    private collections;
+    private metadata;
+    private flushTimers;
+    private loaded;
+    /**
+     * Load everything from disk into memory. Idempotent.
+     */
+    load(): Promise<void>;
+    private loadMetadataCatalog;
+    private loadDataCollections;
+    getMeta<T = any>(key: string): T | undefined;
+    setMeta(key: string, data: any, persist?: boolean): void;
+    getMetaKeys(): string[];
+    getCollection(objectType: string, ct: ContentType): any[];
+    setCollection(objectType: string, ct: ContentType, data: any[]): void;
+    getCollectionKeys(): string[];
+    private scheduleCollectionFlush;
+    private scheduleMetaFlush;
+    flushCollectionNow(key: string): void;
+    flushMetaNow(key: string): void;
+    /**
+     * Flush every dirty file immediately and clear timers.
+     */
+    flushAll(): Promise<void>;
+    get mocksDir(): string;
+}
+export declare const store: InMemoryStore;

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/dist/storage/fs.d.ts

@@ -0,0 +1,6 @@
+export declare function ensureDir(dir: string): void;
+export declare function isDir(p: string): boolean;
+export declare function readJson<T = any>(p: string, fallback: T): T;
+export declare function writeJson(p: string, data: unknown): void;
+export declare function listJsonFiles(dir: string): string[];
+export declare function basenameNoExt(p: string): string;

package/dist/types.d.ts

@@ -0,0 +1,88 @@
+export type ContentType = "snapshots" | "analysis" | "decisions" | "events" | "memory";
+export declare const CONTENT_TYPES: ContentType[];
+/**
+ * The fourth tier of data alongside entities, events, and knowledge.
+ * `memory` collections are keyed by `memoryId`.
+ */
+export declare const MEMORY_CONTENT_TYPE: ContentType;
+/** Primary identity keys accepted across fetch/write engines. */
+export declare const IDENTITY_KEYS: readonly ["recordId", "entityId", "eventId", "knowledgeId", "memoryId"];
+export type IdentityKey = (typeof IDENTITY_KEYS)[number];
+/** Map a target type to its canonical id field. */
+export declare const TARGET_TO_ID_FIELD: Record<string, IdentityKey>;
+export declare const INCLUDE_FLAGS: readonly ["data", "analytics", "enrichment", "insights", "system", "associated", "discovery", "analysis"];
+export type IncludeFlag = (typeof INCLUDE_FLAGS)[number];
+export interface ExplorerQueryParams {
+    filter?: string | string[];
+    sort?: string | string[];
+    searchText?: string;
+    q?: string;
+    limit?: string | number;
+    offset?: string | number;
+    skip?: string | number;
+    includeTotal?: boolean;
+    include?: string | string[];
+    contentType?: string;
+    mode?: "descriptor" | "raw" | "auto";
+    listId?: string;
+    entityName?: string;
+    sourceLens?: "db-first" | "catalox-first";
+    target?: "entity" | "event" | "knowledge" | "memory" | string;
+    includeExactCounts?: boolean;
+    includeInventory?: boolean | string;
+    memoryId?: string;
+    recordId?: string;
+    entityId?: string;
+    eventId?: string;
+    knowledgeId?: string;
+}
+export interface CatalogRelation {
+    sourceProperty?: string;
+    targetObject?: string;
+    targetProperty?: string;
+    relationType?: string;
+}
+export interface ObjectTypeMeta {
+    name: string;
+    summary?: string;
+    rootPropertyCatalog?: RootPropertyCatalogEntry[];
+    catalogRelations?: CatalogRelation[];
+    [key: string]: unknown;
+}
+export interface RootPropertyCatalogEntry {
+    path: string;
+    occurrencePct?: number;
+    types?: string[];
+    sampleValues?: unknown[];
+    [key: string]: unknown;
+}
+export interface ListDescriptor {
+    id?: string;
+    listId?: string;
+    entity?: string;
+    entityName?: string;
+    fields?: string[];
+    projections?: Record<string, unknown>;
+    extensions?: string[];
+    sort?: Record<string, 1 | -1>;
+    query?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface WriteDescriptor {
+    writeDescriptorId?: string;
+    id?: string;
+    targetCollection?: string;
+    schema?: unknown;
+    [key: string]: unknown;
+}
+export interface NarrativeDefinition {
+    key: string;
+    label?: string;
+    description?: string;
+    [key: string]: unknown;
+}
+export interface AgentEntry {
+    id?: string;
+    name?: string;
+    [key: string]: unknown;
+}

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

@@ -13,6 +13,8 @@ npm install -g @x12i/static-memorix-explorer-api
 ```
 
 This makes the `mock-memorix-explorer-api` command available globally.
+The preferred command name is `static-memorix-explorer-api`; the older
+`mock-memorix-explorer-api` name remains as a compatibility alias.
 
 ### From source (git clone)
 
@@ -43,7 +45,7 @@ iteration, but not suitable for distribution.
 ### As a global CLI
 
 ```bash
-mock-memorix-explorer-api
+static-memorix-explorer-api
 ```
 
 After `npm install -g`, the CLI starts the server with default settings. The
@@ -55,6 +57,14 @@ mocks directory defaults to a `mocks/` folder relative to the installed package.
 npx @x12i/static-memorix-explorer-api
 ```
 
+Choose a port with a CLI option or environment variable. CLI options take
+precedence:
+
+```bash
+static-memorix-explorer-api --port 5030 --host 127.0.0.1
+PORT=5030 HOST=127.0.0.1 static-memorix-explorer-api
+```
+
 ### From application code
 
 Importing the package does not open a port. Call `startServer()` explicitly:
@@ -111,11 +121,25 @@ 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
 
-Mutations (POST/PATCH/PUT/DELETE) on lists, narratives, and records are gated
-behind feature flags. All default to `false`.
+Metadata mutations on lists and narratives are gated behind feature flags.
+Record mutations are governed by write descriptors and are available by
+default.
 
 | Variable                                    | Controls              |
 | ------------------------------------------- | --------------------- |

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "@x12i/static-memorix-explorer-api",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Static mock server providing full API parity for the Memorix Explorer API.",
   "type": "module",
   "main": "dist/server.js",
   "exports": {
     ".": {
+      "types": "./dist/server.d.ts",
       "import": "./dist/server.js"
     },
     "./config": {
+      "types": "./dist/config.d.ts",
       "import": "./dist/config.js"
     }
   },
   "bin": {
+    "static-memorix-explorer-api": "dist/server.js",
     "mock-memorix-explorer-api": "dist/server.js"
   },
   "scripts": {
@@ -59,6 +62,6 @@
     "static"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   }
 }