@x12i/static-memorix 2.0.0

package/dist/engine/identity.js

@@ -0,0 +1,50 @@
+/**
+ * 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 function resolveIdField(ct, sample) {
+    if (ct === "memory")
+        return "memoryId";
+    if (sample) {
+        if (ct === "events" && "eventId" in sample)
+            return "eventId";
+        if ("recordId" in sample)
+            return "recordId";
+        if ("entityId" in sample)
+            return "entityId";
+        if ("eventId" in sample)
+            return "eventId";
+        if ("id" in sample)
+            return "id";
+    }
+    if (ct === "events")
+        return "eventId";
+    return "recordId";
+}
+/**
+ * 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 function validateRecordArray(objectType, ct, records) {
+    const errors = [];
+    const expected = resolveIdField(ct, records[0]);
+    for (const rec of records) {
+        if (rec?.[expected] === undefined) {
+            errors.push(`${objectType}/${ct}: record missing identity key (expected ${expected})`);
+        }
+    }
+    return { ok: errors.length === 0, errors };
+}
+/**
+ * Find a record by any of the supported identity keys.
+ */
+export function findByIdentity(records, identity) {
+    const entries = Object.entries(identity).filter(([, v]) => v != null);
+    if (entries.length === 0)
+        return undefined;
+    return records.find((d) => entries.every(([k, v]) => String(d[k]) === String(v)));
+}

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

@@ -0,0 +1,133 @@
+import path from "node:path";
+import { store } from "../storage/InMemoryStore.js";
+import { CONTENT_TYPES } from "../types.js";
+import { DATA_DIR } from "../config.js";
+import fs from "node:fs";
+import { isDir } from "../storage/fs.js";
+export function listObjectTypes() {
+    return store.getMetaKeys()
+        .filter((key) => key.startsWith("object-types/"))
+        .map((key) => key.slice("object-types/".length));
+}
+export function listDataObjectTypes() {
+    if (!isDir(DATA_DIR))
+        return [];
+    return fs
+        .readdirSync(DATA_DIR)
+        .filter((d) => isDir(path.join(DATA_DIR, d)) && d !== "system");
+}
+export function computeInventory(params) {
+    const sourceLens = params.sourceLens || "catalox-first";
+    const target = params.target;
+    const rows = [];
+    const catalogTypes = new Set(listObjectTypes());
+    const dataTypes = new Set(listDataObjectTypes());
+    // Determine which content types to scan. `target=memory` restricts to the
+    // memory tier; otherwise include all tiers (entities/events/knowledge/memory).
+    const contentTypes = target === "memory"
+        ? ["memory"]
+        : CONTENT_TYPES;
+    if (sourceLens === "catalox-first") {
+        const objectTypes = target === "memory"
+            ? ["memory"]
+            : [...catalogTypes, ...dataTypes];
+        for (const ot of objectTypes) {
+            for (const ct of contentTypes) {
+                const data = store.getCollection(ot, ct);
+                const isCatalog = catalogTypes.has(ot);
+                rows.push({
+                    objectType: ot,
+                    contentType: ct,
+                    collection: `${ot}/${ct}`,
+                    count: data.length,
+                    status: data.length > 0 ? "populated" : "empty",
+                    provenance: { source: isCatalog || ot === "memory" ? "catalog" : "orphan" },
+                    missingCollections: !isCatalog && ot !== "memory",
+                });
+            }
+        }
+    }
+    else {
+        // db-first: scan all array keys in store.data
+        const keys = store.getCollectionKeys().filter((k) => !k.startsWith("system/"));
+        for (const key of keys) {
+            const [ot, ct] = key.split("/");
+            if (target === "memory" && ct !== "memory")
+                continue;
+            const data = store.getCollection(ot, ct);
+            const mapped = catalogTypes.has(ot);
+            rows.push({
+                objectType: ot,
+                contentType: ct,
+                collection: key,
+                count: data.length,
+                status: data.length > 0 ? "populated" : "empty",
+                provenance: { source: mapped ? "catalog" : "orphan" },
+                missingCollections: !mapped,
+            });
+        }
+    }
+    return rows;
+}
+export function computeInventorySummary(rows, params) {
+    const declared = rows.length;
+    const populated = rows.filter((r) => r.status === "populated").length;
+    const empty = rows.filter((r) => r.status === "empty").length;
+    const orphans = rows.filter((r) => r.provenance.source === "orphan").length;
+    const summary = {
+        declaredCollections: declared,
+        populatedCollections: populated,
+        emptyCollections: empty,
+        orphanCollections: orphans,
+    };
+    if (params.includeExactCounts) {
+        summary.perObjectType = rows.reduce((acc, r) => {
+            acc[r.objectType] = acc[r.objectType] || {
+                populated: 0,
+                empty: 0,
+                total: 0,
+            };
+            acc[r.objectType].total++;
+            if (r.status === "populated")
+                acc[r.objectType].populated++;
+            else
+                acc[r.objectType].empty++;
+            return acc;
+        }, {});
+    }
+    return summary;
+}
+export function computeInventoryIssues(rows) {
+    return rows.filter((r) => r.provenance.source === "orphan" || r.missingCollections === true);
+}
+export function computeGraph(rows) {
+    const nodes = [];
+    const edges = [];
+    const nodeSet = new Set();
+    for (const r of rows) {
+        if (r.status !== "populated")
+            continue;
+        const nodeId = r.objectType;
+        if (!nodeSet.has(nodeId)) {
+            nodeSet.add(nodeId);
+            nodes.push({ id: nodeId, objectType: nodeId, populated: true });
+        }
+    }
+    for (const ot of nodeSet) {
+        const meta = store.getMeta(`object-types/${ot}`);
+        if (!meta)
+            continue;
+        const relations = meta.catalogRelations || [];
+        for (const rel of relations) {
+            const target = rel.targetObject;
+            if (!target || !nodeSet.has(target))
+                continue;
+            edges.push({
+                from: ot,
+                to: target,
+                relationType: rel.relationType || "related",
+            });
+        }
+    }
+    return { nodes, edges };
+}

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/lists.js

