Session template authoring principles
Session templates are DAG blueprints. These principles keep graphs debuggable, platform-portable, and dense rather than bloated.
Failures must be visible
Use small nodes with one job each. When something breaks, node LastState should identify the step. Avoid monolithic transforms that combine discovery, hydration, analytics, and dashboard publish.
Horizontal splitting
Prefer sibling branches from the input node over deep chains of fat JSON:
- Scoped
system-protobuf-extractper target (EntityDataEvent,EntityState) instead of one fullSimulationFramedump. - Separate discovery leaf (
capture-discovery) from mainline analytics.
Slim intermediates
Scope extraction to what downstream nodes need. Merge structured outputs later with system-arbex-js or heat-system-dataservice-envelope.
system-utils first
Platform templates on system-utils ship with Core API. core-utils and dashboard-utils are versioned companion runners that may be absent on minimal installs. Author templates that work without them; document optional enhancement branches.
Explicit ingest route
| Route | Input node name |
|---|---|
| Capture / protobuf | agnostic-input |
| CSV | csv-input |
| JSON | json-input |
State the route in the template Description.
Guides
Agent corpus: tools/session-template-rag/ in the monorepo.