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

package/README.md

@@ -13,20 +13,63 @@ See [guides/demo-app.md](./guides/demo-app.md) for the full walkthrough.
 ```bash
 npm install
 npm run build
-npm start                 # listens on :4300 (PORT / HOST / MOCKS_DIR env-overridable)
+npm start                 # listens on :5030 (PORT / HOST / MOCKS_DIR env-overridable)
 # dev (no build): npm run dev
 
 # open the demo UI in your browser
-open http://localhost:4300/demo
+open http://localhost:5030/demo
 ```
 
 Health:
 
 ```bash
-curl localhost:4300/health
-curl "localhost:4300/api/explorer/health?includeInventory=1"
+curl localhost:5030/health
+curl "localhost:5030/api/explorer/health?includeInventory=1"
 ```
 
+## Run from CLI or code
+
+Installed CLI, using the default port `5030`:
+
+```bash
+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
+PORT=8080 npx @x12i/static-memorix-explorer-api
+```
+
+Start it programmatically (explicit options take precedence over environment
+defaults):
+
+```js
+import { startServer } from "@x12i/static-memorix-explorer-api";
+
+const app = await startServer({ port: 5030, host: "127.0.0.1" });
+// await app.close();
+```
+
+For code-level tests without binding a port:
+
+```js
+import { buildServer } from "@x12i/static-memorix-explorer-api";
+
+const app = await buildServer();
+const response = await app.inject({ method: "GET", url: "/health" });
+await app.close();
+```
+
+See [guides/running-the-service.md](./guides/running-the-service.md) for all
+CLI, environment, lifecycle, and programmatic examples.
+
 ## Architecture
 
 ```
@@ -139,7 +182,7 @@ Full implementation walkthrough: [guides/demo-app.md](./guides/demo-app.md).
 
 | Var | Default | Notes |
 |-----|---------|-------|
-| `PORT` | `4300` | Listen port |
+| `PORT` | `5030` | Listen port |
 | `HOST` | `0.0.0.0` | Listen host |
 | `MOCKS_DIR` | `<project>/mocks` | Fixture root |
 | `DISK_FLUSH_DEBOUNCE_MS` | `300` | Debounce before disk flush |
@@ -204,6 +247,21 @@ and `knowledgeId`.
 
 ## Release history
 
+### 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)`.
+- Importing the package no longer starts a listener as a side effect.
+- Added CLI, environment override, programmatic startup, and injected-test examples.
+
 ### v1.1.0
 - **Added**: `delete` operation to the write engine
   (`POST /records/write` body `operation:"delete"`).

package/dist/config.d.ts

@@ -0,0 +1,30 @@
+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;
+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

@@ -8,7 +8,7 @@ export const MOCKS_DIR = process.env.MOCKS_DIR
     : path.resolve(ROOT_DIR, "..", "mocks");
 export const METADATA_DIR = path.join(MOCKS_DIR, "metadata");
 export const DATA_DIR = path.join(MOCKS_DIR, "data");
-export const PORT = Number(process.env.PORT || 4300);
+export const PORT = Number(process.env.PORT || 5030);
 export const HOST = process.env.HOST || "0.0.0.0";
 export const DISK_FLUSH_DEBOUNCE_MS = Number(process.env.DISK_FLUSH_DEBOUNCE_MS || 300);
 // ---------------------------------------------------------------------------

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/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: "analysis" | "decisions" | "events" | "memory";
+        collection: string;
+        suggestion: string;
+    }[];
+};

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/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/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/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

@@ -1,10 +1,39 @@
 #!/usr/bin/env node
 import Fastify from "fastify";
