Design graph-native research nodes #104

New issue

Open

opened 2026-07-26 21:16:15 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-07-26 21:16:15 +00:00

(Migrated from github.com)

Goal

Add research-node as a first-class StarIntel object type and render it as an executable investigation plan in the Quasar graph. It is not a generic note, an entity subtype, or an agent chat transcript.

Shared specification

The object type is defined in the canonical StarIntel v0.9 schema and must validate identically in:

Python
JavaScript
Common Lisp
Nim
the bundled browser JavaScript runtime used by Quasar

Quasar must not maintain a private research-node schema or hide portable state in a Quasar-only extension.

Data model

A research node records:

objective and operator instructions
input document IDs and target IDs
ordered actor IDs or actor-selection rules
status: draft, queued, running, paused, blocked, completed, failed, killed
bounded depth, actor runs, requests, elapsed time, repeat-state, and optional cost
stop conditions and loop detection settings
output document IDs, artifact IDs, dependency IDs, and child research-node IDs
run IDs, active actor/run, counters, lifecycle timestamps, errors, and bounded history

Graph semantics

Use normal StarIntel relation documents when graph traversal matters:

researches: research node -> target/input
uses-actor: research node -> actor definition
depends-on: research node -> research node
produced: research node -> output document
spawned: parent research node -> child research node

ID arrays support execution and caching. Relation documents remain the graph authority.

UI

create a research node from the graph context menu, selected documents, target editor, or agent console
compact editor shows objective, inputs, actors, limits, and run controls
full editor exposes the complete plan, stop rules, counters, and history
node badge and border show execution state without replacing the active theme
right-click actions: run, pause, resume, retry, kill, inspect outputs, clone
selecting a research node can isolate its inputs, outputs, dependencies, artifacts, and child runs

Execution contract

Research nodes dispatch browser actors through the capability-scoped actor runtime. Actors never mutate Cytoscape or PouchDB directly. They return validated StarIntel documents, transform operations, events, artifacts, messages, and metrics. The host applies mutations through the existing command and undo path.

Acceptance

canonical research-node schema and conformance fixtures
Python, JavaScript, Common Lisp, and Nim conformance PRs
browser JavaScript schema bundle
Quasar factory, validator, state transitions, and execution-plan compiler
graph rendering and context actions
compact/full editor integration
actor queue execution with pause, retry, kill, limits, and loop detection
provenance relations from every output to the research node and actor run
desktop and mobile coverage

## Goal Add `research-node` as a first-class StarIntel object type and render it as an executable investigation plan in the Quasar graph. It is not a generic note, an entity subtype, or an agent chat transcript. ## Shared specification The object type is defined in the canonical StarIntel v0.9 schema and must validate identically in: - Python - JavaScript - Common Lisp - Nim - the bundled browser JavaScript runtime used by Quasar Quasar must not maintain a private research-node schema or hide portable state in a Quasar-only extension. ## Data model A research node records: - objective and operator instructions - input document IDs and target IDs - ordered actor IDs or actor-selection rules - status: `draft`, `queued`, `running`, `paused`, `blocked`, `completed`, `failed`, `killed` - bounded depth, actor runs, requests, elapsed time, repeat-state, and optional cost - stop conditions and loop detection settings - output document IDs, artifact IDs, dependency IDs, and child research-node IDs - run IDs, active actor/run, counters, lifecycle timestamps, errors, and bounded history ## Graph semantics Use normal StarIntel relation documents when graph traversal matters: - `researches`: research node -> target/input - `uses-actor`: research node -> actor definition - `depends-on`: research node -> research node - `produced`: research node -> output document - `spawned`: parent research node -> child research node ID arrays support execution and caching. Relation documents remain the graph authority. ## UI - create a research node from the graph context menu, selected documents, target editor, or agent console - compact editor shows objective, inputs, actors, limits, and run controls - full editor exposes the complete plan, stop rules, counters, and history - node badge and border show execution state without replacing the active theme - right-click actions: run, pause, resume, retry, kill, inspect outputs, clone - selecting a research node can isolate its inputs, outputs, dependencies, artifacts, and child runs ## Execution contract Research nodes dispatch browser actors through the capability-scoped actor runtime. Actors never mutate Cytoscape or PouchDB directly. They return validated StarIntel documents, transform operations, events, artifacts, messages, and metrics. The host applies mutations through the existing command and undo path. ## Acceptance - [x] canonical `research-node` schema and conformance fixtures - [x] Python, JavaScript, Common Lisp, and Nim conformance PRs - [x] browser JavaScript schema bundle - [x] Quasar factory, validator, state transitions, and execution-plan compiler - [x] graph rendering and context actions - [ ] compact/full editor integration - [x] actor queue execution with pause, retry, kill, limits, and loop detection - [ ] provenance relations from every output to the research node and actor run - [ ] desktop and mobile coverage