@exellix/graphs-studio-data-flow 0.1.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@exellix/graphs-studio-data-flow",
+  "version": "0.1.0",
+  "description": "Information Flow (data-flow) layer helpers for Graphs Studio.",
+  "type": "module",
+  "engines": {
+    "node": ">=20.19.0 || >=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/exellix/graphs-studio.git",
+    "directory": "packages/graphs-studio-data-flow"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./planning": "./src/planning.js",
+    "./lib/memorixScopedConfig.js": "./src/lib/memorixScopedConfig.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "prepublishOnly": "node --test tests/graphs-studio-data-flow.test.mjs"
+  },
+  "dependencies": {
+    "@exellix/graph-engine": "^9.2.3"
+  }
+}

package/src/graphContractMetadata.js

@@ -0,0 +1,484 @@
+/**
+ * View-model + patch helpers for metadata.graphEntry / metadata.graphResponse.
+ * Prefers request/response field names; falls back to legacy execution/finalOutput keys.
+ */
+
+import { normalizeConditionsDataFilters } from './lib/recordEligibilityRules.js';
+import { normalizeGraphEntryInputTypes } from './lib/memorixEntityContentTypes.js';
+import { normalizeFlatRuntimeInput } from './lib/flatRuntimeInput.js';
+
+/**
+ * Default example body format from semantic input `kind` (authoring hint only).
+ * @param {string} kind
+ * @returns {import('../types/graphContracts').GraphEntryExampleFormat}
+ */
+export function inferExampleFormatForInputKind(kind) {
+  const k = String(kind).toLowerCase();
+  if (k === 'content') return 'markdown';
+  if (k === 'query' || k === 'user-input' || k === 'text') return 'text';
+  if (k === 'record' || k === 'metadata') return 'json';
+  return 'json';
+}
+
+/**
+ * Normalize `metadata.graphEntry.exampleInput` (graph-level sample).
+ * @param {unknown} ge `graph.metadata.graphEntry`
+ * @returns {import('../types/graphContracts').GraphEntryExampleInput}
+ */
+export function normalizeGraphEntryExampleInput(ge) {
+  if (!ge || typeof ge !== 'object') return { format: 'json', value: '' };
+  const ex = /** @type {Record<string, unknown>} */ (ge).exampleInput;
+  if (!ex || typeof ex !== 'object') return { format: 'json', value: '' };
+  const fmt = ex.format === 'markdown' || ex.format === 'text' || ex.format === 'json' ? ex.format : 'json';
+  const value = typeof ex.value === 'string' ? ex.value : '';
+  const title = typeof ex.title === 'string' ? ex.title : undefined;
+  return title ? { format: fmt, value, title } : { format: fmt, value };
+}
+
+/**
+ * Normalize plural graph-entry examples. Falls back to the legacy single `exampleInput`.
+ * @param {unknown} ge `graph.metadata.graphEntry`
+ * @returns {import('../types/graphContracts').GraphEntryExampleInput[]}
+ */
+export function normalizeGraphEntryExampleInputs(ge) {
+  if (!ge || typeof ge !== 'object') return [];
+  const raw = /** @type {Record<string, unknown>} */ (ge).exampleInputs;
+  if (Array.isArray(raw)) {
+    return raw
+      .map((item) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
+        const o = /** @type {Record<string, unknown>} */ (item);
+        const fmt = o.format === 'markdown' || o.format === 'text' || o.format === 'json' ? o.format : 'json';
+        const value = typeof o.value === 'string' ? o.value : '';
+        const title = typeof o.title === 'string' ? o.title.trim() : '';
+        return title ? { format: fmt, value, title } : { format: fmt, value };
+      })
+      .filter(Boolean);
+  }
+  const single = normalizeGraphEntryExampleInput(ge);
+  if (single.value.trim()) return [single];
+
+  const src = /** @type {Record<string, unknown>} */ (ge);
+  const legacy = src.requestExample !== undefined ? src.requestExample : src.executionExample;
+  if (legacy != null && typeof legacy === 'object' && !Array.isArray(legacy)) {
+    const flat = normalizeFlatRuntimeInput(/** @type {Record<string, unknown>} */ (legacy));
+    if (Object.keys(flat).length > 0) {
+      return [{ format: 'json', value: JSON.stringify(flat) }];
+    }
+  }
+  return [];
+}
+
+/**
+ * Normalize plural graph-response final output examples. Falls back to the legacy
+ * single `responseExample` / `finalOutputExample` object.
+ * @param {unknown} gr `graph.metadata.graphResponse`
+ * @returns {import('../types/graphContracts').GraphResponseOutputExample[]}
+ */
+export function normalizeGraphResponseOutputExamples(gr) {
+  if (!gr || typeof gr !== 'object') return [];
+  const src = /** @type {Record<string, unknown>} */ (gr);
+  const raw = src.outputExamples;
+  if (Array.isArray(raw)) {
+    return raw
+      .map((item) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
+        const o = /** @type {Record<string, unknown>} */ (item);
+        const fmt = o.format === 'markdown' || o.format === 'text' || o.format === 'json' ? o.format : 'json';
+        const value = typeof o.value === 'string' ? o.value : '';
+        const title = typeof o.title === 'string' ? o.title.trim() : '';
+        return title ? { format: fmt, value, title } : { format: fmt, value };
+      })
+      .filter(Boolean);
+  }
+
+  const single = src.responseExample !== undefined ? src.responseExample : src.finalOutputExample;
+  if (single === undefined) return [];
+  try {
+    return [{ format: 'json', value: JSON.stringify(single, null, 2) }];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Normalize data-level filters stored on `metadata.graphEntry.inputs[]`.
+ * Keys may be authored as `field` or `data.field`; persisted keys are relative to `data`.
+ * @param {unknown} value
+ * @returns {Record<string, unknown>|undefined}
+ */
+export function normalizeGraphEntryDataFilters(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (const [rawKey, rawValue] of Object.entries(/** @type {Record<string, unknown>} */ (value))) {
+    const key = String(rawKey)
+      .trim()
+      .replace(/^data\./, '');
+    if (!key || !/^[\w.]+$/.test(key)) continue;
+    const valueType = typeof rawValue;
+    if (rawValue == null) continue;
+    if (valueType === 'string' || valueType === 'number' || valueType === 'boolean') {
+      out[key] = rawValue;
+      continue;
+    }
+    if (Array.isArray(rawValue) && rawValue.every((v) => typeof v === 'string' || typeof v === 'number')) {
+      out[key] = rawValue;
+      continue;
+    }
+    if (rawValue && typeof rawValue === 'object' && !Array.isArray(rawValue)) {
+      /** @type {Record<string, unknown>} */
+      const ops = {};
+      for (const op of ['$gte', '$lte', '$gt', '$lt', '$eq', '$ne']) {
+        const opValue = /** @type {Record<string, unknown>} */ (rawValue)[op];
+        if (opValue == null) continue;
+        if (
+          typeof opValue === 'string' ||
+          typeof opValue === 'number' ||
+          typeof opValue === 'boolean' ||
+          (Array.isArray(opValue) && opValue.every((v) => typeof v === 'string' || typeof v === 'number'))
+        ) {
+          ops[op] = opValue;
+        }
+      }
+      if (Object.keys(ops).length) out[key] = ops;
+    }
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+/**
+ * Infer graph-entry record slots from task-node `inputsConfig.record` bindings.
+ *
+ * @param {unknown} nodes
+ * @returns {import('../types/graphContracts').GraphEntryInputSpec[]}
+ */
+export function inferGraphEntryInputsFromTaskNodes(nodes) {
+  if (!Array.isArray(nodes)) return [];
+  /** @type {Map<string, import('../types/graphContracts').GraphEntryInputSpec>} */
+  const byPath = new Map();
+  for (const node of nodes) {
+    if (!node || typeof node !== 'object' || Array.isArray(node) || /** @type {{ type?: unknown }} */ (node).type !== 'task') {
+      continue;
+    }
+    const inputsConfig = /** @type {{ record?: unknown }} */ (node).inputsConfig;
+    if (!inputsConfig || typeof inputsConfig !== 'object' || Array.isArray(inputsConfig)) continue;
+    const record = /** @type {{ type?: unknown; path?: unknown }} */ (inputsConfig).record;
+    if (!record || typeof record !== 'object' || Array.isArray(record)) continue;
+    if (record.type !== 'executionMemoryPath') continue;
+    const path = typeof record.path === 'string' ? record.path.trim() : '';
+    if (!path || path === 'input.raw') continue;
+    if (!byPath.has(path)) {
+      byPath.set(path, { kind: 'record', path, required: true });
+    }
+  }
+  return [...byPath.values()];
+}
+
+/**
+ * Effective graph-entry contract for simulate/run: persisted `metadata.graphEntry`
+ * plus inferred record slots from task nodes when the executable graph omits them.
+ *
+ * @param {unknown} graph
+ * @returns {Record<string, unknown>}
+ */
+export function resolveEffectiveGraphEntry(graph) {
+  const g = graph && typeof graph === 'object' && !Array.isArray(graph) ? /** @type {Record<string, unknown>} */ (graph) : {};
+  const md =
+    g.metadata && typeof g.metadata === 'object' && !Array.isArray(g.metadata)
+      ? /** @type {Record<string, unknown>} */ (g.metadata)
+      : {};
+  const ge =
+    md.graphEntry && typeof md.graphEntry === 'object' && !Array.isArray(md.graphEntry)
+      ? { .../** @type {Record<string, unknown>} */ (md.graphEntry) }
+      : {};
+  if (normalizeGraphEntryInputs(ge).length === 0) {
+    const inferred = inferGraphEntryInputsFromTaskNodes(g.nodes);
+    if (inferred.length > 0) ge.inputs = inferred;
+  }
+  return ge;
+}
+
+/**
+ * Ensure working metadata exposes a graph-entry input contract for Design/Simulate UI.
+ *
+ * @param {unknown} metadata
+ * @param {unknown} nodes
+ * @returns {Record<string, unknown>}
+ */
+export function ensureGraphEntryInputsOnMetadata(metadata, nodes) {
+  const md = metadata && typeof metadata === 'object' && !Array.isArray(metadata) ? { ...metadata } : {};
+  const ge =
+    md.graphEntry && typeof md.graphEntry === 'object' && !Array.isArray(md.graphEntry)
+      ? { .../** @type {Record<string, unknown>} */ (md.graphEntry) }
+      : {};
+  if (normalizeGraphEntryInputs(ge).length === 0) {
+    const inferred = inferGraphEntryInputsFromTaskNodes(nodes);
+    if (inferred.length > 0) ge.inputs = inferred;
+  }
+  if (Object.keys(ge).length > 0) md.graphEntry = ge;
+  else delete md.graphEntry;
+  return md;
+}
+
+/**
+ * Normalize `metadata.graphEntry.inputs` from persisted graph JSON (no aliases).
+ * @param {unknown} ge `graph.metadata.graphEntry`
+ * @returns {import('../types/graphContracts').GraphEntryInputSpec[]}
+ */
+export function normalizeGraphEntryInputs(ge) {
+  if (!ge || typeof ge !== 'object') return [];
+  const raw = /** @type {{ inputs?: unknown }} */ (ge).inputs;
+  if (!Array.isArray(raw)) return [];
+  /** @type {import('../types/graphContracts').GraphEntryInputSpec[]} */
+  const out = [];
+  for (const item of raw) {
+    if (!item || typeof item !== 'object') continue;
+    const o = /** @type {Record<string, unknown>} */ (item);
+    const kind = typeof o.kind === 'string' ? o.kind.trim() : '';
+    const path = typeof o.path === 'string' ? o.path.trim() : '';
+    const hasSelection = ['entityIds', 'inputTypes', 'narrativeTypeIds', 'scopingQuestionIds'].some((key) => {
+      const rawList = o[key];
+      return Array.isArray(rawList) && rawList.some((v) => typeof v === 'string' && v.trim());
+    });
+    if (!kind && !path && !hasSelection) continue;
+    /** @type {import('../types/graphContracts').GraphEntryInputSpec} */
+    const spec = {
+      kind,
+      path,
+      required: Boolean(o.required),
+    };
+    if (o.cardinality === 'many' || o.cardinality === 'one') spec.cardinality = o.cardinality;
+    for (const key of ['entityIds', 'narrativeTypeIds', 'scopingQuestionIds']) {
+      const rawList = o[key];
+      if (Array.isArray(rawList)) {
+        const list = rawList.map((v) => (typeof v === 'string' ? v.trim() : '')).filter(Boolean);
+        if (list.length) spec[key] = list;
+      }
+    }
+    const inputTypes = normalizeGraphEntryInputTypes(o.inputTypes);
+    if (inputTypes) spec.inputTypes = inputTypes;
+    if (typeof o.name === 'string' && o.name.trim()) spec.name = o.name.trim();
+    if (typeof o.title === 'string' && o.title.trim()) spec.title = o.title.trim();
+    if (typeof o.description === 'string' && o.description.trim()) spec.description = o.description.trim();
+    const dataFilters = normalizeGraphEntryDataFilters(o.dataFilters);
+    if (dataFilters) spec.dataFilters = dataFilters;
+    if ('schema' in o) spec.schema = o.schema;
+    const example = typeof o.example === 'string' ? o.example : '';
+    const exFmt =
+      o.exampleFormat === 'markdown' || o.exampleFormat === 'text' || o.exampleFormat === 'json'
+        ? o.exampleFormat
+        : undefined;
+    if (example.trim()) {
+      spec.example = example.trim();
+      spec.exampleFormat = exFmt ?? inferExampleFormatForInputKind(kind);
+    } else if (exFmt) {
+      spec.exampleFormat = exFmt;
+    }
+    out.push(spec);
+  }
+  return out;
+}
+
+/**
+ * Normalize `metadata.graphEntry.conditions` (narratives, record gates, `aiCondition`, catalog ids).
+ *
+ * @param {unknown} raw
+ * @returns {import('../types/graphContracts').GraphEntryConditions | undefined}
+ */
+export function normalizeGraphEntryConditions(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+  const src = /** @type {Record<string, unknown>} */ (raw);
+  const narratives = Array.isArray(src.narratives)
+    ? src.narratives.map((x) => String(x).trim()).filter(Boolean)
+    : [];
+  let aiCondition;
+  if (src.aiCondition && typeof src.aiCondition === 'object' && !Array.isArray(src.aiCondition)) {
+    const ac = /** @type {Record<string, unknown>} */ (src.aiCondition);
+    const cond = typeof ac.condition === 'string' ? ac.condition.trim() : '';
+    if (cond) aiCondition = { ...ac, condition: cond };
+  } else if (typeof src.aiFilter === 'string' && src.aiFilter.trim()) {
+    aiCondition = { condition: src.aiFilter.trim() };
+  }
+  const df = normalizeConditionsDataFilters(src.dataFilters);
+  const catalogIds = Array.isArray(src.dataFilters)
+    ? src.dataFilters.map((x) => String(x).trim()).filter(Boolean)
+    : [];
+  /** @type {import('../types/graphContracts').GraphEntryConditions} */
+  const out = {};
+  if (narratives.length) out.narratives = narratives;
+  if (df && Array.isArray(df.rules) && df.rules.length > 0) out.dataFilters = df;
+  else if (catalogIds.length) out.dataFilters = catalogIds;
+  if (aiCondition) out.aiCondition = aiCondition;
+  if (src.jsonConditions && typeof src.jsonConditions === 'object' && !Array.isArray(src.jsonConditions)) {
+    out.jsonConditions = src.jsonConditions;
+  }
+  if (src.jsConditionFunction && typeof src.jsConditionFunction === 'object' && !Array.isArray(src.jsConditionFunction)) {
+    out.jsConditionFunction = src.jsConditionFunction;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+/** @param {unknown} o @param {string} k */
+function hasOwn(o, k) {
+  return o != null && typeof o === 'object' && Object.prototype.hasOwnProperty.call(o, k);
+}
+
+/**
+ * Heuristic: paths that look like trace/debug go to debug bucket when splitting legacy `notableExecutionPaths`.
+ * @param {string} s
+ */
+export function isDebugResponsePath(s) {
+  const lower = String(s).toLowerCase();
+  return (
+    lower.includes('_trace') ||
+    lower.includes('.trace') ||
+    lower.includes('debug') ||
+    lower.endsWith('trace')
+  );
+}
+
+/**
+ * @param {string[]|undefined} paths
+ * @returns {{ primary: string[], debug: string[] }}
+ */
+export function splitNotableExecutionPaths(paths) {
+  const primary = [];
+  const debug = [];
+  if (!Array.isArray(paths)) return { primary, debug };
+  for (const p of paths) {
+    const s = String(p).trim();
+    if (!s) continue;
+    if (isDebugResponsePath(s)) debug.push(s);
+    else primary.push(s);
+  }
+  return { primary, debug };
+}
+
+/**
+ * @param {Record<string, unknown>|undefined} metadata  `graph.metadata`
+ * @returns {{
+ *   summary: string;
+ *   inputs: import('../types/graphContracts').GraphEntryInputSpec[];
+ *   exampleInput: import('../types/graphContracts').GraphEntryExampleInput;
+ *   exampleInputs: import('../types/graphContracts').GraphEntryExampleInput[];
+ *   requestExample: unknown;
+ *   requestSchema: unknown;
+ *   requiredRequestPaths: string[];
+ *   conditions: import('../types/graphContracts').GraphEntryConditions | Record<string, never>;
+ * }}
+ */
+export function getEntryRequestViewState(metadata) {
+  const ge = metadata?.graphEntry;
+  if (!ge || typeof ge !== 'object') {
+    return {
+      summary: '',
+      inputs: [],
+      exampleInput: { format: 'json', value: '' },
+      exampleInputs: [],
+      requestExample: undefined,
+      requestSchema: undefined,
+      requiredRequestPaths: [],
+      conditions: {},
+    };
+  }
+  return {
+    summary: typeof ge.summary === 'string' ? ge.summary : '',
+    inputs: normalizeGraphEntryInputs(ge),
+    exampleInput: normalizeGraphEntryExampleInput(ge),
+    exampleInputs: normalizeGraphEntryExampleInputs(ge),
+    requestExample: ge.requestExample !== undefined ? ge.requestExample : ge.executionExample,
+    requestSchema: ge.requestSchema !== undefined ? ge.requestSchema : ge.executionSchema,
+    requiredRequestPaths: Array.isArray(ge.requiredExecutionPaths) ? [...ge.requiredExecutionPaths] : [],
+    conditions: normalizeGraphEntryConditions(ge.conditions) ?? {},
+  };
+}
+
+/** @param {Record<string, unknown>|undefined} metadata  `graph.metadata` @param {unknown} [rootResponse] canonical `graph.response` */
+export function getResponseViewState(metadata, rootResponse) {
+  const studio = metadata?.graphsStudio && typeof metadata.graphsStudio === 'object' ? metadata.graphsStudio : {};
+  const gr =
+    metadata?.graphResponse && typeof metadata.graphResponse === 'object'
+      ? metadata.graphResponse
+      : studio?.graphResponse && typeof studio.graphResponse === 'object'
+        ? studio.graphResponse
+        : undefined;
+  const root = rootResponse && typeof rootResponse === 'object' && !Array.isArray(rootResponse) ? rootResponse : undefined;
+  if (!gr && !root) {
+    return {
+      summary: '',
+      responseExample: undefined,
+      outputExamples: [],
+      responseSchema: undefined,
+      responseMapping: undefined,
+      primaryResponsePaths: [],
+      debugResponsePaths: [],
+    };
+  }
+
+  const summary = typeof gr?.summary === 'string' ? gr.summary : '';
+  const responseExample = gr?.responseExample !== undefined ? gr.responseExample : gr?.finalOutputExample;
+  const responseSchema = gr?.responseSchema !== undefined ? gr.responseSchema : gr?.finalOutputSchema;
+  const responseMapping = root !== undefined ? root : gr?.responseMapping !== undefined ? gr.responseMapping : undefined;
+
+  let primaryResponsePaths;
+  let debugResponsePaths;
+
+  if (gr && (hasOwn(gr, 'primaryResponsePaths') || hasOwn(gr, 'debugResponsePaths'))) {
+    primaryResponsePaths = Array.isArray(gr.primaryResponsePaths) ? [...gr.primaryResponsePaths] : [];
+    debugResponsePaths = Array.isArray(gr.debugResponsePaths) ? [...gr.debugResponsePaths] : [];
+  } else {
+    const split = splitNotableExecutionPaths(gr?.notableExecutionPaths);
+    primaryResponsePaths = split.primary;
+    debugResponsePaths = split.debug;
+  }
+
+  return {
+    summary,
+    responseExample,
+    outputExamples: normalizeGraphResponseOutputExamples(gr),
+    responseSchema,
+    responseMapping,
+    primaryResponsePaths,
+    debugResponsePaths,
+  };
+}
+
+/**
+ * Shallow patch with undefined = delete key.
+ * @param {Record<string, unknown>|undefined} prev
+ * @param {Record<string, unknown>} patch
+ */
+export function applyObjectPatch(prev, patch) {
+  const base = { ...(prev && typeof prev === 'object' ? prev : {}) };
+  for (const [k, v] of Object.entries(patch)) {
+    if (v === undefined) delete base[k];
+    else base[k] = v;
+  }
+  return base;
+}
+
+/**
+ * @param {Record<string, unknown>|undefined} prevGe
+ * @param {Record<string, unknown>} patch
+ */
+export function applyGraphEntryPatch(prevGe, patch) {
+  return applyObjectPatch(prevGe, patch);
+}
+
+/**
+ * Keeps `notableExecutionPaths` aligned with primary + debug for older consumers.
+ * @param {Record<string, unknown>|undefined} prevGr
+ * @param {Record<string, unknown>} patch
+ */
+export function applyGraphResponsePatch(prevGr, patch) {
+  const base = applyObjectPatch(prevGr, patch);
+  if (hasOwn(patch, 'primaryResponsePaths') || hasOwn(patch, 'debugResponsePaths')) {
+    const p = Array.isArray(base.primaryResponsePaths) ? base.primaryResponsePaths : [];
+    const d = Array.isArray(base.debugResponsePaths) ? base.debugResponsePaths : [];
+    const merged = [...new Set([...p, ...d].map((x) => String(x).trim()).filter(Boolean))];
+    if (merged.length) base.notableExecutionPaths = merged;
+    else delete base.notableExecutionPaths;
+  }
+  return base;
+}

package/src/index.js

@@ -0,0 +1,8 @@
+export * from './informationFlowLayerDocument.js';
+export { applyInformationFlowLayerToGraph as applyDataFlowLayerToGraph } from './informationFlowLayerDocument.js';
+
+export {
+  getEntryRequestViewState,
+  getResponseViewState,
+  isDebugResponsePath,
+} from './graphContractMetadata.js';