hgraph Development

View saved version →

---
name: hgraph-compute-sink-node
description: Implement or review C++ hgraph compute nodes, sink nodes, algorithms, and concrete operator-node specializations. Use when adding or changing a static node `eval`, lifecycle hooks, local or recordable state, REF usage, incremental or windowed algorithms, input-type branching, operator strategy selection or overload registration, type-erased node strategy, node naming, complexity documentation, or native/Python behavioral tests for a compute or sink node.
---

# HGraph Compute and Sink Nodes

Build C++-first nodes whose per-tick path is small, whose lifecycle and state
semantics are explicit, and whose names and tests fit the operator system.

## Start from the existing contract

1. Read the current repository's `AGENTS.md` and the relevant operator
   definition, implementation, registration, and tests before editing.
2. Establish whether the task targets hgraph core or a downstream extension:
   - In the hgraph core checkout, read the applicable parts of
     `docs/source/user_guide/cpp/authoring_nodes.rst` and use
     `tests/cpp/test_static_node.cpp` as the compact executable reference for
     lifecycle hooks, `State`, and `RecordableState`.
   - In a downstream project, use that project's extension layout and tests,
     plus the public hgraph headers and documentation for its pinned hgraph
     version. Do not assume the hgraph core source tree is present.
3. Classify the work before choosing a type:
   - Use a compute node for time-series input plus an output.
   - Use a sink node for time-series input and a side effect with no output.
   - Implement an operator specialization when the behavior belongs to an
     existing abstract operator or valid implementations may vary by type or
     algorithm.
   - Introduce a standalone node only when the behavior is not an operator and
     cannot be expressed clearly as a graph.

Keep static node implementation structs empty. Put instance data in the
appropriate selector or plan rather than in members.

Keep the node's per-tick implementation logic in `eval`. Extract a helper only
when it is a well-defined operation with its own clear contract or is genuinely
shared by multiple callers. Do not scatter one node's implementation across
single-use helper functions. Keep one-off lifecycle work in `start` and `stop`
as described below.

## Design the hot path first

Treat `eval` as the hot path. Leave only work that depends on the current tick.

- Prefer typed `In`, `Out`, `State`, and `RecordableState` access.
- Avoid schema discovery, registry lookup, overload selection, RTTI, string
  construction, parsing, policy selection, and representation selection in
  `eval`.
- Avoid avoidable allocation, container growth, reference counting, locking,
  and Python conversion in `eval`. Reuse pre-sized storage when the algorithm
  requires scratch space.
- Resolve wiring-time scalar policies to a concrete overload or plan. Do not
  branch on a policy string every tick.
- Read each input view only as often as needed. Use modified/delta access when
  full-value traversal is unnecessary.
- Emit no output when the contract calls for no tick; do not manufacture an
  unchanged value merely to simplify control flow.

If expensive work appears unavoidable, state why, inspect neighboring hot-path
code, and add focused performance evidence for a material regression risk.

## Select input types through operators

Treat an `if`/`else`, `switch`, schema-kind test, RTTI check, or visitor branch
that chooses node behaviour from an input's type as a design signal: stop and
make the alternatives operator overloads. Wiring already knows the concrete
input schemas, so select the implementation once there instead of rediscovering
the type during `start` or on every `eval`.

- If an operator already describes the behaviour, implement and register a
  more-specific node or graph overload.
- If no operator exists, introduce an implementation-free operator contract,

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: hgraph-write-graphs
description: Implement or review composable C++ hgraph graphs and Python `@graph` functions. Use when adding or changing graph composition, wiring-time type or scalar decisions, graph overloads and polymorphism, `GlobalState` or `LOGGER` graph injection, conditional wiring, graph documentation, or native/Python graph behavior tests.
---

# Write HGraph Graphs

Build behavior by composing small typed nodes and graphs at wiring time. Prefer
graphs as the ordinary unit of reuse; reserve new nodes for genuine runtime
primitives or demonstrated performance needs.

## Start from the existing contract

1. Read the current repository's `AGENTS.md`, the relevant operator and graph
   code, and nearby tests before editing.
2. Establish whether the task targets hgraph core or a downstream extension:
   - In the hgraph core checkout, read the applicable parts of
     `docs/source/user_guide/cpp/authoring_graphs.rst`,
     `docs/source/user_guide/python/tutorial/graph.rst`, and
     `docs/source/developer_guide/graph_wiring.rst`.
   - In a downstream project, use that project's graph conventions and tests,
     plus the public hgraph documentation for its pinned hgraph version. Do
     not assume the hgraph core source tree is present.
3. Identify the existing nodes, operators and graphs that already provide the
   required primitives. Compose them before creating a new primitive.
4. Preserve equivalent first-class C++ wiring and Python authoring behavior
   for every public cross-language feature.

Apply all repository documentation and type-system rules. A graph is not a
shortcut around signature validation, generic resolution or operator dispatch.

## Prefer a graph to a node

Start new behavior as a graph. A graph combines small, purpose-specific,
efficient and well-tested nodes into more complicated behavior, reducing the
new runtime code and validation surface.