@@ -0,0 +1,62 @@
+import { store } from "../storage/InMemoryStore.js";
+import { CONTENT_TYPES } from "../types.js";
+import { queryMockCollection } from "../engine/query.js";
+export function listListDescriptors(entityName) {
+    const out = [];
+    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);
+        }
+    }
+    return out;
+}
+export function getListDescriptor(listId) {
+    return store.getMeta(`lists/${listId}`);
+}
+/**
+ * Executes a list descriptor query pipeline against local data arrays.
+ */
+export async function executeListDescriptor(desc, params = {}) {
+    const entity = desc.entity || desc.entityName;
+    if (!entity) {
+        return { rows: [], page: { offset: 0, limit: 50 } };
+    }
+    // Gather base collection (snapshots by default).
+    const baseCt = desc.baseContentType || "snapshots";
+    let records = store.getCollection(entity, baseCt);
+    // Apply descriptor query if present
+    if (desc.query) {
+        const mingo = (await import("mingo")).default;
+        const query = new mingo.Query(desc.query);
+        records = query.find(records).all();
+    }
+    const result = queryMockCollection(records, { ...params, ...(desc.query ? { filter: undefined } : {}) });
+    // Apply projections / field selection
+    const fields = desc.fields || (desc.projections ? Object.keys(desc.projections) : null);
+    if (fields && fields.length) {
+        result.rows = result.rows.map((r) => {
+            const proj = { id: r.id ?? r.recordId };
+            for (const f of fields) {
+                if (f in r)
+                    proj[f] = r[f];
+            }
+            return proj;
+        });
+    }
+    return result;
+}
+/**
+ * Suggest extensions / analytics for unjoined content types.
+ */
+export function suggestListExtensions(entityName) {
+    const available = CONTENT_TYPES.filter((ct) => store.getCollection(entityName, ct).length > 0);
+    const suggestions = available
+        .filter((ct) => ct !== "snapshots")
+        .map((ct) => ({
+        contentType: ct,
+        collection: `${entityName}/${ct}`,
+        suggestion: `Add extension join for ${ct} records into the entity view.`,
+    }));
+    return { entityName, suggestions };
+}

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

