@exellix/graphs-studio-data-flow 0.1.0

package/src/lib/taskNodeConfiguration.js

@@ -0,0 +1,117 @@
+/**
+ * Task-node execution authoring — graph-engine 5.0+ (`taskConfiguration`), not `metadata`.
+ *
+ * Pure metadata on task nodes is allowlisted in `@exellix/graph-engine` (graphReadability,
+ * catalogBinding, …); execution wiring lives here.
+ */
+
+/**
+ * @param {unknown} node
+ * @returns {Record<string, unknown> | null}
+ */
+export function readTaskConfiguration(node) {
+  if (!node || typeof node !== 'object' || Array.isArray(node)) return null;
+  const n = /** @type {Record<string, unknown>} */ (node);
+  const tc = n.taskConfiguration;
+  if (tc && typeof tc === 'object' && !Array.isArray(tc)) {
+    return /** @type {Record<string, unknown>} */ (tc);
+  }
+  const params = n.parameters;
+  if (params && typeof params === 'object' && !Array.isArray(params)) {
+    const ptc = /** @type {Record<string, unknown>} */ (params).taskConfiguration;
+    if (ptc && typeof ptc === 'object' && !Array.isArray(ptc)) {
+      return /** @type {Record<string, unknown>} */ (ptc);
+    }
+  }
+  return null;
+}
+
+/**
+ * Shallow node copy with an isolated `taskConfiguration` bag (avoids cross-node mutation when
+ * template/import code reused the same `taskConfiguration` object on multiple nodes).
+ *
+ * @template {Record<string, unknown>} T
+ * @param {T} node
+ * @returns {T}
+ */
+export function cloneNodeForTaskConfigurationEdit(node) {
+  if (!node || typeof node !== 'object' || Array.isArray(node)) {
+    return /** @type {T} */ (node);
+  }
+  const copy = { ...node };
+  const tc = node.taskConfiguration;
+  if (tc && typeof tc === 'object' && !Array.isArray(tc)) {
+    try {
+      if (typeof structuredClone === 'function') {
+        copy.taskConfiguration = structuredClone(tc);
+      } else {
+        copy.taskConfiguration = JSON.parse(JSON.stringify(tc));
+      }
+    } catch {
+      copy.taskConfiguration = { .../** @type {Record<string, unknown>} */ (tc) };
+    }
+  }
+  if ('modelConfig' in copy) delete copy.modelConfig;
+  return /** @type {T} */ (copy);
+}
+
+/**
+ * @param {Record<string, unknown>} node mutates
+ * @returns {Record<string, unknown>}
+ */
+export function ensureTaskConfiguration(node) {
+  if (
+    !node.taskConfiguration ||
+    typeof node.taskConfiguration !== 'object' ||
+    Array.isArray(node.taskConfiguration)
+  ) {
+    node.taskConfiguration = {};
+  }
+  return /** @type {Record<string, unknown>} */ (node.taskConfiguration);
+}
+
+/**
+ * @param {Record<string, unknown>} node mutates
+ * @param {(input: Record<string, unknown>) => Record<string, unknown> | undefined} update
+ */
+export function patchInputSynthesisOnNode(node, update) {
+  const tc = ensureTaskConfiguration(node);
+  const profileRaw = tc.aiTaskProfile;
+  const profile =
+    profileRaw && typeof profileRaw === 'object' && !Array.isArray(profileRaw)
+      ? /** @type {Record<string, unknown>} */ ({ ...profileRaw })
+      : {};
+  const isRaw = profile.inputSynthesis;
+  const current =
+    isRaw && typeof isRaw === 'object' && !Array.isArray(isRaw)
+      ? /** @type {Record<string, unknown>} */ ({ ...isRaw })
+      : {};
+  const next = update(current);
+  if (!next || Object.keys(next).length === 0) {
+    delete profile.inputSynthesis;
+  } else {
+    profile.inputSynthesis = next;
+  }
+  if (Object.keys(profile).length === 0) {
+    delete tc.aiTaskProfile;
+  } else {
+    tc.aiTaskProfile = profile;
+  }
+  pruneEmptyTaskConfiguration(node);
+}
+
+export { patchWebQueryTemplateOnNode, patchWebScopingOnNode } from './webQueryTemplate.js';
+
+/**
+ * Drop empty `taskConfiguration` after edits.
+ *
+ * @param {unknown} node mutates
+ */
+export function pruneEmptyTaskConfiguration(node) {
+  if (!node || typeof node !== 'object' || Array.isArray(node)) return;
+  const tc = /** @type {Record<string, unknown>} */ (node).taskConfiguration;
+  if (!tc || typeof tc !== 'object' || Array.isArray(tc)) return;
+  if (Object.keys(tc).length === 0) {
+    delete /** @type {Record<string, unknown>} */ (node).taskConfiguration;
+  }
+}

