@exellix/graphs-studio-data-flow 0.1.0

package/src/lib/memorixEntityContentTypes.js

@@ -0,0 +1,116 @@
+/**
+ * Memorix entity **content types** for graph entry (`metadata.graphEntry.inputs[].inputTypes`).
+ *
+ * Catalox catalog `memorix_entity_content_types` holds **metadata only** (labels, which XMemory
+ * op-tier to count via `data.countBinding`, optional `data.editorSlot`). Document counts for
+ * **Current records** come from Memorix / XMemory via `@exellix/exellix-runtime`, not from Catalox.
+ */
+
+export const MEMORIX_ENTITY_CONTENT_TYPES_CATALOG_ID = 'memorix_entity_content_types';
+
+/** @type {Readonly<Record<string, string>>} Deprecated graph-entry ids → canonical `contentTypeKey`. */
+export const DEPRECATED_GRAPH_ENTRY_INPUT_TYPE_IDS = Object.freeze({
+  snapshotsRecords: 'snapshots',
+  scoppedQuestions: 'scoping_questions',
+  eventTrigger: 'event_trigger',
+});
+
+/**
+ * @param {unknown} v
+ * @returns {string}
+ */
+export function pickMemorixContentTypeStr(v) {
+  return typeof v === 'string' ? v.trim() : '';
+}
+
+/**
+ * @param {string} typeId
+ * @returns {string}
+ */
+export function normalizeMemorixEntityContentTypeId(typeId) {
+  const id = pickMemorixContentTypeStr(typeId);
+  if (!id) return '';
+  return DEPRECATED_GRAPH_ENTRY_INPUT_TYPE_IDS[id] ?? id;
+}
+
+/**
+ * @param {unknown} rawTypes
+ * @returns {string[]|undefined}
+ */
+export function normalizeGraphEntryInputTypes(rawTypes) {
+  if (!Array.isArray(rawTypes)) return undefined;
+  const out = [];
+  const seen = new Set();
+  for (const t of rawTypes) {
+    const id = normalizeMemorixEntityContentTypeId(t);
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  return out.length ? out : undefined;
+}
+
+/**
+ * @param {{ itemId?: string, data?: unknown }} row
+ * @returns {string}
+ */
+export function memorixEntityContentTypeKeyFromRow(row) {
+  if (!row || typeof row !== 'object') return '';
+  const itemId = pickMemorixContentTypeStr(row.itemId);
+  const data =
+    row.data != null && typeof row.data === 'object' && !Array.isArray(row.data)
+      ? /** @type {Record<string, unknown>} */ (row.data)
+      : {};
+  const fromData = pickMemorixContentTypeStr(data.contentTypeKey ?? data.key ?? data.slug);
+  return fromData || itemId;
+}
+
+/**
+ * @param {Array<{ itemId?: string, data?: unknown }>} catalogRows
+ * @param {string} typeId
+ * @returns {{ itemId?: string, data?: unknown } | null}
+ */
+export function findMemorixEntityContentTypeCatalogRow(catalogRows, typeId) {
+  const id = normalizeMemorixEntityContentTypeId(typeId);
+  if (!id || !Array.isArray(catalogRows)) return null;
+  for (const row of catalogRows) {
+    if (!row || typeof row !== 'object') continue;
+    const key = memorixEntityContentTypeKeyFromRow(row);
+    const itemId = pickMemorixContentTypeStr(row.itemId);
+    if (key === id || itemId === id) return row;
+  }
+  return null;
+}
+
+/**
+ * @param {Array<{ itemId?: string, data?: unknown }>} items
+ * @param {string} typeId
+ * @returns {{ countBinding: string, editorSlot: string | null } | null}
+ */
+export function memorixEntityContentTypeBindingFromCatalogItems(items, typeId) {
+  const id = normalizeMemorixEntityContentTypeId(typeId);
+  if (!id || !Array.isArray(items)) return null;
+  for (const it of items) {
+    if (!it || typeof it !== 'object') continue;
+    const row = /** @type {{ itemId?: string, data?: unknown }} */ (it);
+    const key = memorixEntityContentTypeKeyFromRow(row);
+    const itemId = pickMemorixContentTypeStr(row.itemId);
+    if (key !== id && itemId !== id) continue;
+    const data =
+      row.data != null && typeof row.data === 'object' && !Array.isArray(row.data)
+        ? /** @type {Record<string, unknown>} */ (row.data)
+        : {};
+    const countBinding =
+      pickMemorixContentTypeStr(data.countBinding) || pickMemorixContentTypeStr(data.countTier);
+    const editorSlot = pickMemorixContentTypeStr(data.editorSlot) || null;
+    if (!countBinding) {
+      throw new Error(
+        `Memorix entity content type "${id}" is missing data.countBinding in Catalox catalog ` +
+          `"${MEMORIX_ENTITY_CONTENT_TYPES_CATALOG_ID}". ` +
+          'Counts are loaded from Memorix (XMemory op-tier); Catalox only declares which tier to use.',
+      );
+    }
+    return { countBinding, editorSlot };
+  }
+  return null;
+}

package/src/lib/memorixScopedConfig.js

@@ -0,0 +1,108 @@
+/**
+ * Memorix descriptor helpers for scoped local skills — aligned with
+ * `@exellix/graph-engine` `memorixScopedConfig.ts` (graph-engine 6.x).
+ */
+
+/** @typedef {import('@exellix/graph-engine/dist/src/types/taskNodeConfiguration.js').TaskNodeTaskConfiguration} TaskNodeTaskConfiguration */
+
+export const DEFAULT_SCOPED_CONTENT_TYPES = ['inferences', 'decisions'];
+
+/**
+ * @param {TaskNodeTaskConfiguration | Record<string, unknown> | null | undefined} cfg
+ * @returns {string | undefined}
+ */
+export function resolveMemorixItemDescriptorId(cfg) {
+  if (!cfg || typeof cfg !== 'object') return undefined;
+  const memorix = typeof cfg.memorixItemDescriptorId === 'string' ? cfg.memorixItemDescriptorId.trim() : '';
+  if (memorix) return memorix;
+  const item = typeof cfg.itemDescriptorId === 'string' ? cfg.itemDescriptorId.trim() : '';
+  return item || undefined;
+}
+
+/**
+ * @param {TaskNodeTaskConfiguration | Record<string, unknown> | null | undefined} cfg
+ * @param {string} contentType
+ * @returns {string}
+ */
+export function resolveMemorixWriteDescriptorId(cfg, contentType) {
+  const base = cfg && typeof cfg === 'object' ? cfg : {};
+  const mapped = base.memorixWriteDescriptors?.[contentType];
+  if (typeof mapped === 'string' && mapped.trim()) return mapped.trim();
+  if (contentType === 'inferences' || contentType === 'decisions') {
+    const legacy =
+      (typeof base.memorixWriteDescriptorId === 'string' ? base.memorixWriteDescriptorId.trim() : '') ||
+      (typeof base.writeDescriptorId === 'string' ? base.writeDescriptorId.trim() : '');
+    if (legacy && contentType === 'inferences') return legacy;
+  }
+  return contentType;
+}
+
+/**
+ * Pure metadata + `taskConfiguration` execution bag (graph-engine 5.0+).
+ *
+ * @param {unknown} node
+ * @returns {Record<string, unknown>}
+ */
+export function nodeAuthoringBag(node) {
+  const n = /** @type {{ metadata?: unknown; taskConfiguration?: unknown }} */ (node);
+  const meta =
+    n?.metadata && typeof n.metadata === 'object' && !Array.isArray(n.metadata)
+      ? /** @type {Record<string, unknown>} */ (n.metadata)
+      : {};
+  const tc =
+    n?.taskConfiguration && typeof n.taskConfiguration === 'object' && !Array.isArray(n.taskConfiguration)
+      ? /** @type {Record<string, unknown>} */ (n.taskConfiguration)
+      : {};
+  return { ...meta, ...tc };
+}
+
+/**
+ * @param {unknown} node
+ * @returns {string | undefined}
+ */
+export function resolveMemorixItemDescriptorIdFromNode(node) {
+  return resolveMemorixItemDescriptorId(nodeAuthoringBag(node));
+}
+
+/**
+ * Collect unique Memorix item descriptor ids from scoped-data-reader nodes.
+ *
+ * @param {unknown} graph
+ * @returns {string[]}
+ */
+export function collectMemorixItemDescriptorIdsFromGraph(graph) {
+  /** @type {Set<string>} */
+  const ids = new Set();
+  const nodes = Array.isArray(graph?.nodes)
+    ? graph.nodes
+    : graph?.nodes && typeof graph.nodes === 'object'
+      ? Object.values(graph.nodes)
+      : [];
+  for (const node of nodes) {
+    if (!node || typeof node !== 'object') continue;
+    const sk = /** @type {{ skillKey?: string }} */ (node).skillKey;
+    if (sk !== 'scoped-data-reader') continue;
+    const bag = nodeAuthoringBag(node);
+    const id = resolveMemorixItemDescriptorId(bag);
+    if (id) ids.add(id);
+    const pack = bag.pack;
+    if (Array.isArray(pack)) {
+      for (const slot of pack) {
+        if (!slot || typeof slot !== 'object') continue;
+        const slotId = resolveMemorixItemDescriptorId(/** @type {Record<string, unknown>} */ (slot));
+        if (slotId) ids.add(slotId);
+      }
+    }
+  }
+  return [...ids].sort();
+}
+
+/**
+ * @param {unknown} node
+ * @returns {boolean}
+ */
+export function nodeUsesLegacyScopingMapId(node) {
+  const bag = nodeAuthoringBag(node);
+  const legacy = typeof bag.scopingMapId === 'string' ? bag.scopingMapId.trim() : '';
+  return !!legacy && !resolveMemorixItemDescriptorId(bag);
+}

package/src/lib/nodeMetadataAccessors.js

@@ -0,0 +1,59 @@
+/**
+ * Canonical graph-engine 5.0+ readers for task execution fields on **`taskConfiguration`**.
+ *
+ * Legacy shapes (`metadata.aiTaskProfile`, …) are migrated on load by
+ * {@link migrateGraphDocumentTaskNodesForEngine5} and {@link migrateTaskNodeWebQueryTemplate}.
+ */
+
+export {
+  readWebScoping,
+  readNodeWebScopingEnabled,
+  readNodeWebScopingQuestions,
+  readNodeWebQueryTemplate,
+  readNodeWebQueryTemplates,
+  readNodeWebScopeOptions,
+  readNodeWebScopeEnabled,
+  readNodeWebQueryStrings,
+  readAiTaskProfile,
+  patchWebQueryTemplateOnNode,
+  patchWebScopingOnNode,
+  migrateTaskNodeWebQueryTemplate,
+} from './webQueryTemplate.js';
+
+import { readTaskConfiguration } from './taskNodeConfiguration.js';
+
+/**
+ * @param {unknown} node
+ * @returns {Record<string, unknown> | null}
+ */
+function readAiTaskProfileLocal(node) {
+  const tc = readTaskConfiguration(node);
+  if (!tc) return null;
+  const profile = tc.aiTaskProfile;
+  if (!profile || typeof profile !== 'object' || Array.isArray(profile)) return null;
+  return /** @type {Record<string, unknown>} */ (profile);
+}
+
+/**
+ * @param {unknown} node
+ * @returns {Record<string, unknown> | null}
+ */
+export function readInputSynthesis(node) {
+  const profile = readAiTaskProfileLocal(node);
+  if (!profile) return null;
+  const is = profile.inputSynthesis;
+  if (!is || typeof is !== 'object' || Array.isArray(is)) return null;
+  return /** @type {Record<string, unknown>} */ (is);
+}
+
+/**
+ * PRE synthesized-context phase is active iff
+ * `taskConfiguration.aiTaskProfile.inputSynthesis.enabled === true`.
+ *
+ * @param {unknown} node
+ * @returns {boolean}
+ */
+export function readNodeInputSynthesisEnabled(node) {
+  const is = readInputSynthesis(node);
+  return is != null && is.enabled === true;
+}