Topic Suffixes

cross.stream uses special topic suffixes to coordinate between components and track their lifecycle. This reference documents all suffixes, organized by component type.

Topic Naming Convention

When choosing topic names, use hyphens (-) instead of dots (.):

# Good - uses hyphens
"my-topic" | .append

# Avoid - dots can collide with system suffixes
"my.topic" | .append

Dots are reserved for the suffix convention (e.g., .spawn, .recv, .register). Using dots in topic names could accidentally collide with system suffixes, leading to unexpected behavior.

Generators

Suffix	Description	Emitted By
.spawn	Create or update a generator	User
.terminate	Stop a generator	User
.send	Input to duplex generators	User
.running	Generator has started	System
.stopped	Generator pipeline stopped	System
.shutdown	Generator loop fully exited	System
.parse.error	Script parsing failed	System
.recv	Output from generator	System

Handlers

Suffix	Description	Emitted By
.register	Register a handler	User
.unregister	Unregister a handler	User
.active	Handler is now active	System
.unregistered	Handler has been removed	System
.out	Output from handler	System

Commands

Suffix	Description	Emitted By
.define	Define a command	User
.call	Invoke a command	User
.ready	Command ready for calls	System
.error	Command execution failed	System
.response	Command execution result	System

System Topics

System topics manage cross.stream’s internal operations and lifecycle:

Topic	Description	Context
xs.start	System initialization complete	Default
xs.context	New context created	Default
xs.threshold	Stream processing threshold marker	Per-context
xs.pulse	Synthetic pulse events (configurable interval)	Per-context

Customizable Suffixes

The following output suffixes can be customized using return_options:

• .recv (Generators) - Can be changed via return_options.suffix
• .out (Handlers) - Can be changed via return_options.suffix
• .response (Commands) - Can be changed via return_options.suffix

Example customization:

{
  run: {|| "Hello, World!" },
  return_options: {
    suffix: ".message"  # Changes .recv to .message
  }
}

Metadata

All lifecycle and output events include relevant metadata:

• source_id / handler_id / command_id: ID of the component instance
• frame_id: ID of the triggering frame (for handlers/commands)
• Error events include error field with error details
• Stopped events include reason field explaining why the component stopped