5.5.1.5. Tokens

Tokens

Activity tokens are typed values that travel on object flows. They are the application data carried through an Activity; control flows carry control only. An action produces tokens with Output or OutputRange and reads routed inputs with GetTokensOfType<TToken>().

flowchart LR
    produce(Produce values) -->|int tokens| select{Decision}
    select -->|even| sum(Sum values)
    select -->|else| report(Report values)

Loading

Mermaid approximation: this diagram shows the model's routing, not a complete UML Activity notation. Rounded boxes represent actions; edge labels identify token types or guards. Mermaid does not provide native Activity node semantics.

Producing and receiving tokens

.AddInitial(node => node.AddControlFlow("Produce"))
.AddAction(
    "Produce",
    async c => c.OutputRange(new[] { 2, 5, 8 }),
    node => node.AddFlow<int, DecisionNode<int>>())
.AddDecision<int>(decision => decision
    .AddFlow("SumEven", flow => flow
        .AddGuard(async c => c.Token % 2 == 0))
    .AddElseFlow("ReportOther"))
.AddAction("SumEven", async c =>
{
    var values = c.GetTokensOfType<int>();
    await reports.WriteSumAsync(values.Sum(), c.CancellationToken);
})
.AddAction("ReportOther", async c =>
    await reports.WriteValuesAsync(
        c.GetTokensOfType<int>(), c.CancellationToken))

The generic argument on AddFlow<TToken> describes the object type carried by that edge. A flow guard can filter tokens; a transformation can change the type before they reach the target. Tokens may also be forwarded using PassTokensOfTypeOn<TToken>() or PassAllTokensOn() where the node/context API supports it.

Structured nodes pass selected parent tokens through input pins, and return data through output pins. Use a Data Store Node when a graph must retain tokens across later activations. See Data Flow and Implicit Fork and Join for routing and token reuse semantics.

Provenance during streaming

Orleans Activity streaming tracks transactional/streamed provenance on token envelopes, independently of the application payload type. A consumer receiving any streamed input becomes streamed and emits streamed outputs. This includes control inputs, not just object inputs.

Color survives flow guards, transformations, zero-weight/control paths, exception recovery, and nested Activity boundaries. Forked occurrences can retain the same logical identity while carrying independent provenance; routing copies do not isolate mutable application payload objects.

Idle transactional tokens waiting for missing inputs do not hold their transaction open. When the regular transaction closes during streaming, its remaining idle marking becomes streamed. Transactional tokens arriving at a Data Store become streamed immediately during the busy period. These rules allow later regular events to influence a running network without waiting for all of its descendants.

At natural quiescence, ordinary transaction semantics are restored for the persisted marking. Provenance is engine metadata for execution ownership, not a durable application-level work identifier or an exactly-once guarantee.