Create a node only when the behavior requires a new per-tick primitive, side
effect, lifecycle service, runtime state transition, or a measured performance
improvement that composition cannot provide. Document that reason. Apply
`$hgraph-compute-sink-node` when implementing or reviewing the node.

Keep the trade-off explicit:

- Prefer composition and reuse by default.
- Measure before replacing a clear graph with a fused node for performance.
- Keep a justified fused node narrow and expose it through the same operator or
  graph contract where practical.

## Keep graph work at wiring time

A C++ graph's `compose` method and a Python `@graph` function execute once while
the graph is wired. Graphs flatten into their nodes and do not exist as runtime
evaluation objects.

Keep the graph's wiring implementation in `compose` or the decorated graph
function. Extract a helper only when it is a well-defined operation with its
own clear contract or is genuinely shared by multiple callers. Do not scatter
one graph's composition across single-use helper functions.

- Treat ports as typed wiring handles, never as current values.
- Inspect scalars, resolved types and wiring metadata only to choose topology.
- Do not retain runtime state or expect the graph body to run on a tick.
- Do not perform runtime side effects in a graph body.
- Move lifecycle and tick-dependent behavior into nodes.

The topology, overloads, bindings and policies selected by the graph are fixed
when graph composition returns.

## Compose for reuse and polymorphism

Use graphs as the primary workers for reusable behavior:

- Factor repeated compositions into small graphs with precise typed
  signatures.
- Compose graphs from other graphs; do not duplicate their internal nodes.
- Use generic graph signatures for type-safe reuse across compatible schemas.
- Use operator overloads when callers need polymorphic selection by type,
  shape or wiring-time algorithm policy.
- Use higher-order graph parameters when the caller should supply behavior.
- Keep wiring-time policy selection out of ever

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: hgraph-write-operators
description: Define or review hgraph operator contracts and overload families in C++ and Python. Use when adding a C++ operator marker or Python `@operator`, replacing input-type or wiring-policy branches with overload selection, implementing node or graph overloads, registering C++ or Python candidates, designing defaults/resolvers/requires predicates, diagnosing overload ranking or ambiguity, generating the Python operator surface, or testing operator dispatch and cross-language parity.
---

# HGraph Operator Authoring

Define a public function-like contract once, then let wiring select the most
specific registered implementation for the concrete argument schemas and
fixed scalar choices. Keep the contract pure and the implementations typed.

## Read the existing family first

1. Read the current repository's `AGENTS.md`. In the hgraph core checkout,
   also read `docs/source/developer_guide/operators.rst`; in a downstream
   project, use its extension conventions and the public operator
   documentation for the pinned hgraph version instead.
2. Inspect the nearest operator marker, implementation header, registration
   translation unit, C++ tests, and Python compatibility tests.
3. For a compute or sink implementation, also follow
   `../hgraph-compute-sink-node/SKILL.md`. For a graph overload, follow
   `../hgraph-write-graphs/SKILL.md`.
4. Inspect `include/hgraph/types/operator_dispatch.h` only when the task needs
   defaults, `requires_`, output resolution, variadic arguments, or dispatch
   diagnostics beyond the established neighbouring pattern.

## Define a pure function contract

Treat an operator as a function interface. It names one logical operation,
describes the general call shape, and documents behaviour shared by every
implementation. It is not executable. "Pure contract" means
implementation-free here; a sink operator may still contractually describe a
side effect.

- Give the marker only its name and abstract signature. Do not put `eval`,
  `start`, `stop`, `compose`, state, or implementation decisions on it.
- Document the semantic result, tick/validity expectations, errors, wiring-time
  policies, and argument meanings. Describe the supported family without
  promising one representation or algorithm unless that is part of the
  contract.
- Choose parameter names deliberately; implementations should preserve those
  names and their roles so named calls remain coherent.
- Use broad base type contracts in the marker. Use independent type variables
  when operands or output may differ; repeat a variable only when equality of
  those types is part of the public contract.
- Match the public Python operator name exactly, including any trailing
  underscore.

For example:

```cpp
/** Normalize values according to the wiring-time mode.
    @param ts Values to normalize.
    @param mode Supported normalization contract.
    @return Values in the overload-selected output shape. */
struct normalize : Operator<"normalize",
                            In<"ts", TsVar<"S">>,
                            Scalar<"mode", NormalizeMode>,
                            Out<TsVar<"O">>>
{
};
```

The marker signature is documentary. Candidate matching uses each
implementation's own signature, which is what permits a single operator to
cover concrete, generic, and heterogeneous types through node and graph
realizations. Output-producing and sink contracts remain distinct call shapes.

## Use overloads instead of type switches

When implementation code starts branching on an input type, schema kind,
scalar type, or fixed policy, move that choice into operator resolution. Wiring
knows these facts and should select the implementation once.

- Add an overload to the existing operator when the behaviour already has a
  contract.
- Introduce a new operator when no contract exists for the functionality; do
  not leave a standalone type-switching node as the public abstraction.
- Use a graph-level dynamic s

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.