@@ -0,0 +1,67 @@
+import { store } from "../storage/InMemoryStore.js";
+import { CONTENT_TYPES } from "../types.js";
+/**
+ * Discover narrative keys tagged on records via doc.narratives.*.
+ */
+export function discoverRecordNarrativeTags(entityName) {
+    const tags = new Set();
+    for (const ct of CONTENT_TYPES) {
+        const records = store.getCollection(entityName, ct);
+        for (const doc of records) {
+            const narratives = doc.narratives || {};
+            for (const key of Object.keys(narratives))
+                tags.add(key);
+        }
+    }
+    return [...tags];
+}
+export function mergeCatalogWithSignals(authored, recordTags) {
+    const result = [];
+    const authoredKeys = Object.keys(authored || {});
+    for (const key of authoredKeys) {
+        result.push({ ...authored[key], key, signaled: recordTags.includes(key) });
+    }
+    for (const tag of recordTags) {
+        if (!authoredKeys.includes(tag)) {
+            result.push({ key: tag, signaled: true });
+        }
+    }
+    return result;
+}
+export function getMergedNarratives(entityName) {
+    if (entityName) {
+        const authored = store.getMeta(`narratives/${entityName}`) || {};
+        const recordTags = discoverRecordNarrativeTags(entityName);
+        return mergeCatalogWithSignals(authored, recordTags);
+    }
+    // global across all entities
+    const out = {};
+    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);
+    }
+    return out;
+}
+export function getRawNarratives(entityName) {
+    return (store.getMeta(`narratives/${entityName}`) || {});
+}
+export function queryNarrativeRecords(entityName, key) {
+    const results = [];
+    for (const ct of CONTENT_TYPES) {
+        const records = store.getCollection(entityName, ct);
+        for (const doc of records) {
+            const narratives = doc.narratives || {};
+            const val = narratives[key];
+            if (val === true || val === key)
+                results.push(doc);
+        }
+    }
+    return results;
+}
+export function listNarrativeEntities() {
+    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/objectTypes.js

@@ -0,0 +1,71 @@
+import { store } from "../storage/InMemoryStore.js";
+import { CONTENT_TYPES } from "../types.js";
+/**
+ * Full-scan all record arrays in ./data/{name}/*.json, compute property
+ * occurrence percentages, data types, and paths.
+ */
+export function computeRootPropertyCatalog(objectType) {
+    const counts = new Map();
+    const typesMap = new Map();
+    const samples = new Map();
+    let totalDocs = 0;
+    for (const ct of CONTENT_TYPES) {
+        const records = store.getCollection(objectType, ct);
+        for (const doc of records) {
+            totalDocs++;
+            const flat = flatten(doc);
+            for (const [p, v] of Object.entries(flat)) {
+                counts.set(p, (counts.get(p) || 0) + 1);
+                const t = typeOf(v);
+                if (!typesMap.has(p))
+                    typesMap.set(p, new Set());
+                typesMap.get(p).add(t);
+                if (!samples.has(p))
+                    samples.set(p, []);
+                const arr = samples.get(p);
+                if (arr.length < 3 && !arr.includes(v))
+                    arr.push(v);
+            }
+        }
+    }
+    const entries = [];
+    for (const [p, c] of counts.entries()) {
+        entries.push({
+            path: p,
+            occurrencePct: totalDocs ? Math.round((c / totalDocs) * 1000) / 10 : 0,
+            types: [...(typesMap.get(p) || [])],
+            sampleValues: samples.get(p) || [],
+        });
+    }
+    entries.sort((a, b) => b.occurrencePct - a.occurrencePct);
+    // Persist back to metadata
+    const meta = store.getMeta(`object-types/${objectType}`) || { name: objectType };
+    meta.rootPropertyCatalog = entries;
+    store.setMeta(`object-types/${objectType}`, meta);
+    return entries;
+}
+function flatten(obj, prefix = "") {
+    const out = {};
+    if (obj == null || typeof obj !== "object") {
+        if (prefix)
+            out[prefix] = obj;
+        return out;
+    }
+    for (const [k, v] of Object.entries(obj)) {
+        const key = prefix ? `${prefix}.${k}` : k;
+        if (v != null && typeof v === "object" && !Array.isArray(v)) {
+            Object.assign(out, flatten(v, key));
+        }
+        else {
+            out[key] = v;
+        }
+    }
+    return out;
+}
+function typeOf(v) {
+    if (v === null)
+        return "null";
+    if (Array.isArray(v))
+        return "array";
+    return typeof v;
+}

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;