@exellix/graphs-studio-data-flow 0.1.0

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;
+};

package/src/webScopingPlanning.js

@@ -0,0 +1,131 @@
+/**
+ * Design-level web scoping intent (`planning.webScoping`), separate from runtime
+ * `taskConfiguration.aiTaskProfile.webQueryTemplate` (Graphenix 2.7.3 PRE webScope unit).
+ *
+ * Persisted values: `always` | `ai-decision` | `never`.
+ * Legacy values are normalized on read: `required`→`always`, `optional`→`ai-decision`, `disabled`→`never`.
+ *
+ * @typedef {'always'|'ai-decision'|'never'} WebScopingPlanningMode
+ * @typedef {'declared'|'aiTaskProfile-fallback'|'default'} WebScopingPlanningSource
+ */
+import { readNodeWebScopeEnabled } from './lib/nodeMetadataAccessors.js';
+
+export const WEB_SCOPING_PLANNING_MODES = /** @type {const} */ ({
+  always: 'always',
+  aiDecision: 'ai-decision',
+  never: 'never',
+});
+
+const VALID = new Set(Object.values(WEB_SCOPING_PLANNING_MODES));
+
+/** @type {Record<string, WebScopingPlanningMode>} */
+const LEGACY_TO_CANONICAL = {
+  required: 'always',
+  optional: 'ai-decision',
+  disabled: 'never',
+};
+
+/**
+ * @param {unknown} raw
+ * @returns {WebScopingPlanningMode|undefined}
+ */
+function canonicalizeStoredWebScopingPlanning(raw) {
+  if (typeof raw !== 'string') return undefined;
+  const mapped = LEGACY_TO_CANONICAL[raw] ?? raw;
+  if (!VALID.has(mapped)) return undefined;
+  return /** @type {WebScopingPlanningMode} */ (mapped);
+}
+
+/** Skill keys that may declare planning web scoping in the editor. */
+const WEB_SCOPING_PLANNING_SKILL_KEYS = new Set(['professional-answer']);
+
+/**
+ * @param {object|null|undefined} node
+ * @returns {boolean}
+ */
+export function supportsWebScopingPlanning(node) {
+  if (!node || typeof node !== 'object' || node.isVirtual) return false;
+  if (node.type === 'finalizer') return false;
+  const sk = node.skillKey;
+  if (typeof sk !== 'string' || !sk) return false;
+  return WEB_SCOPING_PLANNING_SKILL_KEYS.has(sk);
+}
+
+/**
+ * Declared mode from authored JSON (legacy strings normalized to canonical).
+ * @param {object|null|undefined} node
+ * @returns {WebScopingPlanningMode|undefined}
+ */
+export function getDeclaredWebScopingPlanning(node) {
+  const fromRoot =
+    node &&
+    typeof node === 'object' &&
+    !Array.isArray(node) &&
+    node.planning &&
+    typeof node.planning === 'object' &&
+    !Array.isArray(node.planning)
+      ? /** @type {Record<string, unknown>} */ (node.planning).webScoping
+      : undefined;
+  const fromLegacyMeta = node?.metadata?.planning?.webScoping;
+  const v = fromRoot !== undefined ? fromRoot : fromLegacyMeta;
+  return canonicalizeStoredWebScopingPlanning(v);
+}
+
+/**
+ * Resolved mode for UI, information flow, and focus.
+ *
+ * Precedence:
+ *   1. Explicit design declaration (`planning.webScoping` on the node).
+ *   2. Runtime intent (non-empty `taskConfiguration.aiTaskProfile.webQueryTemplate` via {@link readNodeWebScopeEnabled})
+ *      → treated as `ai-decision` when no explicit design declaration is present.
+ *   3. Default → `never`.
+ *
+ * Narrix `enableWebScope` on the node is not read (graph-engine 5.0+ uses `taskConfiguration` only).
+ *
+ * @param {object|null|undefined} node
+ * @returns {{ mode: WebScopingPlanningMode, source: WebScopingPlanningSource }}
+ */
+export function getResolvedWebScopingPlanning(node) {
+  const declared = getDeclaredWebScopingPlanning(node);
+  if (declared != null) {
+    return { mode: declared, source: 'declared' };
+  }
+  if (readNodeWebScopeEnabled(node)) {
+    return { mode: WEB_SCOPING_PLANNING_MODES.aiDecision, source: 'aiTaskProfile-fallback' };
+  }
+  return { mode: WEB_SCOPING_PLANNING_MODES.never, source: 'default' };
+}
+
+/**
+ * @param {unknown} mode
+ * @returns {string}
+ */
+export function formatWebScopingPlanningLabel(mode) {
+  const c = canonicalizeStoredWebScopingPlanning(mode) ?? WEB_SCOPING_PLANNING_MODES.never;
+  if (c === 'always') return 'Web scope: always';
+  if (c === 'ai-decision') return 'Web scope: AI-decision';
+  return 'Web scope: never';
+}
+
+/**
+ * Flow / summary helpers: `always` and `ai-decision` participate in “intent” surfaces.
+ * Accepts legacy stored modes for robustness.
+ *
+ * @param {string|null|undefined} mode
+ * @returns {boolean}
+ */
+export function isWebScopingPlanningIntentMode(mode) {
+  const c = canonicalizeStoredWebScopingPlanning(mode);
+  return c === 'always' || c === 'ai-decision';
+}
+
+/**
+ * Whether this node should appear in "web scoping intent" surfaces.
+ * @param {object|null|undefined} node
+ * @returns {boolean}
+ */
+export function hasWebScopingPlanningIntent(node) {
+  if (!supportsWebScopingPlanning(node)) return false;
+  const { mode } = getResolvedWebScopingPlanning(node);
+  return isWebScopingPlanningIntentMode(mode);
+}