+import path from "node:path";
+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";
-async function main() {
-    const app = Fastify({ logger: false });
+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 });
     // Global error handler matching predictable error shapes.
     app.setErrorHandler((error, _request, reply) => {
         const normalized = error instanceof Error
@@ -20,22 +49,38 @@ async function main() {
     });
     await store.load();
     await registerRoutes(app);
-    const port = Number(process.env.PORT || PORT);
-    await app.listen({ port, host: HOST });
+    return app;
+}
+/** Build and listen. Options override PORT/HOST environment configuration. */
+export async function startServer(options = {}) {
+    const app = await buildServer(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}`);
-    const shutdown = async () => {
-        console.log("\n[mock-memorix-explorer-api] flushing + shutting down");
-        await store.flushAll();
-        await app.close();
-        process.exit(0);
-    };
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
+    if (options.installSignalHandlers ?? true) {
+        const shutdown = async () => {
+            console.log("\n[mock-memorix-explorer-api] flushing + shutting down");
+            await store.flushAll();
+            await app.close();
+            process.exit(0);
+        };
+        process.once("SIGINT", shutdown);
+        process.once("SIGTERM", shutdown);
+    }
+    return app;
+}
+const isCliEntry = process.argv[1]
+    ? path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+    : false;
+if (isCliEntry) {
+    Promise.resolve().then(() => startServer(parseCliArgs(process.argv.slice(2)))).catch((err) => {
+        // eslint-disable-next-line no-console
+        console.error(err);
+        process.exit(1);
+    });
 }
-main().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/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/demo-app.md

@@ -17,7 +17,7 @@ calls.
 ```bash
 npm run build
 npm start
-# open http://localhost:4300/demo
+# open http://localhost:5030/demo
 ```
 
 Every mutation you make in the UI is persisted back to `mocks/data/**/*.json`
@@ -454,23 +454,23 @@ A 30-second smoke test, runnable from the repo root:
 npm run build && npm start &
 
 # 2. Read
-curl -s "localhost:4300/api/explorer/records/collection?entityName=users&limit=10"
+curl -s "localhost:5030/api/explorer/records/collection?entityName=users&limit=10"
 
 # 3. Create
-curl -s -X POST localhost:4300/api/explorer/records/write \
+curl -s -X POST localhost:5030/api/explorer/records/write \
   -H "Content-Type: application/json" \
   -d '{"writeDescriptorId":"product-task-write","operation":"add","input":{"recordId":"t-smoke-1","title":"Smoke","area":"product","status":"todo","priority":"normal"}}'
 
 # 4. Update (partial)
-curl -s -X POST localhost:4300/api/explorer/records/write \
+curl -s -X POST localhost:5030/api/explorer/records/write \
   -H "Content-Type: application/json" \
   -d '{"writeDescriptorId":"product-task-write","operation":"upsert","input":{"recordId":"t-smoke-1","status":"doing"}}'
 
 # 5. Delete
-curl -s -X DELETE "localhost:4300/api/explorer/records/item?entityName=product&recordId=t-smoke-1&writeDescriptorId=product-task-write"
+curl -s -X DELETE "localhost:5030/api/explorer/records/item?entityName=product&recordId=t-smoke-1&writeDescriptorId=product-task-write"
 
 # 6. Open the UI
-open http://localhost:4300/demo
+open http://localhost:5030/demo
 ```
 
 ---

package/guides/running-the-service.md

@@ -9,10 +9,12 @@ from in-memory state backed by JSON files on disk.
 ### From npm (global)
 
 ```bash
-npm install -g x12i/static-memorix-explorer-api
+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,12 +45,55 @@ 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
 mocks directory defaults to a `mocks/` folder relative to the installed package.
 
+### With `npx` (no global install)
+
+```bash
+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:
+
+```js
+import { startServer } from "@x12i/static-memorix-explorer-api";
+
+const app = await startServer({
+  port: 5030,
+  host: "127.0.0.1",
+  installSignalHandlers: false,
+});
+
+// Later, for example during test teardown:
+await app.close();
+```
+
+For tests that do not need a real TCP listener, build the Fastify app and use
+its injection API:
+
+```js
+import { buildServer } from "@x12i/static-memorix-explorer-api";
+
+const app = await buildServer();
+const response = await app.inject({ method: "GET", url: "/health" });
+console.log(response.json()); // { ok: true }
+await app.close();
+```
+
 ## Configuration
 
 All configuration is via environment variables. Defaults work out of the box.
@@ -57,7 +102,7 @@ All configuration is via environment variables. Defaults work out of the box.
 
 | Variable  | Default     | Description                    |
 | --------- | ----------- | ------------------------------ |
-| `PORT`    | `4300`      | HTTP listen port               |
+| `PORT`    | `5030`      | HTTP listen port               |
 | `HOST`    | `0.0.0.0`   | HTTP listen host               |
 | `MOCKS_DIR` | `<project>/mocks` | Root directory for JSON fixtures |
 
@@ -79,8 +124,9 @@ The health endpoint returns:
 
 ### 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              |
 | ------------------------------------------- | --------------------- |
@@ -117,10 +163,10 @@ mock-memorix-explorer-api
 Once running, verify the server is up:
 
 ```bash
-curl localhost:4300/health
+curl localhost:5030/health
 # {"ok":true}
 
-curl "localhost:4300/api/explorer/health?includeInventory=1"
+curl "localhost:5030/api/explorer/health?includeInventory=1"
 # {"ok":true,"mongoUriConfigured":true,"discoverySample":["assets","findings","memory"],...}
 ```
 

package/guides/using-the-api.md

@@ -3,7 +3,7 @@
 The mock server exposes the full Memorix Explorer API under `/api/explorer/`.
 All responses are JSON. Errors follow the shape `{ ok: false, error: "..." }`.
 
-Base URL defaults to `http://localhost:4300`.
+Base URL defaults to `http://localhost:5030`.
 
 ## Endpoints
 

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "@x12i/static-memorix-explorer-api",
-  "version": "1.1.0",
+  "version": "1.2.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"
   }
 }