Source navigation

Jump from a log line straight to the code that produced it.

Source roots & Maven repos

Open Settings ▸ Source roots and add the source directories for your processor and its node classes. The analyser also searches your local Maven repositories (default ~/.m2/repository) for *-sources.jar when a class isn't under a source root — so third-party node sources resolve too.

A root or repo that can't be found shows red in Settings.

A pane shows the file as it is on disk

Every navigation to a class re-reads its file, even when the pane already shows that class, so a processor rewritten by regeneration is not left on screen in its old form. This applies to the Source tab and to the source pane inside the Topology tab. Reopening a log or graph, or bringing a source pane back into view, rechecks what both panes show. Files are read in the background: while a read is in progress, the pane's header says its text is not yet rechecked, and a read that takes too long says so rather than blocking the window. A class whose file has gone is not shown in its former form; the header says it was shown before. Clicking a node to open its class uses the processor as it is on disk now, so after a class rename it opens the new class. Being current with disk is not the same as matching the run: the header's tooltip still reads Source/run: unverified, with the file and its SHA-256.

Until a source pane has read the selected processor after a configuration change, the analyser does not read it on the window's own thread to answer other questions: context omits node types and says processorModel: not yet read, and a design bean without a class says classLookup: processor source not yet read. When two panes read the processor, the answer from the later request wins even if the earlier one arrives last. Source reads share a pool of two workers with a short queue: a newer request cancels and removes an older one that has not started, and a read that times out says so in the pane. A read that is stuck on an unresponsive disk and ignores cancellation keeps its worker until it returns, so two such reads can occupy both workers; further reads then time out and say so. A node you asked to open says why it did not. Ctrl-click on a type checks that it has source in the background, within the same time limit. A newer click or any navigation — Back, opening a file, a spotlight or opening a node — supersedes it, and a check that runs out of time never opens anything later. If the check cannot run (the reads are backed up) or fails, the node pane says why; Processor-only mode switches to Split so the message and processor are both visible. Back returns to the last file you actually saw: a "not found" pane is not added to the history.

Spring design and file glances

Opening a project, or changing its source roots, scans those authorised roots in the background for Spring FluxtionSpringConfig XML and Java FluxtionGraphBuilder definitions. context {sections: ["design"]} lists their kind, files (path and role) and discovery source; nodes describes the open design's anchors. The Design pane shows a single candidate directly as a read-only glance, without adopting it as the session design. With no candidates it says so and points to source_root {add: [...]} or open {design: <path>}. Several candidates can be opened by naming one with source {file: <path>}; the chooser follows separately. Java builders are highlighted in Design mode. Their sidebar indexes literal addNode/addPublicNode names inside buildGraph, at the line the call starts, even when its arguments wrap. Computed or absent names say name not literal; constructor locations say discovered, no name, not that the object was proven to enter the runtime graph. A trailing varargs string is not treated as a registration name. Existing Spring bean indexing is unchanged.

source {bean: "a"} selects either an XML bean id or a uniquely named Java builder declaration. spotlight {target: "source:design:node:a"} and source:design:bean:a name the same spotlight family; both locate the declaration without asserting its relationship to the running processor. Non-literal and ambiguous names are refused rather than guessed. A line-based anchor retires on an edit; a named anchor can rebind only when that literal name still resolves uniquely in the refreshed design.

No generated processor header is inspected. A project is not a read grant: discovery reads only authorised roots, does not follow directory links and rechecks file containment. Below a root it never descends into .git/, .svn/, .hg/, .gradle/, node_modules/ or .idea/, nor into target/, build/ or out/ beside a build file (pom.xml, build.gradle[.kts], settings.gradle[.kts], build.xml; for out/, also an IntelliJ .iml) — every build copies the Spring design to target/classes/, and that copy is not a second definition. A Java package named build, target or out, and a root that is itself named one of these, are still scanned. It counts at most 10,000 regular files and 20,000 filesystem entries, with the existing 2 MiB/UTF-8 source limit. Exceeding a scan limit reports unavailable with the specific limit and returns no partial candidate list. A file or folder removed or replaced while the scan runs (a build beside the analyser) is skipped; one that cannot be opened is named as unreadable. Individual unreadable, undecodable or oversized files and folders do not erase the readable candidates: up to ten names and the total appear in the Design pane and context.design.note as “2 entries could not be read: …”, with “and N more” when names are omitted. With no readable candidate the message says so, rather than claiming no design exists. A failed first explicit read omits kind until a form has actually loaded; a failed refresh may retain the last good revision and its known form. Working definitions remain relationship unverified, never paired with a run by discovery.

Sources ▸ Open design… selects the session's Spring XML or Java builder. Add its directory to source roots first; opening a project alone grants no file access. Source ▸ Design shows highlighted XML, a bean/config index, Follow design, Show node and Show records. The latter opens the first record logging the selected bean's name. Record and topology context menus offer Show declaration. These links are matched by name and always marked relationship unverified.