package/src/lib/webQueryTemplate.js

@@ -0,0 +1,277 @@
+/**
+ * Graphenix 2.7.3+ web scope authoring on `taskConfiguration.aiTaskProfile.webQueryTemplate`.
+ * Replaces legacy `aiTaskProfile.webScoping` and narrix web keys.
+ */
+
+import { readTaskConfiguration, ensureTaskConfiguration, pruneEmptyTaskConfiguration } from './taskNodeConfiguration.js';
+
+/** Narrix keys forbidden under `taskConfiguration.narrix` (graph-engine 8.6). */
+export const FORBIDDEN_NARRIX_WEB_KEYS = Object.freeze([
+  'enableWebScope',
+  'forceWebScope',
+  'webScopeQuestions',
+  'webScoping',
+  'webScopeTemplates',
+  'webScopeQuestionTemplate',
+  'webScopeObjects',
+  'webScopeEntityIdPath',
+  'webScopeEntityTypePath',
+  'enrichWebScopeQuestionFromExecutionRaw',
+]);
+
+/**
+ * @param {unknown} node
+ * @returns {Record<string, unknown> | null}
+ */
+export function readAiTaskProfile(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);
+}
+
+function cleanString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+/**
+ * @param {unknown} profile
+ * @returns {boolean}
+ */
+export function hasWebScopeAuthoring(profile) {
+  if (!profile || typeof profile !== 'object' || Array.isArray(profile)) return false;
+  const p = /** @type {Record<string, unknown>} */ (profile);
+  if (cleanString(p.webQueryTemplate)) return true;
+  const pack = p.webQueryTemplates;
+  return (
+    Array.isArray(pack) &&
+    pack.some((entry) => typeof entry === 'string' && entry.trim().length > 0)
+  );
+}
+
+/**
+ * @param {unknown} node
+ * @returns {string}
+ */
+export function readNodeWebQueryTemplate(node) {
+  const profile = readAiTaskProfile(node);
+  return profile ? cleanString(profile.webQueryTemplate) : '';
+}
+
+/**
+ * @param {unknown} node
+ * @returns {string[]}
+ */
+export function readNodeWebQueryTemplates(node) {
+  const profile = readAiTaskProfile(node);
+  if (!profile) return [];
+  const pack = profile.webQueryTemplates;
+  if (!Array.isArray(pack)) return [];
+  return pack
+    .filter((q) => typeof q === 'string' && q.trim().length > 0)
+    .map((q) => /** @type {string} */ (q).trim());
+}
+
+/**
+ * @param {unknown} node
+ * @returns {Record<string, unknown>}
+ */
+export function readNodeWebScopeOptions(node) {
+  const profile = readAiTaskProfile(node);
+  if (!profile) return {};
+  const opts = profile.webScopeOptions;
+  if (opts && typeof opts === 'object' && !Array.isArray(opts)) {
+    return /** @type {Record<string, unknown>} */ ({ ...opts });
+  }
+  return {};
+}
+
+/**
+ * Web scope PRE unit is active when a non-empty template (or pack) is authored.
+ *
+ * @param {unknown} node
+ * @returns {boolean}
+ */
+export function readNodeWebScopeEnabled(node) {
+  return hasWebScopeAuthoring(readAiTaskProfile(node));
+}
+
+/**
+ * All authored query strings (primary + pack) for display.
+ *
+ * @param {unknown} node
+ * @returns {string[]}
+ */
+export function readNodeWebQueryStrings(node) {
+  const primary = readNodeWebQueryTemplate(node);
+  const pack = readNodeWebQueryTemplates(node);
+  if (primary && !pack.includes(primary)) return [primary, ...pack];
+  if (primary) return [primary, ...pack.filter((q) => q !== primary)];
+  return pack;
+}
+
+/** @deprecated Use {@link readNodeWebScopeOptions} for entity path hints. */
+export function readWebScoping(node) {
+  const opts = readNodeWebScopeOptions(node);
+  const legacy = readAiTaskProfile(node)?.webScoping;
+  if (legacy && typeof legacy === 'object' && !Array.isArray(legacy)) {
+    return { .../** @type {Record<string, unknown>} */ (legacy), ...opts };
+  }
+  return Object.keys(opts).length > 0 ? opts : null;
+}
+
+/** @deprecated Alias for {@link readNodeWebScopeEnabled}. */
+export function readNodeWebScopingEnabled(node) {
+  return readNodeWebScopeEnabled(node);
+}
+
+/** @deprecated Use {@link readNodeWebQueryStrings}. */
+export function readNodeWebScopingQuestions(node) {
+  return readNodeWebQueryStrings(node);
+}
+
+/**
+ * @param {Record<string, unknown>} narrix mutates
+ */
+export function stripForbiddenNarrixWebKeys(narrix) {
+  for (const k of FORBIDDEN_NARRIX_WEB_KEYS) {
+    if (k in narrix) delete narrix[k];
+  }
+}
+
+/**
+ * Migrate legacy `aiTaskProfile.webScoping` → `webQueryTemplate` on a profile object.
+ *
+ * @param {Record<string, unknown>} profile mutates
+ * @returns {boolean} true when migration changed the profile
+ */
+export function migrateLegacyWebScopingOnProfile(profile) {
+  const ws = profile.webScoping;
+  if (!ws || typeof ws !== 'object' || Array.isArray(ws)) {
+    if ('webScoping' in profile) {
+      delete profile.webScoping;
+      return true;
+    }
+    return false;
+  }
+  const legacy = /** @type {Record<string, unknown>} */ (ws);
+  let changed = false;
+
+  const fromQueryTemplate = cleanString(legacy.queryTemplate);
+  const questions = Array.isArray(legacy.questions)
+    ? legacy.questions.filter((q) => typeof q === 'string' && q.trim()).map((q) => String(q).trim())
+    : [];
+
+  if (!cleanString(profile.webQueryTemplate)) {
+    if (fromQueryTemplate) {
+      profile.webQueryTemplate = fromQueryTemplate;
+      changed = true;
+    } else if (questions.length > 0) {
+      profile.webQueryTemplate = questions[0];
+      if (questions.length > 1) {
+        profile.webQueryTemplates = questions.slice(1);
+      }
+      changed = true;
+    } else if (legacy.enabled === true) {
+      profile.webQueryTemplate = '{{input.question}}';
+      changed = true;
+    }
+  }
+
+  delete profile.webScoping;
+  return true;
+}
+
+/**
+ * @param {Record<string, unknown>} node mutates
+ * @returns {boolean}
+ */
+export function migrateTaskNodeWebQueryTemplate(node) {
+  if (!node || typeof node !== 'object' || Array.isArray(node)) return false;
+  if (node.type === 'finalizer') return false;
+  let changed = false;
+
+  const tc = ensureTaskConfiguration(node);
+  const profileRaw = tc.aiTaskProfile;
+  const profile =
+    profileRaw && typeof profileRaw === 'object' && !Array.isArray(profileRaw)
+      ? /** @type {Record<string, unknown>} */ ({ ...profileRaw })
+      : null;
+
+  if (profile) {
+    if (migrateLegacyWebScopingOnProfile(profile)) changed = true;
+    tc.aiTaskProfile = profile;
+  }
+
+  const narrixRaw = tc.narrix;
+  if (narrixRaw && typeof narrixRaw === 'object' && !Array.isArray(narrixRaw)) {
+    const narrix = /** @type {Record<string, unknown>} */ ({ ...narrixRaw });
+    const before = JSON.stringify(narrix);
+    stripForbiddenNarrixWebKeys(narrix);
+    if (JSON.stringify(narrix) !== before) {
+      tc.narrix = Object.keys(narrix).length > 0 ? narrix : undefined;
+      if (!tc.narrix) delete tc.narrix;
+      changed = true;
+    }
+  }
+
+  pruneEmptyTaskConfiguration(node);
+  return changed;
+}
+
+/**
+ * @param {Record<string, unknown>} doc mutates
+ */
+export function migrateAuthoringDocWebQueryTemplate(doc) {
+  const nodes = doc.nodes ?? doc.graph?.nodes;
+  if (!Array.isArray(nodes)) return;
+  for (const node of nodes) {
+    if (node && typeof node === 'object' && !Array.isArray(node)) {
+      migrateTaskNodeWebQueryTemplate(/** @type {Record<string, unknown>} */ (node));
+      const params = /** @type {Record<string, unknown>} */ (node).parameters;
+      if (params && typeof params === 'object' && !Array.isArray(params)) {
+        migrateTaskNodeWebQueryTemplate(params);
+      }
+    }
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} node mutates
+ * @param {(profile: Record<string, unknown>) => Record<string, unknown> | undefined} update
+ */
+export function patchWebQueryTemplateOnNode(node, update) {
+  const tc = ensureTaskConfiguration(node);
+  const profileRaw = tc.aiTaskProfile;
+  const profile =
+    profileRaw && typeof profileRaw === 'object' && !Array.isArray(profileRaw)
+      ? /** @type {Record<string, unknown>} */ ({ ...profileRaw })
+      : {};
+  migrateLegacyWebScopingOnProfile(profile);
+  const next = update(profile);
+  if (!next || Object.keys(next).length === 0) {
+    delete tc.aiTaskProfile;
+  } else {
+    migrateLegacyWebScopingOnProfile(next);
+    tc.aiTaskProfile = next;
+  }
+  pruneEmptyTaskConfiguration(node);
+}
+
+/** @deprecated Use {@link patchWebQueryTemplateOnNode}. */
+export function patchWebScopingOnNode(node, update) {
+  return patchWebQueryTemplateOnNode(node, (profile) => {
+    const ws = profile.webScoping;
+    const current =
+      ws && typeof ws === 'object' && !Array.isArray(ws)
+        ? /** @type {Record<string, unknown>} */ ({ ...ws })
+        : {};
+    const next = update(current);
+    if (!next || Object.keys(next).length === 0) {
+      const { webScoping: _drop, ...rest } = profile;
+      return Object.keys(rest).length > 0 ? rest : undefined;
+    }
+    return { ...profile, webScoping: next };
+  });
+}

package/src/pathClassification.js

@@ -0,0 +1,133 @@
+/**
+ * Classify execution-memory paths for Information Flow grouping and display.
+ */
+import { isDebugResponsePath } from './graphContractMetadata.js';
+
+/**
+ * @typedef {'input'|'scoped'|'inference'|'triage'|'scopedAnswer'|'response'|'trace'|'external'|'meta'|'job'|'task'|'xynthesized'|'xynthesis'|'other'} PathClassification
+ */
+
+/**
+ * @param {string} path
+ * @returns {{ namespace: string, classification: PathClassification, displayPath: string }}
+ */
+export function classifyExecutionPath(path) {
+  const raw = String(path || '').trim();
+  if (!raw) {
+    return { namespace: 'other', classification: 'other', displayPath: '' };
+  }
+
+  if (raw.startsWith('xmemory-op:')) {
+    return {
+      namespace: 'xmemory-op',
+      classification: 'external',
+      displayPath: raw,
+    };
+  }
+  if (raw.startsWith('xmemory-meta:')) {
+    return {
+      namespace: 'xmemory-meta',
+      classification: 'meta',
+      displayPath: raw,
+    };
+  }
+
+  if (raw === 'finalOutput') {
+    return { namespace: 'finalOutput', classification: 'response', displayPath: 'finalOutput' };
+  }
+
+  if (raw.startsWith('execution._trace') || raw.includes('._trace.') || isDebugResponsePath(raw)) {
+    return {
+      namespace: '_trace',
+      classification: 'trace',
+      displayPath: stripExecutionPrefix(raw),
+    };
+  }
+
+  // Distinguish synthesis-context memory snapshot (xynthesized) from PRE/POST utility outputs (xynthesis).
+  if (raw.startsWith('execution.xynthesized.')) {
+    return {
+      namespace: 'xynthesized',
+      classification: 'xynthesized',
+      displayPath: stripExecutionPrefix(raw),
+    };
+  }
+  if (raw.startsWith('execution.xynthesis.')) {
+    return {
+      namespace: 'xynthesis',
+      classification: 'xynthesis',
+      displayPath: stripExecutionPrefix(raw),
+    };
+  }
+
+  let rest = raw;
+  if (rest.startsWith('execution.')) {
+    rest = rest.slice('execution.'.length);
+  }
+
+  const first = rest.split('.')[0] || '';
+
+  if (first === 'input' || raw.startsWith('execution.input.')) {
+    return {
+      namespace: 'input',
+      classification: 'input',
+      displayPath: rest.startsWith('input.') ? rest.slice('input.'.length) : rest,
+    };
+  }
+
+  if (first === 'scoped' || rest.startsWith('scoped.')) {
+    return {
+      namespace: 'scoped',
+      classification: 'scoped',
+      displayPath: rest,
+    };
+  }
+  if (first === 'inference' || rest.startsWith('inference.')) {
+    return {
+      namespace: 'inference',
+      classification: 'inference',
+      displayPath: rest,
+    };
+  }
+  if (first === 'triage' || rest.startsWith('triage.')) {
+    return {
+      namespace: 'triage',
+      classification: 'triage',
+      displayPath: rest,
+    };
+  }
+  if (first === 'scopedAnswer' || rest.startsWith('scopedAnswer.')) {
+    return {
+      namespace: 'scopedAnswer',
+      classification: 'scopedAnswer',
+      displayPath: rest,
+    };
+  }
+
+  if (rest.startsWith('jobMemory.') || rest.startsWith('jobContext.') || raw.startsWith('jobMemory.')) {
+    return {
+      namespace: 'job',
+      classification: 'job',
+      displayPath: rest,
+    };
+  }
+  if (rest.startsWith('taskMemory.') || raw.startsWith('taskMemory.')) {
+    return {
+      namespace: 'task',
+      classification: 'task',
+      displayPath: rest,
+    };
+  }
+
+  return {
+    namespace: first || 'other',
+    classification: 'other',
+    displayPath: rest,
+  };
+}
+
+/** Prefer short labels: input.* instead of execution.input.* */
+function stripExecutionPrefix(p) {
+  if (p.startsWith('execution.')) return p.slice('execution.'.length);
+  return p;
+}

package/src/planning.js

@@ -0,0 +1,3 @@
+export { buildPlanningInformationFlow } from './informationFlow.js';
+export { buildFocusedInformationFlow } from './informationFlowFocus.js';
+export { buildInformationFlowOutputSurface } from './informationFlowOutputSurface.js';

package/src/planningSourceFamily.js

@@ -0,0 +1,109 @@
+/**
+ * Planning source families for Information Flow — editor-only classification.
+ * @typedef {'scoped-read'|'web-scope'|'other'|'none'} PlanningSourceFamily
+ */
+import { readNodeWebScopeEnabled, readNodeWebQueryTemplate } from './lib/nodeMetadataAccessors.js';
+import { readTaskConfiguration } from './lib/taskNodeConfiguration.js';
+
+/** Future dedicated web retrieval / search skills; aiTaskProfile.webQueryTemplate is primary. */
+export const WEB_SCOPE_SKILL_KEYS = [];
+
+const FAMILY_LABEL = {
+  'scoped-read': 'Scoped read',
+  'web-scope': 'Web scope',
+  other: 'Other',
+  none: '—',
+};
+
+const SECTION_ORDER = ['scoped-read', 'web-scope'];
+
+/**
+ * @param {object|null|undefined} node
+ * @returns {PlanningSourceFamily}
+ */
+export function getPlanningSourceFamily(node) {
+  if (!node || typeof node !== 'object') return 'none';
+  if (node.skillKey === 'scoped-data-reader') return 'scoped-read';
+  if (node.skillKey && WEB_SCOPE_SKILL_KEYS.includes(node.skillKey)) return 'web-scope';
+  if (readNodeWebScopeEnabled(node)) return 'web-scope';
+  return 'none';
+}
+
+/**
+ * @param {PlanningSourceFamily} family
+ */
+export function getPlanningSourceFamilyLabel(family) {
+  return FAMILY_LABEL[family] || family;
+}
+
+/** Stable section order for Sources column (families only). */
+export function planningSourceFamilySectionOrder() {
+  return [...SECTION_ORDER];
+}
+
+/**
+ * @param {object} node - graph node
+ * @returns {{ lines: string[], searchText: string }}
+ */
+export function buildWebScopeCardSummary(node) {
+  if (readNodeWebScopeEnabled(node)) {
+    const narrix = node?.taskConfiguration?.narrix || node?.metadata?.narrix || {};
+    const template = readNodeWebQueryTemplate(node);
+    const lines = [];
+    const parts = [];
+
+    if (template) {
+      const s = `Template: ${template}`;
+      lines.push(s);
+      parts.push(s, template);
+    }
+    if (narrix.questionId) {
+      const s = `Question: ${narrix.questionId}`;
+      lines.push(s);
+      parts.push(s, narrix.questionId);
+    }
+    if (narrix.datasetId) {
+      const s = `Dataset: ${narrix.datasetId}`;
+      lines.push(s);
+      parts.push(s, narrix.datasetId);
+    }
+    if (narrix.layer != null && narrix.layer !== '') {
+      const s = `Layer: ${narrix.layer}`;
+      lines.push(s);
+      parts.push(s, String(narrix.layer));
+    }
+
+    if (Array.isArray(narrix.narrativeTypeIds) && narrix.narrativeTypeIds.length > 0) {
+      const short = narrix.narrativeTypeIds.slice(0, 4).join(', ');
+      const more = narrix.narrativeTypeIds.length > 4 ? ` (+${narrix.narrativeTypeIds.length - 4} more)` : '';
+      const s = `Narrative types: ${short}${more}`;
+      lines.push(s);
+      parts.push(...narrix.narrativeTypeIds.map(String));
+    }
+
+    return {
+      lines,
+      searchText: parts.join(' '),
+    };
+  }
+
+  if (node?.skillKey && WEB_SCOPE_SKILL_KEYS.includes(node.skillKey)) {
+    const sk = node.skillKey;
+    return { lines: [`Web skill: ${sk}`], searchText: sk };
+  }
+
+  return { lines: [], searchText: '' };
+}
+
+/**
+ * Sort key for web-scope flow nodes (stable, deterministic).
+ * @param {object} node - raw graph node
+ * @param {string} title - graphReadability title or id
+ */
+export function webScopeSortKey(node, title) {
+  const tcNar = readTaskConfiguration(node)?.narrix;
+  const narrix = tcNar && typeof tcNar === 'object' ? tcNar : {};
+  const q = narrix.questionId;
+  const d = narrix.datasetId;
+  return [q || '', d || '', title || '', node?.id || ''].join('\0');
+}