@x12i/static-memorix-explorer-api 1.0.0

package/dist/engine/write.js

@@ -0,0 +1,123 @@
+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) {
+        throw Object.assign(new Error(`Write descriptor not found: ${writeDescriptorId}`), {
+            statusCode: 404,
+        });
+    }
+    return desc;
+}
+/**
+ * Validate input against the write descriptor schema (lightweight AJV-free check).
+ */
+export function validateInputSchema(writeSpec, input) {
+    const errors = [];
+    const schema = (writeSpec.schema || {});
+    const payload = Array.isArray(input) ? input : input ? [input] : [];
+    if (schema.required && Array.isArray(schema.required)) {
+        for (const req of schema.required) {
+            for (const item of payload) {
+                if (item?.[req] === undefined) {
+                    errors.push(`Missing required field: ${req}`);
+                }
+            }
+        }
+    }
+    if (schema.properties) {
+        for (const item of payload) {
+            for (const [field, def] of Object.entries(schema.properties)) {
+                if (item[field] === undefined)
+                    continue;
+                if (def.type) {
+                    const actualType = Array.isArray(item[field]) ? "array" : typeof item[field];
+                    const expected = def.type;
+                    if (expected === "array" && !Array.isArray(item[field])) {
+                        errors.push(`Field ${field} must be array`);
+                    }
+                    else if (expected !== "array" && expected !== actualType) {
+                        errors.push(`Field ${field} must be ${expected}, got ${actualType}`);
+                    }
+                }
+            }
+        }
+    }
+    return { ok: errors.length === 0, errors };
+}
+export function parseTargetCollection(target) {
+    const [objectType, ctRaw] = target.split("/");
+    // The `memory` target routes to the standalone memory tier.
+    if (objectType === "memory" || ctRaw === "memory") {
+        return { objectType: "memory", ct: "memory" };
+    }
+    const ct = (ctRaw || "snapshots");
+    return { objectType, ct };
+}
+export function executeOperation(params) {
+    const { objectType, ct } = parseTargetCollection(params.target);
+    const collection = store.getCollection(objectType, ct);
+    const payload = Array.isArray(params.data) ? params.data : [params.data];
+    // Resolve the identity field for this collection tier.
+    // Memory tier uses memoryId; everything else defaults to recordId.
+    const idField = ct === "memory" ? "memoryId" : "recordId";
+    switch (params.op) {
+        case "add": {
+            const nextId = getNextId(collection, idField);
+            for (const item of payload) {
+                collection.push({ ...item, [idField]: item[idField] ?? nextId() });
+            }
+            break;
+        }
+        case "upsert": {
+            for (const item of payload) {
+                const id = item[idField] ?? item.recordId ?? item.id;
+                const idx = collection.findIndex((d) => (d[idField] ?? d.recordId ?? d.id) === id);
+                if (idx >= 0) {
+                    collection[idx] = { ...collection[idx], ...item };
+                }
+                else {
+                    collection.push(item);
+                }
+            }
+            break;
+        }
+        case "patch": {
+            for (const item of payload) {
+                const id = item[idField] ?? item.recordId ?? item.id;
+                const idx = collection.findIndex((d) => (d[idField] ?? d.recordId ?? d.id) === id);
+                if (idx >= 0) {
+                    collection[idx] = { ...collection[idx], ...item };
+                }
+            }
+            break;
+        }
+        case "replace": {
+            return payload;
+        }
+    }
+    store.setCollection(objectType, ct, collection);
+    return payload;
+}
+function getNextId(collection, idField = "recordId") {
+    let max = 0;
+    for (const d of collection) {
+        const id = Number(d[idField] ?? d.recordId ?? d.id);
+        if (!isNaN(id) && id > max)
+            max = id;
+    }
+    let counter = max + 1;
+    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)}`);
+        if (desc)
+            out.push(desc);
+    }
+    return out;
+}

package/dist/routes/helpers.js

@@ -0,0 +1,29 @@
+export function qp(request) {
+    const q = (request.query || {});
+    return {
+        filter: q.filter,
+        sort: q.sort,
+        searchText: q.searchText,
+        q: q.q,
+        limit: q.limit,
+        offset: q.offset,
+        skip: q.skip,
+        includeTotal: q.includeTotal === "1" || q.includeTotal === "true",
+        include: q.include,
+        mode: q.mode,
+        listId: q.listId,
+        entityName: q.entityName,
+        sourceLens: q.sourceLens,
+        target: q.target,
+        includeExactCounts: q.includeExactCounts === "1" || q.includeExactCounts === "true",
+        includeInventory: q.includeInventory === "1" || q.includeInventory === "true",
+        memoryId: q.memoryId,
+        recordId: q.recordId,
+        entityId: q.entityId,
+        eventId: q.eventId,
+        knowledgeId: q.knowledgeId,
+    };
+}
+export function str(v, fallback = "") {
+    return v === undefined || v === null ? fallback : String(v);
+}

package/dist/routes/index.js

@@ -0,0 +1,345 @@
+import { store } from "../storage/InMemoryStore.js";
+import { buildMemorixDbString, buildCataloxDbString, 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";
+import { getSnapshotNormalized, getSnapshotAssociated, getSnapshotAssociatedProperty, getAssociatedProperties, } from "../engine/snapshots.js";
+import { getRecordsCollection, getRecordsFull, getRecordsItem, getRawCollection, getRawItem, getWorkspaceRecords, getRecordContent, } from "../engine/records.js";
+import { listListDescriptors, getListDescriptor, executeListDescriptor, suggestListExtensions, } from "../engine/lists.js";
+import { getMergedNarratives, getRawNarratives, queryNarrativeRecords, } from "../engine/narratives.js";
+import { computeRootPropertyCatalog } from "../engine/objectTypes.js";
+import { loadWriteDescriptor, validateInputSchema, executeOperation, } from "../engine/write.js";
+import { planAssociations, applyAssociations, verifyAssociations, } from "../engine/associations.js";
+export async function registerRoutes(app) {
+    // ---------- A. Health & System Diagnostics ----------
+    app.get("/health", async () => ({ ok: true }));
+    app.get("/api/explorer/health", async (request) => {
+        const includeInventory = qp(request).includeInventory;
+        const objectTypes = listObjectTypes();
+        const base = {
+            ok: true,
+            mongoUriConfigured: true,
+            discoverySample: objectTypes,
+            memorixDb: buildMemorixDbString(),
+            cataloxDb: buildCataloxDbString(),
+        };
+        if (includeInventory) {
+            const rows = computeInventory({ sourceLens: "catalox-first" });
+            const summary = computeInventorySummary(rows, { includeExactCounts: false });
+            return { ...base, inventorySummary: summary };
+        }
+        return base;
+    });
+    // ---------- B. Inventory & Graph Engine ----------
+    app.get("/api/explorer/inventory/collections", async (request) => {
+        const rows = computeInventory(qp(request));
+        return { rows, total: rows.length };
+    });
+    app.get("/api/explorer/inventory/summary", async (request) => {
+        const rows = computeInventory(qp(request));
+        const summary = computeInventorySummary(rows, qp(request));
+        return { summary, rows };
+    });
+    app.get("/api/explorer/inventory/issues", async (request) => {
+        const rows = computeInventory(qp(request));
+        const issues = computeInventoryIssues(rows);
+        return { issues, total: issues.length };
+    });
+    app.get("/api/explorer/inventory/graph", async (request) => {
+        const rows = computeInventory(qp(request));
+        return computeGraph(rows);
+    });
+    // ---------- C. Snapshots & Associated Data Pipeline ----------
+    app.get("/api/explorer/snapshots/:objectType/:recordId", async (request, reply) => {
+        const { objectType, recordId } = request.params;
+        const q = qp(request);
+        const result = getSnapshotNormalized(objectType, recordId, q.include);
+        if (!result)
+            return send404(reply, `Snapshot not found: ${objectType}/${recordId}`);
+        return result;
+    });
+    app.get("/api/explorer/snapshots/:objectType/:recordId/associated", async (request, reply) => {
+        const { objectType, recordId } = request.params;
+        const result = getSnapshotAssociated(objectType, recordId);
+        if (!result)
+            return send404(reply, `Snapshot not found: ${objectType}/${recordId}`);
+        return result;
+    });
+    app.get("/api/explorer/snapshots/:objectType/:recordId/associated/:propertyName", async (request, reply) => {
+        const { objectType, recordId, propertyName } = request.params;
+        const result = getSnapshotAssociatedProperty(objectType, recordId, propertyName);
+        if (result === undefined)
+            return send404(reply, `Associated property not found: ${propertyName}`);
+        return result;
+    });
+    app.get("/api/explorer/snapshots/:objectType/associated-properties", async (request) => {
+        const { objectType } = request.params;
+        return { objectType, properties: getAssociatedProperties(objectType) };
+    });
+    app.post("/api/explorer/associations/plan", async (request) => {
+        const { objectType } = (request.body || {});
+        return { plans: planAssociations(objectType) };
+    });
+    app.post("/api/explorer/associations/apply", async (request) => {
+        const { expectedPlanFingerprint, objectType } = (request.body || {});
+        return { results: applyAssociations(expectedPlanFingerprint, objectType) };
+    });
+    app.post("/api/explorer/associations/verify", async (request) => {
+        const { expectedPlanFingerprint, objectType } = (request.body || {});
+        return { results: verifyAssociations(expectedPlanFingerprint, objectType) };
+    });
+    // ---------- D. Records Engine ----------
+    app.get("/api/explorer/records/collection", async (request) => {
+        const q = qp(request);
+        return await getRecordsCollection(q);
+    });
+    app.get("/api/explorer/records/full", async (request) => {
+        const q = qp(request);
+        const entityName = str(q.entityName);
+        const recordId = str(request.query.recordId);
+        if (!entityName || !recordId)
+            return { error: "entityName and recordId are required" };
+        return getRecordsFull(entityName, recordId);
+    });
+    app.get("/api/explorer/records/item", async (request, reply) => {
+        const q = qp(request);
+        const entityName = str(q.entityName);
+        const recordId = str(request.query.recordId);
+        const itemDescriptor = request.query.itemDescriptor
+            ? JSON.parse(request.query.itemDescriptor)
+            : undefined;
+        const result = getRecordsItem(entityName, recordId, itemDescriptor);
+        if (!result)
+            return send404(reply, `Item not found: ${entityName}/${recordId}`);
+        return result;
+    });
+    app.get("/api/explorer/records/content", async (request, reply) => {
+        const q = qp(request);
+        const entityName = str(q.entityName) || (q.target === "memory" ? "memory" : "");
+        const contentType = request.query.contentType;
+        const identity = {};
+        if (q.recordId)
+            identity.recordId = q.recordId;
+        if (q.entityId)
+            identity.entityId = q.entityId;
+        if (q.eventId)
+            identity.eventId = q.eventId;
+        if (q.knowledgeId)
+            identity.knowledgeId = q.knowledgeId;
+        if (q.memoryId)
+            identity.memoryId = q.memoryId;
+        if (!contentType || Object.keys(identity).length === 0) {
+            return { ok: false, error: "contentType and at least one identity key required" };
+        }
+        const result = getRecordContent(entityName, contentType, identity);
+        if (!result)
+            return send404(reply, `Content not found: ${entityName}/${contentType}`);
+        return result;
+    });
+    app.get("/api/explorer/records/raw-collection", async (request) => {
+        const { entityName, collectionName } = request.query;
+        const name = collectionName || entityName;
+        return getRawCollection(str(entityName), str(name));
+    });
+    app.get("/api/explorer/records/raw-item", async (request, reply) => {
+        const { collectionName, recordId } = request.query;
+        const result = getRawItem(str(collectionName), str(recordId));
+        if (!result)
+            return send404(reply, `Raw item not found: ${collectionName}/${recordId}`);
+        return result;
+    });
+    app.get("/api/explorer/records/workspace", async (request) => {
+        return await getWorkspaceRecords(qp(request));
+    });
+    // ---------- E. Lists Subsystem ----------
+    app.get("/api/explorer/lists", async (request) => {
+        const { entityName } = request.query;
+        return { lists: listListDescriptors(entityName) };
+    });
+    app.get("/api/explorer/lists/:listId", async (request, reply) => {
+        const { listId } = request.params;
+        const desc = getListDescriptor(listId);
+        if (!desc)
+            return send404(reply, `List descriptor not found: ${listId}`);
+        return desc;
+    });
+    app.get("/api/explorer/lists/:listId/records", async (request, reply) => {
+        const { listId } = request.params;
+        const desc = getListDescriptor(listId);
+        if (!desc)
+            return send404(reply, `List descriptor not found: ${listId}`);
+        const result = await executeListDescriptor(desc, qp(request));
+        return result;
+    });
+    app.get("/api/explorer/lists/:listId/records-ws", async (request, reply) => {
+        const { listId } = request.params;
+        const desc = getListDescriptor(listId);
+        if (!desc)
+            return send404(reply, `List descriptor not found: ${listId}`);
+        const result = await executeListDescriptor(desc, qp(request));
+        return result;
+    });
+    app.get("/api/explorer/lists/suggest", async (request) => {
+        const { entityName } = request.query;
+        return suggestListExtensions(str(entityName));
+    });
+    app.post("/api/explorer/lists", async (request) => {
+        if (!metadataWritesEnabled()) {
+            return { ok: false, error: "Metadata writes are disabled" };
+        }
+        const body = (request.body || {});
+        const listId = body.listId || body.id;
+        if (!listId)
+            return { error: "listId required" };
+        store.setMeta(`lists/${listId}`, { ...body, listId });
+        return { ok: true, listId };
+    });
+    app.patch("/api/explorer/lists/:listId", async (request) => {
+        if (!metadataWritesEnabled()) {
+            return { ok: false, error: "Metadata writes are disabled" };
+        }
+        const { listId } = request.params;
+        const existing = getListDescriptor(listId) || {};
+        const updated = { ...existing, ...(request.body || {}), listId };
+        store.setMeta(`lists/${listId}`, updated);
+        return { ok: true, listId, descriptor: updated };
+    });
+    app.put("/api/explorer/lists/:listId/sort", async (request) => {
+        if (!metadataWritesEnabled()) {
+            return { ok: false, error: "Metadata writes are disabled" };
+        }
+        const { listId } = request.params;
+        const existing = getListDescriptor(listId) || {};
+        const updated = { ...existing, sort: (request.body || {}).sort, listId };
+        store.setMeta(`lists/${listId}`, updated);
+        return { ok: true, listId, descriptor: updated };
+    });
+    app.delete("/api/explorer/lists/:listId", async (request) => {
+        if (!metadataWritesEnabled()) {
+            return { ok: false, error: "Metadata writes are disabled" };
+        }
+        const { listId } = request.params;
+        store.setMeta(`lists/${listId}`, undefined, false);
+        return { ok: true, deleted: listId };
+    });
+    // ---------- F. Narratives Engine ----------
+    app.get("/api/explorer/narratives", async () => {
+        return { narratives: getMergedNarratives() };
+    });
+    app.get("/api/explorer/narratives/:entity", async (request) => {
+        const { entity } = request.params;
+        return { entity, narratives: getMergedNarratives(entity) };
+    });
+    app.get("/api/explorer/narratives/:entity/raw", async (request) => {
+        const { entity } = request.params;
+        return { entity, raw: getRawNarratives(entity) };
+    });
+    app.get("/api/explorer/narratives/:entity/:key", async (request, reply) => {
+        const { entity, key } = request.params;
+        const merged = getMergedNarratives(entity);
+        const found = merged.find((n) => n.key === key);
+        if (!found)
+            return send404(reply, `Narrative not found: ${entity}/${key}`);
+        return found;
+    });
+    app.get("/api/explorer/narratives/:entity/:key/records", async (request) => {
+        const { entity, key } = request.params;
+        return { entity, key, records: queryNarrativeRecords(entity, key) };
+    });
+    app.post("/api/explorer/narratives", async (request) => {
+        if (!metadataWritesEnabled()) {
+            return { ok: false, error: "Metadata writes are disabled" };
+        }
+        const { entity, key, ...rest } = (request.body || {});
+        if (!entity || !key)
+            return { error: "entity and key required" };
+        const authored = getRawNarratives(entity);
+        authored[key] = { key, ...rest };
+        store.setMeta(`narratives/${entity}`, authored);
+        return { ok: true, entity, key };
+    });
+    app.patch("/api/explorer/narratives/:entity/:key", async (request) => {
+        if (!metadataWritesEnabled()) {
+            return { ok: false, error: "Metadata writes are disabled" };
+        }
+        const { entity, key } = request.params;
+        const authored = getRawNarratives(entity);
+        authored[key] = { ...authored[key], ...(request.body || {}), key };
+        store.setMeta(`narratives/${entity}`, authored);
+        return { ok: true, entity, key, descriptor: authored[key] };
+    });
+    app.delete("/api/explorer/narratives/:entity/:key", async (request) => {
+        if (!metadataWritesEnabled()) {
+            return { ok: false, error: "Metadata writes are disabled" };
+        }
+        const { entity, key } = request.params;
+        const authored = getRawNarratives(entity);
+        delete authored[key];
+        store.setMeta(`narratives/${entity}`, authored);
+        return { ok: true, entity, key };
+    });
+    // ---------- G. Object Types & Root Property Catalog ----------
+    app.get("/api/explorer/object-types", async () => {
+        return { objectTypes: listObjectTypes().map((name) => store.getMeta(`object-types/${name}`)) };
+    });
+    app.get("/api/explorer/object-types/:name/root-property-catalog", async (request) => {
+        const { name } = request.params;
+        const meta = store.getMeta(`object-types/${name}`);
+        return {
+            objectType: name,
+            rootPropertyCatalog: meta?.rootPropertyCatalog || [],
+        };
+    });
+    app.post("/api/explorer/object-types/:name/root-property-catalog/compute", async (request) => {
+        const { name } = request.params;
+        const entries = computeRootPropertyCatalog(name);
+        return { objectType: name, computed: true, rootPropertyCatalog: entries };
+    });
+    // ---------- H. Record Write Engine ----------
+    app.post("/api/explorer/records/write", async (request) => {
+        const { writeDescriptorId, operation = "add", input, records, dryRun = false, validateOnly = false, } = (request.body || {});
+        if (!writeDescriptorId)
+            return { error: "writeDescriptorId required", ok: false };
+        const writeSpec = loadWriteDescriptor(writeDescriptorId);
+        const targetCollection = writeSpec.targetCollection;
+        if (!targetCollection)
+            return { error: "writeDescriptor missing targetCollection", ok: false };
+        const data = input || records;
+        const validation = validateInputSchema(writeSpec, data);
+        if (!validation.ok) {
+            return { ok: false, validated: false, errors: validation.errors };
+        }
+        if (validateOnly)
+            return { ok: true, validated: true };
+        const results = executeOperation({
+            target: targetCollection,
+            op: operation,
+            data,
+        });
+        if (!dryRun) {
+            await store.flushAll();
+        }
+        return { ok: true, count: results.length, dryRun };
+    });
+    app.get("/api/explorer/object-types/:name", async (request, reply) => {
+        const { name } = request.params;
+        const meta = store.getMeta(`object-types/${name}`);
+        if (!meta)
+            return send404(reply, `Object type not found: ${name}`);
+        return meta;
+    });
+    // ---------- I. Agents Engine ----------
+    app.get("/api/explorer/agents", async () => {
+        const agents = store.getMeta("agents");
+        return agents || { agents: [] };
+    });
+    // ---- Authix / M2M Auth Shim ----
+    app.post("/api/explorer/auth/token", async () => ({
+        access_token: "mock-m2m-token",
+        token_type: "Bearer",
+        expires_in: 3600,
+    }));
+}
+function send404(reply, message) {
+    return reply.code(404).send({ ok: false, error: message });
+}

package/dist/server.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import Fastify from "fastify";
+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 });
+    // Global error handler matching predictable error shapes.
+    app.setErrorHandler((error, _request, reply) => {
+        const status = error.statusCode && error.statusCode >= 400 ? error.statusCode : 500;
+        reply.status(status).send({
+            ok: false,
+            error: error.message || "Internal Server Error",
+        });
+    });
+    await store.load();
+    await registerRoutes(app);
+    const port = Number(process.env.PORT || PORT);
+    await app.listen({ port, host: HOST });
+    // eslint-disable-next-line no-console
+    console.log(`[mock-memorix-explorer-api] listening on ${HOST}:${port}`);
+    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);
+}
+main().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error(err);
+    process.exit(1);
+});