An AI client uses open {design: "src/main/resources/design.xml"} for the session file and source for a glance. Accepted shapes are {file}, {file,line}, {line}, {bean}, {file,bean}, {fqn} and {fqn,method}. Mixed selectors are refused. A glance re-reads disk and joins the Back history without changing the session design. This verb reads XML/Java under authorised local roots; it does not search Maven jars. Paths may be absolute or project/root-relative. Ambiguous files or bean ids are refused.

Follow works with no log open. During an incomplete XML edit it keeps the last good render and shows the parse error; an initially malformed file is visible as text with no bean index. Each parsed revision has a SHA-256 identity. source:design, source:design:bean:<id> and source:design:line:<n> spotlights always refer to the session design, even after a glance at another file. An edited bean's caption is qualified; a removed/duplicate bean or an edited line anchor goes out. Cross-tab targets are shown in sequence. source:design:line may instead name a range, source:design:line:<from>-<to> (first line at or before last, at most 200 lines); unlike a single design line, a range may show partly — one taller than the Source pane clips to it and shows the range's start.

The source {bean} echo's records is a preview count over recordsScanned records; recordsExact says whether that covers the whole log. It never proves that this XML produced those records. File reads are limited to 2 MiB, UTF-8. The analyser never evaluates Spring or writes the source files.

See Spring authoring for diagnostic intake and the distinction between XML input freshness and a relationship to a run.

Event processor

The Source tab renders the selected EventProcessor. Selecting a record scrolls the processor to the method that dispatches that record (its callback), so you land on the code that ran.

Click-through

• Click a node line in the record detail to open that node's class at the relevant method.
• Ctrl/⌘-click an identifier in the source to navigate: a node field's receiver.method() opens that node's class at the method; a field opens its type; a Type opens its source.
• ◀ Back (Alt+Left) returns to the previous source.

Navigation resolves through the processor's field declarations, so it works from any file — the processor or a node class.

Point at Java beside the graph

An assistant can light a named Java document with source:java:<fqn>, or a one-based logical line with source:java:<fqn>:line:<n>. Line numbers follow the editor: a trailing newline creates one final empty line that can also be anchored. Read the actual source before choosing a line number. There is no implicit current-file target or node-to-source inference. A line target may instead be a range, source:java:<fqn>:line:<from>-<to> (first line at or before last, at most 200 lines): the cut-out spans the range's first line's top to its last line's bottom, scrolled so the range is visible; one taller than the viewport clips to it, shows the range's start, and reports partial in the spotlight reply.

For example, after inspecting com.acme.Node, send one spotlight call:

{
  "targets": [
    {"target": "topology:node:node", "caption": "The node being discussed"},
    {"target": "source:java:com.acme.Node:line:3", "caption": "Inspect this declaration"}
  ]
}

With a topology target in the set, the analyser opens the embedded Java viewer and keeps the graph visible. Otherwise it uses that viewer when Topology is already selected, or the Source tab. A set can name only one Java document; unavailable source and out-of-range lines refuse before revealing anything.

This recorded image uses a constructed one-node fixture under an isolated home and predates the Project / Sources / Audit log menu layout. The Java spotlight behaviour shown is unchanged.

The source label and echo state source-viewer · first-match · relationship unverified. They disclose the chosen file/root or archive/entry and the SHA-256 revision of the rendered text. This identifies the source you can inspect; it does not establish that a loaded run used it or that the lit statement ran. The caption is the assistant's commentary.

The two source entrances intentionally differ:

Situation	Java spotlight / viewer	source {fqn} glance
Two roots contain the same FQN	First configured matching root, disclosed	Refuses ambiguity
Source exists only in a local sources jar	Uses it if archive lookup is enabled	Refuses; roots only

Check the disclosed origin before transferring a line number from a glance to a spotlight. Repeating the Java spotlight rereads hits and misses, including changed entries in known jars. Adding a new sources jar requires source reconfiguration or restart because jar discovery is cached. No archive is downloaded. A slow read refuses after ten seconds with “source lookup still running; retry”; its late completion cannot light a target. The built-in bridge allows sixty seconds; a client with a shorter private timeout may give up earlier.

A Java line band spans all wrapped rows and clips to the visible text viewport. partial: true says some of a measurable logical line is outside the viewport. If no band can be measured, partial is omitted; remeasurement puts that target out. The whole-document target lights only the visible text viewport, not its controls. Design XML keeps its different released rule: a line/declaration band must be wholly visible, while source:design means the whole design panel.

Scrolling, resizing or changing wrap remeasures a spotlight or puts it out. Changing the displayed Java revision extinguishes its old captions; they never move silently to the same line number in new text. Click, Escape and spotlight {clear: true} dismiss them. Nothing is saved.