@x12i/static-memorix-explorer-api 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 x12i
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# @x12i/mock-memorix-explorer-api
+
+In-memory mock server that provides **full API parity** for the Memorix Explorer
+Fastify API. No MongoDB, Catalox, or Redis required — state lives in
+`./mocks/**/*.json` and is flushed to disk (debounced) on mutation.
+
+## Quick start
+
+```bash
+npm install
+npm run build
+npm start                 # listens on :4300 (PORT / HOST / MOCKS_DIR env-overridable)
+# dev (no build): npm run dev
+```
+
+Health:
+
+```bash
+curl localhost:4300/health
+curl "localhost:4300/api/explorer/health?includeInventory=1"
+```
+
+## Architecture
+
+```
+Fastify Router (/api/explorer/* + /health + Authix/M2M shim)
+        │
+Query & Interceptor Engine (mingo + narrative virtual filters)
+   ┌────────────┬──────────────────┬──────────────┐
+Inventory/Lenses  Snapshots/Aliases   Records Writer
+   └────────────┴──────────────────┴──────────────┘
+              InMemoryStore (state matrix)
+                        │ debounced disk flush
+         ./mocks/metadata  &  ./mocks/data
+```
+
+## Routes
+
+| Group | Endpoints |
+|------|-----------|
+| Health | `GET /health`, `GET /api/explorer/health?includeInventory=1` |
+| Inventory | `/inventory/collections`, `/summary`, `/issues`, `/graph` (query `sourceLens=db-first\|catalox-first`) |
+| Snapshots | `/snapshots/:objectType/:recordId[.../associated[/:propertyName]]`, `/snapshots/:objectType/associated-properties`, `/associations/plan\|apply\|verify` |
+| Records | `/records/collection`, `/full`, `/item`, `/content`, `/raw-collection`, `/raw-item`, `/workspace` |
+| Lists | `/lists`, `/lists/:listId`, `/lists/:listId/records`, `/lists/suggest`, mutations `POST/PATCH/PUT/DELETE` |
+| Narratives | `/narratives`, `/:entity`, `/:entity/raw`, `/:entity/:key`, `/:entity/:key/records`, mutations `POST/PATCH/DELETE` |
+| Object Types | `/object-types`, `/:name`, `/:name/root-property-catalog`, `POST .../compute` |
+| Write | `POST /records/write` (validate / dryRun / upsert / patch / replace) |
+| Agents | `GET /agents` |
+| Auth shim | `POST /api/explorer/auth/token` |
+
+## Query conventions
+
+- `filter=prop:op:val` — op ∈ `eq,ne,gt,gte,lt,lte,in,nin,exists,regex`
+  (`in`/`nin` use `|` separators). Repeatable / `;`-separated.
+- Virtual narrative filter: `filter=narrativeId:eq:has-vulns` rewrites the
+  query to evaluate `doc.narratives['has-vulns']`.
+- `sort=severity:desc&sort=entityId:asc` (mingo sort).
+- `searchText=` / `q=` full-text substring match.
+- `limit` (max 500), `offset`/`skip`, `includeTotal=1`.
+- `target=memory` to query the memory tier (fourth data tier alongside entities/events/knowledge).
+
+## Identity keys
+
+The mock server accepts the following identity keys across fetch/write engines:
+- `recordId` — entities
+- `entityId` — entities
+- `eventId` — events
+- `knowledgeId` — knowledge
+- `memoryId` — memory
+
+Endpoints like `/records/full` and `/records/content` require exactly one identity key
+per request. Memory collections are keyed by `memoryId` and stored in `./mocks/data/memory/memory.json`.
+
+## Snapshot alias translation
+
+Client `associated.data|discovery|analysis|{custom}` maps to storage
+`associatedData | associatedInferred/associatedDiscovery | associatedAnalysis |
+associated{Custom}`. Raw `associated*` fields are stripped from the returned
+document and recomposed into a normalized `associated` bucket.
+
+## Environment
+
+| Var | Default | Notes |
+|-----|---------|-------|
+| `PORT` | `4300` | Listen port |
+| `HOST` | `0.0.0.0` | Listen host |
+| `MOCKS_DIR` | `<project>/mocks` | Fixture root |
+| `DISK_FLUSH_DEBOUNCE_MS` | `300` | Debounce before disk flush |
+| `MEMORIX_ORG_ID` | `memorix` | Organization prefix for DB routing |
+| `MEMORIX_AGENT_ID` | `default-agent` | Agent prefix for catalox DB routing |
+| `MEMORIX_DEPLOYMENT_PROFILE` | `default` | Deployment profile; `ebook` forces org/agent to `ebooks` |
+| `MEMORIX_EXPLORER_ENABLE_METADATA_WRITES` | `false` | Allow list & narrative mutations |
+| `MEMORIX_EXPLORER_ENABLE_PIPELINE_WRITES` | `false` | Allow pipeline writes |
+| `MEMORIX_EXPLORER_ENABLE_REGISTRY_WRITES` | `false` | Allow registry writes |
+
+## DB Router Simulation
+
+The mock server does not connect to MongoDB, but it **tricks the frontend** into
+thinking it is talking to the routed tenant databases.
+
+- The `GET /api/explorer/health` response now includes a dynamic `memorixDb`
+  field constructed as `<orgId>-memorix-entities + <orgId>-memorix-events`.
+- The agent-scoped catalox DB is reflected in the `cataloxDb` field as
+  `<agentId>-memorix-catalox`.
+
+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`).
+
+## Feature Flag Enforcement
+
+The mock server enforces the following feature-flag gates with error responses:
+- List/narrative mutations (`POST/PATCH/PUT/DELETE /lists`, `/narratives`) require
+  `MEMORIX_EXPLORER_ENABLE_METADATA_WRITES=true`.
+- Pipeline writes (if implemented) require
+  `MEMORIX_EXPLORER_ENABLE_PIPELINE_WRITES=true`.
+- Registry writes (if implemented) require
+  `MEMORIX_EXPLORER_ENABLE_REGISTRY_WRITES=true`.
+
+When a flag is disabled or unset, the mock returns `{ ok: false, error: "..." }`
+matching the production Fastify error shape (typically 403/404).
+
+## The "memory" Target
+
+The API has expanded its domain model to include a fourth tier of data: `memory`.
+The mock's querying and writing engines now support `target=memory` and
+`memoryId` as a valid primary key alongside `recordId`, `entityId`, `eventId`,
+and `knowledgeId`.
+
+- Folder structure: `./mocks/data/memory/memory.json` (seeded with example memories).
+- Inventory engine accepts `target=memory` and includes memory collections in
+  the simulated `inventorySummary`.
+- Records engine accepts `target=memory` and supports `memoryId` for fetching.
+- Write engine validates and persists `memoryId` on memory-tier records.
+- Startup validation (`MemorixRecordArraySchema` mock) allows `memoryId` without
+  throwing schema errors.

package/dist/config.js

@@ -0,0 +1,75 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export const ROOT_DIR = path.resolve(__dirname);
+export const MOCKS_DIR = process.env.MOCKS_DIR
+    ? path.resolve(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 HOST = process.env.HOST || "0.0.0.0";
+export const DISK_FLUSH_DEBOUNCE_MS = Number(process.env.DISK_FLUSH_DEBOUNCE_MS || 300);
+// ---------------------------------------------------------------------------
+// DB Router Simulation (@x12i/memorix-db-router)
+// The mock does not connect to MongoDB, but it must convince the frontend that
+// it is talking to the routed tenant databases.
+// ---------------------------------------------------------------------------
+function resolveOrgId() {
+    if ((process.env.MEMORIX_DEPLOYMENT_PROFILE || "").toLowerCase() === "ebook") {
+        return "ebooks";
+    }
+    return process.env.MEMORIX_ORG_ID || "memorix";
+}
+function resolveAgentId() {
+    if ((process.env.MEMORIX_DEPLOYMENT_PROFILE || "").toLowerCase() === "ebook") {
+        return "ebooks";
+    }
+    return process.env.MEMORIX_AGENT_ID || "default-agent";
+}
+export const MEMORIX_ORG_ID = resolveOrgId();
+export const MEMORIX_AGENT_ID = resolveAgentId();
+export const MEMORIX_DEPLOYMENT_PROFILE = process.env.MEMORIX_DEPLOYMENT_PROFILE || "default";
+/**
+ * Construct the router string the frontend expects.
+ * e.g. "neo-memorix-entities + neo-memorix-events" for MEMORIX_ORG_ID=neo
+ */
+export function buildMemorixDbString() {
+    const org = MEMORIX_ORG_ID;
+    return `${org}-memorix-entities + ${org}-memorix-events`;
+}
+/**
+ * Construct the agent-scoped Catalox DB name.
+ * e.g. "ebooks-memorix-catalox"
+ */
+export function buildCataloxDbString() {
+    return `${MEMORIX_AGENT_ID}-memorix-catalox`;
+}
+// ---------------------------------------------------------------------------
+// Feature Flag Enforcement
+// ---------------------------------------------------------------------------
+function flagEnabled(name) {
+    const v = process.env[name];
+    return v === "1" || v === "true";
+}
+export const FLAGS = {
+    METADATA_WRITES: flagEnabled("MEMORIX_EXPLORER_ENABLE_METADATA_WRITES"),
+    PIPELINE_WRITES: flagEnabled("MEMORIX_EXPLORER_ENABLE_PIPELINE_WRITES"),
+    REGISTRY_WRITES: flagEnabled("MEMORIX_EXPLORER_ENABLE_REGISTRY_WRITES"),
+};
+export function metadataWritesEnabled() {
+    return FLAGS.METADATA_WRITES;
+}
+export function pipelineWritesEnabled() {
+    return FLAGS.PIPELINE_WRITES;
+}
+export function registryWritesEnabled() {
+    return FLAGS.REGISTRY_WRITES;
+}
+export function metadataPath(...segments) {
+    return path.join(METADATA_DIR, ...segments);
+}
+export function dataPath(...segments) {
+    return path.join(DATA_DIR, ...segments);
+}

package/dist/engine/aliases.js

@@ -0,0 +1,74 @@
+export const STORAGE_ALIASES = {
+    data: {
+        clientKey: "data",
+        storageProp: "doc.associatedData",
+        fallbacks: ["associatedData"],
+    },
+    discovery: {
+        clientKey: "discovery",
+        storageProp: "doc.associatedInferred or doc.associatedDiscovery",
+        fallbacks: ["associatedInferred", "associatedDiscovery"],
+    },
+    analysis: {
+        clientKey: "analysis",
+        storageProp: "doc.associatedAnalysis",
+        fallbacks: ["associatedAnalysis"],
+    },
+};
+/**
+ * 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 function buildAssociatedBucket(rawDoc) {
+    const associated = {};
+    const properties = [];
+    const strippedDoc = {};
+    for (const [k, v] of Object.entries(rawDoc)) {
+        if (k.startsWith("associated")) {
+            // Map known aliases: associatedData -> data, associatedInferred -> discovery, etc.
+            const clientKey = aliasStorageToClient(k);
+            associated[clientKey] = v;
+            properties.push({
+                propertyName: clientKey,
+                source: k,
+                count: Array.isArray(v) ? v.length : v != null ? 1 : 0,
+            });
+        }
+        else {
+            strippedDoc[k] = v;
+        }
+    }
+    return { associated, strippedDoc, properties };
+}
+export function aliasStorageToClient(storageKey) {
+    switch (storageKey) {
+        case "associatedData":
+            return "data";
+        case "associatedInferred":
+        case "associatedDiscovery":
+            return "discovery";
+        case "associatedAnalysis":
+            return "analysis";
+        default:
+            // associated{Custom} -> {custom}
+            return storageKey.replace(/^associated/, "").replace(/^./, (c) => c.toLowerCase());
+    }
+}
+export function aliasClientToStorage(clientKey) {
+    const entry = STORAGE_ALIASES[clientKey];
+    if (entry) {
+        return { primary: entry.fallbacks[0], fallbacks: entry.fallbacks };
+    }
+    // custom -> associated{Custom}
+    const cap = clientKey.replace(/^./, (c) => c.toUpperCase());
+    const storage = `associated${cap}`;
+    return { primary: storage, fallbacks: [storage] };
+}
+export function resolveInclude(include) {
+    if (!include)
+        return null;
+    const list = Array.isArray(include) ? include : include.split(",");
+    return new Set(list.map((s) => s.trim()).filter(Boolean));
+}

package/dist/engine/associations.js

@@ -0,0 +1,60 @@
+import { store } from "../storage/InMemoryStore.js";
+import { CONTENT_TYPES } from "../types.js";
+import { computeAssociationFingerprint } from "../engine/snapshots.js";
+import { listDataObjectTypes } from "../engine/inventory.js";
+export function planAssociations(objectType) {
+    const types = objectType ? [objectType] : listDataObjectTypes();
+    const plans = [];
+    for (const ot of types) {
+        const fingerprint = computeAssociationFingerprint(ot);
+        const mutations = [];
+        for (const ct of CONTENT_TYPES) {
+            const records = store.getCollection(ot, ct);
+            mutations.push({
+                recordId: `${ot}/${ct}`,
+                targetArray: `${ot}/${ct}`,
+                op: "noop",
+                count: records.length,
+            });
+        }
+        plans.push({
+            objectType: ot,
+            expectedPlanFingerprint: fingerprint,
+            proposedMutations: mutations,
+        });
+    }
+    return plans;
+}
+export function applyAssociations(expectedPlanFingerprint, objectType) {
+    const types = objectType ? [objectType] : listDataObjectTypes();
+    const results = [];
+    for (const ot of types) {
+        const actual = computeAssociationFingerprint(ot);
+        const mismatch = actual !== expectedPlanFingerprint;
+        results.push({
+            objectType: ot,
+            applied: !mismatch,
+            expectedPlanFingerprint,
+            actualFingerprint: actual,
+            mismatch,
+            count: store.getCollection(ot, "snapshots").length,
+        });
+    }
+    // Trigger flush
+    for (const ot of types) {
+        store.flushCollectionNow(`${ot}/snapshots`);
+    }
+    return results;
+}
+export function verifyAssociations(expectedPlanFingerprint, objectType) {
+    const types = objectType ? [objectType] : listDataObjectTypes();
+    return types.map((ot) => {
+        const actual = computeAssociationFingerprint(ot);
+        return {
+            objectType: ot,
+            expectedPlanFingerprint,
+            actualFingerprint: actual,
+            verified: actual === expectedPlanFingerprint,
+        };
+    });
+}

package/dist/engine/identity.js

@@ -0,0 +1,48 @@
+/**
+ * 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 (ct === "events")
+        return "eventId";
+    if (sample) {
+        if ("recordId" in sample)
+            return "recordId";
+        if ("entityId" in sample)
+            return "entityId";
+        if ("id" in sample)
+            return "id";
+    }
+    return "recordId";
+}
+/**
+ * Mock of the production `MemorixRecordArraySchema`. Validates that each record
+ * in a collection array carries exactly one recognized identity key. Previously
+ * this threw at boot if a collection used `memoryId`; it now accepts it.
+ */
+export function validateRecordArray(objectType, ct, records) {
+    const errors = [];
+    const expected = resolveIdField(ct, records[0]);
+    for (const rec of records) {
+        const present = ["recordId", "entityId", "eventId", "knowledgeId", "memoryId"].filter((k) => rec?.[k] !== undefined);
+        if (present.length === 0) {
+            errors.push(`${objectType}/${ct}: record missing identity key (expected ${expected})`);
+        }
+        else if (present.length > 1) {
+            errors.push(`${objectType}/${ct}: record has multiple identity keys [${present.join(", ")}]`);
+        }
+    }
+    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.js

@@ -0,0 +1,133 @@
+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 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));
+}
+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.js

@@ -0,0 +1,66 @@
+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)}`);
+        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 };
+}