@exellix/graphs-studio-composer-context 0.1.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@exellix/graphs-studio-composer-context",
+  "version": "0.1.0",
+  "description": "Layer-aware composer context for Graphs Studio UI. Not @exellix/graph-composer (OpenRouter execution).",
+  "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-composer-context"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "prepublishOnly": "node --test tests/graphs-studio-composer-context.test.mjs"
+  },
+  "dependencies": {
+    "@exellix/graph-engine": "^9.2.3",
+    "@exellix/graphs-studio-concept": "^0.1.0",
+    "@exellix/graphs-studio-data-flow": "^0.1.0"
+  }
+}

package/src/composerContext.ts

@@ -0,0 +1,75 @@
+import type { GraphAnalysisResult } from './types.js';
+
+function pickNodeSummary(analysis: GraphAnalysisResult, nodeId: string) {
+  const c = analysis.nodeAnalysisById[nodeId];
+  if (!c) return { nodeId, error: 'No contract data' };
+  return {
+    nodeId: c.nodeId,
+    executionType: c.executionType,
+    skillKey: c.skillKey,
+    localSkillKind: c.localSkillKind,
+    sideEffects: c.sideEffects,
+    validation: {
+      hasOutputValidation: Boolean(c.validation?.outputValidation?.items),
+      hasOutputSchema: Boolean(c.validation?.outputSchema?.items),
+    },
+    control: c.control
+      ? {
+          isRoutingNode: c.control.isRoutingNode,
+          predicatePathsThatMatchedWrites: c.control.predicatePathsThatMatchedWrites,
+        }
+      : null,
+    issueTitles: (analysis.issuesByNodeId[nodeId] ?? []).map((i) => ({
+      severity: i.severity,
+      title: i.title,
+    })),
+  };
+}
+
+function pickEdgeSummary(analysis: GraphAnalysisResult, edgeKey: string) {
+  const e = analysis.edgeAnalysisByKey[edgeKey];
+  if (!e) return { edgeKey, error: 'No edge analysis' };
+  return {
+    from: e.from,
+    to: e.to,
+    flowType: e.flowType,
+    branchType: e.branchType,
+    matchedWritesToReads: e.matchedWritesToReads,
+    predicatePaths: e.predicatePaths,
+    predicateProviders: e.predicateProviders,
+    predicateUnresolved: e.predicateUnresolved,
+    issueTitles: (analysis.issuesByEdgeKey[edgeKey] ?? []).map((i) => ({
+      severity: i.severity,
+      title: i.title,
+    })),
+  };
+}
+
+export function buildComposerAnalysisContext(
+  analysis: GraphAnalysisResult | null,
+  scope: {
+    type: 'graph' | 'node' | 'edge';
+    nodeId?: string;
+    edgeKey?: string;
+  }
+): Record<string, unknown> | null {
+  if (!analysis || analysis.status !== 'ok') return null;
+  const base = {
+    graphSummary: analysis.graphSummary,
+    executionOrder: analysis.executionOrder,
+    issueCounts: analysis.graphSummary.issueCounts,
+    topIssues: analysis.graphIssues.slice(0, 12).map((i) => ({
+      severity: i.severity,
+      scopeType: i.scopeType,
+      scopeId: i.scopeId,
+      title: i.title,
+      description: i.description,
+    })),
+  };
+  if (scope.type === 'graph') return { ...base, scope: 'graph' };
+  if (scope.type === 'node' && scope.nodeId)
+    return { ...base, scope: 'node', node: pickNodeSummary(analysis, scope.nodeId) };
+  if (scope.type === 'edge' && scope.edgeKey)
+    return { ...base, scope: 'edge', edge: pickEdgeSummary(analysis, scope.edgeKey) };
+  return base;
+}

package/src/graphComposerPayload.js

@@ -0,0 +1,263 @@
+/**
+ * Shared graph-composer request shape for Prompt panel and Concept Edit.
+ */
+
+export const DEFAULT_AI_SKILLS = [
+  { skillKey: 'professional-answer', description: 'Structured analysis with LLM', isLocal: false },
+];
+
+export const DEFAULT_UTILITY_SKILLS = [
+  { skillKey: 'scoped-data-reader', description: 'Read scoped data', isLocal: true },
+  { skillKey: 'scoped-answer-writer', description: 'Persist results', isLocal: true },
+];
+
+export const DEFAULT_COMPOSER_CONSTRAINTS = { requireFinalizer: true };
+
+const SUGGEST_OBJECTIVE_DEFAULT_DESC =
+  'Infer the graph-level primary intent (L1 headline) from structure, titles, and analysisContext.';
+
+const REVIEW_CONCEPT_DEFAULT_DESC =
+  'Review whether metadata.graphConcept aligns with the graph structure and skills. Return verdict (coherent + summary), categorized findings with severity, and optional suggestedConceptPatch for primary intent fields.';
+
+/**
+ * Used when the Concept Edit tab runs reviewConcept for requirements prefill.
+ * Points the model at docs/graph-composer-concept-requirements.md (repo) for the expected patch shape.
+ */
+export const REVIEW_REQUIREMENTS_DEFAULT_DESC = [
+  'Review metadata.graphConcept against the exellix graph JSON and analysisContext.',
+  'Return: (1) verdict { coherent, summary }; (2) findings[] with category, severity, summary, optional taskIndex (0-based coreTasks index), optional nodeIds, optional suggestedChange.',
+  'Use finding categories when possible: primary_intent, expected_input, output_model, core_task, graph_topology, memory_io, catalog.',
+  '(3) In graphConceptPatch OR suggestedConceptPatch, include partial updates: optional string fields (expectedInput, outputDescription, primaryIntentStatement, etc.) and/or coreTasks[] aligned by INDEX with the current concept.',
+  'Each coreTasks[i] may be partial — especially requirements { skill, catalogBinding, memoryIO } and webQueryTemplate on the task slice.',
+  'Orthogonal lanes: (1) Top-level entityBindings = which memorix-entities catalog ids the graph is about (graph subject; catalog binding, not graphEntry.inputs). (2) Per-task requirements.memoryIO = execution-memory reads/writes for that step (runtime handoff). (3) webQueryTemplate on task aiTaskProfile = PRE webScope Rendrix template — not a substitute for (1).',
+  'Graph-level entityBindings (memorix-entities ids; JSON field names still *EntityCollectionId) are the canonical place for “what entity this graph is about”.',
+  'webQueryTemplate uses Rendrix with flat {{input.*}} refs (e.g. "Patch status for {{input.cveId}}?"). Optional webQueryTemplates[] for pack mode.',
+  'Uncertainty and gaps: still populate graphConceptPatch where you can; ALSO emit top-level requirementOptions[] with taskIndex, field (e.g. memoryIO.writes), ranked candidates { value, rationale, source }, and needsNewArtifact when nothing in-graph fits.',
+  'Do not replace entire graph JSON; only return the patch object for graphConcept.',
+].join(' ');
+
+/**
+ * @param {Record<string, unknown> | null | undefined} t
+ */
+function formatCoreTaskExtras(t) {
+  if (!t || typeof t !== 'object') return '';
+  const parts = [];
+  const req = t.requirements && typeof t.requirements === 'object' ? t.requirements : null;
+  const sk = req?.skill && typeof req.skill === 'object' ? req.skill.skillKey : '';
+  if (typeof sk === 'string' && sk.trim()) parts.push(`skill: ${sk.trim()}`);
+  const mem = req?.memoryIO && typeof req.memoryIO === 'object' ? req.memoryIO : null;
+  if (mem && typeof mem.writes === 'string' && mem.writes.trim()) parts.push(`writes: ${mem.writes.trim()}`);
+  const webTemplate =
+    typeof t.webQueryTemplate === 'string' && t.webQueryTemplate.trim()
+      ? t.webQueryTemplate.trim()
+      : typeof req?.webQueryTemplate === 'string' && req.webQueryTemplate.trim()
+        ? req.webQueryTemplate.trim()
+        : '';
+  if (webTemplate) parts.push(`webQuery: ${webTemplate.slice(0, 80)}${webTemplate.length > 80 ? '…' : ''}`);
+  else if (t.webScoping && typeof t.webScoping === 'object' && t.webScoping.enabled) {
+    parts.push('webScope: legacy webScoping (migrate to webQueryTemplate)');
+  }
+  const syn = t.synthesis && typeof t.synthesis === 'object' ? t.synthesis : null;
+  if (syn && syn.enabled) {
+    if (typeof syn.strategy === 'string' && syn.strategy.trim()) parts.push(`synthesis: ${syn.strategy.trim()}`);
+    const pr = Array.isArray(syn.prompts) ? syn.prompts.map((p) => String(p).trim()).filter(Boolean) : [];
+    if (pr.length) parts.push(`synthesis prompts: ${pr.join('; ')}`);
+  }
+  if (mem && Array.isArray(mem.reads) && mem.reads.some((r) => String(r).trim())) {
+    parts.push(`reads: ${mem.reads.map((r) => String(r).trim()).filter(Boolean).join(', ')}`);
+  }
+  if (mem?.jobContextMappings && typeof mem.jobContextMappings === 'object' && !Array.isArray(mem.jobContextMappings)) {
+    const keys = Object.keys(mem.jobContextMappings);
+    if (keys.length) parts.push(`jobContextMapping: ${JSON.stringify(mem.jobContextMappings)}`);
+  }
+  const cb = req?.catalogBinding && typeof req.catalogBinding === 'object' ? req.catalogBinding : null;
+  if (cb && (String(cb.catalogId || '').trim() || String(cb.scopingMapId || '').trim())) {
+    const idv = [cb.catalogId, cb.version].filter((x) => String(x || '').trim()).join('@');
+    const tail = cb.scopingMapId && String(cb.scopingMapId).trim() ? ` map:${String(cb.scopingMapId).trim()}` : '';
+    parts.push(`catalog: ${idv || '(binding)'}${tail}`);
+  }
+  return parts.length ? ` (${parts.join('; ')})` : '';
+}
+
+/**
+ * @param {{
+ *   action: string,
+ *   scope: 'graph' | 'node' | 'edge',
+ *   description: string,
+ *   selectedItem: object | null,
+ *   getExportableGraph: () => object,
+ *   skillMode: string,
+ *   getAnalysisContext?: () => object | null,
+ *   onlyIfEmpty?: string[],
+ *   catalogPickLists?: { narratives?: Array<{ id: string; label?: string }> } & Record<string, unknown>,
+ * }} p
+ */
+export function buildGraphComposerInput(p) {
+  const {
+    action,
+    scope,
+    description,
+    selectedItem,
+    getExportableGraph,
+    skillMode,
+    getAnalysisContext,
+    onlyIfEmpty,
+    catalogPickLists,
+  } = p;
+
+  const existingGraph = action === 'create' ? undefined : getExportableGraph();
+
+  let focusNodeIds;
+  let desc =
+    (action === 'suggestConceptObjective' || action === 'reviewConcept') && !description.trim()
+      ? action === 'reviewConcept'
+        ? REVIEW_CONCEPT_DEFAULT_DESC
+        : SUGGEST_OBJECTIVE_DEFAULT_DESC
+      : description;
+
+  if (scope === 'node' && selectedItem?.obj?.id) {
+    focusNodeIds = [selectedItem.obj.id];
+  }
+
+  if (scope === 'edge' && selectedItem?.obj) {
+    const { from, to } = selectedItem.obj;
+    const prefix = `[Scope: edge from="${from}" to="${to}"] `;
+    desc = prefix + description;
+    focusNodeIds = [from, to].filter(Boolean);
+  }
+
+  let analysisContext = null;
+  if (typeof getAnalysisContext === 'function') {
+    try {
+      analysisContext = getAnalysisContext();
+    } catch {
+      analysisContext = null;
+    }
+  }
+
+  const intent = {
+    action,
+    description: desc,
+    ...(focusNodeIds?.length ? { focusNodeIds } : {}),
+    ...(action === 'suggestConceptObjective' && Array.isArray(onlyIfEmpty) && onlyIfEmpty.length
+      ? { onlyIfEmpty }
+      : {}),
+  };
+
+  const pickLists = normalizeCatalogPickLists(catalogPickLists);
+
+  return {
+    intent,
+    ...(existingGraph !== undefined ? { existingGraph } : {}),
+    ...(analysisContext ? { analysisContext } : {}),
+    skillMode,
+    aiSkills: DEFAULT_AI_SKILLS,
+    utilitySkills: DEFAULT_UTILITY_SKILLS,
+    constraints: DEFAULT_COMPOSER_CONSTRAINTS,
+    ...(pickLists ? { catalogPickLists: pickLists } : {}),
+  };
+}
+
+/**
+ * Normalize Catalox-sourced picklists (currently `narratives`) before sending to the composer.
+ * Drops empty lists and invalid entries so the AI sees a clean set or no key at all.
+ *
+ * @param {{ narratives?: Array<{ id?: string; label?: string }> } | null | undefined} pickLists
+ */
+function normalizeCatalogPickLists(pickLists) {
+  if (!pickLists || typeof pickLists !== 'object') return null;
+  /** @type {Record<string, Array<{ id: string; label?: string }>>} */
+  const out = {};
+  const narratives = Array.isArray(pickLists.narratives) ? pickLists.narratives : null;
+  if (narratives && narratives.length) {
+    const cleaned = [];
+    for (const n of narratives) {
+      const id = typeof n?.id === 'string' ? n.id.trim() : '';
+      if (!id) continue;
+      const entry = { id };
+      if (typeof n?.label === 'string' && n.label.trim() && n.label.trim() !== id) {
+        entry.label = n.label.trim();
+      }
+      cleaned.push(entry);
+    }
+    if (cleaned.length) out.narratives = cleaned;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+/**
+ * Build a natural-language instruction for create/modify from graphConcept fields.
+ * @param {Record<string, unknown>} graphConcept
+ * @param {'create' | 'modify'} mode
+ */
+export function buildInstructionFromGraphConcept(graphConcept, mode) {
+  const c = graphConcept && typeof graphConcept === 'object' ? graphConcept : {};
+  const lines = [];
+
+  if (typeof c.graphType === 'string' && c.graphType.trim()) {
+    lines.push(`Graph type: ${c.graphType.trim()}.`);
+  }
+  if (typeof c.primaryIntentStatement === 'string' && c.primaryIntentStatement.trim()) {
+    lines.push(`Primary intent (${c.primaryIntentType || 'objective'}): ${c.primaryIntentStatement.trim()}`);
+  }
+  if (typeof c.businessObjective === 'string' && c.businessObjective.trim()) {
+    lines.push(`Business objective: ${c.businessObjective.trim()}`);
+  }
+  if (typeof c.expectedInput === 'string' && c.expectedInput.trim()) {
+    lines.push(`Expected input from callers: ${c.expectedInput.trim()}`);
+  }
+  if (typeof c.outputDescription === 'string' && c.outputDescription.trim()) {
+    lines.push(`Primary outputs / outcome: ${c.outputDescription.trim()}`);
+  }
+  if (Array.isArray(c.coreTasks) && c.coreTasks.length) {
+    lines.push('Core tasks (implement as logical steps / nodes in order):');
+    c.coreTasks.forEach((t, i) => {
+      const stmt = typeof t?.statement === 'string' ? t.statement : '';
+      const tt = typeof t?.taskType === 'string' ? t.taskType : 'objective';
+      if (stmt.trim()) lines.push(`  ${i + 1}. [${tt}] ${stmt.trim()}${formatCoreTaskExtras(t)}`);
+    });
+  }
+  if (typeof c.notes === 'string' && c.notes.trim()) {
+    lines.push(`Additional notes: ${c.notes.trim()}`);
+  }
+
+  const body = lines.join('\n');
+  if (!body.trim()) return '';
+
+  if (mode === 'create') {
+    return `Build a exellix-graph DAG that implements the following product concept. Use a finalizer. Keep the graph focused and coherent.\n\n${body}`;
+  }
+  return `Update the existing graph so it implements this concept. Preserve unrelated structure where possible; align nodes, edges, and readability with:\n\n${body}`;
+}
+
+const traceReviewConceptIo =
+  typeof import.meta !== 'undefined' &&
+  import.meta.env &&
+  String(import.meta.env.VITE_GRAPH_COMPOSER_TRACE_REVIEW || '') === 'true';
+
+/** Passed to POST /api/graph-composer → runGraphComposer(input, options). Set VITE_GRAPH_COMPOSER_TRACE_REVIEW=true for redacted reviewConcept I/O in server logs. */
+export const GRAPH_COMPOSER_API_OPTIONS = {
+  askTimeoutMs: 120_000,
+  maxTokens: 8192,
+  ...(traceReviewConceptIo ? { traceReviewConceptIo: true } : {}),
+};
+
+const CONCEPT_PATCH_KEYS = ['primaryIntentType', 'primaryIntentStatement', 'businessObjective', 'primaryOutcome'];
+
+/**
+ * @param {Record<string, unknown> | null | undefined} patch
+ * @returns {Record<string, string> | null}
+ */
+export function pickNonEmptyConceptPatch(patch) {
+  if (!patch || typeof patch !== 'object') return null;
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (const k of CONCEPT_PATCH_KEYS) {
+    if (patch[k] === undefined || patch[k] === null) continue;
+    const s = typeof patch[k] === 'string' ? patch[k].trim() : String(patch[k]).trim();
+    if (s.length) out[k] = typeof patch[k] === 'string' ? patch[k].trim() : s;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+export const DEFAULT_ONLY_IF_EMPTY_KEYS = [...CONCEPT_PATCH_KEYS];

package/src/graphSuggestions.js

@@ -0,0 +1,304 @@
+/**
+ * Collect suggestion strings from graph node metadata for Concept Requirements editors.
+ * Pure — no React.
+ */
+
+import { requirementsHintsFromNarrative } from '@exellix/graphs-studio-concept';
+import { resolveMemorixItemDescriptorId } from '@exellix/graphs-studio-data-flow/lib/memorixScopedConfig.js';
+
+/** @param {unknown} id */
+function isVirtualId(id) {
+  return (
+    id === '__exellixGraphEntry' ||
+    id === '__exellixGraphResponse' ||
+    (typeof id === 'string' && id.startsWith('__exellix'))
+  );
+}
+
+function trimmed(s) {
+  return typeof s === 'string' ? s.trim() : '';
+}
+
+/**
+ * @typedef {{
+ *   datasetIds: string[],
+ *   narrativeTypeIds: string[],
+ *   writePaths: string[],
+ *   readPaths: string[],
+ *   catalogIds: string[],
+ *   scopingMapIds: string[],
+ *   memorixItemDescriptorIds: string[],
+ *   jobContextEntries: { key: string; value: string }[],
+ * }} GraphSuggestions
+ */
+
+/**
+ * Walk nodes in execution order (when available) and collect unique ids/paths from metadata.
+ *
+ * @param {object | null | undefined} graphData
+ * @param {object | null | undefined} graphAnalysis
+ * @returns {GraphSuggestions}
+ */
+export function collectGraphSuggestions(graphData, graphAnalysis) {
+  /** @type {string[]} */
+  const datasetIds = [];
+  /** @type {string[]} */
+  const narrativeTypeIds = [];
+  /** @type {string[]} */
+  const writePaths = [];
+  /** @type {string[]} */
+  const readPaths = [];
+  /** @type {string[]} */
+  const catalogIds = [];
+  /** @type {string[]} */
+  const scopingMapIds = [];
+  /** @type {string[]} */
+  const memorixItemDescriptorIds = [];
+  /** @type {{ key: string; value: string }[]} */
+  const jobContextEntries = [];
+
+  const rawNodes = graphData?.nodes;
+  const nodes = Array.isArray(rawNodes)
+    ? rawNodes
+    : rawNodes && typeof rawNodes === 'object'
+      ? Object.values(rawNodes)
+      : [];
+
+  const executionOrder =
+    Array.isArray(graphAnalysis?.executionOrder) && graphAnalysis.executionOrder.length > 0
+      ? graphAnalysis.executionOrder
+      : nodes.map((n) => n?.id).filter(Boolean);
+
+  const nodesById = Object.fromEntries(nodes.map((n) => [n.id, n]));
+
+  const ordered = [];
+  for (const id of executionOrder) {
+    const node = nodesById[id];
+    if (node && !isVirtualId(node.id)) ordered.push(node);
+  }
+  for (const node of nodes) {
+    if (!node || isVirtualId(node.id)) continue;
+    if (!ordered.includes(node)) ordered.push(node);
+  }
+
+  const seenDs = new Set();
+  const seenNt = new Set();
+  const seenWrite = new Set();
+  const seenRead = new Set();
+  const seenCat = new Set();
+  const seenScope = new Set();
+  const seenMemorix = new Set();
+  const seenJcm = new Set();
+
+  const pushUnique = (arr, set, v) => {
+    const t = trimmed(v);
+    if (!t || set.has(t)) return;
+    set.add(t);
+    arr.push(t);
+  };
+
+  for (const node of ordered) {
+    const tc =
+      node.taskConfiguration && typeof node.taskConfiguration === 'object' && !Array.isArray(node.taskConfiguration)
+        ? node.taskConfiguration
+        : null;
+    const nar = tc?.narrix ?? node.metadata?.narrix;
+    if (nar && typeof nar === 'object') {
+      pushUnique(datasetIds, seenDs, nar.datasetId);
+      if (Array.isArray(nar.narrativeTypeIds)) {
+        for (const x of nar.narrativeTypeIds) {
+          pushUnique(narrativeTypeIds, seenNt, String(x));
+        }
+      }
+    }
+
+    const path = trimmed(node.executionMapping?.path);
+    pushUnique(writePaths, seenWrite, path);
+
+    const cb = node.metadata?.catalogBinding;
+    if (cb && typeof cb === 'object') {
+      pushUnique(catalogIds, seenCat, cb.catalogId);
+      pushUnique(scopingMapIds, seenScope, cb.scopingMapId);
+    }
+    pushUnique(scopingMapIds, seenScope, tc?.scopingMapId);
+    pushUnique(scopingMapIds, seenScope, node.metadata?.scopingMapId);
+    pushUnique(memorixItemDescriptorIds, seenMemorix, resolveMemorixItemDescriptorId(tc));
+    pushUnique(memorixItemDescriptorIds, seenMemorix, resolveMemorixItemDescriptorId(node.metadata));
+    if (Array.isArray(tc?.pack)) {
+      for (const slot of tc.pack) {
+        pushUnique(memorixItemDescriptorIds, seenMemorix, resolveMemorixItemDescriptorId(slot));
+        pushUnique(scopingMapIds, seenScope, slot?.scopingMapId);
+      }
+    }
+
+    const rawJcm = tc?.jobContextMapping ?? node.metadata?.jobContextMapping ?? node.jobContextMapping;
+    if (rawJcm && typeof rawJcm === 'object' && !Array.isArray(rawJcm)) {
+      for (const [k, v] of Object.entries(rawJcm)) {
+        const key = trimmed(k);
+        let val = '';
+        if (typeof v === 'string') val = trimmed(v);
+        else if (v && typeof v === 'object' && typeof v.path === 'string') val = trimmed(v.path);
+        if (!key || !val) continue;
+        const sig = `${key}\t${val}`;
+        if (seenJcm.has(sig)) continue;
+        seenJcm.add(sig);
+        jobContextEntries.push({ key, value: val });
+        pushUnique(readPaths, seenRead, val);
+      }
+    }
+  }
+
+  return {
+    datasetIds,
+    narrativeTypeIds,
+    writePaths,
+    readPaths,
+    catalogIds,
+    scopingMapIds,
+    memorixItemDescriptorIds,
+    jobContextEntries,
+  };
+}
+
+/** Default shape for {@link augmentGraphSuggestionsWithTaskNarrative} when the parent has no graph yet. */
+export function emptyGraphSuggestions() {
+  return {
+    datasetIds: [],
+    narrativeTypeIds: [],
+    writePaths: [],
+    readPaths: [],
+    catalogIds: [],
+    scopingMapIds: [],
+    memorixItemDescriptorIds: [],
+    jobContextEntries: [],
+  };
+}
+
+/**
+ * Merges Exellix-native Catalox catalog ids into {@link collectGraphSuggestions} output (deduped, order preserved).
+ * Scoping-question rows come from Catalox (`scopingQuestions`, appId `xmemory`). Optional `datasetIds` /
+ * `narrativeTypeIds` keys only merge ids supplied by the caller (e.g. from the graph itself), not legacy narrix catalogs.
+ *
+ * @param {GraphSuggestions} base
+ * @param {{
+ *   narrativeTypeIds?: string[],
+ *   datasetIds?: string[],
+ *   scopedQuestionCatalogIds?: string[],
+ * }} catalox
+ * @returns {GraphSuggestions}
+ */
+export function mergeCataloxIntoGraphSuggestions(base, catalox = {}) {
+  const out = {
+    datasetIds: [...(base.datasetIds || [])],
+    narrativeTypeIds: [...(base.narrativeTypeIds || [])],
+    writePaths: [...(base.writePaths || [])],
+    readPaths: [...(base.readPaths || [])],
+    catalogIds: [...(base.catalogIds || [])],
+    scopingMapIds: [...(base.scopingMapIds || [])],
+    memorixItemDescriptorIds: [...(base.memorixItemDescriptorIds || [])],
+    jobContextEntries: [...(base.jobContextEntries || [])],
+  };
+  const seenDs = new Set(out.datasetIds);
+  const seenNt = new Set(out.narrativeTypeIds);
+  const seenCat = new Set(out.catalogIds);
+  const pushUnique = (arr, set, v) => {
+    const t = trimmed(v);
+    if (!t || set.has(t)) return;
+    set.add(t);
+    arr.push(t);
+  };
+  for (const x of catalox.datasetIds || []) pushUnique(out.datasetIds, seenDs, x);
+  for (const x of catalox.narrativeTypeIds || []) pushUnique(out.narrativeTypeIds, seenNt, x);
+  for (const x of catalox.scopedQuestionCatalogIds || []) pushUnique(out.catalogIds, seenCat, x);
+  return out;
+}
+
+/** @param {unknown} task */
+function taskNarrativeForHints(task) {
+  if (!task || typeof task !== 'object') return '';
+  const t = /** @type {Record<string, unknown>} */ (task);
+  return [t.statement, t.details, t.notes]
+    .map((x) => (typeof x === 'string' ? x : ''))
+    .join('\n')
+    .trim();
+}
+
+/**
+ * Merges {@link collectGraphSuggestions} with regex hints from this step’s statement / Details / notes
+ * (same heuristics as composer prefill). Use when the canvas has little metadata so chips still appear.
+ *
+ * @param {Partial<GraphSuggestions> | null | undefined} base
+ * @param {unknown} task
+ * @returns {GraphSuggestions}
+ */
+export function augmentGraphSuggestionsWithTaskNarrative(base, task) {
+  const b = base && typeof base === 'object' ? base : {};
+  /** @type {GraphSuggestions} */
+  const out = {
+    datasetIds: [...(b.datasetIds || [])],
+    narrativeTypeIds: [...(b.narrativeTypeIds || [])],
+    writePaths: [...(b.writePaths || [])],
+    readPaths: [...(b.readPaths || [])],
+    catalogIds: [...(b.catalogIds || [])],
+    scopingMapIds: [...(b.scopingMapIds || [])],
+    memorixItemDescriptorIds: [...(b.memorixItemDescriptorIds || [])],
+    jobContextEntries: [...(b.jobContextEntries || [])],
+  };
+
+  const seenDs = new Set(out.datasetIds);
+  const seenNt = new Set(out.narrativeTypeIds);
+  const seenW = new Set(out.writePaths);
+  const seenR = new Set(out.readPaths);
+  const seenCat = new Set(out.catalogIds);
+  const seenScope = new Set(out.scopingMapIds);
+  const seenJcm = new Set(out.jobContextEntries.map((e) => `${e.key}\t${e.value}`));
+
+  const pushUnique = (arr, set, v) => {
+    const t = trimmed(v);
+    if (!t || set.has(t)) return;
+    set.add(t);
+    arr.push(t);
+  };
+
+  const narrative = taskNarrativeForHints(task);
+  const networkDs = narrative.match(/\b(network\.[a-z][a-z0-9_.-]*)\b/i);
+  if (networkDs) pushUnique(out.datasetIds, seenDs, networkDs[1]);
+
+  const hints = requirementsHintsFromNarrative(narrative);
+  if (!hints) return out;
+
+  if (hints.memoryIO && typeof hints.memoryIO === 'object') {
+    const m = /** @type {Record<string, unknown>} */ (hints.memoryIO);
+    if (typeof m.writes === 'string') pushUnique(out.writePaths, seenW, m.writes);
+    if (Array.isArray(m.reads)) {
+      for (const r of m.reads) pushUnique(out.readPaths, seenR, r);
+    }
+    const jcm = m.jobContextMappings;
+    if (jcm && typeof jcm === 'object' && !Array.isArray(jcm)) {
+      for (const [k, v] of Object.entries(jcm)) {
+        const key = trimmed(k);
+        const val = trimmed(typeof v === 'string' ? v : '');
+        if (!key || !val) continue;
+        const sig = `${key}\t${val}`;
+        if (seenJcm.has(sig)) continue;
+        seenJcm.add(sig);
+        out.jobContextEntries.push({ key, value: val });
+        pushUnique(out.readPaths, seenR, val);
+      }
+    }
+  }
+
+  return out;
+}
+
+const FINDING_REQ_HINT_RE =
+  /\b(narrix|network\.|dataset|layer|subnet|memory\s*io|memory_io|execution\.|scoped\.|executionMapping|outputMapping|writes?|reads?|catalog|scoping|jobContext|artifact|binding|paths?)\b/i;
+
+/**
+ * Finding summaries from `reviewConcept` that are likely about Narrix / Memory IO / paths — show near requirement fields.
+ * @param {unknown[]} lines
+ */
+export function filterFindingLinesForRequirementsHints(lines) {
+  if (!Array.isArray(lines)) return [];
+  return lines.filter((l) => typeof l === 'string' && FINDING_REQ_HINT_RE.test(l));
+}

package/src/index.js

@@ -0,0 +1,9 @@
+export {
+  buildLayerAwareComposerContext,
+  mergeLayerContextIntoComposerPayload,
+} from './layerAwareComposerContext.js';
+
+export { buildComposerAnalysisContext } from './composerContext.ts';
+
+export * from './graphComposerPayload.js';
+export * from './graphSuggestions.js';

package/src/layerAwareComposerContext.js

@@ -0,0 +1,47 @@
+/**
+ * Layer-aware composer context builder.
+ * @param {object} input
+ * @param {Record<string, unknown> | null} [input.conceptLayer]
+ * @param {Record<string, unknown> | null} [input.dataFlowLayer]
+ * @param {string} [input.syncState]
+ * @param {Record<string, unknown> | null} [input.graphAnalysis]
+ */
+export function buildLayerAwareComposerContext(input) {
+  const parts = [];
+  if (input.syncState && input.syncState !== 'clean') {
+    parts.push(`Layer sync state: ${input.syncState}`);
+  }
+  if (input.conceptLayer?.studioConcept) {
+    parts.push(`Concept layer present for graph ${input.conceptLayer.graphId ?? 'unknown'}`);
+  }
+  if (input.dataFlowLayer?.informationFlow) {
+    const nodeCount = input.dataFlowLayer.informationFlow.nodes?.length ?? 0;
+    parts.push(`Data-flow layer: ${nodeCount} planning nodes`);
+  }
+  if (input.graphAnalysis?.status === 'error') {
+    parts.push(`Graph analysis error: ${input.graphAnalysis.errorMessage ?? 'unknown'}`);
+  }
+  return {
+    layerSummary: parts.join('\n'),
+    hasConceptLayer: Boolean(input.conceptLayer),
+    hasDataFlowLayer: Boolean(input.dataFlowLayer),
+    syncState: input.syncState ?? 'clean',
+  };
+}
+
+/**
+ * @param {Record<string, unknown>} basePayload
+ * @param {ReturnType<typeof buildLayerAwareComposerContext>} layerContext
+ */
+export function mergeLayerContextIntoComposerPayload(basePayload, layerContext) {
+  return {
+    ...basePayload,
+    layerContext,
+    analysisContext: [
+      typeof basePayload.analysisContext === 'string' ? basePayload.analysisContext : '',
+      layerContext.layerSummary,
+    ]
+      .filter(Boolean)
+      .join('\n\n'),
+  };
+}

package/src/types.ts

@@ -0,0 +1,246 @@
+import type { GraphCatalogs, GraphInspection } from '@exellix/graph-engine/dist/src/inspection/types.js';
+import type { GraphContractsInspection, NodeContractInspection } from '@exellix/graph-engine/dist/src/inspection/contractTypes.js';
+
+export type EdgeFlowType = 'structural' | 'data' | 'control' | 'mixed';
+
+export type EdgeAnalysis = {
+  edgeKey: string;
+  edgeIndex: number;
+  from: string;
+  to: string;
+  when?: unknown;
+  flowType: EdgeFlowType;
+  writtenPaths: string[];
+  readPaths: string[];
+  matchedWritesToReads: string[];
+  predicatePaths: string[];
+  predicatePathTails: string[];
+  predicateProviders: string[];
+  predicateUnresolved: boolean;
+  branchType:
+    | 'unconditional'
+    | 'conditional-any'
+    | 'conditional-all'
+    | 'conditional-path'
+    | 'conditional';
+  hasStructuralRole: boolean;
+};
+
+export type GraphIssueSeverity = 'error' | 'warning' | 'info';
+
+export type GraphIssueCategory =
+  | 'structural'
+  | 'contract'
+  | 'routing'
+  | 'readability'
+  | 'validation'
+  | 'scoping'
+  | 'narrix'
+  | 'finalizer'
+  | 'graph-hygiene';
+
+export type GraphIssueScope = 'graph' | 'node' | 'edge';
+
+export type GraphIssue = {
+  id: string;
+  severity: GraphIssueSeverity;
+  scopeType: GraphIssueScope;
+  scopeId: string;
+  category: GraphIssueCategory;
+  title: string;
+  description: string;
+  evidence?: Record<string, unknown>;
+  recommendedAction?: string;
+};
+
+export type GraphSummary = {
+  nodeCount: number;
+  edgeCount: number;
+  entryNodeCount: number;
+  finalizerCount: number;
+  aiTaskCount: number;
+  localSkillCount: number;
+  conditionalEdgeCount: number;
+  routingNodeCount: number;
+  issueCounts: { error: number; warning: number; info: number };
+  readabilityCoverage: { withTitle: number; withAsks: number; withKind: number };
+};
+
+export type AnalysisStatus = 'ok' | 'error';
+
+// --- I/O Resolution types ---
+
+export type IONodeLayer = 'scope' | 'inference' | 'write-back' | 'finalizer';
+
+export type IOEntryTier = 'graph' | 'runtime';
+
+export type IOEntry = {
+  /** Dot-separated execution memory path, or "xmemory-op:{id}", or "finalOutput" */
+  path: string;
+  tier: IOEntryTier;
+  /** Human-readable source label (e.g. "outputMapping", "narrix preprocessor") */
+  source: string;
+  /** For writes: target store ("execution", "xmemory-op", etc.) */
+  target?: string;
+  /** Extra context (collection name, mode, fallback label, etc.) */
+  detail?: string;
+  /** When true, only show in the inspector, not on the node card */
+  _inspectorOnly?: boolean;
+  /** Marks the primary narrix read entry */
+  _narrixPrimary?: boolean;
+};
+
+export type ResolvedNodeIO = {
+  layer: IONodeLayer;
+  reads: IOEntry[];
+  writes: IOEntry[];
+};
+
+export type IOLink = {
+  writtenBy: string;
+  writePath: string;
+  readBy: string;
+  readPath: string;
+};
+
+export type DiagramEdgeKind = 'topology' | 'data' | 'control' | 'mixed';
+
+export type DiagramEdge = {
+  key: string;
+  index: number;
+  from: string;
+  to: string;
+  kind: DiagramEdgeKind;
+  hasCondition: boolean;
+  dataFlowLinks: IOLink[];
+  dataFlowPaths: string[];
+  readPaths: string[];
+  tooltip: string;
+};
+
+export type DiagramModel = {
+  topologyEdges: DiagramEdge[];
+  dataFlowLinks: IOLink[];
+  virtualBoundaryEdges: Array<{ from: string; to: string }>;
+  unresolvedReads: DanglingRead[];
+  orphanedWrites: OrphanedWrite[];
+  edgesByIndex: DiagramEdge[];
+  edgesByKey: Record<string, DiagramEdge>;
+};
+
+export type RuntimeFinalizerReadStatus = 'connected' | 'no-authored-edge' | 'missing-writer';
+
+export type RuntimeFinalizerReadContract = {
+  key: string;
+  finalizerId: string;
+  finalizerTitle: string;
+  readPath: string;
+  readSource: string;
+  authoredSource: string;
+  writerNodeId: string;
+  writerTitle: string;
+  writerPath: string;
+  matchingWriterCount: number;
+  matchingAuthoredEdgeIndex: number;
+  matchingAuthoredEdgeKey: string;
+  status: RuntimeFinalizerReadStatus;
+  statusLabel: string;
+};
+
+export type RuntimeFinalizerContract = {
+  finalizerId: string;
+  finalizerTitle: string;
+  finalizerType: string;
+  strategy: string;
+  reads: RuntimeFinalizerReadContract[];
+  connectedCount: number;
+  missingCount: number;
+  totalCount: number;
+  statusLabel: string;
+};
+
+export type RuntimeEdgeContract = {
+  key: string;
+  index: number;
+  from: string;
+  to: string;
+  kind: DiagramEdgeKind;
+  runtimeDataPaths: string[];
+  dataFlowLinks: IOLink[];
+  sourceWritePaths: string[];
+  targetReadPaths: string[];
+  explanation: string;
+  fixHint: string;
+};
+
+export type RuntimeDataContract = {
+  finalizerContracts: RuntimeFinalizerContract[];
+  edgeContractsByIndex: RuntimeEdgeContract[];
+  edgeContractsByKey: Record<string, RuntimeEdgeContract>;
+  summary: {
+    dataHandoffEdgeCount: number;
+    topologyOnlyEdgeCount: number;
+    conditionalEdgeCount: number;
+    finalizerReadCount: number;
+    connectedFinalizerReadCount: number;
+    missingFinalizerReadCount: number;
+    finalizerInputStatusLabel: string;
+  };
+};
+
+export type DanglingRead = {
+  nodeId: string;
+  path: string;
+  tier: IOEntryTier;
+  source: string;
+};
+
+export type OrphanedWrite = {
+  nodeId: string;
+  path: string;
+  tier: IOEntryTier;
+  source: string;
+};
+
+// --- Simplified filter state ---
+
+export type AnalysisFilters = {
+  layer: 'all' | IONodeLayer;
+  hasIssues: boolean;
+};
+
+export const defaultAnalysisFilters: AnalysisFilters = {
+  layer: 'all',
+  hasIssues: false,
+};
+
+// --- Graph analysis result ---
+
+export type GraphAnalysisResult = {
+  status: AnalysisStatus;
+  errorMessage?: string;
+  graphInspection: GraphInspection;
+  graphContractInspection: GraphContractsInspection;
+  graphSummary: GraphSummary;
+  /** Same as graphContractInspection.nodes — alias for inspector */
+  nodeAnalysisById: Record<string, NodeContractInspection>;
+  edgeAnalysisByKey: Record<string, EdgeAnalysis>;
+  edgeAnalysisByIndex: EdgeAnalysis[];
+  graphIssues: GraphIssue[];
+  issuesByNodeId: Record<string, GraphIssue[]>;
+  issuesByEdgeKey: Record<string, GraphIssue[]>;
+  executionOrder: string[];
+  catalogs: GraphCatalogs;
+  /** Resolved I/O for each node (Tier 1 + Tier 2) */
+  nodeIO: Record<string, ResolvedNodeIO>;
+  /** Cross-node write-to-read links */
+  ioLinks: IOLink[];
+  /** Reads with no matching upstream write */
+  danglingReads: DanglingRead[];
+  /** Writes no downstream node reads */
+  orphanedWrites: OrphanedWrite[];
+  /** Runtime-backed diagram semantics consumed by the graph canvas. */
+  diagramModel: DiagramModel;
+  /** Studio-facing runtime data summary derived from graph-engine inspection. */
+  runtimeDataContract: RuntimeDataContract;
+};